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 of a JPEG/PNG/GIF/BMP and WEBP(Since 6.0) image.
Decoding of a JPEG/PNG/GIF/BMP/WEBP(Since 6.0) and HEIF(Since 6.5) image. Encoding supports gif images including the animated, but decoding gif does not support the animated.

The decoding of a jpeg/png/gif/bmp/webp/heif image located at a given path, to a buffer can be done by calling image_util_decode_run() function and decoding of a jpeg/png/gif/bmp/webp/heif 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/webp 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/WEBP encoding/decoding colorspace

Functions
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 of 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) TIZEN_DEPRECATED_API
	Sets the output buffer to which the decoded buffer will be written to.
int	image_util_decode_set_colorspace (image_util_decode_h handle, image_util_colorspace_e colorspace)
	Sets the decoded image colorspace format.
int	image_util_decode_set_jpeg_downscale (image_util_decode_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) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().
int	image_util_decode_run2 (image_util_decode_h handle, image_util_image_h *image)
	Decodes the image with the given decode handle.
int	image_util_decode_run_async2 (image_util_decode_h handle, image_util_decode_completed2_cb callback, void *user_data)
	Starts decoding of the image with the given decode handle.
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 of image util encoding.
int	image_util_encode_set_resolution (image_util_encode_h handle, unsigned long width, unsigned long height) TIZEN_DEPRECATED_API
	Sets the resolution of the encoded image.
int	image_util_encode_set_colorspace (image_util_encode_h handle, image_util_colorspace_e colorspace) TIZEN_DEPRECATED_API
	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_webp_lossless (image_util_encode_h handle, bool lossless)
	Sets lossless compression of WEBP images.
int	image_util_encode_set_gif_frame_delay_time (image_util_encode_h handle, unsigned long long delay_time) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	Sets the input buffer from which to encode.
int	image_util_encode_set_output_path (image_util_encode_h handle, const char *path) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	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) TIZEN_DEPRECATED_API
	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_to_file (image_util_encode_h handle, image_util_image_h image, const char *file_path)
	Encodes the image and save it to a file in the given encoding handle.
int	image_util_encode_run_to_buffer (image_util_encode_h handle, image_util_image_h image, unsigned char *buffer, size_t buffer_size)
	Encodes the image to save it to a buffer in the given encoding handle.
int	image_util_encode_run_async_to_file (image_util_encode_h handle, image_util_image_h image, const char file_path, image_util_encode_to_file_completed_cb completed_cb, void user_data)
	Encodes the image and save it to a file in the given encoding handle asynchronously.
int	image_util_encode_run_async_to_buffer (image_util_encode_h handle, image_util_image_h image, image_util_encode_to_buffer_completed_cb completed_cb, void *user_data)
	Encodes the image and save it to a buffer in the given encoding handle asynchronously.
int	image_util_encode_destroy (image_util_encode_h handle)
	Destroys the image encoding handle.
int	image_util_agif_encode_create (image_util_agif_encode_h *handle)
	Creates a handle for encoding an animated GIF.
int	image_util_agif_encode_add_frame (image_util_agif_encode_h handle, image_util_image_h image, unsigned int time_delay)
	Encodes an image and adds the encoded image to the frames of the animated GIF.
int	image_util_agif_encode_save_to_file (image_util_agif_encode_h handle, const char *file_path)
	Saves the animated GIF image to the file.
int	image_util_agif_encode_save_to_buffer (image_util_agif_encode_h handle, unsigned char *buffer, size_t buffer_size)
	Saves the animated GIF image to the buffer.
int	image_util_agif_encode_destroy (image_util_agif_encode_h handle)
	Destroys the handle for encoding an animated GIF.
int	image_util_anim_encode_create (image_util_anim_type_e image_type, image_util_anim_encode_h *handle)
	Creates a handle for encoding animation.
int	image_util_anim_encode_set_loop_count (image_util_anim_encode_h handle, unsigned int loop_count)
	Sets a number of times to repeat the animation.
int	image_util_anim_encode_set_background_color (image_util_anim_encode_h handle, unsigned char r, unsigned char g, unsigned char b, unsigned char a)
	Sets a background color of the animation.
int	image_util_anim_encode_set_lossless (image_util_anim_encode_h handle, bool lossless)
	Sets lossless compression of animation.
int	image_util_anim_encode_add_frame (image_util_anim_encode_h handle, image_util_image_h image, unsigned int time_delay)
	Encodes an image and adds image to the frame of the animated image.
