int SetDIBitsToDevice(hdc, XDest, YDest, cx, cy, XSrc, YSrc, uStartScan, cScanLines, lpvBits, lpbmi, fuColorUse) | |||||
HDC hdc; | /* handle of device context | */ | |||
int XDest; | /* x-coordinate origin of destination rect | */ | |||
int YDest; | /* y-coordinate origin of destination rect | */ | |||
int cx; | /* rectangle width | */ | |||
int cy; | /* rectangle height, */ | ||||
int XSrc; | /* x-coordinate origin of source rect | */ | |||
int YSrc; | /* y-coordinate origin of source rect | */ | |||
UINT uStartScan; | /* number of first scan line in array | */ | |||
UINT cScanLines; | /* number of scan lines | */ | |||
void FAR* lpvBits; | /* address of array with DIB bits | */ | |||
BITMAPINFO FAR* lpbmi; | /* address of structure with bitmap info | */ | |||
UINT fuColorUse; | /* RGB or palette indices | */ |
The SetDIBitsToDevice function sets bits from a device-independent bitmap (DIB) directly on a device surface. The device coordinates specified define a rectangle within the total bitmap. SetDIBitsToDevice sets the bits in this rectangle directly on the display surface of the output device associated with the given device context, at the specified logical coordinates.
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.
cx
Specifies the x-extent, in device units, of the rectangle in the bitmap.
cy
Specifies the y-extent, in device units, of the rectangle in the bitmap.
XSrc
Specifies the x-coordinate, in device units, of the source rectangle in the bitmap.
YSrc
Specifies the y-coordinate, in device units, of the source rectangle in the bitmap.
uStartScan
Specifies the scan-line number of the device-independent bitmap that is contained in the first scan line of the buffer pointed to by the lpvBits parameter.
cScanLines
Specifies the number of scan lines in the lpvBits buffer to copy to the device.
lpvBits
Points to the DIB bits that are stored as an array of bytes.
lpbmi
Points to a BITMAPINFO structure that contains information about the 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 lpbmi parameter 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 currently realized logical palette. |
DIB_RGB_COLORS | The color table contains literal RGB values. |
The return value is the number of scan lines set, if the function is successful.
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.
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, 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.