View source for GpiCreateBitmap

This function creates a bit map and returns the bit-map handle.
==Syntax==
 GpiCreateBitmap(hps, pbmpNew, flOptions, pbInitData, pbmiInfoTable)

==Parameters==
; hps ([[HPS]]) - input : Presentation-space handle.
The associated device should, if possible, hold the bit map in its own memory. Where this is not possible, main memory is used and
the bit map is held in a format compatible with the device.

; pbmpNew (P[[BITMAPINFOHEADER2]]) - input : Pointer to the bit-map information header.
This structure defines the format of the bit map to be created.

; flOptions ([[ULONG]]) - input : Options.
If the bit map is stored on a device, the flOptions parameter is passed to the device. Bits 16 through 31 can be used for special
features known to be supported by the particular device driver.
The following option is supported:
* CBM_INIT : Initialize the bit map with pbInitData .

; pbInitData ([[PBYTE]]) - input : Buffer address.
The address in application storage from which initialization data is to be copied, if CBM_INIT is set. This field must point to a
doubleword aligned address to assure correct creation of the bit map by the device in device specific format.

; pbmiInfoTable (P[[BITMAPINFO2]]) - input : Pointer to the bit-map information table.
This defines the format of the data in pbInitData . It is ignored if CBM_INIT is not set.

==Return Code==
; hbm ([[HBITMAP]]) - returns : Bit-map handle and error indicators.
* <>0:   New bit-map handle
* GPI_ERROR: Error.

==Errors== 
Possible returns from WinGetLastError
; PMERR_INV_HPS (0x207F) : An invalid presentation-space handle was specified.
; PMERR_PS_BUSY (0x20F4) : An attempt was made to access the presentation space from more than one thread simultaneously.
; PMERR_INV_INFO_TABLE (0x208F) : An invalid bit-map info table was specified with a bit-map operation.
; PMERR_INV_USAGE_PARM (0x20D1) : An invalid options parameter was specified with GpiCreateBitmap.

==Remarks==

On some devices it is possible to create the bit map in device memory. Even when this is not possible, a bit map always belongs to a particular device. The device is specified through the device context associated with the specified presentation space. The device context can be any device context that describes the physical device (such as any window device context for the screen).
There are a number of standard bit-map formats that should normally be adhered to. Other formats can be used if supported by the device.

A newly created bit map can be filled with data supplied by the application. This is useful where the bit map always contains, or always starts with, the same image, captured in the application. A bit-map information structure is also passed, which defines the format and color usage of the initialization data. It is assumed that enough data is passed to initialize the entire bit map.

Some bit-map functions, including those that draw into the bit map, require the bit map to be selected into a memory device context, using GpiSetBitmap. This is true whether device or main memory is used to hold the bit map.

The bit map is owned by the process from which this function is issued. It cannot be accessed directly from any other process. If it still exists when the process terminates, it is automatically deleted by the system.

Some restrictions apply when using this function. Refer to "Format of Interchange Files" in the Presentation Manager Programming
Reference for additional details.
==Example Code==
<PRE>
#define INCL_GPIBITMAPS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS hps; /* Presentation-space handle. */
PBITMAPINFOHEADER2 pbmpNew; /* Pointer to the bit-map information header. */
ULONG flOptions; /* Options. */
PBYTE pbInitData; /* Buffer address. */
PBITMAPINFO2 pbmiInfoTable; /* Pointer to the bit-map information table. */
HBITMAP hbm; /* Bit-map handle and error indicators. */

hbm = GpiCreateBitmap(hps, pbmpNew, flOptions, pbInitData, pbmiInfoTable);
</PRE>
The following example loads a bit map resource from memory and uses the GpiCreateBitmap function to create the bit map. This is similar to using the GpiLoadBitmap function, except it gives the application the chance to modify the bit map image data before creating the bit map.
<PRE>
#define INCL_GPIBITMAPS     /* GPI bit map functions */
#define INCL_DOSRESOURCES   /* Dos Resource functions */
#include <os2.h>

HPS hps;                    /* presentation space handle */
                            /* address of bit map image data in resource */
BITMAPINFOHEADER2 bmih;     /* bit map info structure */
HBITMAP hbm;                /* bit map handle */

memset (&bmih,0, sizeof(BITMAPINFOHEADER2));
bmih.cbFix = sizeof(BITMAPINFOHEADER2);
bmih.cx = 32;
bmih.cy = 32;
bmih.cPlanes = 1;
bmih.cBitCount = 32*32;

hbm = GpiCreateBitmap(hps, &bmih, 0L, NULL, NULL);

</PRE>

==Related Functions==
* [[GpiBitBlt]]
* [[GpiDeleteBitmap]]
* [[GpiDrawBits]]
* [[GpiLoadBitmap]]
* [[GpiQueryBitmapBits]]
* [[GpiQueryBitmapDimension]]
* [[GpiQueryBitmapHandle]]
* [[GpiQueryBitmapParameters]]
* [[GpiQueryDeviceBitmapFormats]]
* [[GpiSetBitmap]]
* [[GpiSetBitmapBits]]
* [[GpiSetBitmapDimension]]
* [[GpiSetBitmapId]]
* [[GpiWCBitBlt]]

[[Category:Gpi]]