DrvPlgBlt function (winddi.h)

Article
10/13/2021

The DrvPlgBlt function provides rotate bit-block transfer capabilities between combinations of device-managed and GDI-managed surfaces.

Syntax

BOOL DrvPlgBlt(
  [in, out]      SURFOBJ         *psoTrg,
  [in, out]      SURFOBJ         *psoSrc,
  [in, optional] SURFOBJ         *psoMsk,
  [in]           CLIPOBJ         *pco,
  [in, optional] XLATEOBJ        *pxlo,
  [in, optional] COLORADJUSTMENT *pca,
  [in, optional] POINTL          *pptlBrushOrg,
  [in]           POINTFIX        *pptfx,
  [in]           RECTL           *prcl,
  [in, optional] POINTL          *pptl,
  [in]           ULONG           iMode
);

Parameters

[in, out] psoTrg

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

[in, out] psoSrc

Pointer to a SURFOBJ structure that describes the source for the bit-block transfer operation.

[in, optional] psoMsk

Pointer to an optional SURFOBJ structure that represents a mask for the source. It is defined by a logic map, which is a bitmap with one bit per pixel.

This mask limits the area of the source that is copied. A mask has an implicit rop4 of 0xCCAA, which means the source should be copied wherever the mask is one, but the destination should be left alone wherever the mask is zero.

If this parameter is NULL, rop4 is implicitly 0xCCCC, which means the source should be copied everywhere in the source rectangle.

The mask is always large enough to contain the relevant source; tiling is unnecessary.

[in] pco

Pointer to a CLIPOBJ structure that limits the area of the destination to be modified. GDI functions enumerate the clip region as a set of rectangles.

Whenever possible, GDI simplifies the clipping involved. Unlike the DrvBitBlt function, DrvPlgBlt can be called with a single clipping rectangle. This prevents rounding errors in clipping the output.

[in, optional] pxlo

Pointer to a XLATEOBJ structure that defines how color indices are translated between the source and target surfaces. The XLATEOBJ can also be queried to find the RGB color for any source index. If pxlo is NULL, no translation is needed.

A high quality rotate bit-block transfer is needed to interpolate colors.

[in, optional] pca

Pointer to a COLORADJUSTMENT structure that defines the color adjustment values to be applied to the source bitmap before stretching the bits. For more information about this structure, see the Microsoft Windows SDK documentation.

[in, optional] pptlBrushOrg

Pointer to a BRUSHOBJ structure that indicates the origin of the halftone brush. Device drivers that use halftone brushes should align the upper left pixel of the brush's pattern with this point on the device surface.

[in] pptfx

Pointer to three POINTFIX structures that define a parallelogram in the destination surface. Define pptfx[0] as A, pptfx[1] as B, and pptfx[2] as C. A, B, and C define three vertices of a parallelogram. A fourth implicit vertex is given as:

    D = B + C − A

DrvPlgBlt is never called with A, B, and C collinear.

[in] prcl

Pointer to a RECTL structure that defines the area to be copied, in the coordinate system of the source surface. The points of the source rectangle are well ordered. DrvPlgBlt will never be given an empty source rectangle.

[in, optional] pptl

Pointer to a POINTL structure that specifies which pixel in the given mask corresponds to the upper-left pixel in the source rectangle. Ignore this parameter if no psoMsk is specified.

[in] iMode

Defines how source pixels are combined to get output pixels. This value can be one of the following:

Value	Meaning
BLACKONWHITE	On a shrinking bit-block transfer, pixels should be combined with an AND operation. On a stretching bit-block transfer, pixels should be replicated.
COLORONCOLOR	On a shrinking bit-block transfer, enough pixels should be ignored so that pixels need not be combined. On a stretching bit-block transfer, pixels should be replicated.
HALFTONE	The driver can use groups of pixels in the output surface to best approximate the color or gray level of the input.
WHITEONBLACK	On a shrinking bit-block transfer, pixels should be combined with an OR operation. On a stretching bit-block transfer, pixels should be replicated.

The methods WHITEONBLACK, BLACKONWHITE, and COLORONCOLOR provide compatibility for old applications, but do not produce the best results for color surfaces.

Return value

DrvPlgBlt returns TRUE upon success. Otherwise, it reports an error and returns FALSE.

Remarks

Similar to DrvStretchBlt, DrvPlgBlt enables a device driver to write to GDI bitmaps, especially when the driver can do halftoning.

To transform the bitmap, this function performs bit-block transfers from a rectangle defined by prcl to any parallelogram. The parallelogram is defined by pptfx, which points to an array of three points.

The source rectangle at prcl is considered to be a geometric rectangle whose corners are displaced by (-0.5,-0.5) from the given integer coordinates. This exactly matches the source rectangle for DrvStretchBlt. The source rectangle is always well ordered.

The upper-left corner of the source rectangle is mapped to the first point, A. The upper-right corner of the source rectangle is mapped to the second point, B. The lower-left corner of the source rectangle is mapped to the third point, C. The lower right corner of the source rectangle is mapped to the implicit point in the parallelogram defined by treating the three given points as vectors and computing:

    D = B + C - A

Note that a stretch blt can be expressed exactly as a parallelogram blt, but the coordinates given for the destination will have a fractional part of 0.5.

DrvPlgBlt is optional for graphics drivers. It is provided only for certain types of rotation. The driver should call EngPlgBlt if DrvPlgBlt is called to perform operations it does not support.

Requirements

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