Sample Modification Helper Functions

The sample modification helper functions perform a number of useful operations on individual samples or arrays of samples. They are primarily used for combining and manipulating input image data before writing it to an output DXSurface.

To use these functions, you must include the file Dxhelper.h from the DXMedia\Include directory in your program.

Sample Modification Functions

DXApplyColorChannelLookupArray Applies a color channel lookup table to an array of DXBASESAMPLE structures.
DXApplyLookupTable Applies a lookup table to a single DXBASESAMPLE structure.
DXApplyLookupTableArray Applies a lookup table to an array of DXBASESAMPLE structures.
DXConvertToGray Converts a color sample to gray scale.
DXDitherArray Dithers a specified array of samples.
DXInvertAlpha Inverts the specified alpha value.
DXPreMultArray Multiplies the color components of an array of samples by its alpha value.
DXPreMultSample Multiplies the color components of a sample by its alpha value.
DXSampleFromColorRef Converts a COLORREF value to a DXSAMPLE structure format.
DXUnPreMultArray Converts an array of DXPMSAMPLE colors to DXSAMPLE format.
DXUnPreMultSample Converts a DXPMSAMPLE color to DXSAMPLE format.
DXWeightedAverage Produces a weighted average of two samples.
DXWeightedAverageArray Produces a weighted average of two arrays of samples.

DXApplyColorChannelLookupArray

Applies a color channel lookup table to an array of DXBASESAMPLE structures.

Syntax

DXBASESAMPLE *DXApplyColorChannelLookupArray(
	DXBASESAMPLE *pBuffer,
	ULONG cSamples,
	const BYTE *pAlphaTable,
	const BYTE *pRedTable,
	const BYTE *pGreenTable,
	const BYTE *pBlueTable
);

Parameters

pBuffer
[in] Pointer to a source array of DXBASESAMPLE structures.
cSamples
[in] Number of samples to convert.
pAlphaTable
[in] Pointer to the alpha channel lookup table.
pRedTable
[in] Pointer to the red lookup table.
pGreenTable
[in] Pointer to the green lookup table.
pBlueTable
[in] Pointer to the blue lookup table.

Return Value

Returns a pointer to the converted array of DXBASESAMPLE structures.

Remarks

This function enables you to apply a different lookup table to each color channel separately. In standard usage, you would use the IDXLUTBuilder interface to create a lookup table, and the IDXLookupTable::GetTables method to fill the arrays. You can also create your own lookup table arrays.

DXApplyLookupTable

Applies a lookup table to a single DXBASESAMPLE structure.

Syntax

DXBASESAMPLE DXApplyLookupTable(
	const DXBASESAMPLE Src,
	const BYTE *pTable
);

Parameters

Src
[in] Source DXBASESAMPLE structure.
pTable
[in] Pointer to the lookup table to use for converting the samples.

Return Value

Returns the converted DXBASESAMPLE structure.

Remarks

Unlike DXApplyColorChannelLookupArray, this function uses a single lookup table for all four color channels.

DXApplyLookupTableArray

Applies a lookup table to an array of DXBASESAMPLE structures.

Syntax

DXApplyLookupTableArray(
	DXBASESAMPLE *pBuffer,
	ULONG cSamples,
	const BYTE *pTable
);

Parameters

pBuffer
[in] Pointer to a source array of DXBASESAMPLE structures.
cSamples
[in] Number of samples to convert.
pTable
[in] Pointer to the lookup table to use for converting the samples.

Return Value

Returns a pointer to the converted array of DXBASESAMPLE structures.

DXConvertToGray

Converts a color sample to gray scale.

Syntax

DXBASESAMPLE DXConvertToGray( 
    DXBASESAMPLE Sample 
);

Parameters

Sample
[in] The DXBASESAMPLE to convert to gray.

Return Value

Returns the converted DXBASESAMPLE.

DXDitherArray

Dithers a specified array of samples.

Syntax

DXDitherArray( 
    const DXDITHERDESC *pDitherDesc 
);

Parameters

pDitherDesc
[in, out] Pointer to a DXDITHERDESC structure that contains the samples to dither.

Return Value

No return value. The function dithers the samples specified in DXDITHERDESC and returns.

DXInvertAlpha

Inverts the specified alpha value.

Syntax