int	image_util_anim_encode_save_to_file (image_util_anim_encode_h handle, const char *file_path)
	Saves the animated WEBP or GIF image to the file.
int	image_util_anim_encode_save_to_buffer (image_util_anim_encode_h handle, unsigned char *buffer, size_t buffer_size)
	Saves the animation WEBP or GIF image to the buffer.
int	image_util_anim_encode_destroy (image_util_anim_encode_h handle)
	Destroys the handle for encoding animation.
Typedefs
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_decode_completed2_cb )(int error_code, image_util_image_h image, void *user_data)
	Called when image_util_decode_run_async2() finishes decoding an image.
typedef void(*	image_util_encode_completed_cb )(int error_code, void *user_data, unsigned long long size) TIZEN_DEPRECATED_API
	Called when Image-util encoding is finished just before returning the output.
typedef void(*	image_util_encode_to_file_completed_cb )(image_util_error_e error_code, void *user_data)
	Called when image encoding is finished just after storing the output to the file.
typedef void(*	image_util_encode_to_buffer_completed_cb )(image_util_error_e error_code, unsigned char buffer, size_t buffer_size, void user_data)
	Called when image encoding is finished just after storing the output to the buffer.
typedef void *	image_util_decode_h
	Image-util decoding handle.
typedef void *	image_util_encode_h
	Image-util encoding handle.
typedef void *	image_util_agif_encode_h
	Image-util animation GIF encoding handle.
typedef void *	image_util_anim_encode_h
	Image-util animation encoding handle.

Typedef Documentation

typedef void* image_util_agif_encode_h

Image-util animation GIF encoding handle.

Since :: 5.5

typedef void* image_util_anim_encode_h

Image-util animation encoding handle.

Since :: 6.0

typedef void(* image_util_decode_completed2_cb)(int error_code, image_util_image_h image, void *user_data)

Called when image_util_decode_run_async2() finishes decoding an image.

Since :: 5.5

Remarks:: The callback is called in a separate thread(not in the main loop).
The image should not be released by the application.
The image can be used only in the callback. To use outside, make a copy using image_util_clone_image().

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 IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
[in]	image	The decoded image (or `NULL` if decoding failed)
[in]	user_data	The user data passed from the callback registration function

Precondition:: image_util_decode_run_async2() will invoke this function.

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.

Deprecated:: Deprecated since 5.5.

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

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

Deprecated:: Deprecated since 5.5. Use image_util_encode_run_async_to_file() or image_util_encode_run_async_to_buffer() instead.

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 void(* image_util_encode_to_buffer_completed_cb)(image_util_error_e error_code, unsigned char *buffer, size_t buffer_size, void *user_data)

Called when image encoding is finished just after storing the output to the buffer.

Since :: 5.5

Remarks:: The output will be stored in the buffer.
The callback is called in a separate thread (not in the main loop).
The buffer should not be released by the application.
The buffer can be used only in the callback. To use outside, make a copy.

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 IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
[in]	buffer	The buffer for the encoded image
[in]	buffer_size	The size of the buffer for the encoded image
[in]	user_data	The user data passed from the callback registration function

Precondition:: image_util_encode_run_to_buffer() will invoke this function.

typedef void(* image_util_encode_to_file_completed_cb)(image_util_error_e error_code, void *user_data)

Called when image encoding is finished just after storing the output to the file.

Since :: 5.5

Remarks:: The output will be stored in the file set using image_util_encode_run_to_file().
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 IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
[in]	user_data	The user data passed from the callback registration function

Precondition:: image_util_encode_run_to_file() will invoke this function.

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

Enumeration Type Documentation

enum image_util_anim_type_e

Enumeration for animated image type.

Since :: 6.0

Enumerator:

IMAGE_UTIL_ANIM_GIF	Image format animated GIF
IMAGE_UTIL_ANIM_WEBP	Image format animated WEBP

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 :: 2.4

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
IMAGE_UTIL_WEBP	Image format WEBP (Since 6.0)
IMAGE_UTIL_HEIF	Image format HEIF (Since 6.5)

Function Documentation

int image_util_agif_encode_add_frame	(	image_util_agif_encode_h	handle,
		image_util_image_h	image,
		unsigned int	time_delay
	)

Encodes an image and adds the encoded image to the frames of the animated GIF.

Since :: 5.5

