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.
A version of this page is also available for
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->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 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 dwFillValuein the DDALPHABLTFXstructure 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->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_WAITNOTBUSY

Waits for a previously initiated drawing operation to complete instead of returning immediately with the DDERR_WASSTILLDRAWINGreturn 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 DDALPHABLTFXstructure.

Return Value

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

 

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

Remarks

When lpDDSrcSurface= NULL, the lpSrcRectargument must also equal NULL. 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 IDirectDrawSurface::Bltcall to perform scrolling and other blit operations that involve overlapping rectangles.

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