MoveAndGetRunInfo method

  • Article

Moves the sample pointer to a specified row and retrieves a pointer to the run information associated with that row.

Syntax

unsigned long retVal = object.MoveAndGetRunInfo(Row, ppInfo);

Parameters

  • Row [in]
    Type: unsigned long

    Row in which to place the sample pointer. The run information will be for this row of samples.

  • ppInfo [out]
    Type: DXRUNINFO

    Address of a pointer to a DXRUNINFO structure to store the 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 the counts is equal to the width of the locked region. Typically, you receive 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 IDXARGBReadPtr::MoveToXY, IDXARGBReadPtr::MoveToRow, or BADFOOD:inet_IDXARGBReadPtr_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 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 does not specify DXLOCKF_WANTRUNINFO when the surface is locked.

If a DXSurface object is marked as transient—its surface status flags specify DXSURF_TRANSIENT—then the surface does not create detailed run information and always returns 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 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 because most pixels must 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 value 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.