From: Ji Yong Min Date: Thu, 11 Feb 2016 06:02:19 +0000 (+0900) Subject: Update doxygen (seperate doc to transform and encode/decode modules) X-Git-Tag: submit/tizen/20160223.021211~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F70%2F59170%2F5;p=platform%2Fcore%2Fapi%2Fimage-util.git Update doxygen (seperate doc to transform and encode/decode modules) Change-Id: Icb456835a1eb3162691b87d63195110a6dbfe3b8 Signed-off-by: Jiyong Min --- diff --git a/doc/image_util_doc.h b/doc/image_util_doc.h index d2d4797..a98b3aa 100755 --- a/doc/image_util_doc.h +++ b/doc/image_util_doc.h @@ -25,7 +25,8 @@ /** * @defgroup CAPI_MEDIA_IMAGE_UTIL_MODULE Image Util - * @brief The @ref CAPI_MEDIA_IMAGE_UTIL_MODULE APIs provides functions for encoding and decoding of images . + * @brief The @ref CAPI_MEDIA_IMAGE_UTIL_MODULE APIs provides functions for common of images . + * * @ingroup CAPI_MEDIA_FRAMEWORK * * @section CAPI_MEDIA_IMAGE_UTIL_MODULE_HEADER Required Header @@ -33,17 +34,51 @@ * * @section CAPI_MEDIA_IMAGE_UTIL_MODULE_OVERVIEW Overview * - * Image Util API provides support for encoding and decoding of images. The API allows : - *- Encoding/Decoding of a JPEG image. - *- Encoding/Decoding of a JPEG image to/from memory. + * Image Util API provides support for common functions of images. The API allows : + *- Calculate the size of the image buffer for the specified resolution and colorspace to be used in the image util module. + *- Extracts representative color from an image buffer. + * + * The API consists of @ref CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE,@ref CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE. + */ + +/** + * @defgroup CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE Image Util Transform + * @brief The @ref CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE APIs provides functions for transfroming of images . + * + * @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE + * + * @section CAPI_MEDIA_IMAGE_UTIL_MODULE_TRANSFORM_HEADER Required Header + * \#include + * + * @section CAPI_MEDIA_IMAGE_UTIL_MODULE_TRANSFORM_OVERVIEW Overview + * + * Image Util API provides support for transforming of images. The API allows : *- Image transformation(Colorspace conversion/Resize/Rotate/Crop) . * - * The decoding of a jpeg image located at a given path, to a buffer can be done by calling #image_util_decode_jpeg() function and decoding of a jpeg image on memory - * can be done by calling #image_util_decode_jpeg_from_memory(). Similarly, for encoding #image_util_encode_jpeg() and #image_util_encode_jpeg_to_memory() functions can be called - * to encode an image buffer to a jpeg image and a jpeg buffer respectively. The API also allows to transform including convert the colorspace(#image_util_colorspace_e) of an image by calling + * The API allows to transform(Colorspace conversion/Resize/Rotate/Crop) including convert the colorspace(#image_util_colorspace_e) of an image by calling * #image_util_transform_run() function. + */ + +/** + * @defgroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE Image Util Encode/Decode + * @brief The @ref CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE APIs provides functions for encoding and decoding of images . + * + * @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE + * + * @section CAPI_MEDIA_IMAGE_UTIL_MODULE_ENCODE_DECODE_HEADER Required Header + * \#include + * + * @section CAPI_MEDIA_IMAGE_UTIL_MODULE_ENCODE_DECODE_OVERVIEW 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_run_set_output_buffer() functions can be called + * to encode an image buffer to a jpeg/png/gif/bmp image and a buffer respectively. * - * @subsection CAPI_MEDIA_IMAGE_UTIL_FOREACH_OPERATIONS Foreach Operations + * @subsection CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_FOREACH_OPERATIONS Foreach Operations *
* * @@ -51,9 +86,9 @@ * * * - * - * - * + * + * + * * *
FOREACHDESCRIPTION
image_util_foreach_supported_jpeg_colorspace()image_util_supported_jpeg_colorspace_cb() Supported JPEG encoding/decoding colorspaceimage_util_foreach_supported_colorspace()image_util_supported_colorspace_cb() Supported JPEG/PNG/GIF/BMP encoding/decoding colorspace
*/ diff --git a/include/image_util.h b/include/image_util.h index 369653b..dc45078 100755 --- a/include/image_util.h +++ b/include/image_util.h @@ -34,6 +34,62 @@ extern "C" * @{ */ +/** +* @brief Calculates the size of the image buffer for the specified resolution and colorspace. +* @since_tizen 2.3 +* +* @param[in] width The image width +* @param[in] height The image height +* @param[in] colorspace The image colorspace +* @param[out] size The Calculated buffer size +* +* @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_PERMISSION_DENIED The application does not have the privilege to call this funtion +* +* @see image_util_transform_run() +* @see image_util_decode_jpeg() +* @see image_util_decode_jpeg_from_memory() +* @see image_util_encode_jpeg() +* @see image_util_encode_jpeg_to_memory() +*/ +int image_util_calculate_buffer_size(int width, int height, image_util_colorspace_e colorspace , unsigned int *size); + +/** +* @brief Extracts representative color from an image buffer +* @since_tizen 3.0 +* @remarks @a image_buffer should be RGB888 colorspace. +* +* @param[in] image_buffer The original image buffer +* @param[in] width The image width +* @param[in] height The image height +* @param[out] rgb_r The red color in RGB color space +* @param[out] rgb_g The green color in RGB color space +* @param[out] rgb_b The blue color in RGB color space +* +* @return 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_OUT_OF_MEMORY out of memory +* @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation +* +*/ +int image_util_extract_color_from_memory(const unsigned char *image_buffer, int width, int height, unsigned char *rgb_r, unsigned char *rgb_g, unsigned char *rgb_b); + +/** + * @} + */ + +/** + * @addtogroup CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE + * @{ + */ + /** * @brief Creates a handle to image util transform. * @since_tizen 2.3 @@ -332,74 +388,6 @@ int image_util_transform_run(transformation_h handle, media_packet_h src, image_ */ int image_util_transform_destroy(transformation_h handle); -/** -* @deprecated Deprecated since 3.0. Use image_util_supported_colorspace_cb() instead. -* @brief Called once for each supported JPEG encode/decode colorspace. -* @since_tizen 2.3 -* -* @param[in] colorspace The colorspace -* @param[in] user_data The user data passed from the foreach function -* -* @return @c true to continue with the next iteration of the loop, \n -* otherwise @c false to break out of the loop -* -* @pre image_util_foreach_supported_jpeg_colorspace() invokes this callback. -* -* @see image_util_foreach_supported_jpeg_colorspace() -* @see image_util_encode_jpeg() -* @see image_util_encode_jpeg_to_memory() -* @see image_util_decode_jpeg() -* @see image_util_decode_jpeg_from_memory() -*/ -typedef bool(*image_util_supported_jpeg_colorspace_cb)(image_util_colorspace_e colorspace, void *user_data); - -/** -* @deprecated Deprecated since 3.0. Use image_util_foreach_supported_colorspace() instead. -* @brief Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one. -* @since_tizen 2.3 -* -* @param[in] callback The callback function to invoke -* @param[in] user_data The user data to be passed to the callback function -* @return 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_PERMISSION_DENIED The application does not have the privilege to call this funtion -* @post This function invokes image_util_supported_jpeg_colorspace_cb() repeatedly to retrieve each supported JPEG encoding/decoding colorspace. -* -* @see image_util_supported_jpeg_colorspace_cb() -* @see image_util_encode_jpeg() -* @see image_util_encode_jpeg_to_memory() -* @see image_util_decode_jpeg() -* @see image_util_decode_jpeg_from_memory() -*/ -int image_util_foreach_supported_jpeg_colorspace(image_util_supported_jpeg_colorspace_cb callback, void *user_data); - -/** -* @brief Calculates the size of the image buffer for the specified resolution and colorspace. -* @since_tizen 2.3 -* -* @param[in] width The image width -* @param[in] height The image height -* @param[in] colorspace The image colorspace -* @param[out] size The Calculated buffer size -* -* @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_PERMISSION_DENIED The application does not have the privilege to call this funtion -* -* @see image_util_transform_run() -* @see image_util_decode_jpeg() -* @see image_util_decode_jpeg_from_memory() -* @see image_util_encode_jpeg() -* @see image_util_encode_jpeg_to_memory() -*/ -int image_util_calculate_buffer_size(int width, int height, image_util_colorspace_e colorspace , unsigned int *size); - /** * @internal * @brief Converts the image's colorspace. @@ -535,8 +523,58 @@ int image_util_rotate(unsigned char *dest, int *dest_width, int *dest_height, im */ int image_util_crop(unsigned char *dest, int x, int y, int *width, int *height, const unsigned char *src, int src_width, int src_height, image_util_colorspace_e colorspace); +/** + * @} + */ +/** +* @addtogroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE +* @{ +*/ +/** +* @deprecated Deprecated since 3.0. Use image_util_supported_colorspace_cb() instead. +* @brief Called once for each supported JPEG encode/decode colorspace. +* @since_tizen 2.3 +* +* @param[in] colorspace The colorspace +* @param[in] user_data The user data passed from the foreach function +* +* @return @c true to continue with the next iteration of the loop, \n +* otherwise @c false to break out of the loop +* +* @pre image_util_foreach_supported_jpeg_colorspace() invokes this callback. +* +* @see image_util_foreach_supported_jpeg_colorspace() +* @see image_util_encode_jpeg() +* @see image_util_encode_jpeg_to_memory() +* @see image_util_decode_jpeg() +* @see image_util_decode_jpeg_from_memory() +*/ +typedef bool(*image_util_supported_jpeg_colorspace_cb)(image_util_colorspace_e colorspace, void *user_data); + +/** +* @deprecated Deprecated since 3.0. Use image_util_foreach_supported_colorspace() instead. +* @brief Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one. +* @since_tizen 2.3 +* +* @param[in] callback The callback function to invoke +* @param[in] user_data The user data to be passed to the callback function +* @return 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_PERMISSION_DENIED The application does not have the privilege to call this funtion +* @post This function invokes image_util_supported_jpeg_colorspace_cb() repeatedly to retrieve each supported JPEG encoding/decoding colorspace. +* +* @see image_util_supported_jpeg_colorspace_cb() +* @see image_util_encode_jpeg() +* @see image_util_encode_jpeg_to_memory() +* @see image_util_decode_jpeg() +* @see image_util_decode_jpeg_from_memory() +*/ +int image_util_foreach_supported_jpeg_colorspace(image_util_supported_jpeg_colorspace_cb callback, void *user_data); /** * @deprecated Deprecated since 3.0. Use image_util_decode_create() instead. @@ -737,29 +775,6 @@ int image_util_encode_jpeg(const unsigned char *buffer, int width, int height, i */ 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); -/** -* @brief Extracts representative color from an image buffer -* @since_tizen 3.0 -* @remarks @a image_buffer should be RGB888 colorspace. -* -* @param[in] image_buffer The original image buffer -* @param[in] width The image width -* @param[in] height The image height -* @param[out] rgb_r The red color in RGB color space -* @param[out] rgb_g The green color in RGB color space -* @param[out] rgb_b The blue color in RGB color space -* -* @return 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_OUT_OF_MEMORY out of memory -* @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation -* -*/ -int image_util_extract_color_from_memory(const unsigned char *image_buffer, int width, int height, unsigned char *rgb_r, unsigned char *rgb_g, unsigned char *rgb_b); - /** * @brief Called once for each supported image encode/decode colorspace. * @since_tizen 3.0 diff --git a/include/image_util_type.h b/include/image_util_type.h index 32ef371..b744e12 100755 --- a/include/image_util_type.h +++ b/include/image_util_type.h @@ -80,15 +80,13 @@ typedef enum { } image_util_colorspace_e; /** - * @brief Enumeration for scale decoding. - * @since_tizen 2.4 + * @} + */ + +/** + * @addtogroup CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE + * @{ */ -typedef enum { - 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 */ -} image_util_scale_e; /** * @brief Enumeration for rotation. @@ -104,14 +102,14 @@ typedef enum { } image_util_rotation_e; /** -* @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE +* @ingroup CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE * @brief Image util handle. * @since_tizen 2.3 */ typedef struct transformation_s *transformation_h; /** -* @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE +* @ingroup CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE * @brief Called when transform is finished just before returning the output. * @since_tizen 2.3 * @@ -124,6 +122,15 @@ typedef struct transformation_s *transformation_h; */ typedef void(*image_util_transform_completed_cb)(media_packet_h *dst, int error_code, void *user_data); +/** + * @} + */ + +/** + * @addtogroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE + * @{ + */ + /** * @brief Enumeration for Image types. * @since_tizen 3.0 @@ -135,6 +142,17 @@ typedef enum { IMAGE_UTIL_BMP, /**< Image format BMP */ } image_util_type_e; +/** + * @brief Enumeration for scale decoding. + * @since_tizen 2.4 + */ +typedef enum { + 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 */ +} image_util_scale_e; + /** * @brief Enumeration for PNG compression values. * @since_tizen 3.0 @@ -153,7 +171,7 @@ typedef enum { } image_util_png_compression_e; /** -* @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE +* @ingroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE * @brief Called when Image-util decoding is finished just before returning the output. * @since_tizen 3.0 * @@ -173,7 +191,7 @@ typedef enum { typedef void (*image_util_decode_completed_cb) (int error_code, void *user_data, unsigned long width, unsigned long height, unsigned long long size); /** -* @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE +* @ingroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE * @brief Called when Image-util encoding is finished just before returning the output. * @since_tizen 3.0 * @@ -191,14 +209,14 @@ typedef void (*image_util_decode_completed_cb) (int error_code, void *user_data, typedef void (*image_util_encode_completed_cb) (int error_code, void *user_data, unsigned long long size); /** -* @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE +* @ingroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE * @brief Image-util decoding handle. * @since_tizen 3.0 */ typedef void *image_util_decode_h; /** -* @ingroup CAPI_MEDIA_IMAGE_UTIL_MODULE +* @ingroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE * @brief Image-util encoding handle. * @since_tizen 3.0 */ diff --git a/packaging/capi-media-image-util.spec b/packaging/capi-media-image-util.spec index 21a908d..3b49dd0 100755 --- 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.1.8 +Version: 0.1.9 Release: 1 Group: Multimedia/API License: Apache-2.0