Blitting with Blt
A version of this page is also available for
4/8/2010
When using the IDirectDrawSurface::Blt method, you supply a valid rectangle in the source surface (or NULL to specify the entire surface), and a rectangle in the destination surface to which the source image will be copied (again, NULL means the rectangle covers the entire surface).
If a clipper is attached to the destination surface, the bounds of the destination rectangle can fall outside the surface and clipping will be performed.
If there is no clipper, the destination rectangle must fall entirely within the surface or else the method will fail with DDERR_INVALIDRECT. (For more information on clipping, see Working with DirectDraw Clippers.)
Scaling
The Blt method automatically rescales the source image to fit the destination rectangle. If resizing is not your intention, for best performance you should make sure that your source and destination rectangles are exactly the same size.
Hardware acceleration for scaling depends on the DDFXCAPS_BLT* flags in the dwFXCaps member of the DDCAPS structure for the device.
If, for example, a device has the DDFXCAPS_BLTSTRETCHXN capability but not DDFXCAPS_BLTSTRETCHX, it can assist when the x-axis of the source rectangle is being multiplied by a whole number but not when non-integral (arbitrary) scaling is being done.
Devices might also support arithmetic scaling, which is scaling by interpolation rather than simple multiplication or deletion of pixels.
For instance, if an axis was being increased by one-third, the pixels would be recolored to provide a closer approximation to the original image than would be produced by the doubling of every third pixel on that axis.
Applications cannot control the type of scaling done by the driver, except by setting the DDBLTFX_ARITHSTRETCHY flag in the dwDDFX member of the DDBLTFX structure passed to Blt. This flag requests that arithmetic stretching be done on the y-axis.
Arithmetic stretching on the x-axis and arithmetic shrinking are not currently supported in the DirectDraw API, but a driver may perform them by default.
Other Effects
If you do not require any special effects other than scaling when using Blt, you can pass NULL as the lpDDBltFx parameter. Otherwise you can choose among a variety of effects specified in a DDBLTFX structure.
Among these, color fills and mirroring are supported by the HEL, so they are always available.
Most other effects depend on hardware support.
For a complete view of the effects capabilities of the HEL, run the DDraw Caps utility supplied with the DirectX Programmer's Reference and select HEL FX Caps from the HEL menu.
For an explanation of the various flags, see DDCAPS.
You can also check HEL capabilities within your own application by using the IDirectDraw::GetCaps method.
When you specify an effect that requires a value in one of the members of the DDBLTFX structure passed to the IDirectDrawSurface::Blt method, you must also include the appropriate flags in the dwFlags parameter to show which members of the structure are valid.
Some effects require only the setting of a flag in the dwFlags member of DDBLTFX. One of these is DDBLTFX_NOTEARING. You can use this flag when you are blitting animated images directly to the front buffer, so that the blit is timed to coincide with the screen refresh and the possibility of tearing is minimized.
Mirroring and rotation are also set by using flags.
Blitting effects include the standard raster operations (ROPs) used by GDI functions such as BitBlt. The only ROPs supported by the HEL are SRCCOPY (the default), BLACKNESS, and WHITENESS.
Hardware support for other ROPs can be examined in the DDCAPS structure for the driver. If you want to use any of the standard ROPS with the Blt method, you flag them in the dwROP member of the DDBLTFX structure.
The dwDDROP member of the DDBLTFX structure is for specifying ROPs specific to DirectDraw. However, no such ROPs are currently defined.
Alpha and Z Values
To perform blits that use and preserve alpha channel information, use the IDirectDrawSurface::AlphaBlt method. This method is currently unique to Windows Embedded CE, and fully supports alpha channel information during blit operations.
For an explanation of the use of alpha channels, see Alpha Blitting.
Code Example
The following code example, in which it is assumed that lpDDS is a valid IDirectDrawSurface pointer, creates a symmetrical image within the surface by mirroring a rectangle from left to right.
Note
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
RECT rcSource, rcDest;
DDBLTFX ddbltfx;
ZeroMemory(&ddbltfx, sizeof(ddbltfx));
ddbltfx.dwSize = sizeof(ddbltfx);
ddbltfx.dwDDFX = DDBLTFX_MIRRORLEFTRIGHT;
rcSource.top = 0; rcSource.left = 0;
rcSource.bottom = 100; rcSource.right = 200;
rcDest.top = 0; rcDest.left = 201;
rcDest.bottom = 100; rcDest.right = 401;
HRESULT hr = lpDDS->Blt(&rcDest,
lpDDS,
&rcSource,
DDBLT_WAITNOTBUSY | DDBLT_DDFX,
&ddbltfx);