Important Notice
The pages on this site contain documentation for very old MS-DOS software,
purely for historical purposes.
If you're looking for up-to-date documentation, particularly for programming,
you should not rely on the information found here, as it will be woefully
out of date.
GpiCreateBitmap (1.2)
◄Function Group► ◄Overview► ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
#define INCL_GPIBITMAPS
HBITMAP GpiCreateBitmap(hps, pbmpFormat, flOptions, pbData, pbmiData)
HPS hps; /* presentation-space handle */
PBITMAPINFOHEADER pbmpFormat; /* address of structure for format data */
ULONG flOptions; /* options */
PBYTE pbData; /* address of buffer of image data */
PBITMAPINFO pbmiData; /* address of structure for color and format */
The GpiCreateBitmap function creates a bitmap and returns a bitmap handle
identifying the bitmap. The new bitmap has the width, height, and format
specified by fields of the structure pointed to by pbmpFormat. The
flOptions parameter specifies whether to initialize the bitmap color and
image. If the parameter is CBM_INIT, the function uses the bitmap image data
pointed to by pbData and the bitmap color data pointed to by pbmiData to
initialize the bitmap. If CBM_INIT is not given, the bitmap's initial image
and color are undefined.
The bitmap handle can be used in subsequent functions that accept bitmap
handles. In most cases, the bitmap is set to a memory presentation space
using the GpiSetBitmap function, then copied to the screen or a printer
using the GpiBitBlt function.
Parameter Description
────────────────────────────────────────────────────────────────────────────
hps Identifies the presentation space.
pbmpFormat Points to the BITMAPINFOHEADER structure that contains the
bitmap format data.
flOptions Specifies whether to initialize the bitmap. It can one of the
following values:
Value Meaning
────────────────────────────────────────────────────────────────
CBM_INIT Initializes the bitmap, using the bitmap image and
color data specified by the pbData and pbmiData
parameters.
0x0000 Does not initialize the bitmap.
pbData Points to the buffer that contains bitmap image data. The image
data defines the color of each pel in the bitmap. This parameter
is ignored if CBM_INIT is not given.
pbmiData Points to a BITMAPINFO structure that contains the bitmap format
and color data. The format data is identical to the data pointed
to by the pbmpFormat parameter. The color data follows
immediately after the format data, and consists of two or more
RGB color values. The exact number depends on the bitmap format.
This parameter is ignored if CBM_INIT is not given.
Return Value
The return value identifies the new bitmap if the function is successful, or
is GPI_ERROR if an error occurred.
Errors
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
PMERR_INV_HPS
PMERR_INV_INFO_TABLE
PMERR_INV_USAGE
PMERR_INV_USAGE_PARM
PMERR_PS_BUSY
Comments
The full number of bitmap formats depends on what the associated device
supports. However, most devices support the following standard bitmap
formats:
Format Description
────────────────────────────────────────────────────────────────────────────
Monochrome 1 bit per pel and 1 color plane
16-color 4 bits per pel and 1 color plane
256-color 8 bits per pel and 1 color plane
Full-color 24 bits per pel and 1 color plane
When initializing the bitmap, the bitmap color data must consist of an
appropriate number of RGB color values. For monochrome format, it must have
2 values; for 16-color format, 16 values; and for 256-color format, 256
values. No color values are required for the full-color format, since the
image data for each pel fully specifies the pel color.
When CBM_INIT is given, the function continues to copy data from the buffer
until the entire bitmap is initialized. The function expects each row of
image data to contain a multiple of 32 bits (4 bytes). Although the bitmap
width does not have to be a multiple of 32, the image data must be. Any
extra bits at the end of a row are ignored.
The new bitmap belongs to the device context associated with the given
presentation space. It can be set to any presentation space having the same
device context or having a compatible device context.
Example
The following example loads a bitmap resource from memory and uses the
GpiCreateBitmap function to create the bitmap. This is similar to using the
GpiLoadBitmap function, except it gives the application the chance to modify
the bitmap image data before creating the bitmap.
SEL sel; /* selector for segment containing bitmap resource */
PBITMAPFILEHEADER pbfh; /* bitmap resource header information */
PBYTE pb; /* address of bitmap image data in resource */
HBITMAP hbm; /* bitmap handle */
/* load bitmap resource #1 */
DosGetResource((HMODULE) NULL, RT_BITMAP, 1, &sel);
pbfh = MAKEP(sel, 0); /* bitmap file header in resource */
pb = MAKEP(sel, pbfh->offBits); /* image data starts at offBits */
/* make any changes to bitmap image data here */
hbm = GpiCreateBitmap(hps, /* presentation space */
&(pbfh->bmp), /* bitmap information in file */
CBM_INIT, /* initialize the bitmap */
pb, /* bitmap data */
&(pbfh->bmp)); /* bitmap information in file */
DosFreeSeg(sel); /* free bitmap resource */
See Also
DosFreeSeg, DosGetResource, GpiDeleteBitmap, GpiLoadBitmap,
GpiQueryDeviceBitmapFormats, WinGetLastError, BITMAPINFO, BITMAPINFOHEADER
♦