Jump to content

GpiCreateBitmap: Difference between revisions

From EDM2
Created page with "This function creates a bit map and returns the bit-map handle. ==Syntax== <PRE> #define INCL_GPIBITMAPS Or use INCL_GPI, INCL_PM,: #include <os2.h> HPS hps; /* Presenta..."
 
No edit summary
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
This function creates a bit map and returns the bit-map handle.
This function creates a bit map and returns the bit-map handle.
==Syntax==
==Syntax==
<PRE>
GpiCreateBitmap(hps, pbmpNew, flOptions, pbInitData, pbmiInfoTable)
#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>
==Parameters==
==Parameters==
; hps (HPS) - input : Presentation-space handle.
; 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 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.
the bit map is held in a format compatible with the device.


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


; flOptions (ULONG) - input : Options.
; 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
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.
features known to be supported by the particular device driver.
Line 28: Line 17:
* CBM_INIT : Initialize the bit map with pbInitData .
* CBM_INIT : Initialize the bit map with pbInitData .


; pbInitData (PBYTE) - input : Buffer address.
; 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
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.
doubleword aligned address to assure correct creation of the bit map by the device in device specific format.


; pbmiInfoTable (PBITMAPINFO2) - input : Pointer to the bit-map information table.
; 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.
This defines the format of the data in pbInitData . It is ignored if CBM_INIT is not set.


==Return Code==
==Return Code==
; hbm (HBITMAP) - returns : Bit-map handle and error indicators.
; hbm ([[HBITMAP]]) - returns : Bit-map handle and error indicators.
* <>0:  New bit-map handle
* <>0:  New bit-map handle
* GPI_ERROR: Error.
* GPI_ERROR: Error.
Line 61: Line 50:
Reference for additional details.
Reference for additional details.
==Example Code==
==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.
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>
<PRE>
Line 84: Line 86:


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


[[Category:Gpi]]
[[Category:Gpi]]

Latest revision as of 23:28, 7 April 2025

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 (PBITMAPINFOHEADER2) - 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 (PBITMAPINFO2) - 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

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

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.

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

Related Functions