Remarks:: This function should be called for each image which you want to add to the animated GIF. Each image should be the same size.
The supported colorspace is IMAGE_UTIL_COLORSPACE_RGBA8888.
You should call image_util_agif_encode_save_to_file() or image_util_agif_encode_save_to_buffer() to save the animated GIF.
If you call this function after image_util_agif_encode_save_to_file() or image_util_agif_encode_save_to_buffer() function is called, this function will encode a new animated GIF.

Parameters:

[in]	handle	The handle of encoding an animated GIF
[in]	image	The handle of the image for each frame
[in]	time_delay	The time delay between image and the next image (in 0.01sec increments)

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	Not supported format

Precondition:: image_util_agif_encode_create()

Postcondition:: image_util_agif_encode_save_to_file(); image_util_agif_encode_save_to_buffer(); image_util_agif_encode_destroy()

See also:: image_util_agif_encode_create(); image_util_agif_encode_save_to_file(); image_util_agif_encode_save_to_buffer(); image_util_agif_encode_destroy()

int image_util_agif_encode_create ( image_util_agif_encode_h * handle )

Creates a handle for encoding an animated GIF.

Since :: 5.5

Remarks:: The handle should be released using image_util_agif_encode_destroy().

Parameters:

[out] handle The handle of encoding an animated GIF

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

Postcondition:: image_util_agif_encode_destroy()

See also:: image_util_agif_encode_add_frame(); image_util_agif_encode_save_to_file(); image_util_agif_encode_save_to_buffer(); image_util_agif_encode_destroy()

int image_util_agif_encode_destroy ( image_util_agif_encode_h handle )

Destroys the handle for encoding an animated GIF.

Since :: 5.5

Remarks:: Any created animated GIF encoding handle created should be destroyed.

Parameters:

[in] handle The handle of encoding an animated GIF

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

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: image_util_agif_encode_create()

See also:: image_util_agif_encode_create()

int image_util_agif_encode_save_to_buffer	(	image_util_agif_encode_h	handle,
		unsigned char **	buffer,
		size_t *	buffer_size
	)

Saves the animated GIF image to the buffer.

After the data has been written to a buffer, the file cannot be modified. In other words,
it is not possible to add frames to the buffer.
Saving animation flushes the frames that has been added to the encoder.
However, the encoder can be still used after the data is written.
For example, although you write the data to one buffer(B0),
you can do the following operations:

1. Add frames 1-10 to the encoder.
2. Save the data in the encoder to another buffer(B1). 10 frames will be saved.
3. Add more frames (11-20) to the same encoder.
4. Save the data in the encoder to the other buffer (B2)
It is not possible to save the changed data to B1 file used in step 4.

Since :: 5.5

Remarks:: The buffer should be released using free() after using it.

Parameters:

[in]	handle	The handle of encoding an animated GIF
[out]	buffer	The buffer in which the animated GIF is saved
[out]	buffer_size	The size of the 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_OUT_OF_MEMORY	Out of memory

Precondition:: image_util_agif_encode_create()

Postcondition:: image_util_agif_encode_destroy()

See also:: image_util_agif_encode_create(); image_util_agif_encode_add_frame(); image_util_agif_encode_destroy()

int image_util_agif_encode_save_to_file	(	image_util_agif_encode_h	handle,
		const char *	file_path
	)

Saves the animated GIF image to the file.

After the data has been written to a file, the file cannot be modified. In other words,
it is not possible to add frames to the file.
Saving animation flushes the frames that has been added to the encoder.
However, the encoder can be still used after the data is written.
For example, although you write the data to one file(B0),
you can do the following operations:

1. Add frames 1-10 to the encoder.
2. Save the data in the encoder to another file(B1). 10 frames will be saved.
3. Add more frames (11-20) to the same encoder.
4. Save the data in the encoder to the other file (B2)
It is not possible to save the changed data to B1 file used in step 4.

Since :: 5.5

Remarks:: http://tizen.org/privilege/mediastorage is required if file_path value is media storage.
http://tizen.org/privilege/externalstorage is required if file_path value is external storage.

Parameters:

[in]	handle	The handle of encoding an animated GIF
[in]	file_path	The file path for saving the animated GIF

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

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_PERMISSION_DENIED	Permission denied
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

Precondition:: image_util_agif_encode_create()

Postcondition:: image_util_agif_encode_destroy()

See also:: image_util_agif_encode_create(); image_util_agif_encode_add_frame(); image_util_agif_encode_destroy()

