Working with images

To use the image library, you must attach to the library by calling img_lib_attach() . When you call this function, the image library initializes and loads the codecs it finds listed in the img.conf configuration file. You can customize this file to load just the codecs your application requires.

Here's an example that demonstrates how to use img_lib_attach():

img_lib_t ilib = NULL;
int rc;

if ((rc = img_lib_attach(&ilib)) != IMG_ERR_OK) {
    fprintf(stderr, "img_lib_attach() failed: %d\n", rc);
    return -1;
}

To load your image, follow these steps:

1. Open the data source for your image.

   The image data must come from a source, such as a file, TCP/IP socket, or memory buffer. This step involves establishing the origin of the data and opening that data source. 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.

   If the image data is stored in a file, you can use the file-based image functions in the image library to work with the data. Otherwise, you can create an input stream to access the data. You can call io_open() to associate an io_stream_t with the data source. Then, you can work with the image data using the stream.

2. Determine the codecs that are available to handle your image.

   You can retrieve a list of all codecs that are registered with the image library by calling img_codec_list() . If you have additional information about the data, you can use several other functions to retrieve a smaller set of available codecs:

   • If you know the MIME type of the image, use img_codec_list_bymime() .
   • If you know the file name extension, use img_codec_list_byext() .
   Note: MIME types and extensions don't necessarily guarantee that the data is in a certain format. If decoding fails because the MIME type or extension is incorrect, you should try one of the other codecs that's returned by img_codec_list().
3. Choose a valid codec.

   This step involves allowing the codecs you've identified to peek at the data to determine which one can handle the data. You can call 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.

4. Initialize 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. The img_decode_begin() function initializes and allocates the resources that the codec needs for the decode operation.

5. Decode frames.

   Decode frames using img_decode_frame() until you're finished or there are no more frames to decode (that is, when img_decode_frame() returns IMG_ERR_NODATA). The img_t structure represents a decoded frame.

6. Finish the decoding.

   Call img_decode_finish() to allow the decoder to clean up after itself. The img_decode_finish() function deallocates resources that the codec used.

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 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 outlined above, except for establishing the input source and associating it with an io_stream_t. This function 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 how to use img_load_file():

int rc;
img_t img;

...

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

/* Preselect a format (that is, force the image to be
   loaded in the format we specify) */
img.format = IMG_FMT_PKLE_ARGB1555;
img.flags |= IMG_FORMAT;

/* Perform optional clipping */
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));

/* Clear the img_t and free any library-allocated memory */
img_reset(&img);

/* Detach from the library */
img_lib_detach(ilib);

After you finish using the image library, you should clean up the resources by unlocking the hardware and freeing any memory that the image library allocated in the img_t structure. For example, consider performing the following clean-up operations: