Load an image

To load an image, follow these steps:

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

3. Associating the image library conventional IO interface with the input source

   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.

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

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

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

7. Finalizing the decoding

   Call img_decode_finish() to allow the decoder to clean up after itself.

Although this process may seem complicated, there are two higher-level API calls that simplify the process:

img_load_file()

This function takes care of all of the steps outlined above. However, this function loads only the first frame, and works only with a file source.

img_load()

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.

Here's an example of using img_load_file():

int rc;
img_t img;

...

/* initialize an img_t by setting its flags to 0 */
img.flags = 0;

/* if we want, we can preselect a format (ie force the image to be
   loaded in the format we specify) by enabling the following two
   lines */

img.format = IMG_FMT_PKLE_ARGB1555;
img.flags |= IMG_FORMAT;

/* likewise, we can 'clip' the loaded image by enabling the following */

img.w = 100;
img.flags |= IMG_W;

img.h = 100;
img.flags |= IMG_H;

if ((rc = img_load_file(ilib, argv[optind], NULL, &img)) != IMG_ERR_OK) {
        fprintf(stderr, "img_load_file(%s) failed: %d\n", argv[optind], rc);
        return -1;
}

fprintf(stdout, "img is %dx%dx%d\n", img.w, img.h, IMG_FMT_BPP(img.format));



/* for our purposes we're done with the img lib */
img_lib_detach(ilib);