Export (0) Print
Expand All
4 out of 14 rated this helpful - Rate this topic

CreateDIBSection function

The CreateDIBSection function creates a DIB that applications can write to directly. The function gives you a pointer to the location of the bitmap bit values. You can supply a handle to a file-mapping object that the function will use to create the bitmap, or you can let the system allocate the memory for the bitmap.

Syntax


HBITMAP CreateDIBSection(
  _In_   HDC hdc,
  _In_   const BITMAPINFO *pbmi,
  _In_   UINT iUsage,
  _Out_  VOID **ppvBits,
  _In_   HANDLE hSection,
  _In_   DWORD dwOffset
);

Parameters

hdc [in]

A handle to a device context. If the value of iUsage is DIB_PAL_COLORS, the function uses this device context's logical palette to initialize the DIB colors.

pbmi [in]

A pointer to a BITMAPINFO structure that specifies various attributes of the DIB, including the bitmap dimensions and colors.

iUsage [in]

The type of data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi (either logical palette indexes or literal RGB values). The following values are defined.

ValueMeaning
DIB_PAL_COLORS

The bmiColors member is an array of 16-bit indexes into the logical palette of the device context specified by hdc.

DIB_RGB_COLORS

The BITMAPINFO structure contains an array of literal RGB values.

 

ppvBits [out]

A pointer to a variable that receives a pointer to the location of the DIB bit values.

hSection [in]

A handle to a file-mapping object that the function will use to create the DIB. This parameter can be NULL.

If hSection is not NULL, it must be a handle to a file-mapping object created by calling the CreateFileMapping function with the PAGE_READWRITE or PAGE_WRITECOPY flag. Read-only DIB sections are not supported. Handles created by other means will cause CreateDIBSection to fail.

If hSection is not NULL, the CreateDIBSection function locates the bitmap bit values at offset dwOffset in the file-mapping object referred to by hSection. An application can later retrieve the hSection handle by calling the GetObject function with the HBITMAP returned by CreateDIBSection.

If hSection is NULL, the system allocates memory for the DIB. In this case, the CreateDIBSection function ignores the dwOffset parameter. An application cannot later obtain a handle to this memory. The dshSection member of the DIBSECTION structure filled in by calling the GetObject function will be NULL.

dwOffset [in]

The offset from the beginning of the file-mapping object referenced by hSection where storage for the bitmap bit values is to begin. This value is ignored if hSection is NULL. The bitmap bit values are aligned on doubleword boundaries, so dwOffset must be a multiple of the size of a DWORD.

Return value

If the function succeeds, the return value is a handle to the newly created DIB, and *ppvBits points to the bitmap bit values.

If the function fails, the return value is NULL, and *ppvBits is NULL.

This function can return the following value.

Return codeDescription
ERROR_INVALID_PARAMETER

One or more of the input parameters is invalid.

 

Remarks

As noted above, if hSection is NULL, the system allocates memory for the DIB. The system closes the handle to that memory when you later delete the DIB by calling the DeleteObject function. If hSection is not NULL, you must close the hSection memory handle yourself after calling DeleteObject to delete the bitmap.

You cannot paste a DIB section from one application into another application.

CreateDIBSection does not use the BITMAPINFOHEADER parameters biXPelsPerMeter or biYPelsPerMeter and will not provide resolution information in the BITMAPINFO structure.

You need to guarantee that the GDI subsystem has completed any drawing to a bitmap created by CreateDIBSection before you draw to the bitmap yourself. Access to the bitmap must be synchronized. Do this by calling the GdiFlush function. This applies to any use of the pointer to the bitmap bit values, including passing the pointer in calls to functions such as SetDIBits.

ICM: No color management is done.

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
CreateFileMapping
DeleteObject
DIBSECTION
GetDIBColorTable
GetObject
GdiFlush
SetDIBits
SetDIBColorTable

 

 

Build date: 6/12/2013

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.