PgDrawImage(), PgDrawImagev(), PgDrawImageCx(), PgDrawImageCxv()

Draw an image

Synopsis:

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

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

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

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

Library:

ph

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 the dimensions specified by the PhDim_t structure pointed to by size.

---

PgDrawImage() and PgDrawImageCx() don't draw an image if there isn't enough room in the draw buffer to store at least one scan line. PgDrawImagev() and PgDrawImageCxv() act the same way if the image isn't in shared memory. PgDrawImage() and PgDrawImagev() work on the current draw context, while you can specify the draw context dc for PgDrawImageCx() and PgDrawImageCxv(). Instead of using these functions, we recommend using a PhImage_t structure and calling one of the PgDrawPhImage*() functions. These functions automatically handle palettes, transparency, and so on.

---

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 (see the QNX Neutrino Utilities Reference). To calculate the tag, use PtCRC(). 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. For information on the possible types, see PhImage_t.

---

If you call the “v” forms 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:

PgDrawPhImage*(), PgDrawRepPhImagev(), PgDrawTImage*(), PgFlush*(), PgSetFillColor*(), PgSetPalette*(), PgShmemCreate(), PhDim_t, PhImage_t, PhMakeTransBitmap(), PhMakeTransparent(), PhPoint_t, PtCRC(), PxLoadImage()

“Images” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide