PhImage_t

Data and characteristics of an image

Synopsis:

typedef struct PhImage
{
    int         type;
    unsigned long     image_tag;
    int         bpl;
    PhDim_t     size;
    unsigned long     palette_tag;
    int         colors;
    PgAlpha_t   *alpha;
    PgColor_t   transparent;
    char        format;
    char        flags;
    char        ghost_bpl;
    char        spare1;
    char        *ghost_bitmap;
    int         mask_bpl;
    char        *mask_bm;
    PgColor_t   *palette;
    char        *image;
} PhImage_t;

Description:

The PhImage_t structure describes the data and characteristics of an image. When you give an image to a PtLabel subclass widget, this is the structure you must provide. To get a pointer to this structure, use PhCreateImage() or PxLoadImage(). To free the allocated members of this structure, call PhReleaseImage().

The structure contains at least the following members:

int type

The graphic type; see “Image types,” below.

unsigned long image_tag

The image-data tag, a cyclic redundancy check (CRC) that's used extensively by phrelay (see the QNX Neutrino Utilities Reference) to cache images.

This tag is filled in automatically for images created in PhAB or by PxLoadImage(). If you're creating an image in some other way, you should fill in the tag by calling PtCRC(), passing it the image pixel data and the size of that data.

int bpl

The number of bytes in each line of the image.

PhDim_t size

A PhDim_t structure that defines the size of the image.

unsigned long palette_tag

The palette-data tag.

int colors

The number of colors in the image.

PgAlpha_t *alpha

The image alpha map that's used if the source alpha map option is enabled.

PgColor_t transparent

The color to mask out when drawing.

char format

Not used.

char flags

The image flags. The valid bits are:

• Ph_RELEASE_IMAGE—free the image data.
• Ph_RELEASE_PALETTE—free the palette data.
• Ph_RELEASE_TRANSPARENCY_MASK—free the transparency mask bitmap.
• Ph_RELEASE_GHOST_BITMAP—free the bitmap used for ghosting.
• Ph_RELEASE_IMAGE_ALL—free all the above.
• Ph_USE_TRANSPARENCY — make the image transparent by using the color specified by the transparent member as the key for a chroma operation.

A widget automatically frees the memory pointed to by the PhImage_t members if these bits are set. Calling PhReleaseImage() with an image frees any resources that have the corresponding bit set in the image flags.

char ghost_bpl

The number of bytes per line for the ghosting bitmap.

char *ghost_bitmap

A pointer to the transparency mask for ghosting an image. The leftmost pixel corresponds to the top bit of the first byte in the mask.

int mask_bpl

The number of bytes per line for the transparency mask.

char *mask_bm

A pointer to the transparency mask. The leftmost pixel corresponds to the top bit of the first byte in the mask.

PgColor_t *palette

The image palette.

char *image

The image pixel data.

Image types

The types of image are:

Pg_BITMAP_BACKFILL

A bitonal image; the two colors are specified in the color palette.

Pg_BITMAP_TRANSPARENT

A monochrome image with transparent regions. The bits in the image data that are set to 1 are drawn using color palette entry 1; zeros are treated as transparent, so they're not drawn.

Pg_IMAGE_DIRECT_1555

This format has, for each pixel, one bit of alpha, and 5 bits each of red, green, and blue.

Pg_IMAGE_DIRECT_4444

This format has 4 bits of alpha, and 4 bits each of red, green, and blue.

Pg_IMAGE_DIRECT_444

This format requires 2 bytes per pixel. It 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_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_8888

This format is an array of 4-byte color entries. The least significant byte is the blue component, after that there is the green component, following that there is the red component and the most significant byte 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_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 two.

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 two.

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.

For convenience, you can AND Pg_IMAGE_CLASS_MASK with the image type to determine the image's 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.

---

The Pg_BITMAP_BACKFILL and Pg_BITMAP_TRANSPARENT types don't fit into the “image class” scheme. If you're checking the class, check the type against these two constants first. If it doesn't match either of them, check the class as described above.

---

Classification:

Photon

See also:

ApGetImageRes(), PgColor_t, PgDrawPhImage*(), PgDrawPhImageRect*(), PgDrawRepPhImage*(), PhCreateImage(), PhDim_t, PhMakeGhostBitmap(), PhMakeTransBitmap(), PhMakeTransparent(), PhReleaseImage(), PmMemCreateMC(), PmMemFlush(), PxLoadImage()

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