Tizen Native API  5.5
Image Util Transform

The Image Util Transform APIs provides functions for transforming of images .

Required Header

#include <image_util.h>

Overview

Image Util API provides support for transforming of images. The API allows :

The API allows to transform(Colorspace conversion/Resize/Rotate/Crop) including convert the colorspace(image_util_colorspace_e) of an image by calling image_util_transform_run() function.

Functions

int image_util_transform_create (transformation_h *handle)
 Creates a handle of image util transform.
int image_util_transform_set_hardware_acceleration (transformation_h handle, bool mode) TIZEN_DEPRECATED_API
 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)
 Transforms the image for given image util handle.
int image_util_transform_run2 (transformation_h handle, image_util_image_h src, image_util_image_h *dst)
 Synchronously transforms an image with the given transformation handle.
int image_util_transform_run2_async (transformation_h handle, image_util_image_h src, image_util_transform_completed2_cb callback, void *user_data)
 Synchronously transforms an image with the given transformation handle.
int image_util_transform_destroy (transformation_h handle)
 Destroys a handle to image util.
int image_util_create_image (unsigned int width, unsigned int height, image_util_colorspace_e colorspace, const unsigned char *data, size_t data_size, image_util_image_h *image)
 Creates an image handle.
int image_util_clone_image (image_util_image_h src, image_util_image_h *dst)
 Clones an image handle.
int image_util_get_image (image_util_image_h image, unsigned int *width, unsigned int *height, image_util_colorspace_e *colorspace, unsigned char **data, size_t *data_size)
 Gets the information from the image.
int image_util_destroy_image (image_util_image_h image)
 Destroys an image handle.

Typedefs

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 void(* image_util_transform_completed2_cb )(image_util_image_h dst, int error_code, void *user_data)
 Called when transforming an image is completed.

Typedef Documentation

typedef void(* image_util_transform_completed2_cb)(image_util_image_h dst, int error_code, void *user_data)

Called when transforming an image is completed.

Since :
5.5
Remarks:
The dst can be used only in the callback. To use outside, make a copy using image_util_clone_image().
The callback is called in a separate thread(not in the main loop).
Parameters:
[in]dstThe transformed image
[in]error_codeThe error code of transformation
[in]user_dataThe user data passed from the callback registration function
Precondition:
image_util_transform_run2_async()
See also:
image_util_transform_run2_async()
image_util_clone_image()
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.

Since :
2.3
Remarks:
The dst should be released using media_packet_destroy().
The callback is called in a separate thread(not in the main loop).
Parameters:
[in,out]dstThe result buffer of image util transform
[in]error_codeThe error code of image util transform
[in]user_dataThe user data passed from the callback registration function
Precondition:
image_util_transform_run() will invoke this function.
typedef struct transformation_s* transformation_h

Image util handle.

Since :
2.3

Enumeration Type Documentation

Enumeration for rotation.

Since :
2.3
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

Clones an image handle.

Since :
5.5
Remarks:
The dst should be released using image_util_destroy_image().
Parameters:
[in]srcThe handle of the image
[out]dstA handle of the cloned image
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
See also:
image_util_destroy_image()
image_util_get_image()
int image_util_create_image ( unsigned int  width,
unsigned int  height,
image_util_colorspace_e  colorspace,
const unsigned char *  data,
size_t  data_size,
image_util_image_h image 
)

Creates an image handle.

Since :
5.5
Remarks:
The image should be released using image_util_destroy_image().
Parameters:
[in]widthThe width of image
[in]heightThe height of image
[in]colorspaceThe colorspace of image
[in]dataThe data of image
[in]data_sizeThe size of data
[out]imageA handle of image
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
See also:
image_util_destroy_image()
image_util_get_image()
image_util_clone_image()

Destroys an image handle.

The function frees all resources related to the @ image. The image handle no longer can be used to perform any operations. A new image handle has to be created before the next usage.

Since :
5.5
Parameters:
[in]imageThe handle of the image
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
image_util_create_image()
int image_util_get_image ( image_util_image_h  image,
unsigned int *  width,
unsigned int *  height,
image_util_colorspace_e colorspace,
unsigned char **  data,
size_t *  data_size 
)

Gets the information from the image.

