IDirectDrawSurface::AlphaBlt

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method blits a rectangular source image to a destination rectangle.

Syntax

HRESULT AlphaBlt( 
  LPRECT lpDestRect, 
  LPDIRECTDRAWSURFACE lpDDSrcSurface, 
  LPRECT lpSrcRect, 
  DWORD dwFlags, 
  LPDDALPHABLTFX lpDDAlphaBltFX
);

Parameters

• lpDestRect
  Pointer to destination rectangle for blit operation.

  This parameter specifies a rectangular region of the destination surface.

  If the rectangle overlaps the boundaries of the destination surface, the driver clips it to the destination surface.

  If a null pointer is specified, the effective destination rectangle is the entire destination surface.

• lpDDSrcSurface
  Pointer to source surface for blit operation.

  If a null pointer is specified, a color-fill operation is performed. In this case, the lpDDAlphaBltFX->dwFillValue argument specifies the effective source color and alpha values to be used for the color fill.

• lpSrcRect
  Pointer to source rectangle for blit operation.

  This parameter specifies a rectangular region of the source surface.

  The rectangle must not exceed the boundaries of the source surface or the call will fail.

  If a null pointer is specified, the effective source rectangle is the entire source surface.

  A null pointer must always be specified if the lpDDSrcSurface argument is a null pointer.

• dwFlags
  The following table shows the possible flags.

  Flag	Description
  DDABLT_ALPHADESTNEG	Treats the destination alpha values as inverted (where 0 indicates fully opaque and MAX indicates fully transparent).
  DDABLT_ALPHASRCNEG	Treats the source alpha values as inverted (where 0 indicates fully opaque and MAX indicates fully transparent).
  DDABLT_COLORFILL	Uses the dwFillValue in the DDALPHABLTFX structure to perform an alpha-blended colorfill operation.
  DDABLT_NOBLEND	Writes the source pixel values to the destination surface without blending. The pixels are converted from the source pixel format to the destination format, but no color keying, alpha blending, or RGBA scaling is performed. In the case of a fill operation (lpDDSrcSurface=NULL), lpDDAlphaBltFX->dwFillValue contains the source alpha and color components that are to be converted to the destination pixel format and used to fill the destination. This flag cannot be used with the DDABLT_KEYSRC and DDABLT_KEYDEST flags.
  DDABLT_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.
  DDABLT_WAITVSYNC	Waits for a V-Sync before performing the blit operation.

• lpDDAlphaBltFX
  Pointer to DDALPHABLTFX structure.

Return Value

The method returns DD_OK if successful or one of the following error values otherwise:

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

Remarks

When lpDDSrcSurface = NULL, the lpSrcRect argument must also equal NULL. If a FOURCC surface contains an alpha channel, that channel is automatically enabled unless the DDABLT_NOBLEND flag is set.

Overlapping rectangles are not supported. The call fails if the source and destination rectangles lie on the same surface and overlap each other. Applications should use the IDirectDrawSurface::Blt call to perform scrolling and other blit operations that involve overlapping rectangles.

Requirements