EngTextOut

BOOL EngTextOut(

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
);

EngTextOut causes GDI to render a set of glyphs at specified positions.

Parameters

pso

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

pstro

Points to a STROBJ structure that defines the glyphs to be rendered and the positions where they are to be placed.

pfo

Points to a FONTOBJ structure that is used to retrieve information about the font and its glyphs.

pco

Points to a CLIPOBJ structure that defines the clip region through which rendering must be done. No pixels can be affected outside this clip region.

prclExtra

Points to a null-terminated array of rectangles. These rectangles are bottom-right exclusive. The pixels of the rectangles are to be combined with the pixels of the glyphs to produce the foreground pixels. The extra rectangles are used to simulate underlining or strike-out.

A null rectangle has both coordinates of both points set to zero.

prclOpaque

Points to a single opaque rectangle that 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

Points to the brush object to be used for the foreground pixels. This brush will always be a solid color brush.

pboOpaque

Points to the brush object for 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

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

mix

Specifies foreground and background raster operations (mix modes) for pboFore.

Return Value

The return value is TRUE if the function is successful. Otherwise, it is FALSE, and an error code is logged.

Comments

The driver should call EngTextOut when it has hooked DrvTextOut and cannot render the glyphs.

Note  The driver cannot punt to EngTextOut if it has hooked DrvTextOut for a device managed surface.

The input parameters to EngTextOut define two sets of pixels: foreground and opaque. The driver must render the surface so 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 set of pixels is defined to be the union of the pixels of the glyphs and the pixels of the extra rectangles pointed to by prclExtra. These extra rectangles are used to simulate strike-through or underlines. The opaque pixels are defined by the opaque rectangle at prclOpaque.

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 EngTextOut define the set of glyph pixels, the set of extra rectangles, the opaque rectangle, and the clip region. The driver must calculate and then render the set of foreground and opaque pixels.

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 Win32 SDK.

See Also

CLIPOBJ, DEVINFO, DrvTextOut, FONTOBJ, STROBJ, SURFOBJ