img_decode_callouts_t

Decoder callout table

Synopsis:

#include <img/img.h>

typedef struct {
    img_decode_choose_format_f      *choose_format_f;
    img_decode_setup_f              *setup_f;
    img_decode_abort_f              *abort_f;
    img_decode_scanline_f           *scanline_f;
    img_decode_set_palette_f        *set_palette_f;
    img_decode_set_transparency_f   *set_transparency_f;
    img_decode_frame_f              *frame_f;
    img_decode_set_value_f          *set_value_f;
    uintptr_t                       data;

} img_decode_callouts_t;

Description:

The img_decode_callouts_t structure defines a decoder callout table. It provides the decoder with a list of callouts for it to invoke at various stages of the decoding:

img_decode_choose_format_f *choose_format_f

A pointer to a function that chooses a format for the image from the list provided by the decoder. You will get this callout first (unless the format was preselected, in which case it will not be called at all).

The function takes this form:

typdef unsigned (img_decode_choose_format_f) (
        uintptr_t data,
        img_t *img,
        const img_format_t *formats,
        unsigned nformats );

The arguments for this function are:

data
Application data — the value of the data member of the img_decode_callouts_t.
img
A pointer to a partially filled img_t structure providing vital information about the frame.
formats
An array of possible img_format_t formats to choose from.
nformats
The number of elements in the formats array.

If you do not supply a choose_format() callout, the library will supply a default that chooses the first format in the list.

The function should return an index within the formats array, or an out-of-bounds value (for example, nformats) to indicate that no format was desired; the decoder will error out with IMG_ERR_NOSUPPORT.

Alternatively, it can return an out-of-bounds value (for example, nformats) to indicate that none of the formats were acceptable. In this case it can pick a different format by setting img->format and asserting the IMG_FORMAT bit of img->flags. In this case, the end result will be the same as if this format was initially selected before load time.

img_decode_setup_f* setup_f

A pointer to a function that does any setup required to begin frame decoding.

The function takes this form:

typedef int (img_decode_setup_f) ( uintptr_t data,
                                   img_t *img,
                                   unsigned flags );

The arguments for this function are:

data
Application data — the value of the data member of the img_decode_callouts_t.
img
A pointer to a partially filled img_t structure providing vital information about the frame being decoded.
flags
Flags to provide hints about the data and how it will arrive, which may influence assumptions and actions your function takes. Flags can have the following values:
  • IMG_SETUP_PAL_SHARED — the palette (if any) can be shared between this and other frames in the decoding. This is meaningful for multiple frame formats, but can otherwise be ignored.
  • IMG_SETUP_TOP_DOWN — scanlines are completed in order, moving from the top down
  • IMG_SETUP_BOTTOM_UP — scanlines are completed in order, moving from the bottom up
  • IMG_SETUP_MULTIPASS — scanline processing is fragmented across multiple passes (for example, planar and some interlacing schemes).

Your setup function can, but does not have to, set up the access field for the img_t. This field tells the decoder how to record the image data being decoded. You set this up by setting up either img->access.direct or img->access.indirect and asserting the appropriate flags, IMG_DIRECT or IMG_INDIRECT.

Alternatively, the code that called img_decode_frame() (or img_load_file() etc) could set this up before calling img_deocode_frame(), img_load_file(), and so on, or you can rely on the library's default behavior, which is to allocate memory from system RAM for the image and/or palette (the library will do this only if the IMG_DIRECT, IMG_INDIRECT and IMG_PALETTE flags aren't already set).

If you rely on this default behavior, you can later free the memory by simply freeing img_t::access.direct.data or img_t::palette (but not both). You only need to do this if the image decode succeeds, and only once you are done with the image. You do not need to worry about freeing if the decoding fails, as it's taken care of automatically.

It should return IMG_ERR_OK if everything is ok, otherwise return some other error code. Anything other than IMG_ERR_OK causes the decoding to stop and the error code is propagated back to the application.

img_decode_abort_f* abort_f

A pointer to a function that called if the decoding fails (after setup_f has been called). The library will automatically release any memory it allocated as part of the setup (if you have relied on the default behavior described above in img_decode_setup_f).

The function takes this form:

typedef void (img_decode_abort_f) (
        uintptr_t data,
        img_t *img );

The arguments for this function are:

data
Application data — the value of the data member of the img_decode_callouts_t.
info
A pointer to an img_t structure that needs to be released.

img_decode_scanline_f* scanline_f

A pointer to a function that's invoked to notify the application when a scanline has been decoded.

The function takes this form:

typedef int (img_decode_scanline_f) (
        uintptr_t data,
        img_t *img,
        unsigned row,
        unsigned npass_line,
        unsigned npass_total );


The arguments for this function are:

