DD::Image::LUT Class Reference

#include <LUT.h>

Inherited by AlexaV3LogC_LUT_Class, ArriLogC4_LUT_Class, BlackMagicGEN5_LUT_Class, CLog_LUT_Class, Cineon_LUT_Class, Gamma_LUT_Class, HybridLogGamma_LUT_Class, Linear_LUT_Class, Log3G10_LUT_Class, Log3G12_LUT_Class, PLogLin_LUT_Class, Panalog_LUT_Class, Protune_LUT_Class, REDLog_LUT_Class, SLog1_LUT_Class, SLog2_LUT_Class, SLog3_LUT_Class, SLog_LUT_Class, ST2084_LUT_Class, ViperLog_LUT_Class, rec709_LUT_Class, and sRGB_LUT_Class.

Public Types
enum	DataType {   INVALID , MONITOR , VIEWER , INT8 ,   INT16 , LOG , FLOAT , GAMMA1_8 ,   GAMMA2_2 , GAMMA2_4 , PANALOG , REDLOG ,   VIPERLOG , ALEXAV3LOGC , PLOGLIN , SLOG ,   SLOG1 , SLOG2 , SLOG3 , CLOG ,   PROTUNE , GAMMA2_6 , LOG3G10 , LOG3G12 ,   BT1886 , HDR2084 , HYBRIDLOGGAMMA , ST2084 ,   BLACKMAGIC_GEN5 , ARRILOGC4 , TYPES_END }
typedef int	BuiltinLUTId

Public Member Functions
bool	isToTableValid () const
float	test (float) const
bool	linear () const
bool	zero () const
void	append (Hash &) const
virtual float	to_byte (float) const =0
void	to_byte (uchar *, const float *, int W, int delta=1) const
void	to_byte (uchar *, const float *, const float *alpha, int W, int delta=1) const
void	to_short (U16 *, const float *, int W, int bits=16, int delta=1) const
void	to_short (U16 *, const float *, const float *alpha, int W, int bits=16, int delta=1) const
virtual float	from_byte (float) const =0
void	from_byte (float *, const uchar *, int W, int delta=1) const
void	from_byte (float *, const uchar *, const uchar *alpha, int W, int delta=1) const
void	from_short (float *, const U16 *, int W, int bits=16, int delta=1) const
void	from_short (float *, const U16 *, const U16 *alpha, int W, int bits=16, int delta=1) const
void	to_float (float *, const float *, int W, int delta=1) const
void	to_float (float *, const float *, const float *alpha, int W, int delta=1) const
void	from_float (float *, const float *, int W, int delta=1) const
void	from_float (float *, const float *, const float *alpha, int W, int delta=1) const
float	fromFloat (float v) const
float	fromFloatFast (float v) const
float	toFloat (float v) const
float	toFloatFast (float v) const

Static Public Member Functions
static LUT *	Linear ()
static void	setBuiltin (BuiltinLUTId n, const char *name, LUT *lut)
static LUT *	GetBuiltinLUT (BuiltinLUTId id)
static LUT *	GetBuiltinLutByName (const char *name)
static LUT *	Builtin (BuiltinLUTId n, Reader *)
static LUT *	Builtin (const char *name, Reader *)
static LUT *	Builtin (BuiltinLUTId n, Writer *)
static LUT *	Builtin (const char *name, Writer *)
static void	append (BuiltinLUTId n, Hash &)
static LUT *	GetDefaultLutForType (DataType)
static LUT *	GetLut (DataType, const Reader *)
static LUT *	GetLut (DataType, const Writer *)
static void	SetLut (DataType, LUT *)
static LUT *	sRGB ()

Static Public Attributes
static const char *	builtin_names []

Protected Member Functions
void	fillToTable () const
void	fillFromTable ()
void	validate ()

Static Protected Member Functions
static void	InitialiseBuiltin (BuiltinLUTId id)

Protected Attributes
Hash	hash

Detailed Description

A LUT defines a mapping function. One side is the floating point numbers used in Nuke. The other side (the side it goes "to" and "from") is generally values that are used in a file or by a piece of hardware.

