Compositing Helper Functions

Compositing is a way of combining two samples using their color components weighted by their alpha values. The helper functions in this section perform compositing-over operations on individual samples or an array of samples. This section also describes functions for filling DXSurface objects, which you can use to initialize a surface with a default color.

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

Compositing Functions

DXBitBlt Copies a region of a DXSurface to a second DXSurface.

DXCompositeOver Composites an alpha-premultiplied source sample over a destination sample.

DXCompositeUnder Composites an alpha-premultiplied source sample under a destination sample.

DXConstOverArray Composites a single color over an array of samples.

DXConstUnderArray Composites a single color under an array of samples.

DXFillSurface Fills an entire DXSurface with a color.

DXFillSurfaceRect Fills a region of a surface with a specified color.

DXOverArray Composites an array of source samples over an array of destination samples.

DXOverArrayMMX Composites an array of source samples over an array of destination samples, using the MMX instruction set for large arrays of samples.

DXSrcCopy Copies a region of a source surface to a destination surface.

DXWeightedAverageArrayOver Takes a weighted average of two sample arrays and composites the result over a third.

DXBitBlt

Copies a region of a DXSurface to a second DXSurface.

Syntax

HRESULT DXBitBlt(
	IDXSurface *pDest,
	const CDXDBnds &DestBnds,
	IDXSurface *pSrc,
	const CDXDBnds &SrcBnds,
	DWORD dwFlags,
	ULONG ulTimeout
);

Parameters

pDest
[in] Pointer to the destination DXSurface.

DestBnds
[in] Bounds of the destination region.

pSrc
[in] Pointer to the source DXSurface.

SrcBnds
[in] Bounds of the destination region.

dwFlags
[in] One of the DXBLTOPTIONS used to specify what type of blit operation to perform.

ulTimeout
[in] Time in milliseconds to allow for each surface lock before returning.

Return Value

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

Remarks

This helper function performs a fast blitting operation with no error checking or parameter validation. Using DXBitBlt also requires that you call the IDXSurface::LockSurface method on any of the surfaces you are using prior to blitting. If your transform or application is only doing a single blit, it is much safer to use the IDXSurfaceFactory::BitBlt method.
Because this is a helper function and not a method on a COM interface, applications that use DXBitBlt need to link with Dxtrans.lib.

See Also

IDXSurfaceFactory::BitBlt, IDXSurface::LockSurface

DXCompositeOver

Composites an alpha-premultiplied source sample over a destination sample.

Syntax

void DXCompositeOver(
	DXPMSAMPLE &Dst,
	const DXPMSAMPLE &Src
);

Parameters

Dst
[in, out] Sample that lies under the source sample. When the function returns, this parameter holds the return value.

Src
[in] Sample to be composited over the destination.

Return Value

No return value.

Remarks

A composite over operation uses the alpha value of the source sample to combine the colors. To obtain the result, the source is scaled by alpha, the destination is scaled by the inverse of alpha, and the two values are added.

DXCompositeUnder

Composites an alpha-premultiplied source sample under a destination sample.

Syntax

DXPMSAMPLE DXCompositeUnder(
	DXPMSAMPLE Dst,
	DXPMSAMPLE Src 
);

Parameters

Dst
[in] Sample that lies over the source sample

Src
[in] Sample to be composited under the destination.

Return Value

Returns a DXPMSAMPLE structure value resulting from the composite operation.

Remarks

A composite under operation uses the alpha value of the destination sample to combine the colors. To obtain the result, the destination is scaled by alpha, the source is scaled by the inverse of alpha, and the two values are added.

DXConstOverArray

Composites a single color over an array of samples.

Syntax

void DXConstOverArray(
	DXPMSAMPLE *pDest,
	const DXPMSAMPLE &val,
	ULONG nCount
);

Parameters

pDest
[in] Pointer to the samples that will be modified by compositing the color val over the pDest samples.

val
[in] Color value to composite over the array samples.

nCount
[in] Number of samples in the array.

Return Value

No return value.

Remarks

This a version of the DXCompositeOver function that operates on an array of samples.

DXConstUnderArray

Composites a single color under an array of samples.

Syntax

void DXConstUnderArray(
	DXPMSAMPLE *pDest,
	const DXPMSAMPLE &val,
	ULONG nCount
);

Parameters

pDest
[in] Pointer to the samples that will be modified by compositing the color val under the pDest samples.

val
[in] Color value to composite under the array samples.

nCount
[in] Number of samples in the array.

Return Value

No return value.

Remarks

This a version of the DXCompositeUnder function that operates on an array of samples.

DXFillSurface

Fills an entire DXSurface with a color.

Syntax

