Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
SetDIBitsToDevice

SetDIBitsToDevice function

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.

Syntax


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
);

Parameters

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.

ValueMeaning
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 value

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.

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

Examples

For an example, see Testing a Printer for JPEG or PNG Support.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Wingdi.h (include Windows.h)

Library

Gdi32.lib

DLL

Gdi32.dll

See also

Bitmaps Overview
Bitmap Functions
BITMAPINFO
GetSystemPaletteEntries
SetDIBits
StretchDIBits

 

 

Community Additions

ADD
Show:
© 2015 Microsoft