Bit block transfer (bitblt) functions implemented by drivers must copy blocks of bits from one surface to another. These functions include:
There is also a display-driver-specific bitblt function called DrvSaveScreenBits.
If the surface being drawn on is a device-managed surface or bitmap, the driver must support a minimum level of bit block transfer functions. If the surface is a GDI-managed standard format bitmap, GDI handles all of these operations unless the driver hooks out any of the calls in EngAssociateSurface.
DrvBitBlt provides general bit block transfer capabilities. If a driver supports a device-managed surface or bitmap, the driver must implement DrvCopyBits. At a minimum, the driver must do the following when DrvCopyBits is called:
The driver can use the GDI CLIPOBJ enumeration services to reduce the clipping to a series of clip rectangles. GDI passes down a translation vector, XLATEOBJ, to assist in color index translation between source and destination surfaces.
If the surface of a device is organized as a standard-format DIB, the driver can support only simple transfers. If a call comes in with a complicated ROP, the driver can punt the block transfer request back to GDI with a call to EngCopyBits. This allows GDI to break up the call into simpler functions the driver can perform.
If a source is used, DrvBitBlt maps a geometric source rectangle exactly onto a geometric destination rectangle. If there is no source, the pptlSrc parameter is ignored. The destination rectangle is the surface to be modified and it is defined by two integer points, upper left and lower right. The rectangle is lower right exclusive; the lower and right edges of the rectangle are not part of the block transfer. DrvBitBlt cannot be called with an empty destination rectangle. The two points of the rectangle are always well ordered.
DrvBitBlt deals with different ROPs and can perform some optimizations, depending on the device. In some cases, if the ROP is a solid color, a fill rather than a bitblt can be done. For devices that do not support all ROPs, true WYSIWYG is not always possible. The PostScript driver, for example, supports no ROPs.
Optionally, a block transfer handled by DrvBitBlt can be masked and involve color index translation. A translation vector assists in color index translation for palettes. The transfer might need to be arbitrarily clipped by a display driver, using a series of clip rectangles. The required region and information are furnished by GDI.
Implementing DrvBitBlt represents a significant portion of the work involved in writing a driver for a raster display driver that does not have a standard-format frame buffer. The Microsoft VGA driver furnished with the DDK provides example code that completely supports the basic function for a planar device. Implementing DrvBitBlt for other devices may be less complex.
DrvStretchBlt can be optionally provided, even for drivers that support device-managed surfaces. This function provides capabilities for stretching block transfers between device-managed and GDI-managed surfaces. DrvStretchBlt supports only certain types of stretching, such as stretching by integer multiples.
DrvStretchBlt also allows a driver to write on GDI bitmaps, especially when the driver can do halftoning. The function also permits the same halftoning algorithm to be applied to GDI bitmaps and device surfaces.
DrvStretchBlt maps a geometric source rectangle exactly onto a geometric destination rectangle. The source is a rectangle with corners displaced by (-0.5,-0.5) from the given integer coordinates. The points specified in the function parameters lie on integer coordinates that correspond to pixel centers. A rectangle defined by two such points is considered to be geometric, with two vertices whose coordinates are the given points, but with 0.5 subtracted from each coordinate. (GDI POINTL structures use a shorthand notation for specifying these fractional coordinate vertices.) Note that the edges of any such rectangle never intersect a pixel, but go around a set of pixels. The pixels inside the rectangle are normal pixels for a “bottom right-exclusive” rectangle.
The points of the source rectangle are well ordered. DrvStretchBlt cannot be given an empty source rectangle. Unlike DrvBitBlt, DrvStretchBlt can be called with a single clipping rectangle to prevent round-off errors in clipping the output.
The destination rectangle is defined by two integer points. These points are not well ordered and the coordinates of the second point are not necessarily larger than those of the first. The source rectangle these points describe does not include the lower and right edges. Because the rectangle is not well ordered, DrvStretchBlt must sometimes perform inversions in both x and y. (The driver must not attempt to read pixels that do not lie on the source surface). DrvStretchBlt cannot be called with an empty destination rectangle.
For color translation, DrvStretchBlt provides a pointer, pxlo, to XLATEOBJ that is used to translate between the source and destination surfaces. XLATEOBJ can be queried to find the destination index for any source index. For a high-quality stretching block transfer, DrvStretchBlt is required to interpolate colors in some cases. DrvStretchBlt also uses the COLORADJUSTMENT structure to define the color adjustment values that are to be applied to the source bitmap before the bits are stretched.
DrvStretchBlt uses the iMode parameter to define how the source pixels are to be combined for output. In particular, iMode provides the HALFTONE option that permits the driver to use groups of pixels in the output surface to best approximate the color or grey level of the output. Changes to the COLORADJUSTMENT structure are passed to the driver after the next DrvStretchBlt call with an iMode of HALFTONE. In addition, if the driver wants GDI to handle halftoning for GDI bitmaps, the driver can hook out DrvStretchBlt, set the iMode parameter to HALFTONE, and return it in EngStretchBlt.
If DrvStretchBlt has hooked a call to EngStretchBlt and is asked to do something it does not support, it returns the request to GDI so that the appropriate function can handle it.
DrvCopyBits is called by GDI from its simulation operations to translate between a device-managed raster surface and a GDI standard-format bitmap. DrvCopyBits provides a fast path for SRCCOPY (0xCCCC) ROP bit-block transfers.
Required for a graphics driver with device-managed bitmaps or raster surfaces, this function must translate driver surfaces to and from any standard-format bitmap. DrvCopyBits is never called with an empty destination rectangle, and the two points of the destination rectangle are always well ordered. This call has the same requirements as DrvBitBlt.
DrvCopyBits is also called with RLE bitmaps (see the Win32 SDK) and DDBs. The bitmaps are provided to this function as a result of application program calls to several Win32 GDI routines. The optional DDB is supported only by a few specialized drivers.