Share via


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:

DDERR_GENERIC DDERR_NOPALETTEATTACHED
DDERR_INVALIDOBJECT DDERR_NOSTRETCHHW
DDERR_INVALIDPARAMS DDERR_OVERLAPPINGRECTS
DDERR_INVALIDRECT DDERR_SURFACEBUSY
DDERR_NOALPHAHW DDERR_SURFACELOST
DDERR_NOBLTHW DDERR_UNSUPPORTED
DDERR_NOMIRRORHW  

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.