IDirectDrawSurface5::AlphaBlt

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The IDirectDrawSurface5::AlphaBltmethod 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->dwFillValueargument 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 lpDDSrcSurfaceargument is a null pointer.

dwFlags

The following flags are defined:

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_KEYSRCflag 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->dwFillValuecontains 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_KEYSRCand DDABLT_KEYDESTflags.
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_WASSTILLDRAWINGreturn 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_WASSTILLDRAWINGinstead 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 DDALPHABLTFXstructure.

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 lpSrcRectargument 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_NOBLENDflag 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::Bltcall to perform scrolling and other blit operations that involve overlapping rectangles.

Requirements

Runs on	Versions	Declared in	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	ddraw.h	ddraw.lib