IDXARGBReadWritePtr Interface

The IDXARGBReadWritePtr interface enables Microsoft® DirectX® Transform objects to gain read/write access to samples contained in a DXSurface object. This interface contains methods that select various locations within a DXSurface and pack ARGB32 or PMARGB32 transformed samples into the native, underlying format of the output surface. A pointer to this interface is returned when you use the IDXSurface::LockSurface method with the DXLOCKF_READWRITE flag set.

This interface inherits from IDXARGBReadPtr interface.

For more information on using this interface, see Applying Transforms through DXSurfaces.

If you create a custom DXSurface, you need to implement this interface on your object, which is used to access samples within your custom surface.

WARNING In order to achieve fast performance on these methods, no parameter validation is done before execution. Passing invalid parameters to any of these methods might cause the .dll to crash.

IDXARGBWriteReadPtr Methods

CopyAndMoveBoth Copies the specified number of samples from the current position of the source surface to the current position of the output surface.

CopyRect Copies the specified number of samples from the specified rectangle in the source surface to the current position on the output surface.

FillAndMove Fills the output surface with the specified sample value starting at the current position and advances the current position.

FillRect Fills the specified rectangle with the specified sample value, optionally doing an alpha blend with the destination.

OverArrayAndMove Alpha blends an array of samples over the output surface and moves the pointer a specified number of samples.

OverSample Alpha blends the specified sample value over the sample at the specified position.

PackAndMove Places a buffer of ARGB32 samples into the output surfaces and moves the sample pointer.

PackPremultAndMove Places a buffer of PMARGB32 samples into the output surfaces and moves the sample pointer.

PackRect Accepts a buffer of either PMARGB32 or ARGB32 samples and writes them to a subsection of the output surface defined by a DXPACKEDRECTDESC structure.

IDXARGBReadWritePtr::CopyAndMoveBoth

IDXARGBReadWritePtr Interface

Copies the specified number of samples from the current position of the source surface to the current position of the output surface.

Syntax

void CopyAndMoveBoth(
    DXBASESAMPLE *pScratchBuffer,
    IDXARGBReadPtr *pSrc,
    ULONG cSamples,
    BOOL bIsOpaque
);

Parameters

pScratchBuffer
[in] Pointer to a buffer that may be used by the method. The initial contents of the buffer are ignored, and when the call returns the buffer contents are undefined. The buffer must be at least [cSamples * sizeof(DXBASESAMPLE)] bytes in size. If the surface pixel format is either ARGB32 or PMARGB32, this buffer is not required and pScratchBuffer can be NULL.

pSrc
[in] Source surface read pointer to copy from.

cSamples
[in] Number of samples to copy.

bIsOpaque
[in] Value specifying whether the samples are opaque or transparent. If TRUE, the caller guarantees that all of the samples being copied have an alpha channel value of 255. In some cases this can enable faster code performance. If you are not sure that all samples are opaque, specify FALSE.

Return Value

No return value.

Remarks

After a call to this method, the positions of both the source and destination surfaces are advanced by cSamples.

See Also

IDXARGBReadWritePtr::CopyRect, DXBASESAMPLE

IDXARGBReadWritePtr::CopyRect

IDXARGBReadWritePtr Interface

Copies the specified number of samples from the specified rectangle in the source surface to the current position on the output surface.

Syntax

void CopyRect(
    DXBASESAMPLE *pScratchBuffer,
    const RECT *pDestRect,
    IDXARGBReadPtr *pSrc,
    const POINT *pSrcOrigin,
    BOOL bIsOpaque
);

Parameters

pScratchBuffer
[in] Pointer to a buffer that may be used by the method. The initial contents of the buffer are ignored, and when the call returns the buffer contents are undefined. The buffer must be at least [ (pDestRect.right - pDestRect.left) * sizeof(DXBASESAMPLE) ] bytes in size. If the surface pixel format is either ARGB32 or PMARGB32, this buffer is not required and pScratchBuffer can be NULL.
pDestRect
[in] Pointer to the region, relative to the locked region in the output surface, to copy to. If this parameter is NULL, the entire locked region is used.

pSrc
[in] Source surface read pointer to copy from.

pSrcOrigin
[in] Pointer to the point at which the copy starts, relative to the locked source region. If this parameter is NULL, the point (0,0) relative to the locked source region is used.

bIsOpaque
[in] Value specifying whether the samples are opaque or transparent. If TRUE, the caller is guaranteeing that all of the samples being copied have an alpha channel value of 255. In some cases this can enable faster code performance. If you are not sure that all samples are opaque, specify FALSE.

