BOOL DrvBitBlt(
IN SURFOBJ *psoDst, | |
IN SURFOBJ *psoSrc, | |
IN SURFOBJ *psoMask, | |
IN CLIPOBJ *pco, | |
IN XLATEOBJ *pxlo, | |
IN RECTL *prclDst, | |
IN POINTL *pptlSrc, | |
IN POINTL *pptlMask, | |
IN BRUSHOBJ *pbo, | |
IN POINTL *pptlBrush, | |
IN ROP4 rop4 | |
); |
DrvBitBlt provides general bit-block transfer capabilities between device-managed surfaces, between GDI-managed standard-format bitmaps, or between a device-managed surface and a GDI-managed standard-format bitmap.
The mask will be large enough to cover the destination rectangle.
If this parameter is null and a mask is required by the rop4 parameter,
the implicit mask in the brush is used.
If the source surface is palette-managed, its colors are represented by indices into a lookup table of RGB values. The XLATEOBJ structure can be queried for a translate vector that will allow the device driver to translate any source index into a color index for the destination.
The situation is more complicated when, for example, the source is RGB, but the destination is palette-managed. In this case, the closest match to each source RGB value must be found in the destination palette. The driver can call the XLATEOBJ_iXlate service to perform this operation.
Optionally, the device driver can match colors when the target palette is the
default device palette.
DrvBitBlt is never called with an empty destination rectangle. The two
points that define the rectangle are always well-ordered.
This is a quaternary raster operation, which is an extension of the ternary Rop3 operation. A Rop4 has 16 relevant bits, which are similar to the 8 defining bits of a Rop3. The simplest way to implement a Rop4 is to consider its 2 bytes separately: The low byte specifies a Rop3 that should be calculated if the mask is one; the high byte specifies a Rop3 that can be calculated and applied if the mask is 0.
The return value is TRUE if the bit-block transfer operation is successful. Otherwise, it is FALSE, and an error code is logged.
DrvBitBlt is optional if the device surface is a standard-format bitmap created using EngCreateBitmap. It is required if the device’s surface was created using EngCreateDeviceSurface. If a device’s surface is a standard-format bitmap, DrvBitBlt will not be called unless the driver hooks the call with DrvSynchronize. The driver then has the option to pass complicated transfers back to GDI by calling EngBitBlt. The EngBitBlt function divides the transfer into simpler calls for the driver.
A driver must implement DrvBitBlt if drawing is done on device-managed surfaces. At a minimum, DrvBitBlt must support the following:
GDI’s CLIPOBJ_Xxx services allow the clipping to be reduced to a series of clipping rectangles. A translation vector assists in color index translation for palettes.
Note Do not dereference parameter pointers unless the ROP indicates they are needed. For example, never unnecessarily dereference pbo->iSolidColor because doing so for a ROP such as BLACKNESS can cause an access violation. (This rule also applies to any function that includes a MIX parameter.)
DrvBitBlt is a large and complex function that performs most of the work required to write a driver for a raster display device that does not have a standard format frame buffer. Sample code is provided for the Microsoft VGA driver that illustrates the basic functionality of a planar device.
For more information on raster operations, see the Win32 SDK.
BRUSHOBJ, BRUSHOBJ_pvGetRbrush, CLIPOBJ, DrvSynchronize, EngAssociateSurface, EngBitBlt, EngCreateBitmap, EngCreateDeviceSurface, SURFOBJ, XLATEOBJ, XLATEOBJ_iXlate