IDXLUTBuilder Interface

The IDXLUTBuilder interface enables you to construct a lookup table for an input DXSurface. A lookup table is a set of four arrays of 256 numbers each, with one array for each color channel and one array for the alpha channel. Each color channel of each sample in an image is modified by a lookup table with the following code.

pBuffer[i].Color   = pColorLookupTable[pBuffer[i].Color];

In effect, the previous color value is used as an index to the modified color value stored in the lookup table array.

There are a number of standard color corrections that you can perform with Microsoft® DirectX® Transform lookup tables, which are listed in the OPIDDXLUTBUILDER enumeration. You can also specify any number of color corrections in any order.

To use this interface, call the COM CoCreateInstance method as shown in the following:

   IDXLUTBuilder*  g_pLUTBuilder;
   hr = CoCreateInstance( CLSID_DXLUTBuilder, NULL, CLSCTX_INPROC,
                             IID_IDXLUTBuilder, (void **)&g_pLUTBuilder );
	...							 
						 
   IDXLookupTable* g_pLUT;
   hr = g_pLUTBuilder->QueryInterface( IID_IDXLookupTable,
                                          (void **)&g_pLUT );

When you implement this interface, the call to the QueryInterface method should return an IDXLookupTable pointer. Use this pointer as a parameter to the IDXSurfaceModifier::SetLookup method to connect your lookup table to the DXSurfaceModifier object (Surface Modifier).

IDXLUTBuilder Methods

GetBrightness Retrieves the current settings for the lookup table brightness curve.

GetBuildOrder Retrieves the order of operations used to build the lookup table.

GetColorBalance Retrieves the tint curves used for color balance operations on the selected color.

GetContrast Retrieves the current settings for the lookup table contrast curve.

GetGamma Retrieves the value used for Gamma correction.

GetInvert Retrieves the threshold value used for color inversion.

GetLevelsPerChannel Retrieves the number of color levels to use for the posterizing operation.

GetNumBuildSteps Retrieves the number of lookup table operations to perform.

GetOpacity Retrieves the opacity adjustment used for the lookup table.

GetThreshold Retrieves the value used for threshold filtering operations.

SetBrightness Sets the values for the lookup table brightness curve.

SetBuildOrder Sets the order of operations used to build the lookup table.

SetColorBalance Sets the tint curves used for color balance operations on the selected color.

SetContrast Sets the values for the lookup table contrast curve.

SetGamma Sets the value used for Gamma correction.

SetInvert Sets the threshold value used for color inversion.

SetLevelsPerChannel Sets the number of color levels to use for the posterizing operation.

SetOpacity Sets the opacity adjustment used for the lookup table.

SetThreshold Sets the value used for threshold filtering operations.

IDXLUTBuilder::GetBrightness

IDXLUTBuilder Interface

Retrieves the current settings for the lookup table brightness curve.

Syntax

HRESULT GetBrightness(
    ULONG *pulCount,
    float Weights[]
);

Parameters

pulCount
[out] Pointer to the number of entries in the brightness curve. This value should be less than or equal to 256.

Weights
[out] Array that holds the brightness curve values. These values should be greater than or equal to zero and are usually around 1.0.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For brightness adjustments, each color channel value is multiplied by the Weights value. The adjustment is applied in pulCount steps over the 256 values of the lookup table.

IDXLUTBuilder::GetBuildOrder

IDXLUTBuilder Interface

Retrieves the order of operations used to build the lookup table.

Syntax

HRESULT GetBuildOrder(
    OPIDDXLUTBUILDER OpOrder[],
    ULONG ulSize
);

Parameters

OpOrder
[out] Array of lookup table operations listed in the OPIDDXLUTBUILDER enumeration.

ulSize
[out] Number of lookup table operations in the returned array.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXLUTBuilder::GetColorBalance

IDXLUTBuilder Interface

Retrieves the tint curves used for color balance operations on the selected color.

Syntax

HRESULT GetColorBalance(
    DXLUTCOLOR Color,
    ULONG *pulCount,
    float Weights[] 
);

Parameters

Color
[in] Member of the DXLUTCOLOR enumeration that selects the color channel for this tint curve.

pulCount
[out] Pointer to the number of values in the returned tint curve.

Weights
[out] Array of values that is the tint curve used for color balancing.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

A tint curve is a separate brightness curve for each color channel. This gives you finer control over the output colors than the brightness adjustment alone.