data
Application data — the value of the data member of the img_decode_callouts_t.
img
A pointer to an img_t describing the frame.
row
The index of the scanline that has been decoded. Scanlines are numbered starting at 0 (topmost scanline) to (h - 1), where h represents the height of the image.
npass_line
The number of additional passes required (after this pass) to complete the scanline. Planar formats and some interlaced formats partition scanlines across multiple passes, delivering only portions of the data at a time (this is the case when the IMG_SETUP_MULTIPASS flag bit is set in the setup_f() callout). You know the scanline is complete when this value is 0.
npass_total
The number of additional scanline passes remaining (after this pass) to complete the entire frame. You will know the frame is complete when this value is passed in as 0.

This total includes partial passes, where the IMG_SETUP_MULTIPASS flag was set in the setup_f() callout. If this flag was not set, then a "scanline pass" is equivalent to "scanline completion", that is, npass_total reflects the number of lines left to be decoded. In either case, this value gives you a gauge of the total work left versus what has already been completed.

This function should return IMG_ERR_OK to continue decoding or some other value to abort the decoding. The code you return is propagated back to the application. Normally IMG_ERR_INTR is a good value to use in this case, unless there's another value you wish to use.

img_decode_set_transparency_f* set_transparency_f

A pointer to a function that notifies the application that the image has a transparency color, which means that the designer of the image intented for a particular color in the image to be treated as though it were transparent. Pixels of that color in the source image should not be rendered to the destination.

Note: This function is called only for image formats that support transparency in the form of a color mask (as opposed to transparency achieved through alpha blending), which currently only applies to the GIF format.

The function takes this form:

typedef void (img_decode_set_transparency_f) (
        uintptr_t data,
        img_t *img,
        img_color_t color );

The arguments for this function are:

data
Application data — the value of the data member of the img_decode_callouts_t.
img
A pointer to an img_t describing the frame.
color
The color to treat as transparent. The value will be:
  • an index number (0-255) for palette-based or IMG_FMT_G8
  • a 16-bit value for 16bpp formats (encoding is the same as the image format)
  • a 32-bit value for 24 or 32 bpp formats (encoding is IMG_FMT_PKHE_ARGB8888)
Note: The transparency field of the img_t will have already been set up by the time you receive this callout. The only reason for this callout is to do additional processing as a result of the presence of the transparency.

img_decode_set_palette_f* set_palette_f

A pointer to a function that notifies the application of an image's palette. This function is called after setup before any decoding of the body is done.

If you do not supply a callout, or the supplied callout returns nonzero, the library copies the palette data into the buffer pointed to by img->palette (if the IMG_PALETTE flag bit is set), converting the data to IMG_FMT_PKHE_ARGB8888 as necessary (the proper representation of an img_color_t). If you supply a callout that returns 0, no copying takes place.

The function takes this form:

typedef int (img_decode_set_palette_f) (
        uintptr_t data,
        img_t *img,
        const uint8_t *palette,
        img_format_t format );

The arguments for this function are:

data
Application data — the value of the data member of the img_decode_callouts_t.
img
A pointer to an img_t describing the frame.
palette
A pointer to a palette that is set for the image. The format of the palette data is described by format.
format
The format of the palette. Return 0 if you want the palette data copied to img->palette, or nonzero to indicate that you don't want this copy/conversion to take place.

It should return IMG_ERR_OK if everything is ok, otherwise return some other error code. Anything other than IMG_ERR_OK causes the decoding to stop and the error code is propagated back to the application.

img_decode_frame_f* frame_f

A pointer to a function that is called once a frame is successfully decoded.

The function takes this form:

typedef void ( img_decode_frame_f ) (
        uintptr_t data,
        img_t *img );


img_decode_set_value_f* set_value_f

A pointer to a function that is called to tell the application about additional properties encountered in the file.

The function takes this form:

typedef int (img_decode_set_value_f) (
        uintptr_t data,
        img_t *img,
        unsigned type,
        uintptr_t value );



Some image file formats specify additional information not represented in an img_t, for example DPI, x/y position, comments, and so on. The purpose of this callout is to provide a way for the application to receive this information.

Currently, this callout is called only when processing progressive images (such as progressive JPEG image files).

The arguments for this function are:

data
Application data — the value of the data member of the img_decode_callouts_t.
img
A pointer to an img_t describing the frame.
type
IMG_VALUE_TYPE_PROGRESSIVE
value
0 for a non-progressive image, or 1 for progressive one.
Note: This callout might not be invoked for non-progressive images.

It should return IMG_ERR_OK if everything is OK, otherwise return some other error code. Anything other than IMG_ERR_OK causes the decoding to stop and the error code to be propagated back to the application.

uintptr_t data

User-defined data passed as an additional argument to callouts.

Classification:

Image library