include/image_util.h

   1 /*
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   4 * Licensed under the Apache License, Version 2.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17
  18
  19
  20 #ifndef __TIZEN_MEDIA_IMAGE_UTIL_H__
  21 #define __TIZEN_MEDIA_IMAGE_UTIL_H__
  22
  23 #include <tizen.h>
  24
  25 #ifdef __cplusplus
  26 extern "C"
  27 {
  28 #endif
  29
  30 #define IMAGE_UTIL_ERROR_CLASS          TIZEN_ERROR_MULTIMEDIA_CLASS | 0x70
  31
  32 /**
  33  * @file image_util.h
  34  * @brief This file contains the image util API
  35  */
  36
  37 /**
  38  * @addtogroup CAPI_MEDIA_IMAGE_UTIL_MODULE
  39  * @{
  40  */
  41
  42
  43 typedef enum
  44 {
  45     IMAGE_UTIL_ERROR_NONE =              TIZEN_ERROR_NONE,                                                                                                      /**< Successful */
  46     IMAGE_UTIL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,         /**< Invalid parameter */
  47     IMAGE_UTIL_ERROR_OUT_OF_MEMORY =     TIZEN_ERROR_OUT_OF_MEMORY,                             /**< Out of memory */
  48     IMAGE_UTIL_ERROR_NO_SUCH_FILE  = TIZEN_ERROR_NO_SUCH_FILE,                                                  /**< No such file */
  49     IMAGE_UTIL_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,                 /**< Internal error */
  50     IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT = TIZEN_ERROR_NOT_SUPPORT_API /**< Not supported format */
  51 } image_util_error_e;
  52
  53
  54
  55
  56 /**
  57  * @brief Enumerations of colorspace
  58  */
  59 typedef enum
  60 {
  61         IMAGE_UTIL_COLORSPACE_YV12,                             /**< YV12 - YCrCb planar format */
  62         IMAGE_UTIL_COLORSPACE_YUV422,                   /**< YUV422 - planer */
  63         IMAGE_UTIL_COLORSPACE_I420,                             /**< I420 - planer */
  64         IMAGE_UTIL_COLORSPACE_NV12,                             /**< NV12- planer */
  65
  66         IMAGE_UTIL_COLORSPACE_UYVY,                             /**< UYVY - packed */
  67         IMAGE_UTIL_COLORSPACE_YUYV,                             /**< YUYV - packed */
  68
  69         IMAGE_UTIL_COLORSPACE_RGB565,                   /**< RGB565, high-byte is Blue */
  70         IMAGE_UTIL_COLORSPACE_RGB888,                   /**< RGB888, high-byte is Blue */
  71         IMAGE_UTIL_COLORSPACE_ARGB8888,         /**< ARGB8888, high-byte is Blue */
  72
  73         IMAGE_UTIL_COLORSPACE_BGRA8888,         /**< BGRA8888, high-byte is Alpha */
  74         IMAGE_UTIL_COLORSPACE_RGBA8888,         /**< RGBA8888, high-byte is Alpha */
  75         IMAGE_UTIL_COLORSPACE_BGRX8888,                 /**< BGRX8888, high-byte is X */
  76
  77 }image_util_colorspace_e;
  78
  79
  80 /**
  81  * @brief Enumerations of rotation
  82  */
  83 typedef enum
  84 {
  85         IMAGE_UTIL_ROTATION_NONE = 0,                   /**< None */
  86     IMAGE_UTIL_ROTATION_90 = 1,                 /**< Rotation 90 degree */
  87     IMAGE_UTIL_ROTATION_180,                            /**< Rotation 180 degree */
  88     IMAGE_UTIL_ROTATION_270,                            /**< Rotation 270 degree */
  89     IMAGE_UTIL_ROTATION_FLIP_HORZ,       /**< Flip horizontal */
  90     IMAGE_UTIL_ROTATION_FLIP_VERT,       /**< Flip vertical */
  91 } image_util_rotation_e;
  92
  93
  94
  95
  96 /**
  97  * @brief       Called once for each supported JPEG encode/decode colorspace.
  98  *
  99  * @param[in] colorspace         The colorspace
 100  * @param[in] user_data     The user data passed from the foreach function
 101  *
 102  * @return      @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 103  * @pre         image_util_foreach_supported_jpeg_colorspace() will invokes this callback.
 104  *
 105  * @see image_util_foreach_supported_jpeg_colorspace()
 106  * @see image_util_encode_jpeg()
 107  * @see image_util_encode_jpeg_to_memory()
 108  * @see image_util_decode_jpeg()
 109  * @see image_util_decode_jpeg_from_memory()
 110  */
 111 typedef bool (*image_util_supported_jpeg_colorspace_cb)( image_util_colorspace_e colorspace , void * user_data);
 112
 113 /**
 114  * @brief Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one.
 115  *
 116  * @param[in]   callback    The callback function to invoke
 117  * @param[in]   user_data       The user data to be passed to the callback function
 118  * @return        0 on success, otherwise a negative error value.
 119  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 120  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 121  * @post        This function invokes image_util_supported_jpeg_colorspace_cb() repeatedly to retrieve each supported jpeg encoding/decoding colorspace
 122  *
 123  * @see image_util_supported_jpeg_colorspace_cb()
 124  * @see image_util_encode_jpeg()
 125  * @see image_util_encode_jpeg_to_memory()
 126  * @see image_util_decode_jpeg()
 127  * @see image_util_decode_jpeg_from_memory()
 128  */
 129 int image_util_foreach_supported_jpeg_colorspace(image_util_supported_jpeg_colorspace_cb callback, void * user_data);
 130
 131 /**
 132  * @brief Convert the image's colorspace
 133  *
 134  * @remarks To get @a dest buffer size uses image_util_calculate_buffer_size()
 135  *
 136  * @param[in/out]       dest    The image buffer for result. Must be allocated by you
 137  * @param[in]   dest_colorspace The colorspace to be converted
 138  * @param[in]   src     The source image buffer
 139  * @param[in]   width   The width of source image
 140  * @param[in]   height  The height of source image
 141  * @param[in]   src_colorspace  The colorspace of source image buffer
 142  * @return        0 on success, otherwise a negative error value.
 143  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 144  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 145  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 146  *
 147  * @see image_util_calculate_buffer_size()
 148  */
 149 int image_util_convert_colorspace( unsigned char * dest , image_util_colorspace_e dest_colorspace , const unsigned char * src ,  int width, int height, image_util_colorspace_e src_colorspace);
 150
 151 /**
 152  * @brief Calculates the size of image buffer for the specified resolution and colorspace
 153  *
 154  * @param[in]   width   The image width
 155  * @param[in]   height  The image height
 156  * @param[in]   colorspace      The image colorspace
 157  * @param[out]  size    The Calculated buffer size
 158  * @return        0 on success, otherwise a negative error value.
 159  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 160  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 161  *
 162  * @see image_util_convert_colorspace()
 163  * @see image_util_resize()
 164  * @see image_util_rotation()
 165  */
 166 int image_util_calculate_buffer_size(int width , int height, image_util_colorspace_e colorspace  , unsigned int *size);
 167
 168 /**
 169  * @brief Resize the image to with the specified destination width and height
 170  *
 171  * @remarks Because padding of YUV format, the destination image size can be adjusted.\n
 172  *
 173  * @param[in/out]       dest    The image buffer for result. Must be allocated by you
 174  * @param[in/out]       dest_width      The image width to resize, and resized width
 175  * @param[in/out]       dest_height     The image height to resize, and resized height
 176  * @param[in]   src                             The image buffer for origin image
 177  * @param[in]   src_width               The origin image width
 178  * @param[in]   src_height              The origin image height
 179  * @param[in]   colorspace              The image colorspace
 180  *
 181  * @return        0 on success, otherwise a negative error value.
 182  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 183  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 184  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 185  *
 186  * @see image_util_calculate_buffer_size()
 187  */
 188 int image_util_resize(unsigned char * dest, int *dest_width , int *dest_height, const unsigned char * src, int src_width, int src_height , image_util_colorspace_e colorspace);
 189
 190 /**
 191  * @brief Rotate the image to with the specified angle in degrees.
 192  *
 193  * @remarks Because padding of YUV format, the destination image size can be adjusted.\n
 194  *  Rotations are supported only in these colorspaces\n
 195  * #IMAGE_UTIL_COLORSPACE_YV12 \n
 196  * #IMAGE_UTIL_COLORSPACE_I420 \n
 197  * #IMAGE_UTIL_COLORSPACE_NV12 \n
 198  * #IMAGE_UTIL_COLORSPACE_RGB888 \n
 199  *
 200  * @param[in/out]       dest    The image buffer for result. Must be allocated by you
 201  * @param[out]  dest_width The rotated image width
 202  * @param[out]  dest_height The rotated image height
 203  * @param[in]   dest_rotation   The angle to rotate
 204  * @param[in]   src                             The image buffer for origin image
 205  * @param[in]   src_width               The origin image width
 206  * @param[in]   src_height              The origin image height
 207  * @param[in]   colorspace              The image colorspace
 208  *
 209  * @return        0 on success, otherwise a negative error value.
 210  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 211  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 213  *
 214  * @see image_util_calculate_buffer_size()
 215  */
 216 int image_util_rotate(unsigned char * dest, int *dest_width, int *dest_height, image_util_rotation_e dest_rotation, const unsigned char * src, int src_width, int src_height, image_util_colorspace_e colorspace);
 217
 218 /**
 219  * @brief Crop the image to with the specified point and dimension
 220  *
 221  * @remarks Because padding of YUV format, the destination image size can be adjusted.\n
 222  *  Crop is supported only in these colorspaces\n
 223  * #IMAGE_UTIL_COLORSPACE_YV12 \n
 224  * #IMAGE_UTIL_COLORSPACE_I420 \n
 225  * #IMAGE_UTIL_COLORSPACE_RGB888 \n
 226  * #IMAGE_UTIL_COLORSPACE_RGB565 \n
 227  * #IMAGE_UTIL_COLORSPACE_ARGB8888\n
 228  * #IMAGE_UTIL_COLORSPACE_BGRA8888\n
 229  * #IMAGE_UTIL_COLORSPACE_RGBA8888\n
 230  * #IMAGE_UTIL_COLORSPACE_BGRX8888\n
 231  *
 232  * @param[in/out]       dest    The image buffer for result. Must be allocated by you
 233  * @param[in]   x The starting x-axis of crop
 234  * @param[in]   y The starting y-axis of crop
 235  * @param[in/out]       width  The image width to crop, and cropped width
 236  * @param[in/out]       height  The image height to crop, and cropped height
 237  * @param[in]   src                             The image buffer for origin image
 238  * @param[in]   src_width               The origin image width
 239  * @param[in]   src_height              The origin image height
 240  * @param[in]   colorspace              The image colorspace
 241  *
 242  * @return        0 on success, otherwise a negative error value.
 243  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 244  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 245  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 246  *
 247  * @see image_util_calculate_buffer_size()
 248  */
 249 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);
 250
 251
 252
 253
 254 /**
 255  * @brief Decodes jpeg image to the buffer
 256  *
 257  * @remarks @a image_buffer must be released with free() by you.
 258  *
 259  * @param[in]   path    The image file path
 260  * @param[in]   colorspace      The decoded image colorspace
 261  * @param[out]  image_buffer    The image buffer for decoded image
 262  * @param[out]  width   The image width
 263  * @param[out]  height  The image height
 264  * @param[out]  size            The image buffer size
 265  *
 266  * @return        0 on success, otherwise a negative error value.
 267  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 268  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 269  * @retval       #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 270  * @retval    #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 271  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 272  *
 273  * @see image_util_supported_jpeg_colorspace_cb()
 274  * @see image_util_decode_jpeg_from_memory()
 275  * @see image_util_foreach_supported_jpeg_colorspace()
 276  */
 277 int image_util_decode_jpeg( const char *path , image_util_colorspace_e colorspace, unsigned char ** image_buffer , int *width , int *height , unsigned int *size);
 278
 279 /**
 280  * @brief Decodes jpeg image(on memory) to the buffer
 281  *
 282  * @remarks @a image_buffer must be released with free() by you.
 283  *
 284  * @param[in]   jpeg_buffer     The jpeg image buffer
 285  * @param[in]   jpeg_size               The jpeg image buffer size
 286  * @param[in]   colorspace      The decoded image colorspace
 287  * @param[out]  image_buffer    The image buffer for decoded image
 288  * @param[out]  width   The image width
 289  * @param[out]  height  The image height
 290  * @param[out]  size            The image buffer size
 291  *
 292  * @return        0 on success, otherwise a negative error value.
 293  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 294  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @retval       #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 296  * @retval    #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 297  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 298  *
 299  * @see image_util_supported_jpeg_colorspace_cb()
 300  * @see image_util_decode_jpeg()
 301  * @see image_util_foreach_supported_jpeg_colorspace()
 302  */
 303 int image_util_decode_jpeg_from_memory( const unsigned char * jpeg_buffer , int jpeg_size , image_util_colorspace_e colorspace, unsigned char ** image_buffer , int *width , int *height , unsigned int *size);
 304
 305 /**
 306  * @brief Encodes image to the jpeg image
 307  *
 308  * @param[in]   buffer  The origin image buffer
 309  * @param[in]   width   The origin image width
 310  * @param[in]   height  The origin image height
 311  * @param[in]   colorspace      The origin image colorspace
 312  * @param[in]   quality The quality for JPEG image encoding (1 ~ 100)
 313  * @param[in]   path    The file path to be created
 314  *
 315  * @return        0 on success, otherwise a negative error value.
 316  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 317  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 318  * @retval       #IMAGE_UTIL_ERROR_NO_SUCH_FILE no such file
 319  * @retval    #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 320  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 321  *
 322  * @see image_util_supported_jpeg_colorspace_cb()
 323  * @see image_util_foreach_supported_jpeg_colorspace()
 324  * @see image_util_encode_jpeg_to_memory()
 325  */
 326 int image_util_encode_jpeg( const unsigned char *buffer, int width, int height, image_util_colorspace_e colorspace,  int quality, const char *path);
 327
 328 /**
 329  * @brief Encodes image to the jpeg image
 330  *
 331  * @remarks @a jpeg_buffer must be released with free() by you.
 332  *
 333  * @param[in]   image_buffer    The origin image buffer
 334  * @param[in]   width   The image width
 335  * @param[in]   height  The image height
 336  * @param[in]   colorspace      The origin image colorspace
 337  * @param[in]   quality The quality for JPEG image encoding (1 ~ 100)
 338  * @param[out]  jpeg_buffer     The created jpeg image buffer.  The buffer is created by frameworks
 339  * @param[out]  jpeg_size               The created jpeg image buffer size
 340  *
 341  * @return        0 on success, otherwise a negative error value.
 342  * @retval    #IMAGE_UTIL_ERROR_NONE Successful
 343  * @retval    #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 344  * @retval       #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 345  * @retval    #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 346  * @retval       #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 347  *
 348  * @see image_util_supported_jpeg_colorspace_cb()
 349  * @see image_util_foreach_supported_jpeg_colorspace()
 350  * @see image_util_encode_jpeg()
 351  */
 352 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);
 353
 354
 355
 356
 357 /**
 358  * @}
 359  */
 360
 361 #ifdef __cplusplus
 362 }
 363 #endif
 364
 365 #endif /* __TIZEN_MEDIA_IMAGE_UTIL_H__ */