Unpack method

  • Article

Unpacks the specified number of samples into the supplied buffer in ARGB32 pixel format. This method can only unpack a single row. Use IDXARGBReadPtr::UnpackRect to unpack multiple rows.

Syntax

DXSAMPLE retVal = object.Unpack(pSamples, cSamples, bMove);

Parameters

  • pSamples [in]
    Type: DXSAMPLE

    Pointer to a buffer to store the samples. If the native type of the surface is ARGB32, this pointer can be NULL. Otherwise, it must point to a buffer large enough to hold the samples.

  • cSamples [in]
    Type: unsigned long

    Number of samples to retrieve.

  • bMove [in]
    Type: BOOL

    Value that indicates whether to advance the read pointer. Specify TRUE to advance the horizontal position. Specify FALSE to leave the pointer set to the current location.

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 converts the data to ARGB32 as it is being copied.

If you supply a pointer to a buffer in the pSamples parameter, the samples are stored in that location, and this method returns a pointer to your buffer. If the underlying samples are already in ARGB32 format, the user can obtain a pointer directly to the samples by specifying NULL for the pSamples parameter. In this case, the returned pointer points 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.

Note   Do not use the returned pointer to modify a read-only surface. Good coding practice for read-locked surfaces is to assign the returned pointer to a constant DXSAMPLE pointer.

 

See also

Reference

IDXARGBReadPtr::UnpackPremult

IDXARGBReadPtr::UnpackRect