The LUT class can very quickly convert between an array of floating point number in Nuke and arrays of 8 bit or 16 bit numbers. It can also convert float<->float and may be faster depending on the complexity of the function. All this is done by using lookup tables and linear interpolation between the table entries. When converting to integers, error diffusion is used to hide posterization.

Any subclass must implement to_byte() and from_byte(). For historical reasons these convert to the range 0..255 rather than 0..1.

There is also the pseudo-subclass Linear, which has the same API but does straight line transfer only, avoiding the if statement used to detect this in the LUT class functions.

Member Function Documentation

fillToTable()

void LUT::fillToTable ( ) const

protected

Fill in the table used by toFloatFast() and thus by all the to functions. This is done by calling to_byte(). This can be used by a from_byte() implementation that works by using interpolation to invert the to_byte() function. Does nothing if called a second time.

References fast_rint(), linear(), to_byte(), and zero().

Referenced by test(), to_byte(), to_float(), to_short(), and toFloatFast().

fillFromTable()

void LUT::fillFromTable ( )

protected

Fill in the table used by fromFloatFast() and thus all the from functions. This is done by calling from_byte(). This can be used by a to_byte() implementation taht works by using interpolation to invert the from_byte() function. Does nothing if called a second time.

References from_byte().

Referenced by validate().

validate()

void LUT::validate ( )

protected

Forces fillToTable() and fillFromTable() to fill the tables again and calls them, and calculates a value for hash(). The constructor calls this, but subclasses may want to call this directly if the LUT has other controls that can change it's results.

References fillFromTable(), and DD::Image::Hash::reset().

isToTableValid()

bool DD::Image::LUT::isToTableValid ( ) const

inline

Returns true if the LUT table used by the to functions is valid. It becomes valid after the first time one of the to functions is used.

Referenced by DD::Image::Write::execute().

test()

float LUT::test

(

float

v

)

const

Return the value that to_byte(uchar...) is being calculated to by the lookup table.

References fillToTable().

Referenced by DD::Image::Read::_validate(), and DD::Image::Write::_validate().

linear()

bool DD::Image::LUT::linear ( ) const

inline

Returns true if to_byte(x) appears to return x*255. This is tested when the table is filled in. If true some operators are much faster.

Referenced by fillToTable(), from_float(), and from_short().

zero()

bool DD::Image::LUT::zero ( ) const

inline

Returns true if to_byte(0) returns a value <= 0. This is tested when the table is filled in. If true some operators are much faster.

Referenced by fillToTable().

append() [1/2]

void LUT::append

(

Hash &

hash

)

const

Add the contents of this LUT to the hash. This is pretty fast (it just appends a single internal Hash) because it needs to be called a lot to determine if images have changed.

Referenced by append(), and DD::Image::Read::append().

to_byte() [1/3]

float DD::Image::LUT::to_byte ( float  ) const

pure virtual

This virtual function must be overridden to do the math that converts floating point values to byte values in the range 0-255. Notice that you want as accurate as a result as possible, do not round to the nearest integer. LUT assumes that for any values in the range 0-1.0 that this function is the inverse of to_byte(float).

Referenced by fillToTable(), and DD::Image::Writer::to_byte().

to_byte() [2/3]

void LUT::to_byte	(	uchar *	buf,
		const float *	from,
		int	W,
		int	delta = 1
	)		const

Convert an array of floating point pixel values to an array of bytes, with error diffusion. This is very well optimized and quite fast, and is used by the Nuke viewer when drawing it's display.

W is the number of pixels to convert.

delta is how far apart to put the resulting bytes, allowing you to write to an interlaced buffer.

The input and output buffers must not overlap in memory.

References DD::Image::end(), and fillToTable().

to_byte() [3/3]

void LUT::to_byte	(	uchar *	buf,
		const float *	from,
		const float *	alpha,
		int	W,
		int	delta = 1
	)		const

Convert an array of floating point pixel values to an array of bytes, with error diffusion.

