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]colorspaceThe colorspace
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
otherwise false to break out of the loop
Precondition:
image_util_foreach_supported_jpeg_colorspace() invokes this callback.
See also:
image_util_foreach_supported_jpeg_colorspace()
image_util_encode_jpeg()
image_util_encode_jpeg_to_memory()
image_util_decode_jpeg()
image_util_decode_jpeg_from_memory()
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_codeThe error code of image util transfrom
[in,out]dstThe result buffer of image util transform
[in]user_dataThe user data passed from the callback registration function
Precondition:
image_util_transform_run() will invoke this function.

Enumeration Type Documentation

Enumeration for colorspace.

Enumerator:
IMAGE_UTIL_COLORSPACE_YV12 

YV12 - YCrCb planar format

IMAGE_UTIL_COLORSPACE_YUV422 

YUV422 - planar

IMAGE_UTIL_COLORSPACE_I420 

YUV420 - planar

IMAGE_UTIL_COLORSPACE_NV12 

NV12- planar

IMAGE_UTIL_COLORSPACE_UYVY 

UYVY - packed

IMAGE_UTIL_COLORSPACE_YUYV 

YUYV - packed

IMAGE_UTIL_COLORSPACE_RGB565 

RGB565, high-byte is Blue

IMAGE_UTIL_COLORSPACE_RGB888 

RGB888, high-byte is Blue

IMAGE_UTIL_COLORSPACE_ARGB8888 

ARGB8888, high-byte is Blue

IMAGE_UTIL_COLORSPACE_BGRA8888 

BGRA8888, high-byte is Alpha

IMAGE_UTIL_COLORSPACE_RGBA8888 

RGBA8888, high-byte is Alpha

IMAGE_UTIL_COLORSPACE_BGRX8888 

BGRX8888, high-byte is X

IMAGE_UTIL_COLORSPACE_NV21 

NV12- planar

IMAGE_UTIL_COLORSPACE_NV16 

NV16- planar

IMAGE_UTIL_COLORSPACE_NV61 

NV61- planar

Enumeration for error.

Enumerator:
IMAGE_UTIL_ERROR_NONE 

Successful

IMAGE_UTIL_ERROR_INVALID_PARAMETER 

Invalid parameter

IMAGE_UTIL_ERROR_OUT_OF_MEMORY 

Out of memory

IMAGE_UTIL_ERROR_NO_SUCH_FILE 

No such file

IMAGE_UTIL_ERROR_INVALID_OPERATION 

Internal error

IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT 

Not supported format

IMAGE_UTIL_ERROR_PERMISSION_DENIED 

Permission denied

IMAGE_UTIL_ERROR_NOT_SUPPORTED 

Not supported

Enumeration for rotation.

Enumerator:
IMAGE_UTIL_ROTATION_NONE 

None

IMAGE_UTIL_ROTATION_90 

Rotation 90 degree

IMAGE_UTIL_ROTATION_180 

Rotation 180 degree

IMAGE_UTIL_ROTATION_270 

Rotation 270 degree

IMAGE_UTIL_ROTATION_FLIP_HORZ 

Flip horizontal

IMAGE_UTIL_ROTATION_FLIP_VERT 

Flip vertical


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]widthThe image width
[in]heightThe image height
[in]colorspaceThe image colorspace
[out]sizeThe Calculated buffer size
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_transform_run()
image_util_decode_jpeg()
image_util_decode_jpeg_from_memory()
image_util_encode_jpeg()
image_util_encode_jpeg_to_memory()
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]pathThe image file path
[in]colorspaceThe decoded image colorspace
[out]image_bufferThe image buffer for the decoded image
[out]widthThe image width
[out]heightThe image height
[out]sizeThe image buffer size
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_OUT_OF_MEMORYout of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMATFormat not supported
IMAGE_UTIL_ERROR_INVALID_OPERATIONInvalid operation
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_supported_jpeg_colorspace_cb()
image_util_decode_jpeg_from_memory()
image_util_foreach_supported_jpeg_colorspace()
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_bufferThe JPEG image buffer
[in]jpeg_sizeThe JPEG image buffer size
[in]colorspaceThe decoded image colorspace
[out]image_bufferThe image buffer for the decoded image
[out]widthThe image width
[out]heightThe image height
[out]sizeThe image buffer size
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_OUT_OF_MEMORYout of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMATFormat not supported
IMAGE_UTIL_ERROR_INVALID_OPERATIONInvalid operation
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_supported_jpeg_colorspace_cb()
image_util_decode_jpeg()
image_util_foreach_supported_jpeg_colorspace()
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]bufferThe original image buffer
[in]widthThe original image width
[in]heightThe original image height
[in]colorspaceThe original image colorspace
[in]qualityThe quality for JPEG image encoding (1 ~ 100)
[in]pathThe file path to be created
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_NO_SUCH_FILENo such file
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMATFormat not supported
IMAGE_UTIL_ERROR_INVALID_OPERATIONInvalid operation
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_supported_jpeg_colorspace_cb()
image_util_foreach_supported_jpeg_colorspace()
image_util_encode_jpeg_to_memory()
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_bufferThe original image buffer
[in]widthThe image width
[in]heightThe image height
[in]colorspaceThe original image colorspace
[in]qualityThe quality for JPEG image encoding (1 ~ 100)
[out]jpeg_bufferThe created JPEG image buffer
The buffer is created by frameworks
[out]jpeg_sizeThe created jpeg image buffer size
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_OUT_OF_MEMORYout of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMATFormat not supported
IMAGE_UTIL_ERROR_INVALID_OPERATIONInvalid operation
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_supported_jpeg_colorspace_cb()
image_util_foreach_supported_jpeg_colorspace()
image_util_encode_jpeg()

Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one.

