The SetDIBitsToDevice function sets the pixels in the specified rectangle on the device that is associated with the destination device context using color data from a DIB, JPEG, or PNG image.
int SetDIBitsToDevice( HDC hdc, int xDest, int yDest, DWORD w, DWORD h, int xSrc, int ySrc, UINT StartScan, UINT cLines, const VOID *lpvBits, const BITMAPINFO *lpbmi, UINT ColorUse );
A handle to the device context.
The x-coordinate, in logical units, of the upper-left corner of the destination rectangle.
The y-coordinate, in logical units, of the upper-left corner of the destination rectangle.
The width, in logical units, of the image.
The height, in logical units, of the image.
The x-coordinate, in logical units, of the lower-left corner of the image.
The y-coordinate, in logical units, of the lower-left corner of the image.
The starting scan line in the image.
The number of DIB scan lines contained in the array pointed to by the lpvBits parameter.
A pointer to the color data stored as an array of bytes. For more information, see the following Remarks section.
A pointer to a BITMAPINFO structure that contains information about the DIB.
Indicates whether the bmiColors member of the BITMAPINFO structure contains explicit red, green, blue (RGB) values or indexes into a palette. For more information, see the following Remarks section.
The fuColorUse parameter must be one of the following values.
||The color table consists of an array of 16-bit indexes into the currently selected logical palette.|
||The color table contains literal RGB values.|
If the function succeeds, the return value is the number of scan lines set.
If zero scan lines are set (such as when dwHeight is 0) or the function fails, the function returns zero.
If the driver cannot support the JPEG or PNG file image passed to SetDIBitsToDevice, the function will fail and return GDI_ERROR. If failure does occur, the application must fall back on its own JPEG or PNG support to decompress the image into a bitmap, and then pass the bitmap to SetDIBitsToDevice.
Optimal bitmap drawing speed is obtained when the bitmap bits are indexes into the system palette.
Applications can retrieve the system palette colors and indexes by calling the GetSystemPaletteEntries function. After the colors and indexes are retrieved, the application can create the DIB. For more information about the system palette, see Colors.
The scan lines must be aligned on a DWORD except for RLE-compressed bitmaps.
The origin of a bottom-up DIB is the lower-left corner of the bitmap; the origin of a top-down DIB is the upper-left corner.
To reduce the amount of memory required to set bits from a large DIB on a device surface, an application can band the output by repeatedly calling SetDIBitsToDevice, placing a different portion of the bitmap into the lpvBits array each time. The values of the uStartScan and cScanLines parameters identify the portion of the bitmap contained in the lpvBits array.
The SetDIBitsToDevice function returns an error if it is called by a process that is running in the background while a full-screen MS-DOS session runs in the foreground.
- If the biCompression member of BITMAPINFOHEADER is BI_JPEG or BI_PNG, lpvBits points to a buffer containing a JPEG or PNG image. The biSizeImage member of specifies the size of the buffer. The fuColorUse parameter must be set to DIB_RGB_COLORS.
- To ensure proper metafile spooling while printing, applications must call the CHECKJPEGFORMAT or CHECKPNGFORMAT escape to verify that the printer recognizes the JPEG or PNG image, respectively, before calling SetDIBitsToDevice.
For an example, see Testing a Printer for JPEG or PNG Support.
|Minimum supported client||Windows 2000 Professional [desktop apps only]|
|Minimum supported server||Windows 2000 Server [desktop apps only]|
|Header||wingdi.h (include Windows.h)|