Tizen Native API
|
The Image Util APIs provides functions for encoding and decoding of images .
Required Header
#include <image_util.h>
Overview
Image Util API provides support for encoding and decoding of images. The API allows :
- Encoding/Decoding of a JPEG image.
- Encoding/Decoding of a JPEG image to/from memory.
- Image transformation(Colorspace conversion/Resize/Rotate/Crop) .
The decoding of a jpeg image located at a given path, to a buffer can be done by calling image_util_decode_jpeg() function and decoding of a jpeg image on memory can be done by calling image_util_decode_jpeg_from_memory(). Similarly, for encoding image_util_encode_jpeg() and image_util_encode_jpeg_to_memory() functions can be called to encode an image buffer to a jpeg image and a jpeg buffer respectively. The API also allows to transform including convert the colorspace (image_util_colorspace_e) of an image by calling image_util_transform_run() function.
Foreach Operations
FOREACH | CALLBACK | DESCRIPTION |
---|---|---|
image_util_foreach_supported_jpeg_colorspace() | image_util_supported_jpeg_colorspace_cb() | Supported JPEG encoding/decoding colorspace |
Functions | |
int | image_util_transform_create (transformation_h *handle) |
Creates a handle to image util transform. | |
int | image_util_transform_set_hardware_acceleration (transformation_h handle, bool mode) |
Sets the image util's accurate mode. | |
int | image_util_transform_set_colorspace (transformation_h handle, image_util_colorspace_e colorspace) |
Sets the information of the converting. | |
int | image_util_transform_set_resolution (transformation_h handle, unsigned int width, unsigned int height) |
Sets the information of the resizing. | |
int | image_util_transform_set_rotation (transformation_h handle, image_util_rotation_e rotation) |
Sets the information of the rotating. | |
int | image_util_transform_set_crop_area (transformation_h handle, unsigned int start_x, unsigned int start_y, unsigned int end_x, unsigned int end_y) |
Sets the information of the cropping. | |
int | image_util_transform_get_colorspace (transformation_h handle, image_util_colorspace_e *colorspace) |
Gets the colorspace of the image buffer. | |
int | image_util_transform_get_resolution (transformation_h handle, unsigned int *width, unsigned int *height) |
Gets the resolution of the image buffer. | |
int | image_util_transform_get_rotation (transformation_h handle, image_util_rotation_e *rotation) |
Gets the information of the rotating. | |
int | image_util_transform_get_crop_area (transformation_h handle, unsigned int *start_x, unsigned int *start_y, unsigned int *end_x, unsigned int *end_y) |
Gets the information of the cropping. | |
int | image_util_transform_run (transformation_h handle, media_packet_h src, image_util_transform_completed_cb callback, void *user_data) |
Transform the image for given image util handle. | |
int | image_util_transform_destroy (transformation_h handle) |
Destroys a handle to image util. | |
int | image_util_foreach_supported_jpeg_colorspace (image_util_supported_jpeg_colorspace_cb callback, void *user_data) |
Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one. | |
int | image_util_calculate_buffer_size (int width, int height, image_util_colorspace_e colorspace, unsigned int *size) |
Calculates the size of the image buffer for the specified resolution and colorspace. | |
int | image_util_decode_jpeg (const char *path, image_util_colorspace_e colorspace, unsigned char **image_buffer, int *width, int *height, unsigned int *size) |
Decodes the JPEG image to the buffer. | |
int | image_util_decode_jpeg_from_memory (const unsigned char *jpeg_buffer, int jpeg_size, image_util_colorspace_e colorspace, unsigned char **image_buffer, int *width, int *height, unsigned int *size) |
Decodes the JPEG image(in memory) to the buffer. | |
int | image_util_encode_jpeg (const unsigned char *buffer, int width, int height, image_util_colorspace_e colorspace, int quality, const char *path) |
Encodes the image to the JPEG image. | |
int | image_util_encode_jpeg_to_memory (const unsigned char *image_buffer, int width, int height, image_util_colorspace_e colorspace, int quality, unsigned char **jpeg_buffer, unsigned int *jpeg_size) |
Encodes the image to the JPEG image. | |
Typedefs | |
typedef bool(* | image_util_supported_jpeg_colorspace_cb )(image_util_colorspace_e colorspace, void *user_data) |
Called once for each supported JPEG encode/decode colorspace. | |
typedef struct transformation_s * | transformation_h |
Image util handle. | |
typedef void(* | image_util_transform_completed_cb )(media_packet_h *dst, int error_code, void *user_data) |
Called when transform is finished just before returning the output. |
Typedef Documentation
typedef bool(* image_util_supported_jpeg_colorspace_cb)(image_util_colorspace_e colorspace, void *user_data) |
Called once for each supported JPEG encode/decode colorspace.
- Since :
- 2.3.1
- Parameters:
-
[in] colorspace The colorspace [in] user_data The user data passed from the foreach function
- Returns:
true
to continue with the next iteration of the loop,
otherwisefalse
to break out of the loop
- Precondition:
- image_util_foreach_supported_jpeg_colorspace() invokes this callback.
typedef void(* image_util_transform_completed_cb)(media_packet_h *dst, int error_code, void *user_data) |
Called when transform is finished just before returning the output.
- Parameters:
-
[in] error_code The error code of image util transfrom [in,out] dst The result buffer of image util transform [in] user_data The user data passed from the callback registration function
- Precondition:
- image_util_transform_run() will invoke this function.
Enumeration Type Documentation
Enumeration for colorspace.
- Enumerator:
enum image_util_error_e |
Enumeration for error.
- Enumerator:
Function Documentation
int image_util_calculate_buffer_size | ( | int | width, |
int | height, | ||
image_util_colorspace_e | colorspace, | ||
unsigned int * | size | ||
) |
Calculates the size of the image buffer for the specified resolution and colorspace.
- Since :
- 2.3.1
- Parameters:
-
[in] width The image width [in] height The image height [in] colorspace The image colorspace [out] size The Calculated buffer size
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_decode_jpeg | ( | const char * | path, |
image_util_colorspace_e | colorspace, | ||
unsigned char ** | image_buffer, | ||
int * | width, | ||
int * | height, | ||
unsigned int * | size | ||
) |
Decodes the JPEG image to the buffer.
- Since :
- 2.3.1
- Remarks:
- You must release image_buffer using free().
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
- Parameters:
-
[in] path The image file path [in] colorspace The decoded image colorspace [out] image_buffer The image buffer for the decoded image [out] width The image width [out] height The image height [out] size The image buffer size
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_decode_jpeg_from_memory | ( | const unsigned char * | jpeg_buffer, |
int | jpeg_size, | ||
image_util_colorspace_e | colorspace, | ||
unsigned char ** | image_buffer, | ||
int * | width, | ||
int * | height, | ||
unsigned int * | size | ||
) |
Decodes the JPEG image(in memory) to the buffer.
- Since :
- 2.3.1
- Remarks:
- You must release image_buffer using free().
- Parameters:
-
[in] jpeg_buffer The JPEG image buffer [in] jpeg_size The JPEG image buffer size [in] colorspace The decoded image colorspace [out] image_buffer The image buffer for the decoded image [out] width The image width [out] height The image height [out] size The image buffer size
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_encode_jpeg | ( | const unsigned char * | buffer, |
int | width, | ||
int | height, | ||
image_util_colorspace_e | colorspace, | ||
int | quality, | ||
const char * | path | ||
) |
Encodes the image to the JPEG image.
- Since :
- 2.3.1
- Remarks:
- http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
- Parameters:
-
[in] buffer The original image buffer [in] width The original image width [in] height The original image height [in] colorspace The original image colorspace [in] quality The quality for JPEG image encoding (1 ~ 100) [in] path The file path to be created
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_NO_SUCH_FILE No such file IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_encode_jpeg_to_memory | ( | const unsigned char * | image_buffer, |
int | width, | ||
int | height, | ||
image_util_colorspace_e | colorspace, | ||
int | quality, | ||
unsigned char ** | jpeg_buffer, | ||
unsigned int * | jpeg_size | ||
) |
Encodes the image to the JPEG image.
- Since :
- 2.3.1
- Remarks:
- You must release jpeg_buffer using free().
- Parameters:
-
[in] image_buffer The original image buffer [in] width The image width [in] height The image height [in] colorspace The original image colorspace [in] quality The quality for JPEG image encoding (1 ~ 100) [out] jpeg_buffer The created JPEG image buffer
The buffer is created by frameworks[out] jpeg_size The created jpeg image buffer size
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_foreach_supported_jpeg_colorspace | ( | image_util_supported_jpeg_colorspace_cb | callback, |
void * | user_data | ||
) |
Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one.
- Since :
- 2.3.1
- Parameters:
-
[in] callback The callback function to invoke [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
- Postcondition:
- This function invokes image_util_supported_jpeg_colorspace_cb() repeatedly to retrieve each supported JPEG encoding/decoding colorspace.
int image_util_transform_create | ( | transformation_h * | handle | ) |
Creates a handle to image util transform.
- Since :
- 2.3.1
This function creates a handle to image util transform.
- Remarks:
- You must release the image util handle using image_util_transform_destroy().
- Parameters:
-
[out] handle A handle to image util transform
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
- See also:
- image_util_transform_destroy()
int image_util_transform_destroy | ( | transformation_h | handle | ) |
Destroys a handle to image util.
- Since :
- 2.3.1
The function frees all resources related to the image util handle. The image util handle no longer can be used to perform any operation. A new image util handle has to be created before the next usage.
- Parameters:
-
[in] handle The handle to image util transform
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
- See also:
- image_util_transform_create()
int image_util_transform_get_colorspace | ( | transformation_h | handle, |
image_util_colorspace_e * | colorspace | ||
) |
Gets the colorspace of the image buffer.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in,out] colorspace The colorspace of the image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
int image_util_transform_get_crop_area | ( | transformation_h | handle, |
unsigned int * | start_x, | ||
unsigned int * | start_y, | ||
unsigned int * | end_x, | ||
unsigned int * | end_y | ||
) |
Gets the information of the cropping.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in,out] start_x The start x position of cropped source image buffer [in,out] start_y The start y position of cropped source image buffer [in,out] end_x The end x position of cropped source image buffer [in,out] end_y The end y position of cropped source image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_transform_get_resolution | ( | transformation_h | handle, |
unsigned int * | width, | ||
unsigned int * | height | ||
) |
Gets the resolution of the image buffer.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in,out] width The width of source image buffer [in,out] height The height of source image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_transform_get_rotation | ( | transformation_h | handle, |
image_util_rotation_e * | rotation | ||
) |
Gets the information of the rotating.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in,out] rotation The rotation value of image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
- Precondition:
- image_util_transform_create().
image_util_transform_set_rotation().
int image_util_transform_run | ( | transformation_h | handle, |
media_packet_h | src, | ||
image_util_transform_completed_cb | callback, | ||
void * | user_data | ||
) |
Transform the image for given image util handle.
- Since :
- 2.3.1
- Remarks:
- If H/W acceleration is not set, transformation is done via S/W acceleration.
The function execute asynchronously, which contains complete callback
- Parameters:
-
[in] handle The handle of transform [in] src The handle to image util transform [in] callback The callback function to be invoked [in] user_data The user data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
int image_util_transform_set_colorspace | ( | transformation_h | handle, |
image_util_colorspace_e | colorspace | ||
) |
Sets the information of the converting.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in] colorspace The colorspace of the image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
- Precondition:
- image_util_transform_create().
int image_util_transform_set_crop_area | ( | transformation_h | handle, |
unsigned int | start_x, | ||
unsigned int | start_y, | ||
unsigned int | end_x, | ||
unsigned int | end_y | ||
) |
Sets the information of the cropping.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in] start_x The start x position of cropped image buffer [in] start_y The start y position of cropped image buffer [in] end_x The end x position of cropped image buffer [in] end_y The end y position of cropped image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
- Precondition:
- image_util_transform_create().
int image_util_transform_set_hardware_acceleration | ( | transformation_h | handle, |
bool | mode | ||
) |
Sets the image util's accurate mode.
- Since :
- 2.3.1
This function set if you use hardware accerlation or not.
- Remarks:
- The value returned will be IMAGE_UTIL_ERROR_NOT_SUPPORTED, if H/W acceleration doesn't support on the device.
- Parameters:
-
[in] handle The handle to image util [in] mode Set true
, user can use the hardware acceleration
otherwise setfalse
if user can only software image processing
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion IMAGE_UTIL_ERROR_NOT_SUPPORTED The application does not have the hardware acceleration
- Precondition:
- image_util_transform_create().
int image_util_transform_set_resolution | ( | transformation_h | handle, |
unsigned int | width, | ||
unsigned int | height | ||
) |
Sets the information of the resizing.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in] width The width of image buffer [in] height The height of image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
- Precondition:
- image_util_transform_create().
int image_util_transform_set_rotation | ( | transformation_h | handle, |
image_util_rotation_e | rotation | ||
) |
Sets the information of the rotating.
- Since :
- 2.3.1
- Parameters:
-
[in] handle The handle to image util transform [in] rotation The rotation value of image buffer
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
- Precondition:
- image_util_transform_create().