The Image Util Encode/Decode 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/PNG/GIF/BMP image.
Encoding/Decoding of a JPEG/PNG/GIF/BMP image to/from memory.

The decoding of a jpeg/png/gif/bmp image located at a given path, to a buffer can be done by calling image_util_decode_run() function and decoding of a jpeg image on memory can be done by calling image_util_decode_set_output_buffer(). Similarly, for encoding image_util_encode_run() and image_util_encode_set_output_buffer() functions can be called to encode an image buffer to a jpeg/png/gif/bmp image and a buffer respectively.

Foreach Operations

FOREACH	CALLBACK	DESCRIPTION
image_util_foreach_supported_colorspace()	image_util_supported_colorspace_cb()	Supported JPEG/PNG/GIF/BMP encoding/decoding colorspace

Functions
int	image_util_foreach_supported_jpeg_colorspace (image_util_supported_jpeg_colorspace_cb callback, void *user_data) TIZEN_DEPRECATED_API
	Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one.
int	image_util_decode_jpeg (const char path, image_util_colorspace_e colorspace, unsigned char image_buffer, int width, int height, unsigned int size) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	Encodes the image to the JPEG image.
int	image_util_foreach_supported_colorspace (image_util_type_e image_type, image_util_supported_colorspace_cb callback, void *user_data)
	Retrieves all supported image encoding/decoding colorspace by invoking a callback function once for each one.
int	image_util_decode_create (image_util_decode_h *handle)
	Creates a handle to image util decoding.
int	image_util_decode_set_input_path (image_util_decode_h handle, const char *path)
	Sets the input file path from which to decode.
int	image_util_decode_set_input_buffer (image_util_decode_h handle, const unsigned char *src_buffer, unsigned long long src_size)
	Sets the input buffer from which to decode.
int	image_util_decode_set_output_buffer (image_util_decode_h handle, unsigned char **dst_buffer)
	Sets the output buffer to which the decoded buffer will be written to.
int	image_util_decode_set_colorspace (image_util_encode_h handle, image_util_colorspace_e colorspace)
	Sets the decoded image colorspace format.
int	image_util_decode_set_jpeg_downscale (image_util_encode_h handle, image_util_scale_e down_scale)
	Sets the downscale value at which JPEG image should be decoded.
int	image_util_decode_run (image_util_decode_h handle, unsigned long width, unsigned long height, unsigned long long *size)
	Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().
int	image_util_decode_run_async (image_util_decode_h handle, image_util_decode_completed_cb callback, void *user_data)
	Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().
int	image_util_decode_destroy (image_util_decode_h handle)
	Destroys the image decoding handle.
int	image_util_encode_create (image_util_type_e image_type, image_util_encode_h *handle)
	Creates a handle to image util encoding.
int	image_util_encode_set_resolution (image_util_encode_h handle, unsigned long width, unsigned long height)
	Sets the resolution of the encoded image.
int	image_util_encode_set_colorspace (image_util_encode_h handle, image_util_colorspace_e colorspace)
	Sets the colorspace format for image encoding.
int	image_util_encode_set_quality (image_util_encode_h handle, int quality)
	Sets the quality for image encoding.
int	image_util_encode_set_png_compression (image_util_encode_h handle, image_util_png_compression_e compression)
	Sets the compression value of png image encoding(0~9).
int	image_util_encode_set_gif_frame_delay_time (image_util_encode_h handle, unsigned long long delay_time)
	Sets the time delay between each frame in the encoded animated gif image.
int	image_util_encode_set_input_buffer (image_util_encode_h handle, const unsigned char *src_buffer)
	Sets the input buffer from which to encode.
int	image_util_encode_set_output_path (image_util_encode_h handle, const char *path)
	Sets the output path to which to encoded buffer will be written to.
int	image_util_encode_set_output_buffer (image_util_encode_h handle, unsigned char **dst_buffer)
	Sets the output buffer to which to encoded buffer will be written to.
