BitBlt method

  • Article

Copies samples from one DXSurface to another.

Syntax

HRESULT retVal = object.BitBlt(pDest, pPlacement, pSrc, pClipBounds, dwFlags);

Parameters

  • pDest [in]
    Type: IDXSurface

    Pointer to the destination DXSurface.

  • pPlacement [in]
    Type: const DXVEC

    Pointer to a DXVEC structure that corresponds to the displaced position of the source surface on the destination surface. If this parameter is NULL, the data is placed at the origin of the destination surface.

  • pSrc [in]
    Type: IDXSurface

    Pointer to the source DXSurface.

  • pClipBounds [in]
    Type: const DXBNDS

    Pointer to a DXBNDS structure that corresponds to the portion of the source surface to copy to the destination. If this parameter is NULL, the entire source surface is copied.

  • dwFlags [in]
    Type: DWORD

    One of the DXBLTOPTIONS used to specify what type of blit operation to perform.

Remarks

This method performs all necessary clipping for the specified placement or clipping bounds. If no data is transferred—that is, the clipping results in an empty region—the call returns S_FALSE.

DXBOF_DO_OVER and DXBOF_DITHER are the two valid flags for this method. These flags can be used independently or in combination. If no flags are specified, the data is simply copied from the source to the destination. If the DXBOF_DO_OVER is set, the source data is blended with the destination data by alpha blending. If DXBOF_DITHER is set and the destination's pixel format has fewer bits per pixel of color information than the source, the data is dithered before being copied to or blended with the destination.

The DXBitBlt helper function provided in Dxhelper.h does a faster blit operation than IDXSurfaceFactory::BitBlt, but with no clipping, parameter validation, or error checking.

Coordinates for both clipping and displacement are relative to the upper-left corner of the surfaces.

See also

DXBLTOPTIONS