int image_util_anim_encode_add_frame	(	image_util_anim_encode_h	handle,
		image_util_image_h	image,
		unsigned int	time_delay
	)

Encodes an image and adds image to the frame of the animated image.

Since :: 6.0

Remarks:: This function should be called for each image which you want to add to the animated WEBP or GIF. Each image should be the same size.
The supported colorspaces are IMAGE_UTIL_COLORSPACE_RGBA8888, IMAGE_UTIL_COLORSPACE_ARGB8888, IMAGE_UTIL_COLORSPACE_BGRA8888 and IMAGE_UTIL_COLORSPACE_RGBA8888 for animated WEBP.
The supported colorspace is IMAGE_UTIL_COLORSPACE_RGBA8888 for animated GIF.
You should call image_util_anim_encode_save_to_file() or image_util_anim_encode_save_to_buffer() to save the animated WEBP.
If you call this function after image_util_anim_encode_save_to_file() or image_util_anim_encode_save_to_buffer() function is called, this function will encode a new animated WEBP and GIF.

Parameters:

[in]	handle	The handle of animation encoder
[in]	image	The handle of the image for each frame
[in]	time_delay	The time delay between image and the next image (in 1ms increments for WEBP and 10ms increments for GIF)

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

Precondition:: image_util_anim_encode_create()

Postcondition:: image_util_anim_encode_save_to_file(); image_util_anim_encode_save_to_buffer()

See also:: image_util_anim_encode_save_to_file(); image_util_anim_encode_save_to_buffer()

int image_util_anim_encode_create	(	image_util_anim_type_e	image_type,
		image_util_anim_encode_h *	handle
	)

Creates a handle for encoding animation.

Since :: 6.0

Remarks:: The handle should be released using image_util_anim_encode_destroy().

Parameters:

[in]	image_type	The type of output image to create animation
[out]	handle	The handle of animation encoder

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

See also:: image_util_anim_encode_add_frame(); image_util_anim_encode_save_to_file(); image_util_anim_encode_save_to_buffer(); image_util_anim_encode_destroy()

int image_util_anim_encode_destroy ( image_util_anim_encode_h handle )

Destroys the handle for encoding animation.

Since :: 6.0

Remarks:: Any created animated encoder handle created should be destroyed.

Parameters:

[in] handle The handle of animation encoder

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

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: image_util_anim_encode_create()

See also:: image_util_anim_encode_create()

int image_util_anim_encode_save_to_buffer	(	image_util_anim_encode_h	handle,
		unsigned char **	buffer,
		size_t *	buffer_size
	)

Saves the animation WEBP or GIF image to the buffer.

After the data has been written to a buffer, the file cannot be modified. In other words,
it is not possible to add frames to the buffer.
Saving animation flushes the frames that has been added to the encoder.
However, the encoder can be still used after the data is written.
For example, although you write the data to one buffer(B0),
you can do the following operations:

1. Add frames 1-10 to the encoder.
2. Save the data in the encoder to another buffer(B1). 10 frames will be saved.
3. Add more frames (11-20) to the same encoder.
4. Save the data in the encoder to the other buffer (B2)
It is not possible to save the changed data to B1 file used in step 4.

Since :: 6.0

Remarks:: The buffer should be released using free() after using it.

Parameters:

[in]	handle	The handle of encoding an animated WEBP or GIF
[out]	buffer	The buffer in which the animated WEBP or GIF is saved
[out]	buffer_size	The size of the 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_anim_encode_create()

See also:: image_util_anim_encode_add_frame()

int image_util_anim_encode_save_to_file	(	image_util_anim_encode_h	handle,
		const char *	file_path
	)

Saves the animated WEBP or GIF image to the file.

After the data has been written to a file, the file cannot be modified. In other words,
it is not possible to add frames to the file.
Saving animation flushes the frames that has been added to the encoder.
However, the encoder can be still used after the data is written.
For example, although you write the data to one file(B0),
you can do the following operations:

1. Add frames 1-10 to the encoder.
2. Save the data in the encoder to another file(B1). 10 frames will be saved.
3. Add more frames (11-20) to the same encoder.
4. Save the data in the encoder to the other file (B2)
It is not possible to save the changed data to B1 file used in step 4.

Since :: 6.0

Remarks:: http://tizen.org/privilege/mediastorage is required if file_path value is media storage.
http://tizen.org/privilege/externalstorage is required if file_path value is external storage.

Parameters:

[in]	handle	The handle of encoding an animated WEBP or GIF
[in]	file_path	The file path for saving the animated WEBP or GIF

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

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_PERMISSION_DENIED	Permission denied
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_NO_SUCH_FILE	No such file

Precondition:: image_util_anim_encode_create()

See also:: image_util_anim_encode_add_frame()

int image_util_anim_encode_set_background_color	(	image_util_anim_encode_h	handle,
		unsigned char	r,
		unsigned char	g,
		unsigned char	b,
		unsigned char	a
	)

Sets a background color of the animation.

Since :: 6.0

Remarks:: This function should be called before image_util_anim_encode_add_frame() is called.

Parameters:

[in]	handle	The handle of animation encoder
[in]	r	The red color of the background
[in]	g	The green color of the background
[in]	b	The blue color of the background
[in]	a	The alpha color of the background

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

Precondition:: image_util_anim_encode_create()

int image_util_anim_encode_set_loop_count	(	image_util_anim_encode_h	handle,
		unsigned int	loop_count
	)

Sets a number of times to repeat the animation.

Since :: 6.0

Remarks:: This function should be called before image_util_anim_encode_add_frame() is called.

Parameters:

[in]	handle	The handle of animation encoder
[in]	loop_count	The number of times to repeat the animation

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

Precondition:: image_util_anim_encode_create()

int image_util_anim_encode_set_lossless	(	image_util_anim_encode_h	handle,
		bool	lossless
	)

Sets lossless compression of animation.

Since :: 6.0

Remarks:: This function should be called before image_util_anim_encode_add_frame() is called.

Parameters:

[in]	handle	The handle of animation encoder
[in]	lossless	The flag determining whether the compression is lossless or lossy: true for lossless, false for lossy

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

Precondition:: image_util_anim_encode_create()

int image_util_decode_create ( image_util_decode_h * handle )

Creates a handle of image util decoding.

This function creates a handle of image util decoding.

Since :: 3.0

Remarks:: The handle should be released using image_util_decode_destroy().

Parameters:

[out] handle The handle of 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 of 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_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().

Deprecated:: Deprecated since 5.5. Use image_util_decode_run2() instead.

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 pre-condition are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.

Parameters:

[in]	handle	The handle of 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_run2	(	image_util_decode_h	handle,
		image_util_image_h *	image
	)

Decodes the image with the given decode handle.

This function decodes the image synchronously.

Since :: 5.5

Remarks:: If the decoding fails, the image will be NULL.
The image should be released using image_util_destroy_image().
If any of the required functions listed in the preconditions section has not been called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.

Parameters:

[in]	handle	The handle of image util decoding
[out]	image	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
IMAGE_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format

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

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_destroy(); image_util_destroy_image()

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

Deprecated:: Deprecated since 5.5. Use image_util_decode_run_async2() instead.

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 pre-condition are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.

Parameters:

[in]	handle	The handle of 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_run_async2	(	image_util_decode_h	handle,
		image_util_decode_completed2_cb	callback,
		void *	user_data
	)

Starts decoding of the image with the given decode handle.

This function decodes the image asynchronously.

Since :: 5.5

Remarks:: If the decoding fails, the image_util_decode_completed2_cb() will be called with NULL image and a non-zero error_code.
If any of the required functions listed in the preconditions section has not been called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.

Parameters:

[in]	handle	The handle of 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
IMAGE_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format

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

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_destroy(); image_util_destroy_image(); image_util_decode_completed2_cb()

