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 the color data for a rectangle of pixels in a DIB to the specified destination rectangle.

If the destination rectangle is larger than the source rectangle, this function stretches the rows and columns of color data to fit the destination rectangle.

If the destination rectangle is smaller than the source rectangle, this function compresses the rows and columns by using the specified raster operation.

Syntax 

WINGDIAPI BOOL WINAPI StretchDIBits(
  HDC 
hdc,
  int 
XDest,
  int 
YDest,
  int 
nDestWidth,
  int 
nDestHeight,
  int 
XSrc,
  int 
YSrc,
  int 
nSrcWidth,
  int 
nSrcHeight,
  CONST VOID* 
lpBits,
  CONST BITMAPINFO* 
lpBitsInfo,
  UINT 
iUsage,
  DWORD 
dwRop
);

Parameters

hdc

[in] Handle to the destination device context.

XDest

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

YDest

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

nDestWidth

[in] Integer that specifies the width, in logical units, of the destination rectangle.

nDestHeight

[in] Integer that specifies the height, in logical units, of the destination rectangle.

XSrc

[in] Integer that specifies the x-coordinate, in pixels, of the origin of the source rectangle in the DIB.

YSrc

[in] Integer that specifies the y-coordinate, in pixels, of the origin of the source rectangle in the DIB.

nSrcWidth

[in] Integer that specifies the width, in pixels, of the source rectangle in the DIB.

nSrcHeight

[in] Integer that specifies the height, in pixels, of the source rectangle in the DIB.

lpBits

[in] Pointer to the DIB bits, which are stored as an array of bytes.

lpBitsInfo

[in] Pointer to a BITMAPINFOstructure that contains information about the DIB.

iUsage

[in] Unsigned integer that specifies whether you provided a value for the bmiColorsmember of the BITMAPINFOstructure, and, if so, whether bmiColorscontains explicit red, green, blue (RGB) values or indexes.

The following table shows the possible values.

Value Description

DIB_PAL_COLORS

The array contains 16-bit indexes into the logical palette of the source device context.

DIB_RGB_COLORS

The color table contains literal red, green, and blue values.
dwRop

[in] DWORDthat specifies how to combine the source pixels, the current brush of the destination device context, and the destination pixels to form the new image.

Return Value

Nonzero indicates success.

Zero indicates failure.

To get extended error information, call GetLastError.

Note:
The data type of the return value for StretchDIBitsin Windows Embedded CE is different from the data type for the return value of StretchDIBitson Windows-based desktop systems

Remarks

The origin of a bottom-up DIB is the bottom-left corner; the origin of a top-down DIB is the upper-left corner.

StretchDIBitscreates a mirror image of a bitmap if the signs of the nSrcWidthand nDestWidthparameters differ, or if the signs of the nSrcHeightand nDestHeightparameters differ.

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

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

Requirements

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

See Also

Reference

BITMAPINFO