GpiImage

This function draws a rectangular image, with the top-left corner at the current position.

Syntax

GpiImage(hps, lFormat, psizlImageSize, lLength, pbData)

Parameters

hps (HPS) - input

Presentation-space handle.

lFormat (LONG) - input

Format of image data.

This is a reserved field; must be set to 0.

psizlImageSize (PSIZEL) - input

Size of image area (in pels).

The maximum width allowed is 2 040.

lLength (LONG) - input

Length in bytes of image data.

It must be greater than 0.

pbData (PBYTE) - input

Image data.

Return Code

lHits (LONG) - returns

Correlation and error indicators.

• GPI_OK : Successful
• GPI_HITS : Correlate hits
• 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_IMAGE_FORMAT (0x2084)

An invalid lFormat parameter was specified with GpiImage.

PMERR_INV_IMAGE_DATA_LENGTH (0x2082)

An invalid lLength parameter was specified with GpiImage. There is a mismatch between the image size and the data length.

PMERR_INV_IMAGE_DIMENSION (0x2083)

An invalid psizlImageSize parameter was specified with GpiImage.

Remarks

All images are a rectangular array of pels (display points), each pel being represented by one bit. psizlImageSize, which defines the width and height of the image, determines how many pels there are in the horizontal and vertical directions.

pbData determines which of the pels are visible; a 1 bit sets the associated pel, using the image foreground color and mix, and a 0 bit sets the pel using the image background color and mix.

The top left-hand corner of the image is placed at the current position, and the data supplied is drawn row by row, starting at the top. Each row is drawn from left to right and must be padded out to an integral number of bytes if the image width specified is not a multiple of 8. For example, if the image width specified is 12, each row of data must be padded out to a length of 16 so that the data in the row occupies exactly 2 bytes.

Within each byte the high-order bit is drawn on the left.

The length of image data specified must include the padding of each row of data. The length must be given in bytes, and an error message is issued if it is wrong.

If the image is being stored in a metafile, then (((pels_per_row + 9) / 8) * pels_per_column) + 10, must be less than 32768.

Because of the different sizes of pels for different devices, the relationship of the image with respect to other graphics primitives is device-dependent.

The current position remains unchanged after the image has been drawn.

Graphic Elements and Orders

• Element Type: OCODE_GCBIMG
• Order: Begin Image at Current Position
• Order: Image Data

One order for each pel row of the image.

• Order: End Image

Example Code

This example uses GpiImage to draw an 8-x-8 image. The image data is specified as an array of bytes.

#define INCL_GPIPRIMITIVES /* GPI primitive functions */
#include <os2.h>

HPS hps;                        /* presentation space handle */
SIZEL sizl = { 8, 8 };          /* image is 8 pels wide by 8 pels high */
BYTE abImage[] = { 0x00, 0x18, 0x3c, 0x7e, 0xff, 0xff, 0x7e, 0x3c, 0x18, 0x00 }; /* image data */

GpiImage(hps, 0L, &sizl, 8L, abImage); /* draws the image */

Related Functions

• GpiSetAttrs
• GpiSetBackColor
• GpiSetBackMix
• GpiSetColor
• GpiSetMix