| Platform SDK: DirectX |
When using the IDirectDrawSurface7::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 Clippers.)
Scaling
The Blt method automatically re-scales 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, or else use IDirectDrawSurface7:BltFast. (See Blitting with BltFast.)
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 SDK 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 IDirectDraw7::GetCaps method.
When you specify an effect that requires a value in one of the members of the DDBLTFX structure passed to the IDirectDrawSurface7::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 wish 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
Opacity and depth values are not currently supported in DirectDraw blits. If alpha values are stored in the pixel format, they simply overwrite any alpha values in the destination rectangle. Values from alpha buffers and z-buffers are ignored. The members of the DDBLTFX structure that have to do with alpha channels and z-buffers (members whose names begin with "dwAlpha" and "dwZ"), and the corresponding flags for Blt, are not used. The same applies to the DDBLTFX_ZBUFFERBASEDEST and DDBLTFX_ZBUFFERRANGE flags in the dwDDFX member of the DDBLTFX structure.
Although z-buffers are currently used only in Direct3D applications, you can use IDirectDrawSurface7::Blt to set the depth value for a z-buffer surface, by setting the DDBLT_DEPTHFILL flag. For more information, see Clearing Depth Buffers.
For an overview of the use of alpha channels and z-buffers in Direct3D, see the following topics.
Blt Example
The following example, in which it is assumed that lpDDS is a valid IDirectDrawSurface7 pointer, creates a symmetrical image within the surface by mirroring a rectangle from left to right.
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_WAIT | DDBLT_DDFX,
&ddbltfx);
When using the DirectDrawSurface7.Blt method, you supply a valid rectangle in the source surface (or an empty RECT to specify the entire surface), and a rectangle in the destination surface to which the source image will be copied (again, passing an empty RECT 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 raise the DDERR_INVALIDRECT error. (For more information on clipping, see Clippers.)
Scaling
The Blt method automatically re-scales 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, or else use DirectDrawSurface7.BltFast. (See Blitting with BltFast.)
Hardware acceleration for scaling depends on the DDFXCAPS_BLT* flags in the lFXCaps member of the DDCAPS type 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 lDDFX member of the DDBLTFX type 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 want to use any special effects other than scaling use the DirectDrawSurface7.BltFx method. In this method, you can choose among a variety of effects specified in a DDBLTFX type. 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 SDK 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 DirectDraw7.GetCaps method.
When you specify an effect that requires a value in one of the members of the DDBLTFX structure passed to the DirectDrawSurface7.BltFx method, you must also include the appropriate flags in the flags parameter to show which members of the type are valid.
Some effects require only the setting of a flag in the lDDFX 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 type for the driver. If you wish to use any of the standard ROPS with the BltFx method, you flag them in the lROP member of the DDBLTFX type.
The lDDROP member of the DDBLTFX type is for specifying ROPs specific to DirectDraw. However, no such ROPs are currently defined.
Alpha and Z Values
Opacity and depth values are not currently supported in DirectDraw blits. If alpha values are stored in the pixel format, they simply overwrite any alpha values in the destination rectangle. Values from alpha buffers and z-buffers are ignored. The members of the DDBLTFX type that have to do with alpha channels and z-buffers (members whose names begin with "lAlpha" and "lZ"), and the corresponding flags for BltFx, are not used. The same applies to the DDBLTFX_ZBUFFERBASEDEST and DDBLTFX_ZBUFFERRANGE flags in the lDDFX member of the DDBLTFX structure.
Although z-buffers are currently used only in Direct3D applications, you can use DirectDrawSurface7.Blt to set the depth value for a z-buffer surface, by setting the DDBLT_DEPTHFILL flag. For more information, see Clearing Depth Buffers.
For an overview of the use of alpha channels and z-buffers in Direct3D, see the following topics.
Blt Example
The following example, in which it is assumed that DDS is a valid DirectDrawSurface7 object, creates a symmetrical image within the surface by mirroring a rectangle from left to right.
rcSource As RECT rcDest As RECT ddbltfx As ddbltfx ddbltfx.lDDFX = 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 dds.BltFx rcDest, dds, rcSource, DDBLT_WAIT Or DDBLT_DDFX, ddbltfx