Since :
5.5
Remarks:
The data should be released using free() if that's not NULL. And if you don't want to get specific information, you can set parameters to NULL.
Parameters:
[in]imageThe handle of the image
[out]widthThe width of image
[out]heightThe height of image
[out]colorspaceThe colorspace of image
[out]dataThe data of image
[out]data_sizeThe size of data
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
See also:
image_util_create_image()

Creates a handle of image util transform.

This function creates a handle of image util transform.

Since :
2.3
Remarks:
The handle should be released using image_util_transform_destroy().
Parameters:
[out]handleThe handle for transforming an image
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
See also:
image_util_transform_destroy()

Destroys a handle to image util.

The function frees all resources related to the image util handle. The image util handle no longer can be used to perform any operations. A new image util handle has to be created before the next usage.

Since :
2.3
Parameters:
[in]handleThe handle for transforming an image
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
See also:
image_util_transform_create()

Gets the colorspace of the image buffer.

Since :
2.3
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
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
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
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
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
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
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
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 
)

Transforms the image for given image util handle.

The function execute asynchronously, which contains complete callback
If you set more than two transforming, the order of running is crop or resolution, colorspace converting, rotation.

Since :
2.3
Remarks:
If H/W acceleration is not set, transformation is done via S/W acceleration.
Parameters:
[in]handleThe handle for transforming an image
[in]srcThe handle of source
[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_INVALID_OPERATIONInvalid operation
See also:
image_util_transform_create()
image_util_transform_destroy()

Synchronously transforms an image with the given transformation handle.

This function transforms an image synchronously using the src image handle, which has image information such as size, resolution.
A transformed image is stored into the dst image handle.

Since :
5.5
Remarks:
If transforming is failed, the dst will be null. The dst should be released using image_util_destroy_image().
Parameters:
[in]handleThe handle for transforming an image
[in]srcThe handle of the src image
[out]dstThe transformed image
Returns:
0 on success, otherwise a negative error value
Return values:
IMAGE_UTIL_ERROR_NONESuccessful
IMAGE_UTIL_ERROR_INVALID_PARAMETERInvalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATIONInvalid operation
IMAGE_UTIL_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
Create a transformation handle by calling image_util_transform_create().
Set the transformation information by calling image_util_transform_set_colorspace(), image_util_transform_set_resolution(),
image_util_transform_set_rotation(), image_util_transform_set_crop_area().
See also:
image_util_transform_create()
image_util_transform_destroy()
image_util_transform_set_colorspace()
image_util_transform_set_resolution()
image_util_transform_set_rotation()
image_util_transform_set_crop_area()

Synchronously transforms an image with the given transformation handle.

This function transforms an image asynchronously using the src image handle, which has image information such as size, resolution.
callback will be called after completing transform.

Since :
5.5
Remarks:
If transforming is failed, the dst of callback parameter will be null.
Parameters:
[in]handleThe handle for transforming an image
[in]srcThe handle of the src image
[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_INVALID_OPERATIONInvalid operation
IMAGE_UTIL_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
Create a transformation handle by calling image_util_transform_create().
Set the transformation information by calling image_util_transform_set_colorspace(), image_util_transform_set_resolution(),
image_util_transform_set_rotation(), image_util_transform_set_crop_area().
See also:
image_util_transform_create()
image_util_transform_destroy()
image_util_transform_set_colorspace()
image_util_transform_set_resolution()
image_util_transform_set_rotation()
image_util_transform_set_crop_area()
image_util_transform_completed2_cb()

Sets the information of the converting.

Since :
2.3
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
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
Remarks:
image_util_transform_set_resolution() and image_util_transform_set_crop_area() can't do that at the same time.
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
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.

Deprecated:
Deprecated since 5.0.

This function set if you use hardware acceleration or not.

Since :
2.3
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 for transforming an image
[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_INVALID_OPERATIONInvalid operation
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
Remarks:
image_util_transform_set_resolution() and image_util_transform_set_crop_area() can't do that at the same time.
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
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
Parameters:
[in]handleThe handle for transforming an image
[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_INVALID_OPERATIONInvalid operation
Precondition:
image_util_transform_create().
See also:
image_util_transform_create()
image_util_transform_run()
image_util_transform_destroy()