img_encode_callouts_t

Encoder callout table

Synopsis:

#include <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;

Description:

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 encode. 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_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:

data

Application data -- the value of the data member of the img_encode_callouts_t.

img

A pointer to the img_t structure describing the frame being encoded.

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 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.

img_encode_setup_f* setup_f

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:

data

Application data — the value of the data member of the img_encode_callouts_t.

img

A pointer to the img_t structure describing the frame being encoded.

flags

Flags to provide hints about how the data will be encoded, which may influence assumptions and actions your function takes. It can have the following values:

• IMG_SETUP_TOP_DOWN — scanlines are encoded in order, moving from the top down
• IMG_SETUP_BOTTOM_UP — scanlines are encoded in order, moving from the bottom up
• IMG_SETUP_MULTIPASS — scanline are fragmented across multiple passes (for example, planar and some interlacing schemes).

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.

img_encode_abort_f* abort_f

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:

data

Application data — the value of the data member of the img_encode_callouts_t.

img

A pointer to the img_t structure describing the frame being encoded.

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:

data

Application data — the value of the data member of the img_encode_callouts_t.

img

A pointer to an img_t describing the frame being encoded.

row

The index of the scanline that has been encoded. Scanlines are numbered starting at 0 (the topmost scanline) to image height - 1.

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, encoding 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 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:

data

Application data — the value of the data member of the img_encode_callouts_t.

img

A pointer to an img_t describing the frame.

color

A pointer to an img_color_t to fill with the transparent color. The format of this data should match the format of the frame data itself.

---

If you do not provide this callout, the library will automatically use and convert the image transparency field as needed.

---

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 *palette,
        img_format_t format );

The arguments for this function are:

data

Application data — the value of the data member of the img_encode_callouts_t.

img

A pointer to an img_t describing the frame being encoded.

palette

A pointer to a buffer to fill with palette data.

format

The format that the encoder is expecting the palette data to be in.

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.

img_encode_frame_f* frame_f

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:

data

Application data — the value of the data member of the img_encode_callouts_t.

img

A pointer to an img_t describing the frame being encoded.

uintptrt_t data

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

Classification:

Image library

See also:

img_format_t, img_encode_frame(), IMG_FMT_BPL(), img_write_file()