Return Value

No return value.

Remarks

After this call has been made, the current positions of both pointer objects are undefined. You will need to call MoveToRow, MoveAndGetRunInfo, or MoveToXY to re-establish the pointer location before calling any of the following methods: Unpack, UnpackPremult, CopyAndMoveBoth, FillAndMove, PackAndMove, PackPremultAndMove, or OverArrayAndMove.

See Also

IDXARGBReadWritePtr::CopyAndMoveBoth

IDXARGBReadWritePtr::FillAndMove

IDXARGBReadWritePtr Interface

Fills the output surface with the specified sample value, starting at the current position and advancing the current position.

Syntax

void FillAndMove(
    DXBASESAMPLE *pScratchBuffer,
    DXPMSAMPLE SampVal,
    ULONG cSamples,
    BOOL bDoOver
);

Parameters

pScratchBuffer
[in] Pointer to a buffer that may be used by the method. The initial contents of the buffer are ignored, and when the call returns the buffer contents are undefined. The buffer must be at least [ cSamples*sizeof(DXBASESAMPLE) ] bytes in size. If the surface pixel format is either ARGB32 or PMARGB32, this buffer is not required and pScratchBuffer can be NULL.

SampVal
[in] Alpha-premultiplied color to use for the fill.

cSamples
[in] Number of samples to fill.

bDoOver
[in] Value indicating whether to alpha blend the samples with the existing data or to replace the existing data. If TRUE, the samples are alpha-blended over the current data. If FALSE, the samples replace the current data.

Return Value

No return values

Remarks

This method moves the current position of the pointer object forward along the x-axis by cSamples.

See Also

IDXARGBReadWritePtr::FillRect

IDXARGBReadWritePtr::FillRect

IDXARGBReadWritePtr Interface

Fills the specified rectangle with the specified sample value, optionally doing an alpha blend with the destination.

Syntax

void FillRect(
    const RECT *pRect,
    DXPMSAMPLE SampVal,
    BOOL bDoOver
);

Parameters

pRect
[in] Pointer to the rectangle to fill. If NULL, the whole surface is filled.

SampVal
[in] Alpha-premultiplied color to use for the fill.

bDoOver
[in] Value indicating whether to alpha blend the sample with the existing data or to replace the existing data. If TRUE, the samples are alpha-blended over the current data. If FALSE, the samples replace the current data.

Return Value

No return value.

Remarks

After this call has been made, the current position of the pointer object is undefined. Call MoveToRow, MoveAndGetRunInfo, or MoveToXY to re-establish the pointer location before calling any method that uses the current pointer location.

See Also

IDXARGBReadWrite::FillAndMove, IDXARGBReadPtr::MoveToRow, IDXARGBReadPtr::MoveToXY, IDXARGBReadPtr::MoveAndGetRunInfo

IDXARGBReadWritePtr::OverArrayAndMove

IDXARGBReadWritePtr Interface

Alpha blends an array of samples over the output surface and moves the pointer a specified number of samples.

Syntax

void OverArrayAndMove(
	DXBASESAMPLE *pScratchBuffer,
	const DXPMSAMPLE *pSrc,
	ULONG cSamples
);

Parameters

pScratchBuffer
[in] Pointer to a buffer that can be used by the method. The initial contents of the buffer are ignored, and when the call returns the buffer contents are undefined. The buffer must be at least [ cSamples*sizeof(DXBASESAMPLE) ] bytes in size. If the surface pixel format is either ARGB32 or PMARGB32 this buffer is not required and pScratchBuffer can be NULL.

pSrc
[in] Pointer to an array of DXPMSAMPLE structures that describe the source samples.

cSamples
[in] Number of samples in the arrays.

Return Value

No return value.

Remarks

After a call to this method, the position of the sample pointer is advanced by cSamples.
If you know that the majority of the source samples are translucent, and you are going to blend more than 16 samples, it can be more efficient to do the following: unpack the destination samples, call the DXOverArrayMMX helper function, and then pack the resulting buffer. For PMARGB32 DXSurfaces, the unpack/pack step would not be necessary.

IDXARGBReadWritePtr::OverSample

IDXARGBReadWritePtr Interface

Alpha blends the specified sample value over the sample at the specified position.

Syntax

void OverSample(
    const DXOVERSAMPLEDESC *pOverDesc
);

Parameters

pOverDesc
[in] Pointer to a DXOVERSAMPLEDESC structure holding the position and color of the specified sample on the destination surface.

