GpiLoadBitmap

This function creates and loads a bit map from a resource, and returns the bit-map handle.

Syntax
 hbm = GpiLoadBitmap(hps, Resource, idBitmap, lWidth, lHeight); 

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.


 * Resource (HMODULE) - input : Resource identity containing the bit map.
 * NULLHANDLE Use the .EXE file of the application.
 * Other : Module handle returned from the OS/2 DosLoadModule function.

This parameter must be less or equal to 0xFFFF.
 * idBitmap (ULONG) - input : ID of the bit map within the resource file.


 * lWidth (LONG) - input : Width of the bit map in pels.
 * It must be greater or equal to 0.


 * lHeight (LONG) - input : Height of the bit map in pels.
 * It must be greater or equal to 0.

Return Code

 * hbm (HBITMAP) - returns : Bit-map handle.
 * <>0 : 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_BITMAP_NOT_FOUND (0x200A) : A attempt was made to perform a bit-map operation on a bit map that did not exist.
 * PMERR_INV_BITMAP_DIMENSION (0x2048) : An invalid dimension was specified with a load bit-map function.

Remarks
Some bit-map functions, including drawing into the bit map, require it 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 stretched to the specified lWidth and lHeight. If lWidth or lHeight is 0, the bit map is not stretched in that direction; when, for example, lWidth = 0, the bit map is not stretched horizontally, when lHeight = 0, it is not stretched vertically.

The bit map may have been created by the icon editor in bit-map mode.

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.

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.

Example Code
This example uses the GpiLoadBitmap function to load a bit map from the .EXE file into application memory. The bit map is then selected, displayed, and finally, deleted from memory. 
 * 1) define INCL_GPIBITMAPS                  /* GPI bit map functions */
 * 2) include 

HPS hps;                                 /* presentation space handle */ HBITMAP hbm, hbmPrevious;
 * 1) define BITMAP_ID 1

/* load the bit map from the EXE */ hbm = GpiLoadBitmap(hps, NULLHANDLE, BITMAP_ID, 100L, 100L); hbmPrevious = GpiSetBitmap(hps, hbm);  /* select bit map for PS */

/* bit map displayed with GpiBitBlt */

GpiSetBitmap(hps, hbmPrevious);       /* release bit map from PS */ GpiDeleteBitmap(hbm);                 /* delete the bit map */ 

Related Functions

 * GpiBitBlt
 * GpiCreateBitmap
 * GpiDeleteBitmap
 * GpiDrawBits
 * GpiQueryBitmapBits
 * GpiQueryBitmapDimension
 * GpiQueryBitmapHandle
 * GpiQueryBitmapParameters
 * GpiQueryDeviceBitmapFormats
 * GpiSetBitmap
 * GpiSetBitmapBits
 * GpiSetBitmapDimension
 * GpiSetBitmapId
 * GpiWCBitBlt