int	image_util_encode_run (image_util_encode_h handle, unsigned long long *size)
	Starts encoding of the image and fills the output buffer, set using image_util_encode_set_output_buffer() or image_util_encode_set_output_path().
int	image_util_encode_run_async (image_util_encode_h handle, image_util_encode_completed_cb callback, void *user_data)
	Starts encoding of the image and fills the output buffer, set using image_util_encode_set_output_buffer() or image_util_encode_set_output_path().
int	image_util_encode_destroy (image_util_encode_h handle)
	Destroys the image encoding handle.
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 bool(*	image_util_supported_colorspace_cb )(image_util_colorspace_e colorspace, void *user_data)
	Called once for each supported image encode/decode colorspace.
typedef void(*	image_util_decode_completed_cb )(int error_code, void *user_data, unsigned long width, unsigned long height, unsigned long long size)
	Called when Image-util decoding is finished just before returning the output.
typedef void(*	image_util_encode_completed_cb )(int error_code, void *user_data, unsigned long long size)
	Called when Image-util encoding is finished just before returning the output.
typedef void *	image_util_decode_h
	Image-util decoding handle.
typedef void *	image_util_encode_h
	Image-util encoding handle.

Typedef Documentation

typedef void(* image_util_decode_completed_cb)(int error_code, void *user_data, unsigned long width, unsigned long height, unsigned long long size)

Called when Image-util decoding is finished just before returning the output.

Since :: 3.0

Remarks:: The output will be stored in the pointer set using image_util_decode_set_output_buffer() after this callback.
The callback is called in a separate thread(not in the main loop).

Parameters:

[in]	error_code	The error code of image util decoding IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
[in]	user_data	The user data passed from the callback registration function
[in]	width	Width of the decoded image
[in]	height	Height of the decoded image
[in]	size	Size of the decoded image

Precondition:: image_util_decode_run() will invoke this function.

typedef void* image_util_decode_h

Image-util decoding handle.

Since :: 3.0

typedef void(* image_util_encode_completed_cb)(int error_code, void *user_data, unsigned long long size)

Called when Image-util encoding is finished just before returning the output.

Since :: 3.0

Remarks:: The output will be stored in the pointer set using image_util_encode_set_output_buffer() or image_util_encode_set_output_path() after this callback.
The callback is called in a separate thread(not in the main loop).

Parameters:

[in]	error_code	The error code of image util encoding IMAGE_UTIL_ERROR_NONE Successful IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
[in]	user_data	The user data passed from the callback registration function
[in]	size	Size of the encoded image

Precondition:: image_util_encode_run() will invoke this function.

typedef void* image_util_encode_h

Image-util encoding handle.

Since :: 3.0

typedef bool(* image_util_supported_colorspace_cb)(image_util_colorspace_e colorspace, void *user_data)

Called once for each supported image encode/decode colorspace.

Since :: 3.0

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,
otherwise false to break out of the loop

Precondition:: image_util_foreach_supported_colorspace() invokes this callback.

See also:: image_util_foreach_supported_colorspace(); image_util_encode_create(); image_util_decode_create()

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.

Deprecated:: Deprecated since 3.0. Use image_util_supported_colorspace_cb() instead.

Since :: 2.3

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,
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()

Enumeration Type Documentation

enum image_util_png_compression_e

Enumeration for PNG compression values.

Since :: 3.0

Enumerator:

IMAGE_UTIL_PNG_COMPRESSION_0	No compression
IMAGE_UTIL_PNG_COMPRESSION_1	Compression Level 1. Best speed
IMAGE_UTIL_PNG_COMPRESSION_2	Compression Level 2
IMAGE_UTIL_PNG_COMPRESSION_3	Compression Level 3
IMAGE_UTIL_PNG_COMPRESSION_4	Compression Level 4
IMAGE_UTIL_PNG_COMPRESSION_5	Compression Level 5
IMAGE_UTIL_PNG_COMPRESSION_6	Compression Level 6
IMAGE_UTIL_PNG_COMPRESSION_7	Compression Level 7
IMAGE_UTIL_PNG_COMPRESSION_8	Compression Level 8
IMAGE_UTIL_PNG_COMPRESSION_9	Compression Level 9. Best compression