Since :
2.3.1
Parameters:
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe 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.
See also:
image_util_supported_jpeg_colorspace_cb()
image_util_encode_jpeg()
image_util_encode_jpeg_to_memory()
image_util_decode_jpeg()
image_util_decode_jpeg_from_memory()

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]handleA handle to image util transform
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_OUT_OF_MEMORYOut of memory
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_transform_destroy()

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]handleThe handle to image util transform
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_transform_create()

Gets the colorspace of the image buffer.

Since :
2.3.1
Parameters:
[in]handleThe handle to image util transform
[in,out]colorspaceThe colorspace of the image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMATNot supported format
Precondition:
image_util_transform_create().
image_util_transform_set_crop_area().
See also:
image_util_transform_create()
image_util_transform_destroy()
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]handleThe handle to image util transform
[in,out]start_xThe start x position of cropped source image buffer
[in,out]start_yThe start y position of cropped source image buffer
[in,out]end_xThe end x position of cropped source image buffer
[in,out]end_yThe end y position of cropped source image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
Precondition:
image_util_transform_create().
image_util_transform_set_crop_area().
See also:
image_util_transform_create()
image_util_transform_destroy()
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]handleThe handle to image util transform
[in,out]widthThe width of source image buffer
[in,out]heightThe height of source image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
Precondition:
image_util_transform_create().
image_util_transform_set_resolution().
See also:
image_util_transform_create()
image_util_transform_destroy()

Gets the information of the rotating.

Since :
2.3.1
Parameters:
[in]handleThe handle to image util transform
[in,out]rotationThe rotation value of image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
Precondition:
image_util_transform_create().
image_util_transform_set_rotation().
See also:
image_util_transform_create()
image_util_transform_destroy()
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]handleThe handle of transform
[in]srcThe handle to image util transform
[in]callbackThe callback function to be invoked
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
See also:
image_util_transform_create()
image_util_transform_set_hardware_acceleration
image_util_transform_destroy()

Sets the information of the converting.

Since :
2.3.1
Parameters:
[in]handleThe handle to image util transform
[in]colorspaceThe colorspace of the image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMATNot supported format
Precondition:
image_util_transform_create().
See also:
image_util_transform_create()
image_util_transform_run()
image_util_transform_destroy()
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]handleThe handle to image util transform
[in]start_xThe start x position of cropped image buffer
[in]start_yThe start y position of cropped image buffer
[in]end_xThe end x position of cropped image buffer
[in]end_yThe end y position of cropped image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
Precondition:
image_util_transform_create().
See also:
image_util_transform_create()
image_util_transform_run()
image_util_transform_destroy()

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]handleThe handle to image util
[in]modeSet true, user can use the hardware acceleration
otherwise set false if user can only software image processing
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
IMAGE_UTIL_ERROR_NOT_SUPPORTEDThe application does not have the hardware acceleration
Precondition:
image_util_transform_create().
See also:
image_util_transform_create()
image_util_transform_destroy()
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]handleThe handle to image util transform
[in]widthThe width of image buffer
[in]heightThe height of image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
Precondition:
image_util_transform_create().
See also:
image_util_transform_create()
image_util_transform_run()
image_util_transform_destroy()

Sets the information of the rotating.

Since :
2.3.1
Parameters:
[in]handleThe handle to image util transform
[in]rotationThe rotation value of image buffer
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this funtion
Precondition:
image_util_transform_create().
See also:
image_util_transform_create()
image_util_transform_run()
image_util_transform_destroy()