BOOL DrvStretchBlt(
IN SURFOBJ *psoDest, | |
IN SURFOBJ *psoSrc, | |
IN SURFOBJ *psoMask, | |
IN CLIPOBJ *pco, | |
IN XLATEOBJ *pxlo, | |
IN COLORADJUSTMENT *pca, | |
IN POINTL *pptlHTOrg, | |
IN RECTL *prclDest, | |
IN RECTL *prclSrc, | |
IN POINTL *pptlMask, | |
IN ULONG iMode | |
); |
DrvStretchBlt provides stretching bit-block transfer capabilities between any combination of device-managed and GDI-managed surfaces. This function enables the device driver to write to GDI bitmaps, especially when the driver can do halftoning. This function allows the same halftoning algorithm to be applied to GDI bitmaps and device surfaces.
The mask limits the area of the source that is copied. If this parameter is specified, it has an implicit rop4 of 0xCCAA, meaning the source should be copied wherever the mask is one, but the destination should be left alone wherever the mask is zero.
When this parameter is null there is an implicit rop4 of 0xCCCC, which means that the source should be copied everywhere in the source rectangle.
The mask will always be large enough to contain the relevant source; tiling is
unnecessary.
Whenever possible, GDI simplifies the clipping involved. However, unlike DrvBitBlt,
DrvStretchBlt can be called with a single clipping rectangle. This
prevents rounding errors in clipping the output.
The XLATEOBJ can also be queried to find the RGB color for any source index. A
high quality stretching bit-block transfer will need to interpolate colors in
some cases.
DrvStretchBlt can do inversions of x and y when the
destination rectangle is not well ordered.
The mapping is defined by prclSrc and prclDest. The points specified in prclDest and prclSrc lie on integer coordinates, which correspond to pixel centers. A rectangle defined by two such points is considered to be a geometric rectangle with two vertices whose coordinates are the given points, but with 0.5 subtracted from each coordinate. (POINTL structures should be considered a shorthand notation for specifying these fractional coordinate vertices.)
The edges of any rectangle never intersect a pixel, but go around a set of
pixels. The pixels inside the rectangle are those expected for a “bottom-right
exclusive” rectangle. DrvStretchBlt will map the geometric source
rectangle exactly onto the geometric destination rectangle.
Value |
Meaning |
WHITEONBLACK |
On a shrinking bit-block transfer, pixels should be combined with a Boolean OR operation. On a stretching bit-block transfer, pixels should be replicated. |
BLACKONWHITE |
On a shrinking bit-block transfer, pixels should be combined with a Boolean 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 don’t need to 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. |
The return value is TRUE if the function is successful. Otherwise, it is FALSE, and an error code is logged.
This function can be provided to handle only certain forms of stretching, such as by integer multiples. If the driver has hooked the call and is asked to perform an operation it does not support, the driver should forward the data to EngStretchBlt for GDI to handle.
If the driver wants GDI to handle halftoning, and wants to ensure the proper iMode value, the driver can hook DrvStretchBlt, set iMode to HALFTONE, and call back to GDI with EngStretchBlt with the set iMode value.
DrvStretchBlt is optional for display drivers.