IDXLUTBuilder::GetContrast

IDXLUTBuilder Interface

Retrieves the current settings for the lookup table contrast curve.

Syntax

HRESULT GetContrast(
	ULONG *pulCount,
	float Weights[]
);

Parameters

pulCount
[out] Pointer to the number of entries in the contrast curve.

Weights
[out] Array that holds the contrast curve values.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Contrast adjustments shift the range of each color channel around a midpoint. The adjustment is applied in pulCount steps over the 256 values of the lookup table.

IDXLUTBuilder::GetGamma

IDXLUTBuilder Interface

Retrieves the value used for Gamma correction.

Syntax

HRESULT GetGamma(
    float *pVal
);

Parameters

pVal
[out] Pointer to the value used for Gamma correction.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This is a standard brightness adjustment. Gamma correction values of 1.0 produce no effect.

IDXLUTBuilder::GetInvert

IDXLUTBuilder Interface

Retrieves the threshold value used for color inversion.

Syntax

HRESULT GetInvert(
	float *pThreshold
);

Parameters

pThreshold
[out] Pointer to the threshold value to use for color inversion, which represents a fraction of a one-byte color channel.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Color inversion produces new color values that are the old color values subtracted from 255. Only values above pThreshold*256 are inverted.
This value is used when the OPID_DXLUTBUILDER_Invert lookup table operation is used.

IDXLUTBuilder::GetLevelsPerChannel

IDXLUTBuilder Interface

Retrieves the number of color levels to use for the posterizing operation.

Syntax

HRESULT GetLevelsPerChannel(
	ULONG *pVal
);

Parameters

pVal
[out] Pointer to the number of color levels that should remain after posterizing.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXLUTBuilder::GetNumBuildSteps

IDXLUTBuilder Interface

Retrieves the number of lookup table operations to perform.

Syntax

HRESULT GetNumBuildSteps(
    ULONG *pulNumSteps
);

Parameters

pulNumSteps
[out] Pointer to the number of lookup table operations to perform.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The number of operations pulNumSteps is set through SetBuildOrder.

IDXLUTBuilder::GetOpacity

IDXLUTBuilder Interface

Retrieves the opacity adjustment used for the lookup table.

Syntax

HRESULT GetOpacity(
    float *pVal
);

Parameters

pVal
[out] Pointer to the opacity adjustment for the lookup table.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Each value of alpha in the lookup table is multiplied by this value for opacity.

IDXLUTBuilder::GetThreshold

IDXLUTBuilder Interface

Retrieves the value used for threshold filtering operations.

Syntax

HRESULT GetThreshold(
    float *pVal
);

Parameters

pVal
[in] Pointer to the threshold value.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For the threshold filtering adjustment, each sample color channel whose value is below pVal*255 is set to 0. All color channels whose value is above or equal to that threshold are set to 255.

IDXLUTBuilder::SetBrightness

IDXLUTBuilder Interface

Sets the values for the lookup table brightness curve.

Syntax

HRESULT SetBrightness(
    ULONG ulCount,
    const float Weights[]
);

Parameters

ulCount
[in] Number of entries in the brightness curve. This value should be less than or equal to 256.

Weights
[in] Array that holds the brightness curve values. These values should be greater than or equal to zero and are usually around 1.0.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For brightness adjustment, each color channel value is multiplied by the Weights value. The adjustment is applied in pulCount steps over the 256 values of the lookup table.

IDXLUTBuilder::SetBuildOrder

IDXLUTBuilder Interface

Sets the order of operations used to build the lookup table.

Syntax

HRESULT SetBuildOrder(
    const OPIDDXLUTBUILDER OpOrder[],
    ULONG ulNumSteps
);

Parameters

OpOrder
[in] Array of lookup table operations listed in the OPIDDXLUTBUILDER enumeration.

ulNumSteps
[in] Number of lookup table operations in the returned array.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method sets the number and order of lookup table operations. Keep in mind that the resulting lookup table depends on the order of the operations you specify. For example, a lookup table built by adjusting the brightness before the contrast will be different than one built by adjusting the contrast before the brightness.
The operations are performed in order, starting with the first element in the array OpOrder[0].

IDXLUTBuilder::SetColorBalance

IDXLUTBuilder Interface

Sets the tint curves used for color balance operations on the selected color.

Syntax

