IDirectDrawSurface5::AlphaBlt

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

HRESULT AlphaBlt( 
  LPRECT lpDestRect, 
  LPDIRECTDRAWSURFACE4 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 automatically 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_KEYSRC	Uses the color key associated with the source surface. Source pixels matching the color key are transparent when blitted to the destination. The source color-key value was specified in an earlier call to IDirectDrawSurface5::SetColorKey. The DDABLT_KEYSRC flag cannot be set if the source surface contains an alpha channel.
  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_MIRRORLEFTRIGHT	Mirrors the source image left-to-right in the destination rectangle.
  DDABLT_MIRRORUPDOWN	Mirrors the source image vertically in the destination rectangle.
  DDABLT_DEGRADEARGBSCALING	Causes the runtime to allow the set of RGBA-scaling factors passed by the application to be degraded from distinct values into one or two values, based on the capabilities of the driver. The default behavior is to honor the contents of the RGBA-scaling factors and only call a driver that can perform the RGBA-scaling operation as specified.
  DDABLT_HARDWAREONLY	Mandates hardware acceleration to perform the blit. If the display hardware is unable to perform the blit, the call fails. This flag overrides DirectDraw's default behavior, which is to attempt to perform the blit with software emulation in the event that the display hardware cannot handle it.
  DDABLT_WAIT	Waits for a previously initiated drawing operation to complete instead of returning immediately with the DDERR_WASSTILLDRAWING return value. In the event that a previous drawing operation is still in progress at the time of the call, this flag defers returning from the call until either the new blit operation begins or an error occurs.
  DDABLT_FILTERENABLE	Utilize filtering to enhance the image quality of stretch operations.
  DDABLT_FILTERDISABLE	Utilize nearest-neighbor source pixels in stretch operations. This is the default.
  DDABLT_DONOTWAIT	If a previous drawing operation is still pending, return DDERR_WASSTILLDRAWING instead of waiting for it to finish. This is the default.
  DDABLT_USEFILLVALUE	Fill the destination surface with the pixel value contained in lpDDAlphaBltFx->dwFillValue.
  DDABLT_SOFTWAREONLY	Mandates that the blit be performed by the hardware emulation layer. If the HEL is not present, the blit returns DDERR_UNSUPPORTED.
  DDABLT_FILTERTRANSPBORDER	When filtering, pixels located on the border of the source rectangle are treated as transparent in order to have a smooth blend from the destination to the source pixels.

• lpDDAlphaBltFX
  Pointer to DDALPHABLTFX structure.

Return Values

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

Remarks

When lpDDSrcSurface = NULL, the lpSrcRect argument must also equal NULL. In addition, the following flags must not be set: DDABLT_KEYSRC, DDABLT_MIRRORLEFTRIGHT, and DDABLT_MIRRORUPDOWN. Otherwise, the call will fail.

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 IDirectDrawSurface5::Blt call to perform scrolling and other blit operations that involve overlapping rectangles.

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.