StretchDIBits

The StretchDIBits function moves a source bitmap into a destination bitmap, stretching or compressing the source bitmap as necessary to fit the dimensions of the destination bitmap. The function either converts and copies a device-independent bitmap to a given device or converts and copies a device-specific bitmap to a device-independent bitmap. The fGet parameter specifies whether the source bitmap is a device-independent bitmap or device-specific bitmap. GDI calls this function whenever an application calls the StretchDIBits function (GDI.439).

A graphics device driver must export the StretchDIBits function if the RC_STRETCHDIB value is set in the dpRaster member of the driver's GDIINFO structure.

Parameters

lpPDevice

Points to a PDEVICE or PBITMAP structure specifying a device or a device-specific bitmap.

fGet

Specifies whether to set or retrieve bitmap bits. If this parameter is zero, the function stretches or compresses the bitmap bits in the buffer pointed to by the lpBits parameter and copies them to the given device or bitmap. If this parameter is 1, the function retrieves bits from the device or bitmap.

DestX

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

DestY

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

DestXE

Specifies the width of the destination bitmap in pixels.

DestYE

Specifies the height of the destination bitmap in pixels. If this parameter is negative, the function must “flip” the bitmap, effectively displaying or printing it upside down. In this case, the height of the destination bitmap is the absolute value of the parameter.

SrcX

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

SrcY

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

SrcXE

Specifies the width of the source bitmap in pixels.

SrcYE

Specifies the height of the source bitmap in pixels.

lpBits

Points to the buffer that contains or receives the device-independent bitmap bits. If the fGet parameter is zero, the buffer must contains the bitmap bits to be copied to the device or device-specific bitmap. If fGet is 1, the buffer receives bitmap bits copied from the device or bitmap.

lpBitmapInfo

Points to a BITMAPINFO structure specifying the dimensions and format of the device-independent bitmap. The structure has the following form:

typedef struct tagBITMAPINFO {

BITMAPINFOHEADER bmiHeader;

RGBQUAD bmiColors[1];

} BITMAPINFO;

lpTranslate

Points to an array of color translation values for converting palette colors to actual device colors. This parameter is ignored by devices that do not use color palettes.

dwRop

Specifies the raster operation to use during stretching and compressing. The dwRop 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 the current brush. Depending on the specified raster operation, the brush may be used during the stretching or compressing of the bitmap.

lpDrawMode

Points to a DRAWMODE structure specifying the color information the function 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;

lpClipRect

Points to a RECT structure specifying the clipping rectangle. The structure has the following form:

typedef struct tagRECT {

short left;

short top;

short right;

short bottom;

} RECT;

Return Value

The return value is the number of scan lines copied. Otherwise, it is zero if the function encounters an error or no scan lines copied. The return value is -1 if GDI needs to simulate the operation.

Comments

The export ordinal for this function is 28.

For Windows 3.x, the source bitmap will always be a DIB (with the fGet
parameter set to zero). The destination bitmap can be either a memory bitmap
or the actual device surface.

See Also

DeviceBitmapBits, SetDIBitsToDevice, StretchBlt