img_load_resize_file()

Decode and resize a frame from a file on the filesystem

Synopsis:

#include <img.h>

int img_load_resize_file( img_lib_t                    ilib,
                          const char*                  path,
                          const img_decode_callouts_t* callouts,
                          img_t*                       img );

Arguments:

ilib

A handle for the image library, returned by img_lib_attach().

path

The full path to the file from which the data can be read.

callouts

A pointer to an img_decode_callouts_t structure that provides system callouts for the decoder. If you specify NULL for this value, a set of default callouts is supplied.

img

The address of an img_t structure the function fills in with information about the decoded frame.

If you set the image width and height (img.w and img.h) before calling this function, then the image is sized to fit the specified dimensions rather than clipped, as it is with img_load_file(). The resizing is performed on-the-fly during the decoding, without incurring the memory penalty of loading the entire original image and then subsequently resizing it.

If you specify only one of the dimensions, then the other is calculated based on the aspect ratio of the original image.

You need to also set the corresponding dimension flag in the img structure. For example, if you specify the width, you need to set the IMG_W bit in flags.

Library:

img

Description:

This function decodes a frame from a file on the filesystem, and optionally resizes it if the image width and height is specified. This function decodes only the first frame encountered.

At least these callouts are supported:

set_value_f()

Called when processing progressive images (such as progressive JPEG image files), with a type of IMG_VALUE_TYPE_PROGRESSIVE, and a value of 0 for a non-progressive image, or 1 for progressive one.

This callout might not be invoked for non-progressive images.

choose_format_f()

Lets you set the desired width, height, or both within the callout. In img->flags, set IMG_RESIZE along with the appropriate dimension flags, IMG_W, IMG_H, or both.

In order to get the actual image dimensions in the callout's img structure, the img_load_resize_file() function's img.flags must not have IMG_W and IMG_H flags set.

Returns:

IMG_ERR_OK: Success
IMG_ERR_CORRUPT: Invalid data encountered in the file, preventing the decode from proceeding. Some of the frame may be intact.
IMG_ERR_DLL: An error occurred processing the DLL that handles the file type. Check to make sure that the DLL is not missing or corrupt.
IMG_ERR_FILE: Error accessing path (errno is set).
IMG_ERR_FORMAT: No appropriate codec could be found. The codec you require could be missing or corrupt, or the file could be corrupt.
IMG_ERR_INTR: Decode was interrupted by application.
IMG_ERR_MEM: Memory-allocation failure.
IMG_ERR_NODATA: No frame data was present. This error is highly unlikely, as files generally contain at least one frame.
IMG_ERR_NOSUPPORT: Output data not supported; the codec and application could not agree on an output format.
IMG_ERR_TRUNC: Premature end of file encountered. Some of the frame may be intact.

Classification:

Image library

Safety:
Interrupt handler	No
Signal handler	No
Thread	No