GpiSetBitmap
This function sets a bit map as the currently selected bit map in a memory device context.
Syntax
GpiSetBitmap(hps, hbm)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- hbm (HBITMAP) - input
- Handle of the bit map to be set.
- A null handle causes the currently selected bit map, in the associated device, to be freed.
It is an error if the bit map is currently tagged for area shading (see GpiSetBitmapId).
Return Code
- hbmOld (HBITMAP) - returns
- Old bit-map handle.
- NULLHANDLE : Correct (null handle)
- HBM_ERROR : Error
- Otherwise : Old bit-map handle.
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_HBITMAP (0x207B)
- An invalid bit-map handle was specified.
- PMERR_BITMAP_IN_USE (0x2008)
- An attempt was made either to set a bit map into a device context using GpiSetBitmap while it was already selected into an existing device context, or to tag a bit map with a local pattern set identifier (setid) using GpiSetBitmapId while it was already tagged with an existing setid.
- PMERR_INCOMPATIBLE_BITMAP (0x203A)
- An attempt was made to select a bit map or perform a BitBlt operation on a device context that was incompatible with the format of the bit map.
- PMERR_HBITMAP_BUSY (0x2032)
- An internal bit map busy error was detected. The bit map was locked by one thread during an attempt to access it from another thread.
Remarks
The specified presentation space must be currently associated with a memory device context. The device context can represent a different physical device from the one that the bit map originally loaded or created, providing its format is convertible to one supported on the new device. This is ensured when one of the standard formats is being used.
If a bit map is already current in the device context, the handle of this bit map is returned, before the new bit map is selected.
It is an error if the new bit map is already selected as the current bit map in any device context.
Example Code
This example uses the GpiSetBitmap function to set a newly created bit map in the device context for the associated presentation space.
Once set, the example initializes the bit map image by drawing in the presentation space.
#define INCL_GPIBITMAPS
#define INCL_GPIPRIMITIVES
#include <OS2.H>
HPS hps; /* Presentation space handle */
BITMAPINFOHEADER2 bmp = {12, 64, 64, 1, 1};/* 64x64 mono bit map */
HBITMAP hbm, hbmOld;
POINTL ptlStart = { 0, 0 };
POINTL aptlTriangle[3] = { 32, 32, 63, 63, 0, 0 };
POINTL ptl = { 63, 63 };
hbm = GpiCreateBitmap(hps,
&bmp,
0L,
NULL,
NULL);
/* Set the bit map and draw in it. */
/* sets bit map in device context */
hbmOld = GpiSetBitmap(hps, hbm);
GpiMove(hps, &ptlStart);
GpiBox(hps, DRO_FILL, &ptl, 0L, 0L); /* fills in the bit map */
GpiPolyLine(hps, /* draws a triangle */
1L,
aptlTriangle);
GpiSetBitmap(hps, hbmOld); /* restores the old bit map */
