GpiImage

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

Syntax

 * 1) define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */
 * 2) include 

HPS hps; /* Presentation-space handle. */ LONG lFormat; /* Format of image data. */ PSIZEL psizlImageSize; /* Size of image area (in pels). */ LONG lLength; /* Length in bytes of image data. */ PBYTE pbData; /* Image data. */ LONG lHits; /* Correlation and error indicators. */

lHits = GpiImage(hps, lFormat, psizlImageSize, lLength, pbData); 

Parameters
This is a reserved field; must be set to 0. The maximum width allowed is 2 040. It must be greater than 0.
 * hps (HPS) - input : Presentation-space handle.
 * lFormat (LONG) - input : Format of image data.
 * psizlImageSize (PSIZEL) - input : Size of image area (in pels).
 * lLength (LONG) - input : Length in bytes of image data.
 * 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
One order for each pel row of the image.
 * Element Type: OCODE_GCBIMG
 * Order: Begin Image at Current Position
 * Order: Image Data
 * 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. 
 * 1) define INCL_GPIPRIMITIVES /* GPI primitive functions */
 * 2) include 

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
• GpiSetBackColor • GpiSetBackMix • GpiSetColor • GpiSetMix
 * GpiSetAttrs