Return Value

No return value.

Remarks

This method does not modify the current position of the pointer object.
DXSurface implementations are optimized for opaque colors (alpha = 255). In these cases, this operation is identical to a sample replacement and no blending is done.

IDXARGBReadWritePtr::PackAndMove

IDXARGBReadWritePtr Interface

Places a buffer of ARGB32 samples into the output surface and moves the sample pointer.

Syntax

void PackAndMove(
    const DXSAMPLE *pSamples,
    ULONG cSamples
);

Parameters

pSamples
[in] Pointer to the sample values to pack into the destination surface. If the surface pixel format is ARGB32, the pointer can be NULL, in which case no data copy is performed, but the current pointer location is still updated.

cSamples
[in] Number of samples to convert.

Return Value

No return value.

Remarks

This method will advance the current horizontal position of the pointer to the samples by cSamples amount. If the pixel format of the underlying surface is not ARGB32, this method will convert the samples into the underlying native pixel format.

See Also

IDXARGBReadWritePtr::PackPremultAndMove, IDXARGBReadWritePtr::PackRect

IDXARGBReadWritePtr::PackPremultAndMove

IDXARGBReadWritePtr Interface

Places a buffer of ARGB32 samples into the output surfaces and moves the sample pointer.

Syntax

void PackPremultAndMove(
    const DXPMSAMPLE *pSamples,
    ULONG cSamples
);

Parameters

pSamples
[in] Pointer to the sample values to pack into the destination surface. If the surface pixel format is PMARGB32, the pointer can be NULL, in which case no data copy is performed, but the current pointer location is still updated.

cSamples
[in] Number of samples to convert.

Return Value

No return value.

Remarks

This method will advance the current horizontal position of the pointer to the samples by cSamples amount. If the pixel format of the underlying surface is not PMARGB32, this method will convert the samples into the underlying native pixel format.

See Also

IDXARGBReadWritePtr::PackAndMove, IDXARGBReadWritePtr::PackRect

IDXARGBReadWritePtr::PackRect

IDXARGBReadWritePtr Interface

Accepts a buffer of either PMARGB32 or ARGB32 samples and writes them to a subsection of the output surface defined by a DXPACKEDRECTDESC structure.

Syntax

void PackRect(
    const DXPACKEDRECTDESC *pRectDesc
);

Parameters

pRectDesc
[in] Pointer to a DXPACKEDRECTDESC structure containing sample information to write to the output surface.

Return Value

No return value.

Remarks

This method can be used to pack single columns or rectangular regions of a surface from a buffer of contiguous samples. It can pack them row by row into equally spaced, noncontiguous regions by setting the lRowPadding member of DXPACKEDRECTDESC to nonzero.
The size of the buffer required is [ (Width+lRowPadding) * (Height - 1)) + Width ]. If lRowPadding is zero, this is equivalent to Width*Height.
The packing begins with the sample at the upper-left corner of the rectangle and packs samples from the buffer into the surface until reaching the end of the row. It then adds lRowPadding samples to the buffer pointer and packs the next row.
After this call has been made, the current position of the pointer object is undefined. Call MoveToRow, MoveAndGetRunInfo, or MoveToXY to re-establish the pointer location before calling any method that uses the current pointer location.

See Also

IDXARGBReadWritePtr::PackAndMove, IDXARGBReadWritePtr::PackPremultAndMove, DXPACKEDRECTDESC, IDXARGBReadPtr::MoveToRow, IDXARGBReadPtr::MoveToXY, IDXARGBReadPtr::MoveAndGetRunInfo

CopyAndMoveBoth	Copies the specified number of samples from the current position of the source surface to the current position of the output surface.
CopyRect	Copies the specified number of samples from the specified rectangle in the source surface to the current position on the output surface.
FillAndMove	Fills the output surface with the specified sample value starting at the current position and advances the current position.
FillRect	Fills the specified rectangle with the specified sample value, optionally doing an alpha blend with the destination.
OverArrayAndMove	Alpha blends an array of samples over the output surface and moves the pointer a specified number of samples.
OverSample	Alpha blends the specified sample value over the sample at the specified position.
PackAndMove	Places a buffer of ARGB32 samples into the output surfaces and moves the sample pointer.
PackPremultAndMove	Places a buffer of PMARGB32 samples into the output surfaces and moves the sample pointer.
PackRect	Accepts a buffer of either PMARGB32 or ARGB32 samples and writes them to a subsection of the output surface defined by a DXPACKEDRECTDESC structure.