PgDrawImage(), PgDrawImagemx()

Draw an image

Synopsis:

int PgDrawImage( void const *ptr, 
                 int type,
                 PhPoint_t const *pos,
                 PhDim_t const *size,
                 int bpl, 
                 long tag );

int PgDrawImagemx( void const *ptr,
                   int type,
                   PhPoint_t const *pos,
                   PhDim_t const *size,
                   int bpl, 
                   long tag );

Description:

These functions build a command in the draw buffer to draw an image. The functions start the image at pos and extend it down and to the right according to size.

Instead of using this function, we recommend using a PhImage_t structure and calling PgDrawPhImagemx(). To make one of the colors in the image transparent, call PhMakeTransBitmap().

The bpl argument indicates the number of bytes per line of image data (that is, the offset from one line of data to the next).

To calculate the size of the data transferred to the graphics driver, multiply bpl by size.y. You can determine the size and bpl arguments with the value returned by PxLoadImage().

The tag argument is used for data caching by programs such as phrelay. To calculate the tag, use PxCRC(). This argument is ignored if you set it to 0.

The type argument controls how the image data pointed to by ptr is interpreted by the graphics driver. You can set type to one of the following:

Pg_IMAGE_PALETTE_BYTE

This format packs 1 pixel per byte, allowing up to 256 colors. This format indexes directly into the current palette; see PgSetPalette(). If no palette is set, the function chooses colors from the global palette; this may cause colors to look different on each system.

Pg_IMAGE_PALETTE_NIBBLE

This format packs 2 pixels per byte, allowing up to 16 colors. The first pixel is in the upper half of the byte, the second is in the lower half. These pixel values index directly into the current palette. If no palette is set, the function chooses colors from the global palette.

Pg_IMAGE_DIRECT_8888

This format is an array of 4-byte color entries. The first byte is the red component, the second is the green, the third is the blue, and the fourth is reserved.

Pg_IMAGE_DIRECT_888

This format packs each pixel into 3 bytes. Using this format, you can represent a full 24 bit color image. Here's the bit order:

RRRR.RRRR.GGGG.GGGG.BBBB.BBBB

Pg_IMAGE_DIRECT_555

This format packs each pixel into 2 bytes. Although it allows only 32 levels of each color, this format provides reasonable image reproduction with less data. Here's the bit order:

xRRR.RRGG.GGGB.BBBB

Pg_IMAGE_DIRECT_565

This format packs each pixel into 2 bytes and matches the display format of most 16-bit, direct-color, graphics drivers. Here's the bit order:

RRRR.RGGG.GGGB.BBBB

Pg_IMAGE_DIRECT_444

This format requires 2 bytes per pixel. This format matches the high-speed color lookup tables used by palette-based graphics drivers and provides the fastest method of drawing direct-color images with palette-based graphics drivers. Here's the bit order:

xxxx.RRRR.GGGG.BBBB

Pg_IMAGE_GRADIENT_BYTE

This format uses 1 byte per pixel. The colors are algorithmically generated as a gradient between the color set by PgSetFillColor() and the color set by PgSetTextColor(). A pixel value of 0 produces the "fill color", a pixel value of 255 produces the "text color", and a pixel value of 128 produces an even blend of the fill and text colors.

Pg_IMAGE_GRADIENT_NIBBLE

This format packs 2 pixels per byte, allowing up to 16 levels. The first pixel is in the upper half of the byte and the second pixel is in the lower half. The colors are algorithmically generated as a gradient between the color set by PgSetFillColor() and the color set by PgSetTextColor(). A pixel value of 0 produces the "fill color", a pixel value of 15 produces the "text color", and a pixel value of 8 produces an even blend of the fill and text colors.

For convenience, the following masks can be applied to type to determine the image's class:

• Pg_IMAGE_CLASS_MASK - AND this constant with the image type to determine its class.
• Pg_IMAGE_CLASS_PALETTE - the image requires a palette defined by PgSetPalette().
• Pg_IMAGE_CLASS_GRADIENT - the image requires first and last colors defined by PgSetFillColor() and PgSetTextColor().
• Pg_IMAGE_CLASS_DIRECT - each pixel defines its red, blue, and green components.

If you call the "mx" form of this function, the data isn't physically copied into the draw buffer. Instead, a pointer to the array is stored until the draw buffer is flushed. Make sure you call PgFlush() before you modify the image. If the data is in shared memory, the mx form of this function will automatically pass a shared memory reference instead of the image.

Returns:

0

Success.

-1

The draw buffer is too small to hold the current draw state, the draw command, and one pixel line of the image. Increase the size of the draw buffer or decrease the width of the image.

Examples:

The following example:

PhImage_t    *pimage;

InitPalImage() {
  if (pimage != NULL) return;
  if ((pimage = PxLoadImage( "mackface.bmp", NULL )) == NULL) {
    perror( "Unable to load image" );
    return;
  }
}

DrawPalImage() {
  PhPoint_t    p = { 0, 0 };
    
  InitPalImage();
  if (pimage == NULL) return;
  if ((pimage->palette != NULL) && (pimage->colors > 0))
        PgSetPalette( pimage->palette, 0, 0, pimage->colors, 
                      Pg_PALSET_SOFT, 0 );
    PgDrawImage( pimage->image, pimage->type, &p, 
                 &pimage->size, pimage->bpl, 0 );
}

will draw:

Classification:

Photon

See also:

PgDrawTImage(), PgFlush(), PgSetFillColor(), PgSetPalette(), PgShmemCreate(), PhMakeTransBitmap(), PxCRC(), PxLoadImage()