SetDIBits

3.0

  int SetDIBits(hdc, hbmp, uStartScan, cScanLines, lpvBits, lpbmi, fuColorUse)    
  HDC hdc; /* handle of device context */
  HBITMAP hbmp; /* handle of bitmap, */  
  UINT uStartScan; /* starting scan line */
  UINT cScanLines; /* number of scan lines */
  const void FAR* lpvBits; /* address of array with bitmap bits */
  BITMAPINFO FAR* lpbmi; /* address of structure with bitmap data */
  UINT fuColorUse; /* type of color indices to use */

The SetDIBits function sets the bits of a bitmap to the values given in a device-independent bitmap (DIB) specification.

Parameters

hdc

Identifies the device context.

hbmp

Identifies the bitmap to set the data in.

uStartScan

Specifies the zero-based scan number of the first scan line in the buffer pointed to by the lpvBits parameter.

cScanLines

Specifies the number of scan lines in the lpvBits buffer to copy into the bitmap identified by the hbmp parameter.

lpvBits

Points to the device-independent bitmap bits that are stored as an array of bytes. The format of the bitmap values depends on the biBitCount member of the BITMAPINFOHEADER structure, which is the first member of the BITMAPINFO structure pointed to by the lpbmi parameter.

The BITMAPINFOHEADER structure has the following form:

typedef struct tagBITMAPINFOHEADER {    /* bmih */
    DWORD   biSize;
    LONG    biWidth;
    LONG    biHeight;
    WORD    biPlanes;
    WORD    biBitCount;
    DWORD   biCompression;
    DWORD   biSizeImage;
    LONG    biXPelsPerMeter;
    LONG    biYPelsPerMeter;
    DWORD   biClrUsed;
    DWORD   biClrImportant;
} BITMAPINFOHEADER;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

lpbmi

Points to a BITMAPINFO structure that contains information about the device-independent 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 BITMAPINFO structure 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 palette of the device context identified by the hdc parameter.
DIB_RGB_COLORS The color table contains literal RGB values.

Return Value

The return value is the number of scan lines copied, if the function is successful. Otherwise, it is zero.

Comments

The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.

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 the SetDIBitsToDevice function, 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.

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.

See Also

SetDIBitsToDevice