GpiLoadBitmap

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

Syntax

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.

idBitmap (ULONG) - input

ID of the bit map within the resource file.

This parameter must be less or equal to 0xFFFF.

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

#define INCL_GPIBITMAPS /* Or use INCL_GPI, INCL_PM, Also in COMMON section */
#include <os2.h>

HPS        hps;       /*  Presentation-space handle. */
HMODULE    Resource;  /*  Resource identity containing the bit map. */
ULONG      idBitmap;  /*  ID of the bit map within the resource file. */
LONG       lWidth;    /*  Width of the bit map in pels. */
LONG       lHeight;   /*  Height of the bit map in pels. */
HBITMAP    hbm;       /*  Bit-map handle. */

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

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.

#define INCL_GPIBITMAPS                   /* GPI bit map functions */
#include <os2.h>

HPS hps;                                  /* presentation space handle */
HBITMAP hbm, hbmPrevious;
#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