Nuke binary plugins 15.0.5
 
Loading...
Searching...
No Matches
DD::Image::LUT Class Referenceabstract

#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 LUTLinear ()
 
static void setBuiltin (BuiltinLUTId n, const char *name, LUT *lut)
 
static LUTGetBuiltinLUT (BuiltinLUTId id)
 
static LUTGetBuiltinLutByName (const char *name)
 
static LUTBuiltin (BuiltinLUTId n, Reader *)
 
static LUTBuiltin (const char *name, Reader *)
 
static LUTBuiltin (BuiltinLUTId n, Writer *)
 
static LUTBuiltin (const char *name, Writer *)
 
static void append (BuiltinLUTId n, Hash &)
 
static LUTGetDefaultLutForType (DataType)
 
static LUTGetLut (DataType, const Reader *)
 
static LUTGetLut (DataType, const Writer *)
 
static void SetLut (DataType, LUT *)
 
static LUTsRGB ()
 

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.



©2024 The Foundry Visionmongers, Ltd. All Rights Reserved.
www.foundry.com