StretchBlt

2.x

  BOOL StretchBlt(hdcDest, nXOriginDest, nYOriginDest, nWidthDest, nHeightDest, hdcSrc, nXOriginSrc, nYOriginSrc, nWidthSrc, nHeightSrc, fdwRop)    
  HDC hdcDest; /* destination device-context handle */
  int nXOriginDest; /* x-coordinate of origin of destination rectangle */
  int nYOriginDest; /* y-coordinate of origin of destination rectangle */
  int nWidthDest; /* width of destination rectangle */
  int nHeightDest; /* height of destination rectangle */
  HDC hdcSrc; /* source device-context handle */
  int nXOriginSrc; /* x-coordinate of origin of source rectangle */
  int nYOriginSrc; /* y-coordinate of origin of source rectangle */
  int nWidthSrc; /* width of source rectangle */
  int nHeightSrc; /* height of source rectangle */
  DWORD fdwRop; /* raster operation, */  

The StretchBlt function copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap if necessary to fit the dimensions of the destination rectangle. The StretchBlt function uses the stretching mode of the destination device context (set by the SetStretchBltMode function) to determine how to stretch or compress the bitmap.

Parameters

hdcDest

Identifies the device context to receive the bitmap.

nXOriginDest

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

nYOriginDest

Specifies the logical y-coordinate 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

Identifies the device context that contains the source bitmap.

nXOriginSrc

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

nYOriginSrc

Specifies the logical y-coordinate 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.

fdwRop

Specifies the raster operation to be performed. Raster-operation codes define how the graphics device interface (GDI) combines colors in output operations that involve a current brush, a possible source bitmap, and a destination bitmap. This parameter can be one of the following values:

Code Description

BLACKNESS Turns all output black.
DSTINVERT Inverts the destination bitmap.
MERGECOPY Combines the pattern and the source bitmap by using the Boolean AND operator.
MERGEPAINT Combines the inverted source bitmap with the destination bitmap by using the Boolean OR operator.
NOTSRCCOPY Copies the inverted source bitmap to the destination.
NOTSRCERASE Inverts the result of combining the destination and source bitmaps by using the Boolean OR operator.
PATCOPY Copies the pattern to the destination bitmap.
PATINVERT Combines the destination bitmap with the pattern by using the Boolean XOR operator.
PATPAINT Combines the inverted source bitmap with the pattern by using the Boolean OR operator. Combines the result of this operation with the destination bitmap by using the Boolean OR operator.
SRCAND Combines pixels of the destination and source bitmaps by using the Boolean AND operator.
SRCCOPY Copies the source bitmap to the destination bitmap.
SRCERASE Inverts the destination bitmap and combines the result with the source bitmap by using the Boolean AND operator.
SRCINVERT Combines pixels of the destination and source bitmaps by using the Boolean XOR operator.
SRCPAINT Combines pixels of the destination and source bitmaps by using the Boolean OR operator.
WHITENESS Turns all output white.

Return Value

The return value is nonzero if the function is successful. Otherwise, it is zero.

Comments

The StretchBlt function stretches or compresses the source bitmap in memory and then copies the result to the destination. If a pattern is to be merged with the result, it is not merged until the stretched source bitmap is copied to the destination.

If a brush is used, it is the selected brush in the destination device context.

The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context.

If the destination, source, and pattern bitmaps do not have the same color format, StretchBlt converts the source and pattern bitmaps to match the destination bitmaps. The foreground and background colors of the destination device context are used in the conversion.

If StretchBlt must convert a monochrome bitmap to color, it sets white bits (1) to the background color and black bits (0) to the foreground color. To convert color to monochrome, 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 or 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. Applications can discover whether a device supports StretchBlt by calling the GetDeviceCaps function and specifying the RASTERCAPS index.

Example

The following example retrieves the handle of the desktop window and uses it to create a device context. After retrieving the dimensions of the desktop window, the example calls the StretchBlt function to copy the desktop bitmap into a smaller rectangle in the destination device context.

HWND hwndDesktop;
HDC hdcLocal;
RECT rc;

hwndDesktop = GetDesktopWindow();
hdcLocal = GetDC(hwndDesktop);
GetWindowRect(GetDesktopWindow(), &rc);

StretchBlt(hdc, 10, 10, 138, 106,
    hdcLocal, 0, 0, rc.right, rc.bottom, SRCCOPY);

ReleaseDC(hwndDesktop, hdcLocal);

See Also

BitBlt, GetDeviceCaps, SetStretchBltMode, StretchDIBits