StretchBlt

WORD StretchBlt(LPPDEVICE lpDestDev, WORD wDestX, WORD wDestY, 
    WORD wDestXext, WORD wDestYext, LPPDEVICE lpSrcDev, WORD wSrcX, 
    WORD wSrcY, WORD wSrcXext, WORD wSrcYext, DWORD Rop3, 
    LPBRUSH lpPBrush, LPDRAWMODE lpDrawMode, LPRECT lpClip);

Transfers bits from a source-device rectangle to a destination-device rectangle. The function stretches or compresses the source bits to fit the destination rectangle. The transfer is controlled by a ternary raster operation value that specifies how corresponding bits from the source, destination, and pattern in a brush are combined to form the final bits in the destination.

• Returns one of these values:

lpDestDev

Address of a PDEVICE or PBITMAP structure that specifies the destination device or bitmap.

wDestX and wDestY

x- and y-coordinate of the upper-left corner of the destination rectangle.

wDestXext and wDestYext

Width and height, in device units, of the destination rectangle.

lpSrcDev

Address of a PDEVICE or PBITMAP structure that specifies the source device or bitmap.

wSrcX and wSrcY

x- and y-coordinate of the upper-left corner of the source rectangle.

wSrcXext and wSrcYext

Width and height, in device units, of the source rectangle.

Rop3

Ternary raster operation value. This value determines how StretchBlt combines corresponding pixels from the source, destination, and brush that is used to produce the final pixels in the destination rectangle. This parameter can be any one of 256 ternary raster-operation values; the following lists the most common values.

lpPBrush

Address of a PBRUSH structure that specifies a physical brush. StretchBlt uses this brush only if Rop3 specifies a ternary-raster operation that requires the brush that is used to be combined with source or destination or both.

lpDrawMode

Address of a DRAWMODE structure that specifies the color information StretchBlt needs to determine patterned brush colors and to carry color conversions and transparent copy operations.

lpClip

Address of a RECT structure that specifies the clipping rectangle (in destination-device units).

The export ordinal for this function is 27.

A graphics device driver must export the StretchBlt function if the RC_STRETCHBLT value is set in the dpRaster member of the GDIINFO structure.

Graphics device drivers that support some StretchBlt operations, but not others, can return -1 to direct GDI to carry out the unsupported operations. This also applies to operations in which the StretchBlt function can affect the final output, such as when StretchBlt compresses a bitmap to fit a rectangle in a monochrome bitmap. Although the StretchBlt function must use the current bitmap-stretching mode when compressing or stretching bitmaps, GDI does not make the current mode available to drivers. In such cases, the function should assume that the current mode is COLORONCOLOR or it should return -1 to direct GDI use the proper mode when compressing bitmaps.

The lpDestDev and lpSrcDev parameters can specify the same device that is transferring bits from one part of a device to another is a valid operation. If the source and destination rectangle overlap, StretchBlt transfers bits carefully so that the transfer does not inadvertently overwrite source bits before they have been transferred to the destination.

The Rop3 parameter specifies whether bits from the source, destination, and brush are used in the transfer. If the ternary raster operation specified by Rop3 does not include the source, StretchBlt ignores the source bits. If it does not include the destination, StretchBlt replaces the destination bits without using them to form the final bits.

If Rop3 does not include the brush, StretchBlt ignores the brush. If Rop3 includes the brush, StretchBlt must determine whether the brush is solid or patterned (that is, has an associated bitmap). If the brush has a bitmap, StretchBlt must combine the corresponding bits of the bitmap with the source and destination bits (as specified by the raster operation) to form the final destination bits.

If the source and bitmap associated with the brush do not have the same color format as the destination, StretchBlt must convert the source and brush bitmap to the destination's color format before transferring bits. StretchBlt uses the text (foreground) and background colors specified by the lpDrawMode parameter to convert colors.

To convert a monochrome bitmap to a color bitmap, StretchBlt converts white bits (1) to the background color and converts black bits (0) to the text (foreground) color.

To convert a color bitmap to a monochrome bitmap, StretchBlt converts all pixels that match the background color to white (1), and converts all other pixels to black (0).

In some device drivers, StretchBlt must check the bkMode member of the lpDrawMode parameter as well as the Rop3 parameter to determine how to carry out the transfer. If the bkMode member specifies the background mode TRANSPARENT1, StretchBlt must not transfer source and brush bits that have the same color as the destination's background color (as specified by the bkColor member of lpDrawMode). In other words, the corresponding destination bits must be left unchanged. Other background modes do not affect the transfer. Only device drivers that have set the C1_TRANSPARENT value in the dpCaps1 member of the GDIINFO structure are required to check the background mode.

See also PDEVICE, PBITMAP, DRAWMODE, RECT