SetDIBitsToDevice

3.0

  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.

Parameters

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.

Return Value

The return value is the number of scan lines set, if the function is successful.

Comments

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.

See Also

SetDIBits