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( _In_ HDC hdc, _In_ int XDest, _In_ int YDest, _In_ DWORD dwWidth, _In_ DWORD dwHeight, _In_ int XSrc, _In_ int YSrc, _In_ UINT uStartScan, _In_ UINT cScanLines, _In_ const VOID *lpvBits, _In_ const BITMAPINFO *lpbmi, _In_ UINT fuColorUse );
- hdc [in]
A handle to the device context.
- XDest [in]
The x-coordinate, in logical units, of the upper-left corner of the destination rectangle.
- YDest [in]
The y-coordinate, in logical units, of the upper-left corner of the destination rectangle.
- dwWidth [in]
The width, in logical units, of the image.
- dwHeight [in]
The height, in logical units, of the image.
- XSrc [in]
The x-coordinate, in logical units, of the lower-left corner of the image.
- YSrc [in]
The y-coordinate, in logical units, of the lower-left corner of the image.
- uStartScan [in]
The starting scan line in the image.
- cScanLines [in]
The number of DIB scan lines contained in the array pointed to by the lpvBits parameter.
- lpvBits [in]
A pointer to the color data stored as an array of bytes. For more information, see the following Remarks section.
- lpbmi [in]
A pointer to a BITMAPINFO structure that contains information about the DIB.
- fuColorUse [in]
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.
ICM: Color management is performed if color management has been enabled with a call to SetICMMode with the iEnableICM parameter set to ICM_ON. If the bitmap specified by lpbmi has a BITMAPV4HEADER that specifies the gamma and endpoints members, or a BITMAPV5HEADER that specifies either the gamma and endpoints members or the profileData and profileSize members, then the call treats the bitmap's pixels as being expressed in the color space described by those members, rather than in the device context's source color space.
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]|