IDirectDrawSurface5::Blt

  • Article

This method performs a bit block transfer. This method does not support Z-buffering or alpha blending (see alpha channel) during blit operations.

HRESULT Blt(
  LPRECT lpDestRect, 
  LPDIRECTDRAWSURFACE4 lpDDSrcSurface, 
  LPRECT lpSrcRect, 
  DWORD dwFlags, 
  LPDDBLTFX lpDDBltFx
);

Parameters

  • lpDestRect
    Address of a RECT structure that defines the upper-left and lower-right points of the rectangle to blit to on the destination surface. If this parameter is NULL, the entire destination surface will be used.

  • lpDDSrcSurface
    Address of an IDirectDrawSurface5 interface for the DirectDrawSurface object that is the source of the blit.

  • lpSrcRect
    Address of a RECT structure that defines the upper-left and lower-right points of the rectangle to blit from on the source surface. If this parameter is NULL, the entire source surface will be used.

  • dwFlags
    A combination of flags that determine the valid members of the associated DDBLTFX structure, specify color key information, or that request special behavior from the method.

    The following table shows the possible validation flags.

    Flag Description
    DDBLT_COLORFILL Uses the dwFillColor member of the DDBLTFX structure as the RGB color that fills the destination rectangle on the destination surface.
    DDBLT_DDFX Uses the dwDDFX member of the DDBLTFX structure to specify the effects to use for this blit.
    DDBLT_DDROPS Uses the dwDDROP member of the DDBLTFX structure to specify the raster operations (ROPS) that are not part of the Microsoft® Win32® API.
    DDBLT_DEPTHFILL Uses the dwFillDepth member of the DDBLTFX structure as the depth value with which to fill the destination rectangle on the destination Z-buffer surface.
    DDBLT_KEYDESTOVERRIDE Uses the ddckDestColorkey member of the DDBLTFX structure as the color key for the destination surface.
    DDBLT_KEYSRCOVERRIDE Uses the ddckSrcColorkey member of the DDBLTFX structure as the color key for the source surface.
    DDBLT_ROP Uses the dwROP member of the DDBLTFX structure for the ROP for this blit. These ROPs are the same as those defined in the Win32 API.
    DDBLT_ROTATIONANGLE Uses the dwRotationAngle member of the DDBLTFX structure as the rotation angle (specified in 1/100th of a degree) for the surface.

    The following table shows the possible color key flags.

    Flag Description
    DDBLT_KEYDEST Uses the color key associated with the destination surface.
    DDBLT_KEYSRC Uses the color key associated with the source surface.

    The following table shows the possible behavior flags.

    Flag Description
    DDBLT_ASYNC Performs this blit asynchronously through the FIFO in the order received. If no room is available in the FIFO hardware, the call fails.
    DDBLT_WAIT Postpones the DDERR_WASSTILLDRAWING return value if the blitter is busy, and returns as soon as the blit can be set up or another error occurs.

    The following table shows the obsolete and unsupported flags.

    Flag Description
    All DDBLT_ALPHA flag values. Not currently implemented.
    All DDBLT_ZBUFFER flag values This method does not currently support Z-aware blit operations. None of the flags beginning with DDBLT_ZBUFFER are supported in this release.

  • lpDDBltFx
    Address of the DDBLTFX structure.

Return Values

If the method succeeds, the return value is DD_OK.

If the method fails, the return value may be one of the following error values:

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Remarks

This method is capable of synchronous or asynchronous blits (the default behavior), either display memory to display memory, display memory to system memory, system memory to display memory, or system memory to system memory. The blits can be performed by using source color keys, and destination color keys. Arbitrary stretching or shrinking will be performed if the source and destination rectangles are not the same size.

Typically, IDirectDrawSurface5::Blt returns immediately with an error if the blitter is busy and the blit could not be set up. Specify the DDBLT_WAIT flag to request a synchronous blit. When you include the DDBLT_WAIT flag, the method waits until the blit can be set up or another error occurs before it returns.

The RECT structures are defined so that the right and bottom members are exclusive: right minus left equals the width of the rectangle, not one less than the width.

Requirements

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.
Header: Ddraw.h.
Link Library: Ddraw.lib.

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.