BYTE DXInvertAlpha( 
    BYTE Alpha 
);

Parameters

Alpha
[in] Alpha value of a sample.

Return Value

Returns the inverted alpha, which is computed by a logical NOT operation.

DXPreMultArray

Multiplies the color components of an array of samples by its alpha value.

Syntax

DXPMSAMPLE *DXPreMultArray(
	DXSAMPLE *pBuffer,
	ULONG cSamples
);

Parameters

pBuffer
[in] Pointer to the array of samples to convert.
cSamples
[in] Number of samples to convert.

Return Value

Returns a pointer to an array of alpha-premultiplied samples.

Remarks

This function is useful for switching a sample between ARGB32 and PMARGB32 pixel formats.

See Also

DXPMSAMPLE, DXSAMPLE

DXPreMultSample

Multiplies the color components of a sample by its alpha value.

Syntax

DXPMSAMPLE DXPreMultSample(
    const DXSAMPLE &Src
);

Parameters

Src
[in] Sample to convert.

Return Value

Returns an alpha-premultiplied version of the source sample.

Remarks

This function is useful for switching a sample between ARGB32 and PMARGB32 pixel formats.

See Also

DXPMSAMPLE, DXSAMPLE

DXSampleFromColorRef

Converts a COLORREF value to a DXSAMPLE structure format.

Syntax

DWORD DXSampleFromColorRef(
    COLORREF cr
);

Parameters

cr
[in] COLORREF value for conversion.

Return Value

Returns a converted color value stored in a DXSAMPLE structure.

Remarks

A COLORREF is a standard Windows 32-bit color value. See the Platform SDK documentation for more information.

DXUnPreMultArray

Converts an array of DXPMSAMPLE colors to DXSAMPLE format.

Syntax

DXSAMPLE *DXUnPreMultArray(
	DXPMSAMPLE *pBuffer,
	ULONG cSamples
);

Parameters

pBuffer
[in] Pointer to a source array of DXPMSAMPLE structures.
cSamples
[in] Number of samples to convert.

Return Value

Returns a pointer to an array of converted samples.

DXUnPreMultSample

Converts a DXPMSAMPLE color to DXSAMPLE format.

Syntax

DXSAMPLE DXUnPreMultSample(
	const DXPMSAMPLE &Src
);

Parameters

Src
[in] DXPMSAMPLE color value.

Return Value

Returns a converted DXSAMPLE value.

Remarks

This function is useful for switching a sample between ARGB32 and PMARGB32 pixel formats.

See Also

DXPreMultSample

DXWeightedAverage

Produces a weighted average of two samples.

Syntax

DWORD DXWeightedAverage(
	DXBASESAMPLE S1,
	DXBASESAMPLE S2,
	ULONG Wgt 
);

Parameters

S1
[in] First sample to be scaled.
S2
[in] Second sample to be scaled.
Wgt
[in] ULONG value from 0 to 255 to be used as a weighting for S1.

Return Value

Returns a color value that is a mixture of the two source samples.

Remarks

This function combines two samples, where S1 is weighted by Wgt, and S2 is weighted by the inverse of Wgt. The weight should be a value ranging from 0 to 255. If the Wgt is equal to the alpha value of S1, this operation is equivalent to an alpha blend of S1 over S2.

For example, assume that the RGB format color of S1 is 0xFF0000 (red) and S2 is 0x00FF00 (green). If Wgt is 192 (0xC0), the resulting color is 0xC03F00 (dark orange). Notice that the resulting sample is mostly red because the weighting is large, but that there is some green.

DXWeightedAverageArray

Produces a weighted average of two arrays of samples.

Syntax

void DXWeightedAverageArray(
	DXBASESAMPLE *pS1,
	DXBASESAMPLE *pS2,
	ULONG Wgt,
	DXBASESAMPLE *pResults,
	DWORD dwCount 
);

Parameters

pS1
[in] Pointer to the first array of samples.
pS2
[in] Pointer to the second array of samples.
Wgt
[in] ULONG value from 0 to 255 to be used as a weighting for pS1.
pResults
[in] Pointer to the resulting array.
dwCount
[in] Number of samples to convert.

Return Value

No return value.

Remarks

This function combines two arrays of samples, where pS1 is weighted by Wgt, and pS2 is weighted by (255-Wgt).

Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.