IDXARGBReadPtr Interface
The IDXARGBReadPtr interface enables Microsoft® DirectX® Transform objects to gain read-only access to samples contained in a DXSurface object.
This interface contains methods to move a sample pointer to various locations within a DXSurface and to unpack samples into a common pixel format (either ARGB32 or PMARGB32). Unpacking the samples into a common format means transforms that modify data from DXSurfaces only need to be able to handle these two formats. If the underlying samples in the DXSurface are already ARGB32 or PMARGB32, you can obtain a pointer directly to them by specifying NULL for the working buffer arguments, avoiding the step of copying the samples to the buffer. You can determine the format of the underlying samples by using the GetNativeType method.
Use the IDXSurface::LockSurface method to retrieve a pointer to this interface. For more information on using this interface see the Architecture overview article.
If you create a custom DXSurface, you need to implement this interface on your DXSurface object which is used to access samples within your custom surface. DirectX Transform objects will use this interface to gain access to samples contained in your custom DXSurface.
The coordinates used in all operations for IDXARGBReadPtr and IDXARGBReadWritePtr interfaces are relative to the locked region of the DXSurface. This means, for example, that if you lock a region from (10, 10) to (100, 100) and then call pPtr->MoveToXY(10, 10), the sample pointer will be positioned at the pixel at 20,20 on the surface.
WARNING To achieve fast performance on these methods, no parameter validation occurs before execution. Passing invalid parameters can cause the dynamic-link library (DLL) to crash.
For more information on using this interface, see the About Transforms and DXSurfaces overview article.
IDXARGBReadPtr Methods
GetNativeType Retrieves the native underlying pixel format of a DXSurface. GetSurface Retrieves a pointer to the parent DXSurface. Move Moves the sample pointer along the x-axis relative to its current position. MoveAndGetRunInfo Moves the sample pointer to a specified row and retrieves a pointer to the run information associated with the specified row. MoveToRow Moves the sample pointer to an absolute row along the y-axis and resets the x-axis position to zero. MoveToXY Moves the sample pointer to an absolute position. Unpack Unpacks the specified number of samples into the supplied buffer in ARGB32 pixel format. Can only unpack a single row. Use UnpackRect to unpack multiple rows. UnpackPremult Unpacks the specified number of samples into the supplied buffer in alpha-premultiplied PMARGB32 pixel format. Can only unpack a single row. Use UnpackRect to unpack multiple rows. UnpackRect Unpacks a subsection of source samples defined by a rectangle structure and advances the horizontal position of the read pointer. Use to unpack multiple rows.
IDXARGBReadPtr::GetNativeType
Retrieves the native underlying pixel format of a DXSurface.
Syntax
DXSAMPLEFORMATENUM GetNativeType(
DXNATIVETYPEINFO *pInfo
);
Parameters
- pInfo
- [out] Pointer to a DXNATIVETYPEINFO structure that the method will fill with native type information about the surface. This structure contains the color key, surface pitch, pointers to the samples at the current location, and origin of the surface. This pointer can be NULL, in which case only the DXSAMPLEFORMATENUM enumeration will be returned.
Return Value
Returns a DXSAMPLEFORMATENUM enumerated type, indicating the format of the pixels contained in the surface.
Remarks
This method can be used to directly access the data in the surface. If the calling routine supports the pixel format of the surface, it can use the information in this structure to retrieve or modify data directly in the surface memory. Note that some surfaces, such as procedural surfaces, don't have a backing array of samples, and therefore will always set the entire DXNATIVETYPEINFO structure to zero.
IDXARGBReadPtr::GetSurface
Retrieves a pointer to the parent DXSurface.
Syntax
HRESULT GetSurface(
REFIID riid,
void **ppSurface
);
Parameters
- riid
- [in] Interface to retrieve from the read pointer (typically IID_IDXSurface).
- ppSurface
- [out] Address of a pointer to the requested interface.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
This method is used to get a pointer to the parent surface associated with the specified IDXARGBReadPtr interface. It provides a link between the IDXSurface::LockSurface interface, which exposes the IDXARGBReadPtr and IDXARGBReadWritePtr interfaces, and the DXSurface object, which exposes the IDXSurface interface.
IDXARGBReadPtr::Move
Moves the sample pointer along the x-axis relative to its current position.
Syntax
void Move(
long cSamples
);
Parameters
- cSamples
- [in] Number of samples to move the position along the x-axis.
Return Value
No return value.
Remarks
Specifying a negative value will move the sample pointer backward. Specifying a value larger than the row width may or may not move you to the next row, depending on whether the surface occupies a contiguous block of memory.
See Also
IDXARGBReadPtr::MoveToRow, IDXARGBReadPtr::MoveToXY, IDXARGBReadPtr::MoveAndGetRunInfo
IDXARGBReadPtr::MoveAndGetRunInfo
Moves the sample pointer to a specified row and retrieves a pointer to the run information associated with that row.
Syntax
ULONG MoveAndGetRunInfo(
ULONG Row,
DXRUNINFO **ppInfo
);
Parameters
- Row
- [in] Row to place the sample pointer. The run information will be for this row of samples.
- ppInfo
- [out] Address of a pointer to a DXRUNINFO structure to store the run information.
Return Value
Returns a value indicating the number of DXRUNINFO structures that contain run information.
Remarks
When locking the surface, specify DXLOCKF_WANTRUNINFO to ensure that run information is generated.
The count returned specifies the number of DXRUNINFO structures returned by the call. Each DXRUNINFO structure contains a count of pixels and a type. The sum of all of the counts will equal the width of the locked region. Typically, users of this feature will get the run information and then read the source pixels, performing different operations for each run type. This is useful for skipping clear pixels, copying opaque pixels, and blending translucent or unknown pixels.
The returned data is only valid for as long as the sample pointer is on the specified row. After the sample pointer has been moved to a different row by using the MoveToXY, MoveToRow, or MoveAndGetRunInfo method, the pointer returned by this method should not be used because the underlying surface could reuse a temporary buffer to construct new run information.
All surface implementations are required to support this method. The simplest implementations will only return a count of one DXRUNINFO structure. That structure will be of type DXRUNTYPE_UNKNOWN with a count equal to the width of the locked region. This method will work even if the caller did not specify DXLOCKF_WANTRUNINFO when the surface was locked.
If a DXSurface object is marked as transient (its surface status flags specify DXSURF_TRANSIENT), then the surface will not create detailed run information and will always return a single DXRUNTYPE_UNKNOWN run with a count equal to the width of the entire row.
Run information describes a series of identical pixels. Pixel information stored in a run can improve the efficiency of transform operations.
Pixel runs are described by the DXRUNINFO structure, and include a Count of the identical samples and the Type. The run type can be one of the following elements of the DXRUNTYPE enumeration.
DXRUNTYPE_CLEAR Run is zero alpha (clear). DXRUNTYPE_OPAQUE Run is full alpha (255) and fully opaque. DXRUNTYPE_TRANS Run is nonzero alpha and partially transparent. DXRUNTYPE_UNKNOWN Run type is unknown. DXRUNTYPE_CLEAR and DXRUNTYPE_OPAQUE are always completely contiguous runs of clear or opaque pixels. In the case of a copy operation, the caller would skip the clear pixels and copy the opaque pixels.
DXRUNTYPE_TRANS can contain pixels that are translucent. These runs can benefit from the use of MMX instructions since most pixels will need to be blended if doing an over operation. Use DXOverArrayMMX if doing an over operation with a translucent run.
DXRUNTYPE_UNKNOWN means that the pixels for the specified run could be of any type, clear, translucent, or opaque. The caller should examine each pixel's alpha to determine what operation to perform. Typically, if doing an over operation, it is faster to use DXOverArray instead of the MMX version because clear and opaque pixels are special-cased in this function.
IDXARGBReadPtr::MoveToRow
Moves the sample pointer to an absolute row along the y-axis and resets the x-axis position to zero.
Syntax
void MoveToRow(
ULONG y
);
Parameters
- y
- [in] Row to move to along the y-axis.
Return Value
No return value.
See Also
IDXARGBReadPtr::MoveToXY
Moves the sample pointer to an absolute position.
Syntax
void MoveToXY(
ULONG x,
ULONG y
);
Parameters
- x
- [in] Position along the x-axis.
- y
- [in] Position along the y-axis.
Return Value
No return value.
See Also
IDXARGBReadPtr::Unpack
Unpacks the specified number of samples into the supplied buffer in ARGB32 pixel format. Can only unpack a single row. Use UnpackRect to unpack multiple rows.
Syntax
DXSAMPLE *Unpack(
DXSAMPLE *pSamples,
ULONG cSamples,
BOOL bMove
);
Parameters
- pSamples
- [in] Pointer to a buffer to store the samples. If the surface's native type is ARGB32, then this pointer can be NULL. Otherwise, it must point to a buffer large enough to hold the samples.
- cSamples
- [in] Number of samples to get.
- bMove
- [in] Value indicating whether to advance the read pointer. Specify TRUE to advance the current horizontal position. Specify FALSE to leave the pointer set to the current location.
Return Value
Returns a pointer to a buffer containing the unpacked, converted samples. If pSamples was non-NULL, the return value will always be equal to pSamples. If pSamples was NULL, then the returned pointer points directly to the ARGB samples in the surface memory.
Remarks
This method converts the pixel format of the underlying surface into ARGB32 format in the process of extracting the surface samples into a buffer. If the underlying data is in an alpha-premultiplied format, the method will convert the data to ARGB32 as it is being copied.
If the caller supplies a pointer to a buffer in the pSamples parameter, the samples will be stored in that location, and this method will return a pointer to the user's buffer. If the underlying samples are already ARGB32, the user can obtain a pointer directly to the samples by specifying NULL for the pSamples parameter. In this case, the returned pointer will point directly at the surface memory. This avoids the step of copying the samples to the buffer, which speeds up the operation.
This method uses the DXSAMPLE structure to store color information about the samples.
WARNING: You should never use the returned pointer to modify a read-only surface. A good coding practice for read-locked surfaces is to assign the returned pointer to a constant DXSAMPLE pointer.
See Also
IDXARGBReadPtr::UnpackPremult
Unpacks the specified number of samples into the supplied buffer in alpha-premultiplied PMARGB32 pixel format. Can only unpack a single row. Use UnpackRect to unpack multiple rows.
Syntax
DXPMSAMPLE *UnpackPremult(
DXPMSAMPLE *pSamples,
ULONG cSamples,
BOOL bMove
);
Parameters
- pSamples
- [in] Pointer to buffer you must supply to store the samples. If the surface's native type is PMARGB32 (alpha-premultiplied), this pointer can be NULL. Otherwise it must point to a buffer large enough to hold the samples.
- cSamples
- [in] Number of samples to get.
- bMove
- [in] Value specifying whether to advance the current horizontal position of the read pointer. Specify TRUE to advance or FALSE to leave the pointer set to the current location.
Return Value
Returns a pointer to a buffer containing the unpacked, converted sample data. If pSamples was non-NULL then this will always be equal to pSamples. If pSamples was NULL, then the returned pointer points directly at the samples in the surface memory.
Remarks
This method converts the pixel format of the underlying surface samples into PMARGB32 format before copying them into the buffer that you must supply. If the underlying data is not in alpha-premultiplied format, the samples are converted as they are being copied.
If you supply a buffer in the pSamples parameter, the samples will be stored in that location, and this method will return a pointer to your buffer.
This method uses the DXPMSAMPLE structure to store color information about the samples.
WARNING: You should never use the returned pointer to modify a read-only surface. A good coding practice for read-locked surfaces is to assign the returned pointer to a constant DXSAMPLE pointer.
See Also
IDXARGBReadPtr::UnpackRect
Unpacks a subsection of source samples defined by a rectangle structure and advances the horizontal position of the read pointer. Use to unpack multiple rows.
Syntax
void UnpackRect(
const DXPACKEDRECTDESC *pRectDesc
);
Parameters
- pRectDesc
- [in] Pointer to a DXPACKEDRECTDESC structure to be used in unpacking the rectangular region of samples.
Return Value
No return value.
Remarks
This method can be used to unpack single columns or rectangular regions of a surface into contiguous samples. It also can unpack them row-by-row into equally spaced, noncontiguous regions by setting the lRowPadding member of DXPACKEDRECTDESC to a nonzero value.
The size of the buffer required is ((Width + lRowPadding) * (Height - 1)) + Width. If lRowPadding is zero, then this is equivalent to Width*Height.
UnpackRect starts with the sample at the upper-left corner of the rectangle and unpacks samples into the buffer until reaching the end of the row. It then adds lRowPadding samples to the buffer pointer and unpacks the next row.
After this call has been made, the current position of the pointer object is undefined. You will need to call MoveToRow, MoveAndGetRunInfo, or MoveToXY to re-establish the pointer location before calling Unpack or UnpackPremult.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.