int SetDIBits(hdc, hbmp, uStartScan, cScanLines, lpvBits, lpbmi, fuColorUse) | |||||
HDC hdc; | /* handle of device context | */ | |||
HBITMAP hbmp; | /* handle of bitmap, */ | ||||
UINT uStartScan; | /* starting scan line | */ | |||
UINT cScanLines; | /* number of scan lines | */ | |||
const void FAR* lpvBits; | /* address of array with bitmap bits | */ | |||
BITMAPINFO FAR* lpbmi; | /* address of structure with bitmap data | */ | |||
UINT fuColorUse; | /* type of color indices to use | */ |
The SetDIBits function sets the bits of a bitmap to the values given in a device-independent bitmap (DIB) specification.
hdc
Identifies the device context.
hbmp
Identifies the bitmap to set the data in.
uStartScan
Specifies the zero-based scan number of the first scan line in the buffer pointed to by the lpvBits parameter.
cScanLines
Specifies the number of scan lines in the lpvBits buffer to copy into the bitmap identified by the hbmp parameter.
lpvBits
Points to the device-independent bitmap bits that are stored as an array of bytes. The format of the bitmap values depends on the biBitCount member of the BITMAPINFOHEADER structure, which is the first member of the BITMAPINFO structure pointed to by the lpbmi parameter.
The BITMAPINFOHEADER structure has the following form:
typedef struct tagBITMAPINFOHEADER { /* bmih */
DWORD biSize;
LONG biWidth;
LONG biHeight;
WORD biPlanes;
WORD biBitCount;
DWORD biCompression;
DWORD biSizeImage;
LONG biXPelsPerMeter;
LONG biYPelsPerMeter;
DWORD biClrUsed;
DWORD biClrImportant;
} BITMAPINFOHEADER;
For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.
lpbmi
Points to a BITMAPINFO structure that contains information about the device-independent bitmap. The BITMAPINFO structure has the following form:
typedef struct tagBITMAPINFO { /* bmi */
BITMAPINFOHEADER bmiHeader;
RGBQUAD bmiColors[1];
} BITMAPINFO;
For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.
fuColorUse
Specifies whether the bmiColors member of the BITMAPINFO structure contains explicit RGB values or indices into the currently realized logical palette. This 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 palette of the device context identified by the hdc parameter. |
DIB_RGB_COLORS | The color table contains literal RGB values. |
The return value is the number of scan lines copied, if the function is successful. Otherwise, it is zero.
The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.
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 the SetDIBitsToDevice function, 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.
The origin of a device-independent bitmap is the bottom-left corner of the bitmap, not the top-left corner, which is the origin when the mapping mode is MM_TEXT. GDI performs the necessary transformation to display the image correctly.