alpha is the unconverted alpha for a premultiplied image. This is used to correct the premultiply so it matches how premultiply is usually stored on disk (the stored values are the converted values multiplied by the alpha, rather than the linear values multiplied by the alpha. The alpha channel itself should be converted with Linear::to_byte().

W is the number of pixels to convert.

delta is how far apart to put the resulting bytes, allowing you to write to an interlaced buffer.

The input and output buffers must not overlap in memory.

References DD::Image::end(), and fillToTable().

to_short() [1/2]

void LUT::to_short	(	U16 *	buf,
		const float *	from,
		int	W,
		int	bits = 16,
		int	delta = 1
	)		const

Fill an array of W shorts with n-bit conversion of the floating point pixels. Input values less than zero turn into zero, input values greater than 1 turn into all 1's (even though larger numbers can be represented when bits < 16). See to_byte for how all the other arguments are treated.

Currently no error diffusion is done.

References fillToTable(), and DD::Image::Linear::to_short().

Referenced by DD::Image::Writer::to_short().

to_short() [2/2]

void LUT::to_short	(	U16 *	buf,
		const float *	from,
		const float *	alpha,
		int	W,
		int	bits = 16,
		int	delta = 1
	)		const

Fill an array of W shorts with n-bit conversion of the floating point pixels. Input values less than zero turn into zero, input values greater than 1 turn into all 1's (even though larger numbers can be represented when bits < 16). See to_byte for how all the other arguments are treated.

References fillToTable(), and DD::Image::Linear::to_short().

from_byte() [1/3]

float DD::Image::LUT::from_byte ( float  v ) const

pure virtual

This virtual function should be overridden to do the math that converts byte values in the range 0-255 to floating point. LUT assumes that this function is the inverse of to_byte(float).

Referenced by fillFromTable(), and DD::Image::Reader::from_byte().

from_byte() [2/3]

void LUT::from_byte	(	float *	buf,
		const uchar *	from,
		int	W,
		int	delta = 1
	)		const

Converts bytes through the from_byte(float) virtual function. A 256-entry lookup table filled in by validate() is used for maximum speed.

The input data is W bytes in the range 0-255 pointed to by from. delta is the distance between the input bytes (for the common case where the input is interlaced rgba samples).

The output is written to the first W floats of buf.

The input and output may be the same memory array as long as delta is less or equal to 4. The conversion is done in backwards order so this is possible.

from_byte() [3/3]

void LUT::from_byte	(	float *	buf,
		const uchar *	from,
		const uchar *	alpha,
		int	W,
		int	delta = 1
	)		const

Similar to the previous from_byte() except this divides by the alpha channel then does the conversion, then multiplies by the alpha channel again. This corrects the values for premultiplied pixels in the common case where the renderer multiplied them in 8-bit space rather than in linear light levels. If dividing by the alpha produces a result greater than 1 it assumes it is 1.

The alpha channel should be run through Linear::from_byte() to get the correct alpha channel.

delta is assumed to apply to both the from and alpha arrays.

The input, alpha, and output may be the same memory array as long as delta is less or equal to 4. The conversion is done in backwards order so this is possible.

from_short() [1/2]

void LUT::from_short	(	float *	buf,
		const U16 *	from,
		int	W,
		int	bits = 16,
		int	delta = 1
	)		const

Converts 16-bit data to linear floating point. n 1's is considered 1.0. The resulting floating point numbers are from_byte(255*x/(2^n-1)). The current implementation is not really fast and calls the virtual from_byte() function for each sample.

The input data is W 16-bit words pointed to by from. delta is the distance between each (for the common case where the input is interlaced rgba samples).

The output is written to the first W floats of buf.

The input and output may be the same memory array as long as delta is less or equal to 2. The conversion is done in backwards order so this is possible.

References DD::Image::Linear::from_short(), and linear().

Referenced by DD::Image::Reader::from_short().

from_short() [2/2]

void LUT::from_short	(	float *	buf,
		const U16 *	from,
		const U16 *	alpha,
		int	W,
		int	bits = 16,
		int	delta = 1
	)		const

Similar to the previous from_byte() except this divides by the alpha channel then does the conversion, then multiplies by the alpha channel again. This corrects the values for premultiplied pixels in the common case where the renderer multiplied them in 8-bit space rather than in linear light levels. If dividing by the alpha produces a result greater than 1 it assumes it is 1.

The alpha channel should be run through Linear::from_byte() to get the correct alpha channel.

delta is assumed to apply to both the from and alpha arrays.

The input, alpha, and output may be the same memory array as long as delta is less or equal to 2. The conversion is done in backwards order so this is possible.

References DD::Image::Linear::from_short(), and linear().

to_float() [1/2]

void LUT::to_float	(	float *	to,
		const float *	from,
		int	W,
		int	delta = 1
	)		const

Convert an array of W floating-point values by calling toFloatFast() and write them to to separated by delta.

References fillToTable().

Referenced by DD::Image::Writer::to_float().

to_float() [2/2]

void LUT::to_float	(	float *	to,
		const float *	from,
		const float *	alpha,
		int	W,
		int	delta = 1
	)		const

Convert an array of floating-point values from the 0-1 linear range by calling toFloatFast(x/a)*a where a is the value from the alpha arrays. I.e. unpremultliply by alpha, convert, and then multiply back.

References fillToTable().

from_float() [1/2]

void LUT::from_float	(	float *	dst,
		const float *	src,
		int	W,
		int	delta = 1
	)		const

Convert an array of W floating point values separated by delta using fromFloatFast() and write them to dst, separated by 1. src and dst may point to the same memory.

References linear().

Referenced by DD::Image::Reader::from_float().

from_float() [2/2]

void LUT::from_float	(	float *	dst,
		const float *	src,
		const float *	alpha,
		int	W,
		int	delta = 1
	)		const

Convert using fromFloatFast(x/a)*a, where a is the values from the alpha array. I.e. unpremultiply, convert, then multiply again. src and dst may point to the same memory.

References linear().

fromFloat()

float DD::Image::LUT::fromFloat ( float  v ) const

inline

Calls from_byte(x*255), and thus converts a single floating point value accurately to linear. This may be slow, see fromFloatFast().

fromFloatFast()

float LUT::fromFloatFast

(

float

v

)

const

Converts a single floating point value to linear by using the lookup tables. The value is clamped to the 0-1 range as that is the range of the tables!

toFloat()

float DD::Image::LUT::toFloat ( float  v ) const

inline

Calls to_byte(x)*255, and thus converts a single floating point linear value accurately. This may be slow, see toFloatFast().

toFloatFast()

float LUT::toFloatFast

(

float

v

)

const

Converts a single floating point value from linear to the LUT space by using the lookup tables.

References fillToTable().

Linear()

LUT * LUT::Linear ( )

static

Return a pointer to a LUT that converts colors linear.

References DD::Image::Lock::lock(), and DD::Image::Lock::unlock().

Referenced by DD::Image::Write::execute().

GetBuiltinLUT()

LUT * LUT::GetBuiltinLUT ( BuiltinLUTId  id )

static

Return LUT based on enumeration. If you create an Enumeration_knob using the builtin_names then you can pass the index it stores as an argument to this function to get the chosen LUT.

If you pass zero then getLut(MONITOR) is returned, however this is supposed to indicate that you are to intelligently choose based on data type and call getLut().

Referenced by append().

GetBuiltinLutByName()

LUT * LUT::GetBuiltinLutByName ( const char *  name )

static

Returns the BuiltinLUT named "name". If no match is found, returns the LUT associated with the MONITOR datatype.

append() [2/2]

void LUT::append ( BuiltinLUTId  n, Hash &  hash  )

static

Same as builtin(n)->append(hash), except if n==0 it will append the hash for all the types of data, on the assumption that the one to be chosen will be one of them. This is to generate a hash that will change at the right times for file readers.

References append(), and GetBuiltinLUT().

GetDefaultLutForType()

LUT * LUT::GetDefaultLutForType ( DataType  dataTypeHint )

static

Return the LUT to use by default for the given data type.

Referenced by DD::Image::ToBuffer::to_buffer().

Member Data Documentation

builtin_names

const char * LUT::builtin_names

static

Return a null-terminated array of string names of the built-in LUT types as used by builtin(). This can be used to provide labels for an Enumeration_knob. The first entry says "auto-detect", but you can skip this by adding 1 to the returned value.