IDirectDrawSurface::Blt

IDirectDrawSurface::Blt

Switch on low bandwidth view

Collapse All

Language Filter

8/28/2008

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

Syntax


HRESULT Blt(
  LPRECT lpDestRect, 
  LPDIRECTDRAWSURFACE 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 IDirectDrawSurface 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_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.

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_WAITNOTBUSY	Waits for a previously initiated drawing operation to complete instead of returning immediately with the DDERR_WASSTILLDRAWING return value. If a previous drawing operation is in progress at the time of the call, this flag defers returning from the call until the new blit operation begins or an error occurs.
DDBLT_WAITVSYNC	Waits for a V-Sync before performing the blit operation.

Flag

Description

DDBLT_WAITNOTBUSY

Waits for a previously initiated drawing operation to complete instead of returning immediately with the DDERR_WASSTILLDRAWING return value.

If a previous drawing operation is in progress at the time of the call, this flag defers returning from the call until the new blit operation begins or an error occurs.

DDBLT_WAITVSYNC

Waits for a V-Sync before performing the blit operation.

lpDDBltFx: Address of the DDBLTFX structure.

Return Value

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_NORASTEROPHW

DDERR_NOSTRETCHHW

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

For more information on these error codes see DirectDraw Return Values.

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, IDirectDrawSurface::Blt returns immediately with an error if the blitter is busy and the blit could not be set up. Specify the DDBLT_WAITNOTBUSY flag to request a synchronous blit. When you include the DDBLT_WAITNOTBUSY 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

Header	ddraw.h
Library	ddraw.lib
Windows Embedded CE	Windows Embedded CE 6.0 and later
Windows Mobile	Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later