StretchBlt

The StretchBlt function 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.

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

Parameters

lpDestDev

Points to a PDEVICE or PBITMAP structure specifying the destination device or bitmap.

wDestX

Specifies the x-coordinate of the upper-left corner of the destination rectangle.

wDestY

Specifies the y-coordinate of the upper-left corner of the destination rectangle.

wDestXext

Specifies the width (in device units) of the destination rectangle.

wDestYext

Specifies the height (in device units) of the destination rectangle.

lpSrcDev

Points to a PDEVICE or PBITMAP structure specifying the source device or bitmap.

wSrcX

Specifies the x-coordinate of the upper-left corner of the source rectangle.

wSrcY

Specifies the y-coordinate of the upper-left corner of the source rectangle.

wSrcXext

Specifies the width (in device units) of the source rectangle.

wSrcYext

Specifies the width (in device units) of the source rectangle.

Rop3

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

For more information about ternary raster operations and a complete list of values, see Appendix A, “Binary and Ternary Raster-Operation Codes.”

lpPBrush

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

lpDrawMode

Points to a DRAWMODE structure specifying the color information StretchBlt needs to determine patterned brush colors and to carry color conversions and transparent copy operations. The structure has the following form:

typedef struct tagDRAWMODE {

short Rop2; /*binary-raster operations*/

short bkMode; /*background mode*/

PCOLOR bkColor; /*physical background color*/

PCOLOR TextColor; /*physical text (foreground) color*/

short TBreakExtra;/*number of extra pixels to add to line*/

short BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/

short BreakErr; /*running error term*/

short BreakRem; /*remaining pixels: TBreakExtra%BreakCount*/

short BreakCount; /*number of breaks in the line*/

short CharExtra; /*extra pixels for each character*/

COLORREF LbkColor; /*logical background color*/

COLORREF LTextColor; /*logical text (foreground) color*/

} DRAWMODE;

lpClip

Points to a RECT structure specifying the clipping rectangle (in destination-device units).

Return Value

The return value is 1 if successful. Otherwise, it is zero if an error was encountered or -1 if GDI should carry out the requested operation.

Comments

The export ordinal for this function is 27.

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 mode 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

BitBlt