![[Previous]](../prev.gif) |
![[Contents]](../contents.gif) |
![[Index]](../keyword_index.gif) |
![[Next]](../next.gif) |
|
|
|
|
Decoder callout table
#include <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;
uintptrt_t data;
} img_decode_callouts_t;
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 decode.
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) (
uintptrt_t data,
img_t *img,
const img_format_t *formats,
unsigned nformats );
The arguments for this function are:
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.
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) ( uintptrt_t data,
img_t *img,
unsigned flags );
The arguments for this function are:
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 behaviour, 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 behaviour, 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 decode 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 decode to stop and the error code is propagated back to the application.
A pointer to a function that called if the decode 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 behaviour described above in img_decode_setup_f).
The function takes this form:
typedef void (img_decode_abort_f) (
uintptrt_t data,
img_t *img );
The arguments for this function are:
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) (
uintptrt_t data,
img_t *img,
unsigned row,
unsigned npass_line,
unsigned npass_total );
The arguments for this function are:
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 decode. 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.
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.
 |
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) (
uintptrt_t data,
img_t *img,
img_color_t color );
The arguments for this function are:
|
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. |
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) (
uintptrt_t data,
img_t *img,
const uint8_t *palette,
img_format_t format );
The arguments for this function are:
It should return IMG_ERR_OK if everything is ok, otherwise return some other error code. Anything other than IMG_ERR_OK causes the decode to stop and the error code is propagated back to the application.
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 ) (
uintptrt_t data,
img_t *img );
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) (
uintptrt_t data,
img_t *img,
unsigned type,
uintptrt_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.
At present time, none of the QNX-provided decoders use this callout and no types are defined. It is a placeholder callout.
User-defined data passed as an additional argument to callouts.
Image library
img_format_t, img_decode_frame(), IMG_FMT_BPL(), img_load_file()
|
|
|
|