SetDIBitsToDevice

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 device-independent bitmap (DIB).

Windows 98 and Windows NT 5.0: SetDIBitsToDevice has been extended to allow a JPEG image to be passed as the source image.

int SetDIBitsToDevice(
  HDC hdc,              // handle to device context
  int XDest,            // x-coordinate of upper-left corner of 
                        // dest. rect.
  int YDest,            // y-coordinate of upper-left corner of 
                        // dest. rect.
  DWORD dwWidth,        // source rectangle width
  DWORD dwHeight,       // source rectangle height
  int XSrc,             // x-coordinate of lower-left corner of 
                        // source rect.
  int YSrc,             // y-coordinate of lower-left corner of 
                        // source rect.
  UINT uStartScan,      // first scan line in array
  UINT cScanLines,      // number of scan lines
  CONST VOID *lpvBits,  // address of array with DIB bits
  CONST BITMAPINFO *lpbmi,  // address of structure with bitmap info.
  UINT fuColorUse       // RGB or palette indexes
);
 

Parameters

hdc

Handle to the device context.

XDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

YDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

dwWidth

Specifies the width, in logical units, of the DIB.

dwHeight

Specifies the height, in logical units, of the DIB.

XSrc

Specifies the x-coordinate, in logical units, of the lower-left corner of the DIB.

YSrc

Specifies the y-coordinate, in logical units, of the lower-left corner of the DIB.

uStartScan

Specifies the starting scan line in the DIB.

cScanLines

Specifies the number of DIB scan lines contained in the array pointed to by the lpvBits parameter.

lpvBits

Pointer to DIB color data stored as an array of bytes. For more information, see the following Remarks section.

lpbmi

Pointer to a BITMAPINFO structure that contains information about the DIB.

fuColorUse

Specifies 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.

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indexes into the currently selected logical palette.
DIB_RGB_COLORS	The color table contains literal RGB values

Return Values

If the function succeeds, the return value is the number of scan lines set.

If the function fails, the return value is zero.

Windows NT: To get extended error information, call GetLastError.

Windows 98, Windows NT 5.0 and later: If the driver cannot support the JPEG file image passed to SetDIBitsToDevice, the function will fail and return GDI_ERROR.

Remarks

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 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 device-independent bitmap 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.

Windows 98, Windows NT 5.0 and later:

If the biCompression member of BITMAPINFOHEADER is BI_JPEG, lpvBits points to a buffer containing a JPEG image. The biSizeImage member of BITMAPINFOHEADER specifies the size of the buffer. The fuColorUse parameter must be set to DIB_RGB_COLORS.

If the bV4Compression member of BITMAPV4HEADER is BI_JPEG, lpvBits points to a buffer containing a JPEG image. The bV4SizeImage member of BITMAPV4HEADER specifies the size of the buffer. The fuColorUse parameter must be set to DIB_RGB_COLORS.

If the bV5Compression member of BITMAPV5HEADER is BI_JPEG, lpvBits points to a buffer containing a JPEG image. The bV5SizeImage member of BITMAPV5HEADER specifies the size of the buffer. The fuColorUse parameter must be set to DIB_RGB_COLORS.

ICM: Color management is performed. If the specified BITMAPNFO structure is not BITMAPV4HEADER or BITMAPV5HEADER, the color profile of the current device context is used as the source color space profile. If the BITMAPINFO structure is not BITMAPV4HEADER or BITMAPV5HEADER, the sRGB color space is used. If the specified BITMAPINFO structure is BITMAPV4HEADER or BITMAPV5HEADER, the color space profile associated with the bitmap is used as the source color space.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in wingdi.h.
  Import Library: Use gdi32.lib.

See Also

Bitmaps Overview, Bitmap Functions, BITMAPINFO, GetSystemPaletteEntries, SetDIBits, StretchDIBits