Supporting the DitherOnRealize Flag

In earlier verisions of GDI/DDI, two calls by GDI to display driver functions were required to dither a specified color and then realize a brush for that color. For example, when an application requests that a rectangle be filled with a dithered color, GDI typically calls DrvBitBlt, passing the extents of the rectangle and the brush object to use. The display driver then checks the brush, finds that it has not been realized, and calls back to GDI with BRUSHOBJ_pvGetRbrush for GDI’s realization of the brush. Since GDI doesn’t perform the dithering of a brush, but the display driver does, GDI passes the RGB that the application originally supplied for dithering in a DrvDitherColor call back to the display driver.

DrvDitherColor returns a pointer to an array of color indexes that describe the dither for the supplied color back to GDI. GDI immediately passes this dither information back to the display driver in a call to DrvRealizeBrush. With the BRUSHOBJ realized, control returns back to GDI and subsequently back to the original DrvBitBlt function.

To accomplish dithering using the above technique, GDI has to call DrvDitherColor followed immediately by a call DrvRealizeBrush; two separate function calls. Setting a GCAPS_DITHERONREALIZE flag in the DEVINFO structure and a modification to DrvRealizeBrush to effectively combine these two functions eliminates the need for the separate call to DrvDitherColor and also saves some memory allocation. Under this scheme, if the display driver sets GCAPS_DITHERONREALIZE, GDI calls DrvRealizeBrush with the RGB to be dithered and with the RB_DITHERCOLOR flag set in iHatch. (The RB_DITHERCOLOR flag is set in the high byte of iHatch while the RGB color to be dithered is contained in the three low-order bytes.) The need to call DrvDitherColor is eliminated in this situation since the functionality of both calls are put into one.

For example code, refer to \s3\brush.c.