Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This 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. Windows stretches or compresses the bitmap according to the stretching mode set in the destination device context.

Syntax 

BOOL StretchBlt(
  HDC 
hdcDest, 
  int 
nXOriginDest, 
  int 
nYOriginDest, 
  int 
nWidthDest, 
  int 
nHeightDest, 
  HDC 
hdcSrc, 
  int 
nXOriginSrc, 
  int 
nYOriginSrc, 
  int 
nWidthSrc, 
  int 
nHeightSrc, 
  DWORD 
dwRop
);

Parameters

hdcDest

[in] Handle to the destination device context.

nXOriginDest

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

nYOriginDest

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

nWidthDest

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

nHeightDest

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

hdcSrc

[in] Handle to the source device context.

nXOriginSrc

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

nYOriginSrc

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

nWidthSrc

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

nHeightSrc

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

dwRop

[in] 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 BitBltfor a list of common raster operation codes.

For the complete list of raster operations codes, see Ternary Raster Operations.

Windows CE 1.0 and 1.01 support only the SRCCOPYand SRCINVERTraster operations.

Return Value

Nonzero indicates success.

Zero indicates failure.

To get extended error information, call GetLastError.

Remarks

StretchBltstretches 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, StretchBltconverts the source and pattern bitmaps to match the destination bitmap.

If StretchBltmust 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.

StretchBltcreates a mirror image of a bitmap if the signs of the nWidthSrcand nWidthDestparameters or of the nHeightSrcand nHeightDestparameters differ.

If nWidthSrcand nWidthDesthave different signs, the function creates a mirror image of the bitmap along the x-axis.

If nHeightSrcand nHeightDesthave different signs, the function creates a mirror image of the bitmap along the y-axis.

Windows CE 1.0 and 1.01 do not support mirroring.

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

If hdcspecifies a mirrored device context, the horizontal coordinates increase from right to left rather than from left to right.

For information about blitting to displays with right-to-left orientations, see Creating Bitmaps.

Requirements

Header windows.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also