DrvRealizeBrush

BOOL DrvRealizeBrush(

IN BRUSHOBJ *pbo,
IN SURFOBJ *psoTarget,
IN SURFOBJ *psoPattern,
IN SURFOBJ *psoMask,
IN XLATEOBJ *pxlo,
ULONG iHatch
);

DrvRealizeBrush requests that the driver realize a specified brush for a specified surface.

Parameters

pbo

Points to the BRUSHOBJ that is to be realized. All other parameters, except for psoTarget, can be queried from this object. Parameter specifications are provided as an optimization. This parameter is best used only as a parameter for BRUSHOBJ_pvAllocRBrush, which allocates the memory for the realized brush.

psoTarget

Points to the surface for which the brush is to be realized. This surface can be the physical surface for the device, a device format bitmap, or a standard format bitmap.

psoPattern

Points to the surface that describes the pattern for the brush. For a raster device, this is a bitmap. For a vector device, this is one of the pattern surfaces provided by DrvEnablePDEV.

psoMask

Points to a transparency mask for the brush. This is a 1 bit per pixel bitmap that has the same extent as the pattern. A mask of zero means the pixel is considered a background pixel for the brush. (In transparent background mode, the background pixels are unaffected in a fill.) Plotters can ignore this parameter because they never draw background information.

pxlo

Points to a XLATEOBJ that defines the interpretration of colors in the pattern. A XLATEOBJXxx service routine can be called to translate the colors to device color indices. Vector devices should translate color zero through the XLATEOBJ to get the foreground color for the brush.

iHatch

Specifies whether psoPattern is one of the hatch brushes returned by DrvEnablePDEV. This is true if the value of this parameter is less than HS_API_MAX.

Return Value

The return value is TRUE if the brush was successfully realized. Otherwise, it is FALSE, and an error code is logged.

Comments

To realize a brush, the driver converts a GDI brush into a form that can be used internally. A realized brush contains information and accelerators the driver needs to fill an area with a pattern; information that is defined by the driver and used only by the driver.

The driver's realization of a brush is written into the buffer allocated by a call to BRUSHOBJ_pvAllocRbrush.

DrvRealizeBrush is required for a driver that does any drawing to any surface.

See Also

BRUSHOBJ, BRUSHOBJ_pvAllocRBrush, DrvEnablePDEV, XLATEOBJ