EngBitBlt

EngBitBlt

BOOL EngBitBlt(

IN SURFOBJ *psoDst,
IN SURFOBJ *psoSrc,
IN SURFOBJ *psoMask,
IN CLIPOBJ *pco,
IN XLATEOBJ *pxlo,
IN RECTL *prclDst,
IN POINTL *pptlSrc,
IN POINTL *pptlMask,
IN BRUSHOBJ *pbo,
IN POINTL *pptlBrush,
IN ROP4 rop4
);

EngBitBlt provides general bit-block transfer capabilities either between device-managed surfaces, or between a device-managed surface and a GDI-managed standard format bitmap.

Parameters

psoDst

Points to the SURFOBJ that identifies the surface on which to draw.

psoSrc

If the rop4 requires it, points to a SURFOBJ that defines the source for the bit-block transfer operation.

psoMask

Points to a SURFOBJ that defines a surface to be used as a mask. The mask is defined as a bitmap with 1 bit per pixel. Typically, a mask limits the area that is to be modified in the destination surface. Masking is selected by a rop4 with the value 0xAACC. The destination surface is unaffected when the mask is zero.

The mask is large enough to cover the destination rectangle.

If the value of this parameter is null and a mask is required by the rop4, then the implicit mask in the brush is used. If a mask is required, then psoMask overrides the implicit mask in the brush.

pco

Points to a CLIPOBJ structure. The CLIPOBJ_Xxx service routines are provided to enumerate the clip region as a set of rectangles. This enumeration limits the area of the destination that will be modified. Whenever possible, GDI simplifies the clipping involved; for example, this function is never called with a single clipping rectangle. GDI clips the destination rectangle before calling this function, making additional clipping unnecessary.

pxlo

Points to a XLATEOBJ that tells how color indices should be translated between the source and target surfaces.

prclDst

Points to a RECTL structure in the coordinate system of the destination surface that defines the area to be modified. The rectangle is defined by two points; upper left and lower right. The lower and right edges of this rectangle are not part of the bit-block transfer, meaning the rectangle is lower right exclusive.

EngBitBlt is never called with an empty destination rectangle. The two points that define the rectangle are always well ordered.

pptlSrc

Points to a POINTL structure that defines the upper left corner of the source rectangle, if a source exists. If there is no source, the driver should ignore this parameter.

pptlMask

Points to a POINTL structure that defines which pixel in the mask corresponds to the upper left corner of the destination rectangle. If no mask is specified in psoMask the driver should ignore this parameter.

pbo

Points to the brush object to be used to define the pattern for the bit-block transfer. GDI’s BRUSHOBJ_pvGetRbrush service routine retrieves the device’s realization of the brush. The driver can ignore this parameter if the rop4 parameter does not require a pattern.

pptlBrush

Points to a POINTL structure that defines the origin of the brush in the destination surface. The upper left pixel of the brush is aligned at this point and the brush repeats according to its dimensions. Ignore this parameter if the rop4 parameter does not require a pattern.

rop4

Represents a raster operation that defines how the mask, pattern, source, and destination pixels are combined to write an output pixel to the destination surface.

This is a quaternary raster operation, which is a natural extension of the usual ternary Rop3 operation. A Rop4 has 16 relevant bits, which are similar to the 8 defining bits of a Rop3. (The other, redundant bits of the Rop3 are ignored.) The simplest way to implement a Rop4 is to consider its 2 bytes separately. The lower byte specifies a Rop3 that should be computed wherever the mask is 1. The high byte specifies a Rop3 that can be computed and applied wherever the mask is 0.

Return Value

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

Comments

If a device’s surface is organized as a standard-format bitmap, the driver can request that GDI perform the bit-block transfer by calling EngBitBlt. A driver might do this if it has special hardware to handle simple transfers quickly, but doesn’t want to handle calls with complicated transfers.

GDI services reduce clipping to a series of clip rectangles. A translation vector assists in color index translation for palettes.

If the source surface is palette-managed, its colors are represented by indices into an array of RGB colors. The XLATEOBJ can be queried for a translate vector that allows the driver to quickly translate any source index into a color index for the destination.

The situation is more complicated when, for example, the source is RGB, but the destination is palette-managed. In this case, the closest match for each source RGB value must be found in the destination palette. The XLATEOBJ contains the address of a service routine to perform this operation.

Optionally, the driver can match colors when the target palette is the default device palette.

See the Win32 SDK for more information on raster operations.