Encoder callout table
#include <img/img.h> typedef struct { img_encode_choose_format_f *choose_format_f; img_encode_setup_f *setup_f; img_encode_abort_f *abort_f; img_encode_scanline_f *scanline_f; img_encode_set_palette_f *get_palette_f; img_encode_set_transparency_f *get_transparency_f; img_encode_frame_f *frame_f; uintptrt_t data; } img_encode_callouts_t;
The img_encode_callouts_t structure defines an encoder callout table. It provides the encoder with a list of callouts for it to invoke at various stages of the encoding:
img_encode_choose_format_f *choose_format_f
A pointer to a function that chooses an alternate format for the image from the list provided by the decoder. This is the first callout called during an encode, but it will only be called if the format of the supplied image cannot be represented by the encoder. In this case, the application may prepare to provide the data in one of the formats requested, or it may abort the encode altogether.
The function takes this form:
typdef unsigned (img_encode_choose_format_f) ( uintptrt_t data, const 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 choose the format that best matches the provided image, and it will automatically convert the data to that format as needed.
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 encoder will error out with IMG_ERR_NOSUPPORT.
A pointer to a function that does any setup required to begin frame encoding.
The function takes this form:
typedef int (img_encode_setup_f) ( uintptrt_t data, img_t *img, unsigned flags );
The arguments for this function are:
This function should return IMG_ERR_OK if everything is ok, otherwise return some other error code. Anything other than IMG_ERR_OK causes the encode to stop and the error code is propagated back to the application.
A pointer to a function that called if the encode fails (after setup_f() has been called).
The function takes this form:
typedef void (img_encode_abort_f) ( uintptrt_t data, img_t *img );
The arguments for this function are:
img_encode_scanline_f* scanline_f
A pointer to a function that's invoked to notify the application when a scanline has been encoded.
The function takes this form:
typedef int (img_encode_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 encoded. 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 encoding or some other value to abort the encode. 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_encode_get_transparency_f* get_transparency_f
A pointer to a function that satisfies the request of the image transparency color. You only need to provide this function if, for some reason, the transparency color is not accurately represented in the transparency field of the img_t.
The function takes this form:
typedef int (img_encode_get_transparency_f) ( uintptrt_t data, img_t *img, img_color_t *color );
The arguments for this function are:
This function should return IMG_ERR_OK to signify the validity of the requested field. If some other value is returned, the encoder will ignore the transparency and it will not be represented in the resulting encoded data. The encode will proceed regardless.
img_encode_get_palette_f* get_palette_f
A pointer to a function that satisfies the request of an image's palette. You only need to provide this function if, for some reason, the palette is not accurately represented in the img_t.
The function takes this form:
typedef int (img_encode_get_palette_f) ( uintptrt_t data, img_t *img, uint8_t *palette, img_format_t format );
The arguments for this function are:
This function should return IMG_ERR_OK if everything is ok, otherwise return some other error code. Anything other than IMG_ERR_OK causes the encode 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 encoded.
The function takes this form:
typedef void ( img_encode_frame_f ) ( uintptrt_t data, img_t *img );
The arguments for this function are:
User-defined data passed as an additional argument to callouts.
Image library