DrvTextOut

The DrvTextOut function is the entry point from GDI that calls for the driver to render a set of glyphs at specified positions.

BOOL
  DrvTextOut(
    IN SURFOBJ  *pso,
    IN STROBJ  *pstro,
    IN FONTOBJ  *pfo,
    IN CLIPOBJ  *pco,
    IN RECTL  *prclExtra,
    IN RECTL  *prclOpaque,
    IN BRUSHOBJ  *pboFore,
    IN BRUSHOBJ  *pboOpaque,
    IN POINTL  *pptlOrg,
    IN MIX  mix
    );

Parameters

pso

Pointer to a SURFOBJ structure that describes the surface on which to write.

pstro

Pointer to a STROBJ structure that defines the glyphs to be rendered and the positions in which to place them.

pfo

Pointer to a FONTOBJ structure from which to retrieve information about the font and its glyphs.

pco

Pointer to a CLIPOBJ structure that defines the clip region through which all rendering must be done. The driver cannot affect any pixels outside the clip region.

prclExtra

Pointer to a RECTL structure. GDI always sets this parameter to NULL in calls to this function. It should be ignored by the driver.

prclOpaque

Pointer to a RECTL structure that represents a single opaque rectangle. This rectangle is bottom-right exclusive. Pixels within this rectangle (those that are not foreground and not clipped) are to be rendered with the opaque brush. This rectangle always bounds the text to be drawn. If this parameter is NULL, no opaque pixels are to be rendered.

pboFore

Pointer to a BRUSHOBJ structure that represents the brush object to be used for the foreground pixels. This brush will always be a solid color brush.

pboOpaque

Pointer to a BRUSHOBJ structure that represents the opaque pixels. Both the foreground and background mix modes for this brush are assumed to be R2_COPYPEN. Unless the driver sets the GCAPS_ARBRUSHOPAQUE capabilities bit in the flGraphicsCaps member of the DEVINFO structure, it will always be called with a solid color brush.

pptlOrg

Pointer to a POINTL structure that defines the brush origin for both brushes.

mix

Specifies foreground and background raster operations (mix modes) for pboFore. The driver will only be called with both mix modes equal to COPYPEN unless it sets the GCAPS_ARBMIXTXT capabilities bit in the flGraphicsCaps member of the DEVINFO structure.

Return Value

The return value is TRUE if the function is successful; otherwise, it is FALSE.

Headers

Declared in winddi.h. Include winddi.h.

Comments

The input parameters to DrvTextOut define two sets of pixels: foreground and opaque. The driver must render the surface so that the result is identical to a process where the opaque pixels are rendered first with the opaque brush, and then the foreground pixels are rendered with the foreground brush. Each of these operations is limited by clipping.

The foreground and opaque pixels are regarded as a screen through which color is brushed onto the surface. The glyphs of the font do not have color in themselves.

The input parameters to DrvTextOut define the set of glyph pixels, the set of extra rectangles, the opaque rectangle, and the clip region. It is the driver's responsibility to calculate and then render the set of foreground and opaque pixels.

GDI guarantees that DrvTextOut and DrvDestroyFont never overlap; consequently, the driver can rely on cached information while processing a DrvTextOut call.

The mix mode defines how the incoming pattern should be mixed with the data already on the device surface. The MIX data type consists of two ROP2 values packed into a single ULONG. The low-order byte defines the foreground raster operation; the next byte defines the background raster operation. For more information about raster operation codes, see the Platform SDK documentation.

This is a conditionally required function.

See Also

CLIPOBJ, DEVINFO, FONTOBJ, STROBJ, SURFOBJ, DrvDestroyFont