HRESULT SetColorBalance(
    DXLUTCOLOR Color,
    ULONG ulCount,
    const float Weights[]
);

Parameters

Color
[in] Member of the DXLUTCOLOR enumeration that selects the color channel for this tint curve.

ulCount
[in] Number of values in the returned tint curve. This value should be less than or equal to 256.

Weights
[in] Array of values that is the tint curve used for color balancing.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

A tint curve is a separate brightness curve for each color channel. This gives you finer control over the output colors than the brightness adjustment alone.

IDXLUTBuilder::SetContrast

IDXLUTBuilder Interface

Sets the values for the lookup table contrast curve.

Syntax

HRESULT SetContrast(
    ULONG ulCount,
    const float  Weights[]
);

Parameters

ulCount
[in] Number of entries in the contrast curve. This value should be less than or equal to 256.

Weights
[in] Array that holds the contrast curve values. These values should be greater than or equal to zero and are usually around 1.0.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Contrast adjustments shift the range of each color channel around a midpoint. The adjustment is applied in pulCount steps over the 256 values of the lookup table.

IDXLUTBuilder::SetGamma

IDXLUTBuilder Interface

Sets the value used for Gamma correction.

Syntax

HRESULT SetGamma(
    float newVal
);

Parameters

newVal
[in] Value used for Gamma correction. This value must be greater than zero.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This is a standard brightness adjustment. Gamma correction values of 1.0 produce no effect.

IDXLUTBuilder::SetInvert

IDXLUTBuilder Interface

Sets the threshold value used for color inversion.

Syntax

HRESULT SetInvert(
    float Threshold
);

Parameters

Threshold
[in] Threshold value to use for color inversion, which represents a fraction of a one-byte color channel. This value should be between 0.0 and 1.0.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Color inversion produces new color values that are the previous color values subtracted from 255. Only values above pThreshold*256 are inverted.
This value is used when the OPID_DXLUTBUILDER_Invert lookup table operation is used.

IDXLUTBuilder::SetLevelsPerChannel

IDXLUTBuilder Interface

Sets the number of color levels to use for the posterizing operation.

Syntax

HRESULT SetLevelsPerChannel(
    ULONG newVal
);

Parameters

newVal
[in] Number of color levels that should remain after posterizing.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXLUTBuilder::SetOpacity

IDXLUTBuilder Interface

Sets the opacity adjustment used for the lookup table.

Syntax

HRESULT SetOpacity(
    float newVal
);

Parameters

newVal
[in] Opacity adjustment for the lookup table. The value should range from 0.0 to 1.0.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Each value of alpha in the lookup table is multiplied by this value for opacity.

IDXLUTBuilder::SetThreshold

IDXLUTBuilder Interface

Sets the value used for threshold filtering operations.

Syntax

HRESULT SetThreshold(
    float newVal
);

Parameters

newVal
[in] Threshold value. This number should be between 0.0 and 1.0.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For the threshold filtering adjustment, each sample color channel whose value is below newVal*255 is set to 0. All color channels whose value is above or equal to that threshold are set to 255.

GetBrightness	Retrieves the current settings for the lookup table brightness curve.
GetBuildOrder	Retrieves the order of operations used to build the lookup table.
GetColorBalance	Retrieves the tint curves used for color balance operations on the selected color.
GetContrast	Retrieves the current settings for the lookup table contrast curve.
GetGamma	Retrieves the value used for Gamma correction.
GetInvert	Retrieves the threshold value used for color inversion.
GetLevelsPerChannel	Retrieves the number of color levels to use for the posterizing operation.
GetNumBuildSteps	Retrieves the number of lookup table operations to perform.
GetOpacity	Retrieves the opacity adjustment used for the lookup table.
GetThreshold	Retrieves the value used for threshold filtering operations.
SetBrightness	Sets the values for the lookup table brightness curve.
SetBuildOrder	Sets the order of operations used to build the lookup table.
SetColorBalance	Sets the tint curves used for color balance operations on the selected color.
SetContrast	Sets the values for the lookup table contrast curve.
SetGamma	Sets the value used for Gamma correction.
SetInvert	Sets the threshold value used for color inversion.
SetLevelsPerChannel	Sets the number of color levels to use for the posterizing operation.
SetOpacity	Sets the opacity adjustment used for the lookup table.
SetThreshold	Sets the value used for threshold filtering operations.