StretchBlt

The StretchBlt function copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary. The system stretches or compresses the bitmap according to the stretching mode currently set in the destination device context.

BOOL StretchBlt(
  HDC hdcDest,      // handle to destination device context
  int nXOriginDest, // x-coordinate of upper-left corner of dest. rectangle
  int nYOriginDest, // y-coordinate of upper-left corner of dest. rectangle
  int nWidthDest,   // width of destination rectangle
  int nHeightDest,  // height of destination rectangle
  HDC hdcSrc,       // handle to source device context
  int nXOriginSrc,  // x-coordinate of upper-left corner of source rectangle
  int nYOriginSrc,  // y-coordinate of upper-left corner of source rectangle
  int nWidthSrc,    // width of source rectangle
  int nHeightSrc,   // height of source rectangle
  DWORD dwRop       // raster operation code
);
 

Parameters

hdcDest

Handle to the destination device context.

nXOriginDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nYOriginDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nWidthDest

Specifies the width, in logical units, of the destination rectangle.

nHeightDest

Specifies the height, in logical units, of the destination rectangle.

hdcSrc

Handle to the source device context.

nXOriginSrc

Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.

nYOriginSrc

Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.

nWidthSrc

Specifies the width, in logical units, of the source rectangle.

nHeightSrc

Specifies the height, in logical units, of the source rectangle.

dwRop

Specifies the raster operation to be performed. Raster operation codes define how the system combines colors in output operations that involve a brush, a source bitmap, and a destination bitmap.

See BitBlt for a list of common raster operation codes.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Windows NT: To get extended error information, call GetLastError.

Remarks

StretchBlt stretches or compresses the source bitmap in memory and then copies the result to the destination rectangle. The color data for pattern or destination pixels is merged after the stretching or compression occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

If the specified raster operation requires a brush, the system uses the brush currently selected into the destination device context.

The destination coordinates are transformed by using the transformation currently specified for the destination device context; the source coordinates are transformed by using the transformation currently specified for the source device context.

If the source transformation has a rotation or shear, an error occurs.

If destination, source, and pattern bitmaps do not have the same color format, StretchBlt converts the source and pattern bitmaps to match the destination bitmap.

If StretchBlt must convert a monochrome bitmap to a color bitmap, it sets white bits (1) to the background color and black bits (0) to the foreground color. To convert a color bitmap to a monochrome bitmap, it sets pixels that match the background color to white (1) and sets all other pixels to black (0). The foreground and background colors of the device context with color are used.

StretchBlt creates a mirror image of a bitmap if the signs of the nWidthSrc and nWidthDest parameters or of the nHeightSrc and nHeightDest parameters differ. If nWidthSrc and nWidthDest have different signs, the function creates a mirror image of the bitmap along the x-axis. If nHeightSrc and nHeightDest have different signs, the function creates a mirror image of the bitmap along the y-axis.

Not all devices support the StretchBlt function. For more information, see the GetDeviceCaps.

ICM: No color management is performed when a blit operation occurs.

Windows CE: Windows CE version 1.0 supports only the SRCCOPY and SRCINVERT raster operations. Windows CE version 1.0 does not support mirroring.

This function is the same in Windows CE version 2.0 as it is in Windows desktop platforms.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Requires version 1.0 or later.
  Header: Declared in wingdi.h.
  Import Library: Use gdi32.lib.

See Also

Bitmaps Overview, Bitmap Functions, BitBlt, GetDeviceCaps, MaskBlt, PlgBlt, SetStretchBltMode