int image_util_decode_set_colorspace	(	image_util_decode_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 of 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	Not supported format

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

Postcondition:: image_util_decode_run2() / image_util_decode_run_async2(); 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_run2(); image_util_decode_run_async2(); 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.
Since 6.0, this module supports WEBP image format.
Since 6.5, this module supports HEIF image format.

Parameters:

[in]	handle	The handle of 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	Not supported format

Precondition:: image_util_decode_create()

Postcondition:: image_util_decode_run2() / image_util_decode_run_async2(); image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_run2(); image_util_decode_run_async2(); 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.
Since 6.0, this module supports WEBP image format.
Since 6.5, this module supports HEIF image format.

Parameters:

[in]	handle	The handle of 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_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 function
IMAGE_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format
IMAGE_UTIL_ERROR_NO_SUCH_FILE	No such file

Precondition:: image_util_decode_create()

Postcondition:: image_util_decode_run2() / image_util_decode_run_async2(); image_util_decode_destroy()

See also:: image_util_decode_create(); image_util_decode_run2(); image_util_decode_run_async2(); image_util_decode_destroy()

int image_util_decode_set_jpeg_downscale	(	image_util_decode_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 of 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	Not supported format

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

Postcondition:: image_util_decode_run2() / image_util_decode_run_async2(); 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_run2(); image_util_decode_run_async2(); 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.

Deprecated:: Deprecated since 5.5.

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. dst_buffer should be released after image_util_decode_run() or image_util_decode_run_async().

Parameters:

[in]	handle	The handle of 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 of image util encoding.

This function creates a handle of image util encoding.

Since :: 3.0

Remarks:: The handle should be released using image_util_encode_destroy().

Parameters:

[in]	image_type	The type of output image for which to create encode handle.
[out]	handle	The handle of 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

Postcondition:: image_util_encode_run_to_file(); image_util_encode_run_to_buffer(); image_util_encode_run_async_to_file(); image_util_encode_run_async_to_buffer(); image_util_encode_destroy()

See also:: image_util_encode_run_to_file(); image_util_encode_run_to_buffer(); image_util_encode_run_async_to_file(); image_util_encode_run_async_to_buffer(); 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 of 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_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().

Deprecated:: Deprecated since 5.5. Use image_util_encode_run_to_file() or image_util_encode_run_to_buffer() instead.

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 functions at the pre-condition 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 of 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().

Deprecated:: Deprecated since 5.5. Use image_util_encode_run_async_to_file() or image_util_encode_run_async_to_buffer() instead.

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 functions at the pre-condition 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 of 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_run_async_to_buffer	(	image_util_encode_h	handle,
		image_util_image_h	image,
		image_util_encode_to_buffer_completed_cb	completed_cb,
		void *	user_data
	)

Encodes the image and save it to a buffer in the given encoding handle asynchronously.

The output will be stored in a buffer provided by the completed_cb callback.

Since :: 5.5

Remarks:: If any functions at the pre-condition are not called first, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
The only supported colorspace for BMP and GIF is IMAGE_UTIL_COLORSPACE_RGBA8888.
To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().
Before 6.0, IMAGE_UTIL_COLORSPACE_RGBA8888 was the only supported colorspace for PNG. But since 6.0, this module supports more colorspaces for PNG. To get supported colorspaces for PNG, you can use image_util_foreach_supported_colorspace().
Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.

Parameters:

[in]	handle	The handle of image util encoding
[in]	image	The image handle for encoding
[in]	completed_cb	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
IMAGE_UTIL_ERROR_OUT_OF_MEMORY	Out of memory

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_destroy()

int image_util_encode_run_async_to_file	(	image_util_encode_h	handle,
		image_util_image_h	image,
		const char *	file_path,
		image_util_encode_to_file_completed_cb	completed_cb,
		void *	user_data
	)

Encodes the image and save it to a file in the given encoding handle asynchronously.

The output will be stored in file_path. And the function executes asynchronously.

Since :: 5.5

Remarks:: If any functions at the pre-condition are not called first, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
The only supported colorspace for BMP and GIF is IMAGE_UTIL_COLORSPACE_RGBA8888.
To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().
http://tizen.org/privilege/mediastorage is required if file_path value is media storage.
http://tizen.org/privilege/externalstorage is required if file_path value is external storage.
Before 6.0, IMAGE_UTIL_COLORSPACE_RGBA8888 was the only supported colorspace for PNG. But since 6.0, this module supports more colorspaces for PNG. To get supported colorspaces for PNG, you can use image_util_foreach_supported_colorspace().
Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.

Parameters:

[in]	handle	The handle of image util encoding
[in]	image	The image handle for encoding
[in]	file_path	The file path for encoding image
[in]	completed_cb	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_PERMISSION_DENIED	Permission denied
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_OUT_OF_MEMORY	Out of memory

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_destroy()

int image_util_encode_run_to_buffer	(	image_util_encode_h	handle,
		image_util_image_h	image,
		unsigned char **	buffer,
		size_t *	buffer_size
	)

Encodes the image to save it to a buffer in the given encoding handle.

The function executes synchronously.

Since :: 5.5

Remarks:: If any functions at the pre-condition are not called first, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
The buffer should be released using free().
The only supported colorspace for BMP and GIF is IMAGE_UTIL_COLORSPACE_RGBA8888.
To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().
Before 6.0, IMAGE_UTIL_COLORSPACE_RGBA8888 was the only supported colorspace for PNG. But since 6.0, this module supports more colorspaces for PNG. To get supported colorspaces for PNG, you can use image_util_foreach_supported_colorspace().
Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.

Parameters:

[in]	handle	The handle of image util encoding
[in]	image	The image handle for encoding
[out]	buffer	The buffer that encoded image is stored
[out]	buffer_size	The size of the 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_OUT_OF_MEMORY	Out of memory
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_destroy()

See also:: image_util_encode_create(); image_util_encode_destroy()

int image_util_encode_run_to_file	(	image_util_encode_h	handle,
		image_util_image_h	image,
		const char *	file_path
	)

Encodes the image and save it to a file in the given encoding handle.

The function executes synchronously.

Since :: 5.5

Remarks:: If any functions at the pre-condition are not called first, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
The only supported colorspace for BMP and GIF is IMAGE_UTIL_COLORSPACE_RGBA8888.
To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().
http://tizen.org/privilege/mediastorage is required if file_path value is media storage.
http://tizen.org/privilege/externalstorage is required if file_path value is external storage.
Before 6.0, IMAGE_UTIL_COLORSPACE_RGBA8888 was the only supported colorspace for PNG. But since 6.0, this module supports more colorspaces for PNG. To get supported colorspaces for PNG, you can use image_util_foreach_supported_colorspace().
Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.

Parameters:

[in]	handle	The handle of image util encoding
[in]	image	The image handle for encoding
[in]	file_path	The file path for encoding image

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

Return values:

IMAGE_UTIL_ERROR_NONE	Successful
IMAGE_UTIL_ERROR_PERMISSION_DENIED	Permission denied
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	Not supported format

Precondition:: image_util_encode_create()

Postcondition:: image_util_encode_destroy()

See also:: image_util_encode_create(); 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.

Deprecated:: Deprecated since 5.5. Use image_util_create_image() instead.

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 of image util encoding
[in]	colorspace	The colorspace of the input image to encode

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

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.

Deprecated:: Deprecated since 5.5. Use image_util_agif_encode_add_frame() instead.

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 of 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_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format

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.

Deprecated:: Deprecated since 5.5. Use image_util_create_image() instead.

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 of 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_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.

Deprecated:: Deprecated since 5.5. Use image_util_encode_run_to_buffer() or image_util_encode_run_async_to_buffer() instead.

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.
Before 4.0, output buffer setting is not supported for BMP. IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT will be returned for BMP.
Since 4.0, output buffer setting has been supported for BMP. Applications can set the output buffer to write encoded BMP.
In case of GIF encoding, the output buffer will be completely available only after image_util_encode_destroy(). dst_buffer should be released after image_util_encode_run() or image_util_encode_run_async().

Parameters:

[in]	handle	The handle of 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	Not supported format

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.

Deprecated:: Deprecated since 5.5. Use image_util_encode_run_to_file() or image_util_encode_run_async_to_file() instead.

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 of 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_PERMISSION_DENIED	The application does not have the privilege to call this function
IMAGE_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_NO_SUCH_FILE	No such file

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 the default value is IMAGE_UTIL_PNG_COMPRESSION_6.

Parameters:

[in]	handle	The handle of 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_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_INVALID_OPERATION	Invalid operation
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format

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_run_to_file(); image_util_encode_run_to_buffer(); image_util_encode_run_async_to_file(); image_util_encode_run_async_to_buffer(); 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 of 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_INVALID_PARAMETER	Invalid parameter
IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format

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_run_to_file(); image_util_encode_run_to_buffer(); image_util_encode_run_async_to_file(); image_util_encode_run_async_to_buffer(); 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.

Deprecated:: Deprecated since 5.5. Use image_util_create_image() instead.

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 of 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_encode_set_webp_lossless	(	image_util_encode_h	handle,
		bool	lossless
	)

Sets lossless compression of WEBP images.

Since :: 6.0

Remarks:: If application does not set this, then the default value is false.

Parameters:

[in]	handle	The handle of image util encoding
[in]	lossless	The flag determining whether the compression is lossless or lossy: true for lossless, false for lossy

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	Not supported format

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_run_to_file(); image_util_encode_run_to_buffer(); image_util_encode_run_async_to_file(); image_util_encode_run_async_to_buffer(); 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()

Required Header

Overview

Foreach Operations

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation