SetDIBitsToDevice

int SetDIBitsToDevice(hdc, XDest, YDest, dwWidth, dwHeight, XSrc, YSrc, uStartScan, cScanLines, lpvBits, lpbmi, fuColorUse)
HDC hdc;	/* handle of device context	*/
int XDest;	/* origin of destination rect	*/
int YDest;	/* origin of destination rect	*/
DWORD dwWidth;	/* source rectangle width	*/
DWORD dwHeight;	/* source rectangle height	*/
int XSrc;	/* origin of source rect	*/
int YSrc;	/* origin of source rect	*/
UINT uStartScan;	/* first scan line in array	*/
UINT cScanLines;	/* number of scan lines	*/
LPVOID lpvBits;	/* address of array with DIB bits	*/
LPBITMAPINFO lpbmi;	/* address of structure with bitmap info	*/
UINT fuColorUse;	/* RGB or palette indices	*/

The SetDIBitsToDevice function sets the pixels in the given rectangle on the device that is associated with the destination device-context using color data from a device-independent bitmap (DIB).

Parameters

hdc

Identifies the device context.

XDest

Specifies the logical x-coordinate of the origin of the destination rectangle.

YDest

Specifies the logical y-coordinate of the origin of the destination rectangle.

dwWidth

Specifies the width of the DIB.

dwHeight

Specifies the height of the DIB.

XSrc

Specifies the x-coordinate of the of the DIB origin.

YSrc

Specifies the y-coordinate of the DIB origin.

uStartScan

Specifies the starting scan-line in the DIB.

cScanLines

Specifies the number of DIB scan lines which are contained buffer at which lpvBits points.

lpvBits

Points to DIB color-data stored as an array of bytes.

lpbmi

Points to a BITMAPINFO data structure that contains information about the DIB. The BITMAPINFO structure has the following form:

typedef struct tagBITMAPINFO { /* bmi */

BITMAPINFOHEADER bmiHeader;

RGBQUAD bmiColors[1];

} BITMAPINFO;

fuColorUse

Specifies whether the bmiColors member of the BITMAPINFO data structure contains explicit RGB values or indices into a palette. The fuColorUse parameter must be one of the following values:

Value

Meaning

DIB_PAL_COLORS
	The color table consists of an array of 16-bit indices into the currently selected logical palette.
DIB_PAL_INDICES
	There is no color table for the bitmap. The DIB bits consist of indices into the system palette. No color translation occurs.
DIB_RGB_COLORS
	The color table contains literal RGB values.

Return Value

The return value is the number of scan lines set if the function is successful. Otherwise it is zero.

Comments

Optimal bitmap drawing speed is obtained when the bitmap bits are indices into the system palette.

Applications can retrieve the system palette colors and indices by calling the GetSystemPaletteEntries function. Once the colors and indices are retrieved, the application can create the DIB. (For more information about the system palette, see Chapter 70, “Colors and Color Palettes.”)

The device context identified by hdc is used only if the DIB_PAL_COLORS constant is set for fuColorUse; otherwise it is ignored.

The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.

The origin of a device-independent bitmap is the bottom-left corner of the bitmap, not the top-left corner.

To reduce the amount of memory required to set bits from a large device-independent bitmap on a device surface, an application can band the output by repeatedly calling SetDIBitsToDevice and placing a different portion of the entire bitmap into the lpvBits buffer each time. The values of the uStartScan and cScanLines parameters identify the portion of the entire bitmap that is contained in the lpvBits buffer.