HRESULT DXFillSurface(
	IDXSurface *pSurface,
	DXPMSAMPLE Color,
	BOOL bDoOver = FALSE,
	ULONG ulTimeOut = 10000 
);

Parameters

pSurface
[in] Pointer to the DXSurface to fill.

Color
[in] Color to use for filling.

bDoOver
[in] Boolean value indicating whether the fill should blend the fill color with the surface image. The default value is FALSE.

ulTimeOut
[in] Time, in milliseconds, to wait for a surface lock. The default value is 10 seconds.

Return Value

Returns S_OK for a successful fill operation, or another HRESULT for an error condition.

Remarks

You can use this function to initialize or quickly erase existing surfaces.

DXFillSurfaceRect

Fills a region of a surface with a specified color.

Syntax

HRESULT DXFillSurfaceRect(
	IDXSurface *pSurface,
	RECT &rect,
	DXPMSAMPLE Color,
	BOOL bDoOver = FALSE,
	ULONG ulTimeOut = 10000 
);

Parameters

pSurface
[in] Pointer to the DXSurface to fill.

rect
[in] Rectangular region on the DXSurface to fill.

Color
[in] Color to use for filling.

bDoOver
[in] Boolean value indicating whether the fill should blend the fill color with the surface image. The default value is FALSE.

ulTimeOut
[in] Time in milliseconds to wait for a surface lock. The default value is 10 seconds.

Return Value

Returns S_OK for a successful fill operation, or another HRESULT for an error condition.

DXOverArray

Composites an array of source samples over an array of destination samples.

Syntax

void DXOverArray(
	DXPMSAMPLE *pDest,
	const DXPMSAMPLE *pSrc,
	ULONG nCount
);

Parameters

pDest
[in] Pointer to the samples that will be modified by compositing the pSrc samples over the pDest samples.

pSrc
[in] Pointer to the array of samples to composite over the destination.

nCount
[in] Number of samples in the array.

Return Value

No return value.

See Also

DXCompositeOver

DXOverArrayMMX

Composites an array of source samples over an array of destination samples, using the MMX instruction set for large arrays of samples.

Syntax

void DXOverArrayMMX(
	DXPMSAMPLE *pDest,
	const DXPMSAMPLE *pSrc,
	ULONG nCount
);

Parameters

pDest
[in] Pointer to the samples that will be modified by compositing the pSrc samples over the pDest samples.

pSrc
[in] Pointer to the array of samples to composite over the destination.

nCount
[in] Number of samples in the array.

Return Value

No return value.

Remarks

If the processor does not support MMX you can still call this function, which will perform the same operation but not as quickly.
Note that it is less efficient to use this function if the majority of the samples in the pSrc buffer are clear (alpha = 0) or opaque (alpha = 255). This is because the MMX code must process every sample and cannot skip the clear or opaque samples. If there are many translucent samples, then this function is much more efficient than DXOverArray.

See Also

DXCompositeOver, DXOverArray

DXSrcCopy

Copies a region of a source surface to a destination surface.

Syntax

HRESULT DXSrcCopy(
	HDC hdcDest,
	int nXDest,
	int nYDest,
	int nWidth,
	int nHeight, 
	IDXSurface *pSrcSurface,
	int nXSrc,
	int nYSrc
);

Parameters

hdcDest
[in] Handle to the destination device context.

nXDest
[in] The x-axis position of the destination image.

nYDest
[in] The y-axis position of the destination image.

nWidth
[in] Width of the source image region to copy.

nHeight
[in] Height of the source image region to copy.

pSrcSurface
[in] Pointer to the source DXSurface.

nXSrc
[in] The x-axis position of the region to copy in the source image.

nYSrc
[in] The y-axis position of the region to copy in the source image.

Return Value

Returns S_OK if successful, or another HRESULT for an error condition.

DXWeightedAverageArrayOver

Takes a weighted average of two sample arrays and composites the result over a third.

Syntax

void DXWeightedAverageArrayOver(
	DXPMSAMPLE *pS1,
	DXPMSAMPLE *pS2,
	ULONG Wgt,
	DXPMSAMPLE *pResults,
	DWORD dwCount 
);

Parameters

pS1
[in] Pointer to the first array of samples for the weighted average.

pS2
[in] Pointer to the second array of samples for the weighted average.

Wgt
[in] Number from 0 to 255 that is the weighting for the pS1 samples.

pResults
[in, out] On input, this is a pointer to the third array of samples. The weighted average of the other two arrays is composited over this third array. On output, it contains the pointer to the resulting samples.

dwCount
[in] Number of samples to process.

Return Value

No return value.

See Also

DXCompositeOver, DXWeightedAverage