Information describing an image
#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;
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.
Image library
img_decode_callouts_t(),
img_decode_frame(),
img_decode_validate(),
img_load_file()