DrvRealizeBrush function (winddi.h)

Article
10/13/2021

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

Syntax

BOOL DrvRealizeBrush(
  [in]           BRUSHOBJ *pbo,
  [in, out]      SURFOBJ  *psoTarget,
  [in]           SURFOBJ  *psoPattern,
  [in, optional] SURFOBJ  *psoMask,
  [in]           XLATEOBJ *pxlo,
  [in]           ULONG    iHatch
);

Parameters

[in] pbo

Pointer to the BRUSHOBJ structure 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.

[in, out] psoTarget

Pointer to the SURFOBJ structure 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.

[in] psoPattern

Pointer to the SURFOBJ structure 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.

[in, optional] psoMask

Pointer to a SURFOBJ structure that describes 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.

[in] pxlo

Pointer to a XLATEOBJ structure that defines the interpretation of colors in the pattern. If pxlo is NULL, no translation is needed. A XLATEOBJ_Xxx 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.

[in] 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_DDI_MAX, which is defined in winddi.h.

Return value

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

Remarks

To realize a brush, the driver converts a GDI brush into a form that can be used internally. A realized brush contains device-specific information needed by the device to accelerate drawing using the brush.

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.

Requirements

Requirement	Value
Target Platform	Desktop
Header	winddi.h (include Winddi.h)