enum image_util_scale_e

Enumeration for scale decoding.

Since :: 3.0

Enumerator:

IMAGE_UTIL_DOWNSCALE_1_1	1/1 downscale
IMAGE_UTIL_DOWNSCALE_1_2	1/2 downscale
IMAGE_UTIL_DOWNSCALE_1_4	1/4 downscale
IMAGE_UTIL_DOWNSCALE_1_8	1/8 downscale

enum image_util_type_e

Enumeration for Image types.

Since :: 3.0

Enumerator:

IMAGE_UTIL_JPEG	Image format JPEG
IMAGE_UTIL_PNG	Image format PNG
IMAGE_UTIL_GIF	Image format GIF
IMAGE_UTIL_BMP	Image format BMP

Function Documentation

int image_util_decode_create ( image_util_decode_h * handle )

Creates a handle to image util decoding.

Since :: 3.0

This function creates a handle to image util decoding.

Remarks:: You must release the image util handle using image_util_decode_destroy().

Parameters:

[out] handle A handle to image util decoding

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

See also:: image_util_decode_destroy()

int image_util_decode_destroy ( image_util_decode_h handle )

Destroys the image decoding handle.

Since :: 3.0

Remarks:: Any image handle created should be destroyed.

Parameters:

[in] handle The handle to image util decoding

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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_decode_create()

See also:: image_util_decode_create()

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.

Deprecated:: Deprecated since 3.0. Use image_util_decode_create() instead.

Since :: 2.3

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.
If you decode the JPEG image which has odd numbered width or height to YUV colorspace,
the width or height of decoded data will be rounded down to even numbered width or height.

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

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.

Deprecated:: Deprecated since 3.0. Use image_util_decode_create() instead.

Since :: 2.3

Remarks:: You must release image_buffer using free().
If you decode the JPEG image which has odd numbered width or height to YUV colorspace,
the width or height of decoded data will be rounded down to even numbered width or height.

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

See also:: image_util_supported_jpeg_colorspace_cb(); image_util_decode_jpeg(); image_util_foreach_supported_jpeg_colorspace()

int image_util_decode_run	(	image_util_decode_h	handle,
		unsigned long *	width,
		unsigned long *	height,
		unsigned long long *	size
	)

Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().

Since :: 3.0

Remarks:: The output will be stored in the pointer set using image_util_decode_set_output_buffer().
The function executes synchronously.
When any of the

Precondition:: functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.

Parameters:

[in]	handle	The handle to image util decoding
[out]	width	Width of the decoded image
[out]	height	Height of the decoded image
[out]	size	Size of the decoded image

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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_decode_create(); image_util_decode_set_input_buffer() / image_util_decode_set_input_path().; image_util_decode_set_output_buffer()

Postcondition:: image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_set_input_path(); image_util_decode_set_input_buffer(); image_util_decode_set_output_buffer(); image_util_decode_destroy()

int image_util_decode_run_async	(	image_util_decode_h	handle,
		image_util_decode_completed_cb	callback,
		void *	user_data
	)

Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().

Since :: 3.0

Remarks:: The output will be stored in the pointer set using image_util_decode_set_output_buffer().
The function executes asynchronously, which contains complete callback.
When any of the

Precondition:: functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.

Parameters:

