PgDrawBitmap(), PgDrawBitmapv(), PgDrawBitmapCx(), PgDrawBitmapCxv()

Draw a bitmap

Synopsis:

int  PgDrawBitmap( void const *ptr,
                   int flags,
                   PhPoint_t const *pos,
                   PhPoint_t const *size,
                   int bpl,
                   long tag );

int  PgDrawBitmapv( void const *ptr,
                    int flags,
                    PhPoint_t const *pos,
                    PhPoint_t const *size,
                    int bpl,
                    long tag );

int  PgDrawBitmapCx( void *dc,
                     void const *ptr,
                     int flags,
                     PhPoint_t const *pos,
                     PhPoint_t const *size,
                     int bpl,
                     long tag );

int  PgDrawBitmapCxv( void *dc,
                      void const *ptr,
                      int flags,
                      PhPoint_t const *pos,
                      PhPoint_t const *size,
                      int bpl,
                      long tag );

Arguments:

dc

PgDrawBitmapCx() and PgDrawBitmapCxv() only. A void pointer to any type of draw context. Examples of draw contexts are:

• a PhDrawContext_t returned by PhDCCreate()
• a PmMemoryContext_t returned by PmMemCreateMC()
• a PpPrintContext_t returned by PpCreatePC()
• a PdOffscreenContext_t returned by PdCreateOffscreenContext()

ptr

A pointer to the bitmap data.

flags

Drawing flags. Can be 0 or Pg_BACK_FILL (see below).

pos

The starting position for the bitmap.

size

The size of the bitmap.

bpl

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

tag

Used for data caching by programs such as phrelay (see the QNX Neutrino Utilities Reference). This argument is ignored if you set it to 0. To calculate a tag value, use PtCRC().

Library:

ph

Description:

These functions build a command in the draw buffer to draw a bitmap. The function starts the bitmap at pos and extends it down and to the right according to size.

PgDrawBitmap() and PgDrawBitmapv() work on the current draw context, while you can specify the draw context for PgDrawBitmapCx() and PgDrawBitmapCxv().

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 a PxLoadImage() call.

The data pointed to by ptr is one bit per pixel. If the pixel value is 1, the pixel is drawn with the color set by PgSetTextColor() or PgSetTextDither(). If the pixel value is 0, the pixel is drawn as transparent unless you've set flags to Pg_BACK_FILL. With Pg_BACK_FILL, the pixel is drawn with the color set by PgSetFillColor() or PgSetFillDither(). The pixels are drawn most significant bit first.

---

If you call the “v” or “Cxv”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 bitmap. If the data is in shared memory, the mx form of this function will automatically pass a shared memory reference instead of the bitmap.

---

Returns:

0

Successful completion

-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:

PhPoint_t TestBitmapSize = { 64, 64 };
int TestBitmapBPL = 8;
char TestBitmap[64*8] = { "512 bytes of bitmap data" };

DrawSimpleBitmap() {
    PhPoint_t p = { 8, 8 };

    PgSetTextColor( Pg_WHITE );
    PgDrawBitmap( TestBitmap, 0, &p,
                  &TestBitmapSize, TestBitmapBPL, 0 );
}

will draw:

The following example:

DrawBackFillBitmap() {
    PhPoint_t p = { 8, 8 };

    PgSetTextColor( Pg_WHITE );
    PgSetFillColor( Pg_PURPLE );
    PgDrawBitmap( TestBitmap, Pg_BACK_FILL, &p,
                  &TestBitmapSize, TestBitmapBPL, 0 );
}

will draw:

Classification:

Photon

See also:

PgDrawRepBitmap*(), PgFlush*(), PgSetFillColor*(), PgSetFillDither*(), PgSetTextColor*(), PgSetTextDither*(), PgShmemCreate(), PhPoint_t, PtCRC(), PxLoadImage()

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