From: jiyong.min Date: Thu, 6 Aug 2020 03:54:12 +0000 (+0900) Subject: [ACR-1595] Add animation encoding APIs for GIF and WEBP X-Git-Tag: accepted/tizen/unified/20200906.032707~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3526ad876b441f88e840d400dcbaf951f24b74a1;p=platform%2Fcore%2Fapi%2Fimage-util.git [ACR-1595] Add animation encoding APIs for GIF and WEBP Change-Id: I7e126c9bd21f5690de76be18fe8bc4179fc81e1a --- diff --git a/include/image_util_decode.h b/include/image_util_decode.h index c78bc1d..465e2d0 100644 --- a/include/image_util_decode.h +++ b/include/image_util_decode.h @@ -56,8 +56,8 @@ int image_util_decode_create(image_util_decode_h *handle); * * @remarks One of image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.\n * If both are set then the latest input set, is considered.\n -* http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n -* http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n +* %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n +* %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n * Finds out image type by reading the header of the image provided in input path.\n * Since 6.0, this module supports WEBP image format. * @@ -228,7 +228,7 @@ int image_util_decode_set_jpeg_downscale(image_util_decode_h handle, image_util_ * * @remarks The output will be stored in the pointer set using image_util_decode_set_output_buffer().\n * The function executes synchronously.\n -* When any of the pre-condition are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned. +* When any of the pre-condition are not called, #IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned. * * @param[in] handle The handle of image util decoding * @param[out] width Width of the decoded image diff --git a/include/image_util_encode.h b/include/image_util_encode.h index 0d47a8f..d18308a 100644 --- a/include/image_util_encode.h +++ b/include/image_util_encode.h @@ -302,8 +302,8 @@ int image_util_encode_set_input_buffer(image_util_encode_h handle, const unsigne * * @remarks One of image_util_encode_set_output_path() or image_util_encode_set_output_buffer() should be set.\n * If both are set then the latest output set is considered.\n -* http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n -* http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage. +* %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n +* %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage. * * @param[in] handle The handle of image util encoding * @param[in] path The output file path @@ -455,9 +455,9 @@ int image_util_encode_run_async(image_util_encode_h handle, image_util_encode_co * @remarks If any functions at the pre-condition are not called first, #IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.\n * The only supported colorspace for BMP and GIF is #IMAGE_UTIL_COLORSPACE_RGBA8888.\n * To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().\n -* http://tizen.org/privilege/mediastorage is required if @a file_path value is media storage.\n -* http://tizen.org/privilege/externalstorage is required if @a file_path value is external storage.\n -* 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. +* %http://tizen.org/privilege/mediastorage is required if @a file_path value is media storage.\n +* %http://tizen.org/privilege/externalstorage is required if @a file_path value is external storage.\n +* 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().\n * Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.\n * @@ -493,7 +493,7 @@ int image_util_encode_run_to_file(image_util_encode_h handle, image_util_image_h * The @a buffer should be released using free().\n * The only supported colorspace for BMP and GIF is #IMAGE_UTIL_COLORSPACE_RGBA8888.\n * To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().\n -* 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. +* 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().\n * Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.\n * @@ -528,9 +528,9 @@ int image_util_encode_run_to_buffer(image_util_encode_h handle, image_util_image * @remarks If any functions at the pre-condition are not called first, #IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.\n * The only supported colorspace for BMP and GIF is #IMAGE_UTIL_COLORSPACE_RGBA8888.\n * To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().\n -* http://tizen.org/privilege/mediastorage is required if @a file_path value is media storage.\n -* http://tizen.org/privilege/externalstorage is required if @a file_path value is external storage.\n -* 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. +* %http://tizen.org/privilege/mediastorage is required if @a file_path value is media storage.\n +* %http://tizen.org/privilege/externalstorage is required if @a file_path value is external storage.\n +* 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().\n * Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.\n * @@ -566,7 +566,7 @@ int image_util_encode_run_async_to_file(image_util_encode_h handle, image_util_i * @remarks If any functions at the pre-condition are not called first, #IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.\n * The only supported colorspace for BMP and GIF is #IMAGE_UTIL_COLORSPACE_RGBA8888.\n * To get supported colorspaces for JPEG format, you can use image_util_foreach_supported_colorspace().\n -* 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. +* 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().\n * Since 6.0, this module supports WEBP, you can use image_util_foreach_supported_colorspace() to get supported colorspaces for WEBP.\n * @@ -680,19 +680,20 @@ int image_util_agif_encode_add_frame(image_util_agif_encode_h handle, image_util * @details After the data has been written to a file, * the file cannot be modified. In other words,\n * it is not possible to add frames to the file.\n +* Saving animation flushes the frames that has been added to the encoder.\n * However, the encoder can be still used after the data is written.\n * For example, although you write the data to one file(B0),\n * you can do the following operations:\n * * 1. Add frames 1-10 to the encoder.\n -* 2. Save the data in the encoder to another file(B1).\n +* 2. Save the data in the encoder to another file(B1). 10 frames will be saved.\n * 3. Add more frames (11-20) to the same encoder.\n * 4. Save the data in the encoder to the other file (B2)\n * It is not possible to save the changed data to B1 file used in step 4. * @since_tizen 5.5 * -* @remarks http://tizen.org/privilege/mediastorage is required if @a file_path value is media storage.\n -* http://tizen.org/privilege/externalstorage is required if @a file_path value is external storage. +* @remarks %http://tizen.org/privilege/mediastorage is required if @a file_path value is media storage.\n +* %http://tizen.org/privilege/externalstorage is required if @a file_path value is external storage. * * @param[in] handle The handle of encoding an animated GIF * @param[in] file_path The file path for saving the animated GIF @@ -722,12 +723,13 @@ int image_util_agif_encode_save_to_file(image_util_agif_encode_h handle, const c * @details After the data has been written to a buffer, * the file cannot be modified. In other words,\n * it is not possible to add frames to the buffer.\n +* Saving animation flushes the frames that has been added to the encoder.\n * However, the encoder can be still used after the data is written.\n * For example, although you write the data to one buffer(B0),\n * you can do the following operations:\n * * 1. Add frames 1-10 to the encoder.\n -* 2. Save the data in the encoder to another buffer(B1).\n +* 2. Save the data in the encoder to another buffer(B1). 10 frames will be saved.\n * 3. Add more frames (11-20) to the same encoder.\n * 4. Save the data in the encoder to the other buffer (B2)\n * It is not possible to save the changed data to B1 file used in step 4. @@ -779,6 +781,227 @@ int image_util_agif_encode_save_to_buffer(image_util_agif_encode_h handle, unsig int image_util_agif_encode_destroy(image_util_agif_encode_h handle); /** +* @brief Creates a handle for encoding animation. +* @since_tizen 6.0 +* +* @remarks The @a handle should be released using image_util_anim_encode_destroy(). +* +* @param[in] image_type The type of output image to create animation +* @param[out] handle The handle of animation encoder +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format +* +* @see image_util_anim_encode_add_frame() +* @see image_util_anim_encode_save_to_file() +* @see image_util_anim_encode_save_to_buffer() +* @see image_util_anim_encode_destroy() +* +*/ +int image_util_anim_encode_create(image_util_anim_type_e image_type, image_util_anim_encode_h *handle); + +/** +* @brief Sets a number of times to repeat the animation. +* @since_tizen 6.0 +* +* @remarks This function should be called before image_util_anim_encode_add_frame() is called. +* +* @param[in] handle The handle of animation encoder +* @param[in] loop_count The number of times to repeat the animation +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format +* +* @pre image_util_anim_encode_create() +* +*/ +int image_util_anim_encode_set_loop_count(image_util_anim_encode_h handle, unsigned int loop_count); + +/** +* @brief Sets a background color of the animation. +* @since_tizen 6.0 +* +* @remarks This function should be called before image_util_anim_encode_add_frame() is called. +* +* @param[in] handle The handle of animation encoder +* @param[in] r The red color of the background +* @param[in] g The green color of the background +* @param[in] b The blue color of the background +* @param[in] a The alpha color of the background +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format +* +* @pre image_util_anim_encode_create() +* +*/ +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); + +/** +* @brief Sets lossless compression of animation. +* @since_tizen 6.0 +* +* @remarks This function should be called before image_util_anim_encode_add_frame() is called. +* +* @param[in] handle The handle of animation encoder +* @param[in] lossless The flag determining whether the compression is lossless or lossy: true for lossless, false for lossy +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format +* +* @pre image_util_anim_encode_create() +* +*/ +int image_util_anim_encode_set_lossless(image_util_anim_encode_h handle, bool lossless); + +/** +* @brief Encodes an image and adds image to the frame of the animated image. +* @since_tizen 6.0 +* +* @remarks This function should be called for each @a image which you want to add to the animated WEBP or GIF. Each @a image should be the same size.\n +* The supported colorspaces are #IMAGE_UTIL_COLORSPACE_RGBA8888, #IMAGE_UTIL_COLORSPACE_ARGB8888, #IMAGE_UTIL_COLORSPACE_BGRA8888 and #IMAGE_UTIL_COLORSPACE_RGBA8888 for animated WEBP.\n +* The supported colorspace is #IMAGE_UTIL_COLORSPACE_RGBA8888 for animated GIF.\n +* You should call image_util_anim_encode_save_to_file() or image_util_anim_encode_save_to_buffer() to save the animated WEBP.\n +* 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. +* +* @param[in] handle The handle of animation encoder +* @param[in] image The handle of the image for each frame +* @param[in] time_delay The time delay between @a image and the next image (in 1ms increments for WEBP and 10ms increments for GIF) +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation +* @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory +* +* @pre image_util_anim_encode_create() +* +* @post image_util_anim_encode_save_to_file() +* @post image_util_anim_encode_save_to_buffer() +* +* @see image_util_anim_encode_save_to_file() +* @see image_util_anim_encode_save_to_buffer() +* +*/ +int image_util_anim_encode_add_frame(image_util_anim_encode_h handle, image_util_image_h image, unsigned int time_delay); + +/** +* @brief Saves the animated WEBP or GIF image to the file. +* @details After the data has been written to a file, +* the file cannot be modified. In other words,\n +* it is not possible to add frames to the file.\n +* Saving animation flushes the frames that has been added to the encoder.\n +* However, the encoder can be still used after the data is written.\n +* For example, although you write the data to one file(B0),\n +* you can do the following operations:\n +* +* 1. Add frames 1-10 to the encoder.\n +* 2. Save the data in the encoder to another file(B1). 10 frames will be saved.\n +* 3. Add more frames (11-20) to the same encoder.\n +* 4. Save the data in the encoder to the other file (B2)\n +* It is not possible to save the changed data to B1 file used in step 4. +* @since_tizen 6.0 +* +* @remarks %http://tizen.org/privilege/mediastorage is required if @a file_path value is media storage.\n +* %http://tizen.org/privilege/externalstorage is required if @a file_path value is external storage. +* +* @param[in] handle The handle of encoding an animated WEBP or GIF +* @param[in] file_path The file path for saving the animated WEBP or GIF +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED Permission denied +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation +* @retval #IMAGE_UTIL_ERROR_NO_SUCH_FILE No such file +* +* @pre image_util_anim_encode_create() +* +* @see image_util_anim_encode_add_frame() +* +*/ +int image_util_anim_encode_save_to_file(image_util_anim_encode_h handle, const char *file_path); + +/** +* @brief Saves the animation WEBP or GIF image to the buffer. +* @details After the data has been written to a buffer, +* the file cannot be modified. In other words,\n +* it is not possible to add frames to the buffer.\n +* Saving animation flushes the frames that has been added to the encoder.\n +* However, the encoder can be still used after the data is written.\n +* For example, although you write the data to one buffer(B0),\n +* you can do the following operations:\n +* +* 1. Add frames 1-10 to the encoder.\n +* 2. Save the data in the encoder to another buffer(B1). 10 frames will be saved.\n +* 3. Add more frames (11-20) to the same encoder.\n +* 4. Save the data in the encoder to the other buffer (B2)\n +* It is not possible to save the changed data to B1 file used in step 4. +* @since_tizen 6.0 +* +* @remarks The @a buffer should be released using free() after using it. +* +* @param[in] handle The handle of encoding an animated WEBP or GIF +* @param[out] buffer The buffer in which the animated WEBP or GIF is saved +* @param[out] buffer_size The size of the buffer +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation +* +* @pre image_util_anim_encode_create() +* +* @see image_util_anim_encode_add_frame() +* +*/ +int image_util_anim_encode_save_to_buffer(image_util_anim_encode_h handle, unsigned char **buffer, size_t *buffer_size); + +/** +* @brief Destroys the handle for encoding animation. +* @since_tizen 6.0 +* +* @remarks Any created animated encoder handle created should be destroyed. +* +* @param[in] handle The handle of animation encoder +* +* @return @c 0 on success, +* otherwise a negative error value +* +* @retval #IMAGE_UTIL_ERROR_NONE Successful +* @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter +* +* @pre image_util_anim_encode_create() +* +* @see image_util_anim_encode_create() +* +*/ +int image_util_anim_encode_destroy(image_util_anim_encode_h handle); + +/** * @} */ diff --git a/include/image_util_type.h b/include/image_util_type.h index 80ef349..80d7b9a 100644 --- a/include/image_util_type.h +++ b/include/image_util_type.h @@ -163,7 +163,7 @@ typedef void(*image_util_transform_completed2_cb)(image_util_image_h dst, int er */ /** - * @brief Enumeration for Image types. + * @brief Enumeration for image types. * @since_tizen 3.0 */ typedef enum { @@ -175,6 +175,15 @@ typedef enum { } image_util_type_e; /** + * @brief Enumeration for animated image type. + * @since_tizen 6.0 + */ +typedef enum { + IMAGE_UTIL_ANIM_GIF, /**< Image format animated GIF */ + IMAGE_UTIL_ANIM_WEBP, /**< Image format animated WEBP */ +} image_util_anim_type_e; + +/** * @brief Enumeration for scale decoding. * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif */ @@ -327,12 +336,19 @@ typedef void *image_util_encode_h; /** * @ingroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE -* @brief Image-util animation encoding handle. +* @brief Image-util animation GIF encoding handle. * @since_tizen 5.5 */ typedef void *image_util_agif_encode_h; /** +* @ingroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE +* @brief Image-util animation encoding handle. +* @since_tizen 6.0 +*/ +typedef void *image_util_anim_encode_h; + +/** * @} */ diff --git a/packaging/capi-media-image-util.spec b/packaging/capi-media-image-util.spec index de2440a..65b79bf 100644 --- a/packaging/capi-media-image-util.spec +++ b/packaging/capi-media-image-util.spec @@ -1,6 +1,6 @@ Name: capi-media-image-util Summary: A Image Utility library in Tizen Native API -Version: 0.2.9 +Version: 0.2.10 Release: 0 Group: Multimedia/API License: Apache-2.0