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.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPIPRIMITIVES
 
LONG GpiImage(hps, lFormat, psizl, cbData, pbData)
HPS hps;         /* presentation-space handle                       */
LONG lFormat;    /* image data format                               */
PSIZEL psizl;    /* address of structure for image width and height */
LONG cbData;     /* length in bytes of the image data               */
PBYTE pbData;    /* address of image data                           */
 
The GpiImage function draws an image. An image is a rectangular array of
pels, each pel having either the current foreground or background color.
Each image has a width and height specified by the psizl parameter. The
width and height determines how many pels there are in the horizontal and
vertical directions.
 
GpiImage draws the image by using the image data pointed to by the pbData
parameter to set the color of each pel in the image. Each pel is represented
by one bit in the image data. If the bit is 1, the pel has the foreground
color; if the bit is 0, the pel has the background color. The function
combines each pel with the color already on the display by using the
foreground mix mode for foreground pels and the background mix mode for
background pels. The function places the upper-left corner of the image at
the current position but does not change the current position.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
lFormat    Specifies the format of the image data. This is a reserved field;
           it must be set to zero.
 
psizl      Points to a SIZEL structure containing the width and height of
           the image in pels. The maximum width allowed is 2040 pixels.
 
cbData     Specifies the length in bytes of the image data.
 
pbData     Points to the image data. The pels must be given, row by row,
           starting at the top and running from left to right within each
           row.
 
Return Value
 
The return value is GPI_OK or GPI_HITS if the function is successful (it is
GPI_HITS if the detectable attribute is set for the presentation space and a
correlation hit occurs). The return value is GPI_ERROR if an error occurs.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_INV_HPS
     PMERR_INV_IMAGE_DATA_LENGTH
     PMERR_INV_IMAGE_DIMENSION
     PMERR_INV_IMAGE_FORMAT
     PMERR_PS_BUSY
 
Comments
 
The image data is an array of bytes. Each byte in the array represents eight
pels, with the high bit representing the leftmost pel. The function draws
the image from left to right and top to bottom. For each row of the image,
the function continues to read bytes from the array until all pels in the
row are set. If the image width is not a multiple of 8, any remaining bits
in the last byte for the row are ignored. The function continues until all
rows are set. This means the number of bytes in the image data (and the
length specified for the data) must be equal to the height in pels
multiplied by the width in bytes.
 
Example
 
This example uses GpiImage to draw an 8-by-8 image. The image data is
specified as an array of bytes.
 
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 };
 
GpiImage(hps, 0L, &sizl, 8L, abImage);            /* draws the image */
 
See Also
 
GpiSetAttrs, WinGetLastError, IMAGEBUNDLE, SIZEL
 
                                      ♦