img_t

Information describing an image

Synopsis:

#include <img.h>

typedef struct {
    union {
        struct {
            uint8           *data;
            unsigned        stride;
        } direct;

        struct {
            img_access_f    *access_f;
            Uintptrt        data;
        }               indirect;
    } access;
    unsigned            w, h;
    img_format_t        format;
    unsigned            npalette;
    img_color_t         *palette;
    unsigned            flags;
    union {
            uint8           index;
            uint16          rgb16;
            img_color_t     rgb32;
    }                   transparency;
    unsigned            quality;    
} img_t;

Description:

The img_t structure describes a decoded frame. The members include:

access

A union of two structures, direct and indirect, depending on whether you want the image data to be accessed directly or indirectly. The IMG_DIRECT or IMG_INDIRECT flag should be set to indicate which mode of access is in place.

Using the direct access model, anyone operating on the image data can access it directly via a pointer. The beginning of the image data is pointed to by direct.data, and it is assumed that the data pointed to is a contiguous buffer of h scanlines of direct.stride bytes each.

---

The stride can be much larger (if needed) than the actual number of bytes required to represent a single scanline in the specified format; anyone operating on the image should never overwrite or otherwise give any regard to the “in between” padding bytes.

---

Using the indirect access model, anyone operating on the image data does it through a function; the function pointer is given by indirect.access_f, and indirect.data provides a facility to give your access function some context.

An access function is a function you provide to read or write a run of pixels to or from your image. An access function must be coded either as a reader or writer, there is no way to tell from the parameters the direction of data flow.

    void access_f(uintptr_t data, unsigned x, 
           unsigned y, unsigned n, uint8_t *pixels)
    

• data — the data field (from img_t::access.indirect.data)
• x, y — the x and y position within the image of the pixel run being accessed
• n — the number of pixels in the run
• pixels — pointer to pixel data. If your function is a reader, it should copy the prescribed run of image data to this buffer; if it's a write it should copy the pixels in this buffer to your image

---

The format of the data in pixels will be the same as the format of the image; that is, no data transformation is required at this level. The x, y, and n arguments are guaranteed not to exceed the boundary of your image so you don't have to check for that.

---

w, h

The width and height of the image frame, in pixels. These members are only valid if the IMG_W and IMG_H flag bits are set.

format

The img_format_t format of the image's pixel data. This field is valid if the IMG_FORMAT flag bit is set

npalette

The number of colors in the image palette color table. This field should be used only if the format is palette-based (that is, the IMG_FMT_PALETTE bit is set in format).

palette

The palette color table. This field is valid if the IMG_PALETTE flag bit is set.

flags

Flags indicating which of the fields in the structure are valid. Can be one or more of:

IMG_TRANSPARENCY

The transparency field is valid and the specified color within the image should be treated as transparent.

IMG_FORMAT

The format field is valid.

IMG_W

The w field is valid .

IMG_H

The h field is valid.

IMG_DIRECT

The direct field is valid.

IMG_INDIRECT

The indirect field is valid.

IMG_PALETTE

The palette field is valid.

IMG_QUALITY

The quality field is valid.

transparency

The transparency color. This is valid only if the IMG_TRANSPARENCY flag bit is set. The union field that should be used depends on the format of the image:

• index — for palette-based or grayscale images (the IMG_FMT_PALETTE bit is set in format or the format is IMG_FMT_G8)
• rgb16 — for 16bpp images. Encoded the same as the image data.
• rgb32 — for 24 or 32 bpp RGB images. Encoding is always IMG_FMT_PKHE_ARGB8888.

quality

If the IMG_QUALITY flag is set, the codecs may process the new img_t member unsigned quality. For example, the img_codec_jpg.so will use this value to determine the output quality for encoding. For example, when img_write() is invoked.

Classification:

Image library

See also:

img_decode_callouts_t(), img_decode_frame(), img_decode_validate(), img_load_file()