[in]	handle	The handle to image util decoding
[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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_decode_create(); image_util_decode_set_input_buffer() / image_util_decode_set_input_path().; image_util_decode_set_output_buffer()

Postcondition:: image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_set_input_path(); image_util_decode_set_input_buffer(); image_util_decode_set_output_buffer(); image_util_decode_destroy()

int image_util_decode_set_colorspace	(	image_util_encode_h	handle,
		image_util_colorspace_e	colorspace
	)

Sets the decoded image colorspace format.

Since :: 3.0

Remarks:: The default colorspace is IMAGE_UTIL_COLORSPACE_RGBA8888.
Use image_util_foreach_supported_colorspace to get supported colorspaces for each image format.
Errors would be returned if not supported.

Parameters:

[in]	handle	The handle to image util decoding
[in]	colorspace	The decoded image colorspace

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	Format not supported

Precondition:: image_util_decode_create(); image_util_decode_set_input_path() / image_util_decode_set_input_buffer()

Postcondition:: image_util_decode_run() / image_util_decode_run_async(); image_util_decode_destroy()

See also:: image_util_supported_colorspace_cb(); image_util_foreach_supported_colorspace(); image_util_decode_create(); image_util_decode_set_input_path(); image_util_decode_set_input_buffer(); image_util_decode_set_output_buffer(); image_util_decode_run(); image_util_decode_run_async(); image_util_decode_destroy()

int image_util_decode_set_input_buffer	(	image_util_decode_h	handle,
		const unsigned char *	src_buffer,
		unsigned long long	src_size
	)

Sets the input buffer from which to decode.

Since :: 3.0

Remarks:: One of image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.
If both are set then the latest input set, is considered.
Finds out image type by reading the header of the image provided in input buffer.

Parameters:

[in]	handle	The handle to image util decoding
[in]	src_buffer	The input image buffer
[in]	src_size	The input 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_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Format not supported

Precondition:: image_util_decode_create()

Postcondition:: image_util_decode_run() / image_util_decode_run_async(); image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_set_output_buffer(); image_util_decode_run(); image_util_decode_run_async(); image_util_decode_destroy()

int image_util_decode_set_input_path	(	image_util_decode_h	handle,
		const char *	path
	)

Sets the input file path from which to decode.

Since :: 3.0

Remarks:: One of image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.
If both are set then the latest input set, is considered.
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.
Finds out image type by reading the header of the image provided in input path.

Parameters:

[in]	handle	The handle to image util decoding
[in]	path	The path to input image

Returns:: 0 on success, otherwise a negative error value

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_NO_SUCH_FILE	No such file
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this funtion
IMAGE_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Format not supported

Precondition:: image_util_decode_create()

Postcondition:: image_util_decode_run() / image_util_decode_run_async(); image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_set_output_buffer(); image_util_decode_run(); image_util_decode_run_async(); image_util_decode_destroy()

int image_util_decode_set_jpeg_downscale	(	image_util_encode_h	handle,
		image_util_scale_e	down_scale
	)

Sets the downscale value at which JPEG image should be decoded.

Since :: 3.0

Remarks:: This is API is supported only for JPEG decoding.

Parameters:

[in]	handle	The handle to image util decoding
[in]	down_scale	The downscale at which image is to be decoded

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	Format not supported

Precondition:: image_util_decode_create(); image_util_decode_set_input_path() / image_util_decode_set_input_buffer()

Postcondition:: image_util_decode_run() / image_util_decode_run_async(); image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_set_input_path(); image_util_decode_set_input_buffer(); image_util_decode_set_output_buffer(); image_util_decode_run(); image_util_decode_run_async(); image_util_decode_destroy()

int image_util_decode_set_output_buffer	(	image_util_decode_h	handle,
		unsigned char **	dst_buffer
	)

Sets the output buffer to which the decoded buffer will be written to.

Since :: 3.0

Remarks:: Either image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.
By default the decoded output buffer colorspace will be IMAGE_UTIL_COLORSPACE_RGBA8888. Use image_util_decode_set_colorspace to change the colorspace.

Parameters:

[in]	handle	The handle to image util decoding
[in]	dst_buffer	The decoded output 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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_decode_create()

Postcondition:: image_util_decode_run() / image_util_decode_run_async(); image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_set_input_path(); image_util_decode_set_input_buffer(); image_util_decode_run(); image_util_decode_run_async(); image_util_decode_destroy()

int image_util_encode_create	(	image_util_type_e	image_type,
		image_util_encode_h *	handle
	)

Creates a handle to image util encoding.

Since :: 3.0

This function creates a handle to image util encoding.

Remarks:: You must release the image util handle using image_util_encode_destroy().

Parameters:

[in]	image_type	The type of output image for which to create encode handle.
[out]	handle	A handle to image util encoding

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

See also:: image_util_encode_destroy()

int image_util_encode_destroy ( image_util_encode_h handle )

Destroys the image encoding handle.

Since :: 3.0

Remarks:: Any image handle created should be destroyed.

Parameters:

[in] handle The handle to image util encoding

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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_encode_create()

See also:: image_util_encode_create()

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.

Deprecated:: Deprecated since 3.0. Use image_util_encode_create() instead.

Since :: 2.3

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

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.

Deprecated:: Deprecated since 3.0. Use image_util_encode_create() instead.

Since :: 2.3

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

See also:: image_util_supported_jpeg_colorspace_cb(); image_util_foreach_supported_jpeg_colorspace(); image_util_encode_jpeg()

int image_util_encode_run	(	image_util_encode_h	handle,
		unsigned long long *	size
	)

Starts encoding of the image and fills the output buffer, set using image_util_encode_set_output_buffer() or image_util_encode_set_output_path().

Since :: 3.0

Remarks:: The output will be stored in the pointer set to image_util_encode_set_output_buffer() or image_util_encode_set_output_path().
The function executes synchronously.
When any of the

Precondition:: functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
In case of animated gif encoding, image_util_encode_set_resolution(), image_util_encode_set_input_buffer() and
image_util_encode_set_gif_frame_delay_time() MUST be called for each frame. In case of animated gif encoding, call image_util_encode_run() for each frame to encode progressively.

Parameters:

[in]	handle	The handle to image util encoding
[out]	size	Size of the encoded image

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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_output_buffer() / image_util_encode_set_output_path()

Postcondition:: image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_gif_frame_delay_time(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_destroy()

int image_util_encode_run_async	(	image_util_encode_h	handle,
		image_util_encode_completed_cb	callback,
		void *	user_data
	)

Starts encoding of the image and fills the output buffer, set using image_util_encode_set_output_buffer() or image_util_encode_set_output_path().

Since :: 3.0

Remarks:: The output will be stored in the pointer set to image_util_encode_set_output_buffer() or image_util_encode_set_output_path().
The function executes asynchronously, which contains complete callback.
When any of the

Precondition:: functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
In case of animated gif encoding, image_util_encode_set_resolution(), image_util_encode_set_input_buffer() and
image_util_encode_set_gif_frame_delay_time() MUST be called for each frame. In case of animated gif encoding, call image_util_encode_run_async() for each frame to encode progressively.

Parameters:

[in]	handle	The handle to image util encoding
[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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_output_buffer() / image_util_encode_set_output_path()

Postcondition:: image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_gif_frame_delay_time(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_destroy()

int image_util_encode_set_colorspace	(	image_util_encode_h	handle,
		image_util_colorspace_e	colorspace
	)

Sets the colorspace format for image encoding.

Since :: 3.0

Remarks:: The default colorspace is IMAGE_UTIL_COLORSPACE_RGBA8888.
Use image_util_foreach_supported_colorspace to get supported colorspaces for each image format.
Errors would be returned if not supported.

Parameters:

[in]	handle	The handle to image util encoding
[in]	colorspace	The encoded image colorspace

Returns:: 0 on success, otherwise a negative error value

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Format not supported
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_supported_colorspace_cb(); image_util_foreach_supported_colorspace(); image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_encode_set_gif_frame_delay_time	(	image_util_encode_h	handle,
		unsigned long long	delay_time
	)

Sets the time delay between each frame in the encoded animated gif image.

Since :: 3.0

Remarks:: In case animated gif image if this is not set then there will be no delay between each frame.
This should be set for each frame in the animated gif image.
This can be set a different value for each frame, which results in different delay time between different frames.

Parameters:

[in]	handle	The handle to image util encoding
[in]	delay_time	Time delay between each frame in the encoded image, in 0.01sec units.

Returns:: 0 on success, otherwise a negative error value

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Format not supported
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_encode_set_input_buffer	(	image_util_encode_h	handle,
		const unsigned char *	src_buffer
	)

Sets the input buffer from which to encode.

Since :: 3.0

Remarks:: Either image_util_encode_set_output_path() or image_util_encode_set_output_buffer() should be set.
By default the input buffer colorspace will be considered as IMAGE_UTIL_COLORSPACE_RGBA8888.
Use image_util_encode_set_colorspace to change the colorspace.
While encoding animated gif image, input buffer should be set for each frame.

Parameters:

[in]	handle	The handle to image util decoding
[in]	src_buffer	The input 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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_encode_set_output_buffer	(	image_util_encode_h	handle,
		unsigned char **	dst_buffer
	)

Sets the output buffer to which to encoded buffer will be written to.

Since :: 3.0

Remarks:: One of image_util_encode_set_output_path() or image_util_encode_set_output_buffer() should be set.
If both are set then the latest output set is considered.
Output buffer setting is not supported for bmp. IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT will be returned for bmp.
In case of gif encoding, the output buffer will be completely available only after image_util_encode_destroy().

Parameters:

[in]	handle	The handle to image util encoding
[in]	dst_buffer	The output 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_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Format not supported

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_encode_set_output_path	(	image_util_encode_h	handle,
		const char *	path
	)

Sets the output path to which to encoded buffer will be written to.

Since :: 3.0

Remarks:: One of image_util_encode_set_output_path() or image_util_encode_set_output_buffer() should be set.
If both are set then the latest output set is considered.
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]	handle	The handle to image util encoding
[in]	path	The output file path

Returns:: 0 on success, otherwise a negative error value

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_NO_SUCH_FILE	No such file
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this funtion

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_encode_set_png_compression	(	image_util_encode_h	handle,
		image_util_png_compression_e	compression
	)

Sets the compression value of png image encoding(0~9).

Since :: 3.0

Remarks:: If application does not set this, then default compression of 6 is set.

Parameters:

[in]	handle	The handle to image util encoding
[in]	compression	The compression value valid from 0~9

Returns:: 0 on success, otherwise a negative error value

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Format not supported
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_encode_set_quality	(	image_util_encode_h	handle,
		int	quality
	)

Sets the quality for image encoding.

Since :: 3.0

Remarks:: If application does not set this, then by default quality of 75 is set.
Quality is supported for JPEG format. IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT will be returned for other formats.

Parameters:

[in]	handle	The handle to image util encoding
[in]	quality	Encoding quality from 1~100

Returns:: 0 on success, otherwise a negative error value

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Format not supported
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_resolution(); image_util_encode_set_input_buffer(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_encode_set_resolution	(	image_util_encode_h	handle,
		unsigned long	width,
		unsigned long	height
	)

Sets the resolution of the encoded image.

Since :: 3.0

Remarks:: This should be called before calling image_util_encode_run().
While encoding animated gif image, resolution should be set for each frame.

Parameters:

[in]	handle	The handle to image util encoding
[in]	width	Width of the original image
[in]	height	Height of the original image

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_INVALID_OPERATION	Invalid operation

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_run() / image_util_encode_run_async(); image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_set_input_buffer(); image_util_encode_set_output_path(); image_util_encode_set_output_buffer(); image_util_encode_run(); image_util_encode_run_async(); image_util_encode_destroy()

int image_util_foreach_supported_colorspace	(	image_util_type_e	image_type,
		image_util_supported_colorspace_cb	callback,
		void *	user_data
	)

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

Since :: 3.0

Parameters:

[in]	image_type	The type of supported image for which to create encode/decode handle
[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

Postcondition:: This function invokes image_util_supported_colorspace_cb() repeatedly to retrieve each supported image encoding/decoding colorspace.

See also:: image_util_supported_colorspace_cb(); image_util_encode_create(); image_util_decode_create()

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.

Deprecated:: Deprecated since 3.0. Use image_util_foreach_supported_colorspace() instead.

Since :: 2.3

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.

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()

Required Header

Overview

Foreach Operations

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation