img_t

Information describing an image

Synopsis:

#include <img/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.

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

Note: 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.
IMG_PAL8_ALPHA: The PAL8 image palette contains alpha data. Therefore, color values can be treated as 8888 instead of 888.
IMG_TRANSPARENCY_TO_ALPHA: Convert transparency into alpha values if supported by destination format. This capability allows transparency to be utilized even if chroma is not supported.
IMG_SRC_FMT_TRANSPARENCY: Indicates whether or not the source image contains any type of transparency. This flag is set by the Image library only. Applications can't set this flag, but they can use it to determine the existence of transparency for optimizations.

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