Load an image

To load an image, follow these steps:

Enumeration of codecs

First, you need a list of codecs that are installed, which you can retrieve by calling
img_codec_list().

Note:
If you have additional information about the data (for example, a mime-type or extension), you could use a variant such as img_codec_list_byext() or img_codec_list_bymime(). This will give you a list of codecs including only those that match the specified criteria. Keep in mind though, that extensions or mime types do not necessarily guarantee the data is of a specific format (that is, they can lie). So it's always good to be prepared to try all the codecs if one that handles the format that data claims to be in fails.

Establishing the underlying input source

The image data has to come from a source, such as a file, TCP/IP socket, or memory buffer. This step involves establishing the origin of the data. This step may involve no work at all (that is, if it's a file already stored in memory), or it may involve opening a file or performing some other task.

The image library decoders need a conventional way to access the data, which is where the IO streams come in. Use io_open() to associate an io_stream_t with the data source from the previous step.

Data recognition

This step involves allowing the codecs you've enumerated to peek at the data to determine which one is capable of handling the data. You can do this with img_decode_validate(), which runs through the list of codecs and indicates which (if any) approved of the data. You can then use that codec to decode the data.

Initializing the decoder

This step notifies the decoder of an imminent decode operation, and allows it to set up any resources it may require. Use img_decode_begin() to perform this step.

Decoding frames

Decode frames using img_decode_frame() until you're finished or there are no more (when img_decode_frame() returns IMG_ERR_NODATA).

This function takes care of all the steps, except for establishing the input source and associating it with an io_stream_t. This provides the convenience of img_load_file() but lifts the file only restriction. Like img_load_file(), it's limited to loading only the first frame.