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 #ifndef __TIZEN_MEDIA_IMAGE_UTIL_H__
  18 #define __TIZEN_MEDIA_IMAGE_UTIL_H__
  19
  20 #include <image_util_type.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27 /**
  28  * @file image_util.h
  29  * @brief This file contains the image util API.
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_MEDIA_IMAGE_UTIL_MODULE
  34  * @{
  35  */
  36
  37 /**
  38 * @brief Creates a handle to image util transform.
  39 * @since_tizen 2.3
  40 *
  41 * @details This function creates a handle to image util transform.
  42 *
  43 * @remarks You must release the @a image util handle using image_util_transform_destroy().
  44 *
  45 * @param[out] handle A handle to image util transform
  46 *
  47 * @return @c 0 on success,
  48 *               otherwise a negative error value
  49 *
  50 * @retval #IMAGE_UTIL_ERROR_NONE Successful
  51 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  52 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
  53 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
  54 *
  55 * @see image_util_transform_destroy()
  56 *
  57 */
  58 int image_util_transform_create(transformation_h *handle);
  59
  60 /**
  61 * @brief Sets the image util's accurate mode.
  62 * @since_tizen 2.3
  63 *
  64 * @details This function set if you use hardware accerlation or not.
  65 *
  66 * @remarks The value returned will be IMAGE_UTIL_ERROR_NOT_SUPPORTED, if H/W acceleration doesn't support on the device.
  67 *
  68 * @param[in] handle The handle to image util
  69 * @param [in] mode Set @c true, user can use the hardware acceleration\n
  70 *                               otherwise set @c false if user can only software image processing
  71 *
  72 * @return @c 0 on success,
  73 *               otherwise a negative error value
  74 *
  75 * @retval #IMAGE_UTIL_ERROR_NONE Successful
  76 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  77 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
  78 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
  79 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED The application does not have the hardware acceleration
  80 *
  81 * @pre image_util_transform_create().
  82 *
  83 * @see image_util_transform_create()
  84 * @see image_util_transform_destroy()
  85 */
  86 int image_util_transform_set_hardware_acceleration(transformation_h handle, bool mode);
  87
  88 /**
  89 * @brief Sets the information of the converting
  90 * @since_tizen 2.3
  91 *
  92 * @param[in] handle The handle to image util transform
  93 * @param[in] colorspace The colorspace of the image buffer
  94 *
  95 * @return @c 0 on success,
  96 *               otherwise a negative error value
  97 *
  98 * @retval #IMAGE_UTIL_ERROR_NONE Successful
  99 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 100 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 101 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 102 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 103 *
 104 * @pre image_util_transform_create().
 105 *
 106 * @see image_util_transform_create()
 107 * @see image_util_transform_run()
 108 * @see image_util_transform_destroy()
 109 */
 110 int image_util_transform_set_colorspace(transformation_h handle, image_util_colorspace_e colorspace);
 111
 112 /**
 113 * @brief Sets the information of the resizing
 114 * @since_tizen 2.3
 115 *
 116 * @remarks image_util_transform_set_resolution and image_util_transform_set_crop_area can't do that at the same time.
 117 *
 118 * @param[in] handle The handle to image util transform
 119 * @param[in] width The width of image buffer
 120 * @param[in] height The height of image buffer
 121 *
 122 * @return @c 0 on success,
 123 *               otherwise a negative error value
 124 *
 125 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 126 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 127 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 128 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 129 *
 130 * @pre image_util_transform_create().
 131 *
 132 * @see image_util_transform_create()
 133 * @see image_util_transform_run()
 134 * @see image_util_transform_destroy()
 135 */
 136 int image_util_transform_set_resolution(transformation_h handle, unsigned int width, unsigned int height);
 137
 138 /**
 139 * @brief Sets the information of the rotating
 140 * @since_tizen 2.3
 141 *
 142 * @param[in] handle The handle to image util transform
 143 * @param[in] rotation The rotation value of image buffer
 144 *
 145 * @return @c 0 on success,
 146 *               otherwise a negative error value
 147 *
 148 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 149 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 150 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 151 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 152 *
 153 * @pre image_util_transform_create().
 154 *
 155 * @see image_util_transform_create()
 156 * @see image_util_transform_run()
 157 * @see image_util_transform_destroy()
 158 */
 159 int image_util_transform_set_rotation(transformation_h handle, image_util_rotation_e rotation);
 160
 161 /**
 162 * @brief Sets the information of the cropping
 163 * @since_tizen 2.3
 164 *
 165 * @remarks image_util_transform_set_resolution and image_util_transform_set_crop_area can't do that at the same time.
 166 *
 167 * @param[in] handle The handle to image util transform
 168 * @param[in] start_x The start x position of cropped image buffer
 169 * @param[in] start_y The start y position of cropped image buffer
 170 * @param[in] end_x The end x position of cropped image buffer
 171 * @param[in] end_y The end y position of cropped image buffer
 172 *
 173 * @return @c 0 on success,
 174 *               otherwise a negative error value
 175 *
 176 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 177 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 178 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 179 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 180 *
 181 * @pre image_util_transform_create().
 182 *
 183 * @see image_util_transform_create()
 184 * @see image_util_transform_run()
 185 * @see image_util_transform_destroy()
 186 */
 187 int image_util_transform_set_crop_area(transformation_h handle, unsigned int start_x, unsigned int start_y, unsigned int end_x, unsigned int end_y);
 188
 189 /**
 190 * @brief Gets the colorspace of the image buffer
 191 * @since_tizen 2.3
 192 *
 193 * @param[in] handle The handle to image util transform
 194 * @param[in, out] colorspace The colorspace of the image buffer
 195 *
 196 * @return @c 0 on success,
 197 *               otherwise a negative error value
 198 *
 199 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 200 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 201 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 202 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 203 *
 204 * @pre image_util_transform_create().\n
 205 *            image_util_transform_set_crop_area().
 206 *
 207 * @see image_util_transform_create()
 208 * @see image_util_transform_destroy()
 209 */
 210 int image_util_transform_get_colorspace(transformation_h handle, image_util_colorspace_e *colorspace);
 211
 212 /**
 213 * @brief Gets the resolution of the image buffer
 214 * @since_tizen 2.3
 215 *
 216 * @param[in] handle The handle to image util transform
 217 * @param[in, out] width The width of source image buffer
 218 * @param[in, out] height The height of source image buffer
 219 *
 220 * @return @c 0 on success,
 221 *               otherwise a negative error value
 222 *
 223 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 224 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 225 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 226 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 227 *
 228 * @pre image_util_transform_create().\n
 229 *            image_util_transform_set_resolution().
 230 *
 231 * @see image_util_transform_create()
 232 * @see image_util_transform_destroy()
 233 */
 234 int image_util_transform_get_resolution(transformation_h handle, unsigned int *width, unsigned int *height);
 235
 236 /**
 237 * @brief Gets the information of the rotating
 238 * @since_tizen 2.3
 239 *
 240 * @param[in] handle The handle to image util transform
 241 * @param[in, out] rotation The rotation value of image buffer
 242 *
 243 * @return @c 0 on success,
 244 *               otherwise a negative error value
 245 *
 246 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 247 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 248 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 249 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 250 *
 251 * @pre image_util_transform_create().\n
 252 *            image_util_transform_set_rotation().
 253 *
 254 * @see image_util_transform_create()
 255 * @see image_util_transform_destroy()
 256 */
 257 int image_util_transform_get_rotation(transformation_h handle, image_util_rotation_e *rotation);
 258
 259 /**
 260 * @brief Gets the information of the cropping
 261 * @since_tizen 2.3
 262 *
 263 * @param[in] handle The handle to image util transform
 264 * @param[in, out] start_x The start x position of cropped source image buffer
 265 * @param[in, out] start_y The start y position of cropped source image buffer
 266 * @param[in, out] end_x The end x position of cropped source image buffer
 267 * @param[in, out] end_y The end y position of cropped source image buffer
 268 *
 269 * @return @c 0 on success,
 270 *               otherwise a negative error value
 271 *
 272 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 273 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 274 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 275 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 276 *
 277 * @pre image_util_transform_create().\n
 278 *            image_util_transform_set_crop_area().
 279 *
 280 * @see image_util_transform_create()
 281 * @see image_util_transform_destroy()
 282 */
 283 int image_util_transform_get_crop_area(transformation_h handle, unsigned int *start_x, unsigned int *start_y, unsigned int *end_x, unsigned int *end_y);
 284
 285 /**
 286 * @brief Transform the image for given image util handle.
 287 * @since_tizen 2.3
 288 *
 289 * @remarks If H/W acceleration is not set, transformation is done via S/W acceleration.
 290 *
 291 * @details The function execute asynchronously, which contains complete callback \n
 292 *          If you set more than two transforming, the order of running is crop or resolution, colorspace converting, rotaion. \n
 293 *
 294 * @param[in] handle The handle of transform
 295 * @param[in] src The handle to image util transform
 296 * @param[in] callback The callback function to be invoked
 297 * @param[in] user_data The user data to be passed to the callback function
 298 *
 299 * @return @c 0 on success,
 300 *               otherwise a negative error value
 301 *
 302 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 303 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 304 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 305 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 306 *
 307 * @see image_util_transform_create()
 308 * @see image_util_transform_set_hardware_acceleration
 309 * @see image_util_transform_destroy()
 310 */
 311 int image_util_transform_run(transformation_h handle, media_packet_h src, image_util_transform_completed_cb callback, void *user_data);
 312
 313 /**
 314 * @brief Destroys a handle to image util.
 315 * @since_tizen 2.3
 316 *
 317 * @details The function frees all resources related to the image util handle. The image util
 318 *               handle no longer can be used to perform any operation. A new image util handle
 319 *               has to be created before the next usage.
 320 *
 321 * @param[in] handle The handle to image util transform
 322 *
 323 * @return @c 0 on success,
 324 *               otherwise a negative error value
 325 *
 326 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 327 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 328 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 329 *
 330 * @see image_util_transform_create()
 331 *
 332 */
 333 int image_util_transform_destroy(transformation_h handle);
 334
 335 /**
 336 * @deprecated Deprecated since 3.0. Use image_util_supported_colorspace_cb() instead.
 337 * @brief Called once for each supported JPEG encode/decode colorspace.
 338 * @since_tizen 2.3
 339 *
 340 * @param[in] colorspace The colorspace
 341 * @param[in] user_data The user data passed from the foreach function
 342 *
 343 * @return @c true to continue with the next iteration of the loop, \n
 344 *         otherwise @c false to break out of the loop
 345 *
 346 * @pre image_util_foreach_supported_jpeg_colorspace() invokes this callback.
 347 *
 348 * @see image_util_foreach_supported_jpeg_colorspace()
 349 * @see image_util_encode_jpeg()
 350 * @see image_util_encode_jpeg_to_memory()
 351 * @see image_util_decode_jpeg()
 352 * @see image_util_decode_jpeg_from_memory()
 353 */
 354 typedef bool(*image_util_supported_jpeg_colorspace_cb)(image_util_colorspace_e colorspace, void *user_data);
 355
 356 /**
 357 * @deprecated Deprecated since 3.0. Use image_util_foreach_supported_colorspace() instead.
 358 * @brief Retrieves all supported JPEG encoding/decoding colorspace by invoking a callback function once for each one.
 359 * @since_tizen 2.3
 360 *
 361 * @param[in] callback The callback function to invoke
 362 * @param[in] user_data The user data to be passed to the callback function
 363 * @return 0 on success,
 364 *         otherwise a negative error value
 365 *
 366 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 367 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 368 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 369 * @post This function invokes image_util_supported_jpeg_colorspace_cb() repeatedly to retrieve each supported JPEG encoding/decoding colorspace.
 370 *
 371 * @see image_util_supported_jpeg_colorspace_cb()
 372 * @see image_util_encode_jpeg()
 373 * @see image_util_encode_jpeg_to_memory()
 374 * @see image_util_decode_jpeg()
 375 * @see image_util_decode_jpeg_from_memory()
 376 */
 377 int image_util_foreach_supported_jpeg_colorspace(image_util_supported_jpeg_colorspace_cb callback, void *user_data);
 378
 379 /**
 380 * @brief Calculates the size of the image buffer for the specified resolution and colorspace.
 381 * @since_tizen 2.3
 382 *
 383 * @param[in] width The image width
 384 * @param[in] height The image height
 385 * @param[in] colorspace The image colorspace
 386 * @param[out] size The Calculated buffer size
 387 *
 388 * @return @c 0 on success,
 389 *               otherwise a negative error value
 390 *
 391 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 392 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 393 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 394 *
 395 * @see image_util_transform_run()
 396 * @see image_util_decode_jpeg()
 397 * @see image_util_decode_jpeg_from_memory()
 398 * @see image_util_encode_jpeg()
 399 * @see image_util_encode_jpeg_to_memory()
 400 */
 401 int image_util_calculate_buffer_size(int width, int height, image_util_colorspace_e colorspace , unsigned int *size);
 402
 403 /**
 404 * @internal
 405 * @brief Converts the image's colorspace.
 406 * @since_tizen 2.3
 407 *
 408 * @remarks You must get the @a dest buffer size using image_util_transform_calculate_buffer_size().
 409 *
 410 * @param[in, out] dest The image buffer for result \n
 411 *                     Must be allocated by the user
 412 * @param[in] dest_colorspace The colorspace to be converted
 413 * @param[in] src The source image buffer
 414 * @param[in] width The width of the source image
 415 * @param[in] height The height of the source image
 416 * @param[in] src_colorspace The colorspace of the source image buffer
 417 *
 418 * @return %c 0 on success
 419 *            otherwise a negative error value
 420 *
 421 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 422 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 423 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 424 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 425 *
 426 * @see image_util_transform_calculate_buffer_size()
 427 * @see image_util_transform_create()
 428 * @see image_util_transform_destroy()
 429 */
 430 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);
 431
 432 /**
 433 * @internal
 434 * @brief Resizes the image to the specified destination width and height.
 435 * @since_tizen 2.3
 436 *
 437 * @remarks Because of YUV format padding, the destination image size can be adjusted.
 438 *
 439 * @param[in, out] dest The image buffer for result \n
 440 *                     Must be allocated by the user.
 441 * @param[in, out] dest_width The image width to resize, and resized width
 442 * @param[in, out] dest_height The image height to resize, and resized height
 443 * @param[in] src The image buffer for the original image
 444 * @param[in] src_width The original image width
 445 * @param[in] src_height The original image height
 446 * @param[in] colorspace The image colorspace
 447 *
 448 *
 449 * @return @c 0 on success,
 450 *               otherwise a negative error value
 451 *
 452 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 453 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 454 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 455 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 456 *
 457 * @see image_util_transform_calculate_buffer_size()
 458 */
 459 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);
 460
 461 /**
 462 * @internal
 463 * @brief Rotates the image to the specified angle given in degrees.
 464 * @since_tizen 2.3
 465 *
 466 * @remarks Because of YUV format padding, the destination image size can be adjusted.
 467 * Rotations are supported only in these color spaces\n
 468 * #IMAGE_UTIL_COLORSPACE_YV12\n
 469 * #IMAGE_UTIL_COLORSPACE_I420\n
 470 * #IMAGE_UTIL_COLORSPACE_NV12\n
 471 * #IMAGE_UTIL_COLORSPACE_RGB888\n
 472 * #IMAGE_UTIL_COLORSPACE_RGB565\n
 473 * #IMAGE_UTIL_COLORSPACE_ARGB8888\n
 474 * #IMAGE_UTIL_COLORSPACE_BGRA8888\n
 475 * #IMAGE_UTIL_COLORSPACE_RGBA8888\n
 476 * #IMAGE_UTIL_COLORSPACE_BGRX8888\n.
 477 *
 478 * @param[in, out] dest The image buffer for result \n
 479 *                     Must be allocated by the user.
 480 * @param[out] dest_width The rotated image width
 481 * @param[out] dest_height The rotated image height
 482 * @param[in] dest_rotation The angle to rotate
 483 * @param[in] src The image buffer for the original image
 484 * @param[in] src_width The original image width
 485 * @param[in] src_height The original image height
 486 * @param[in] colorspace The image colorspace
 487 *
 488 * @return @c 0 on success,
 489 *               otherwise a negative error value
 490 *
 491 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 492 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 493 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 494 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 495 *
 496 * @see image_util_transform_calculate_buffer_size()
 497 */
 498 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);
 499
 500 /**
 501 * @internal
 502 * @brief Crops the image to the specified point and dimension.
 503 * @since_tizen 2.3
 504 *
 505 * @remarks Because of YUV format padding, the destination image size can be adjusted.
 506 * Crop is supported only in these colorspaces\n
 507 * #IMAGE_UTIL_COLORSPACE_YV12 \n
 508 * #IMAGE_UTIL_COLORSPACE_I420 \n
 509 * #IMAGE_UTIL_COLORSPACE_RGB888 \n
 510 * #IMAGE_UTIL_COLORSPACE_RGB565 \n
 511 * #IMAGE_UTIL_COLORSPACE_ARGB8888\n
 512 * #IMAGE_UTIL_COLORSPACE_BGRA8888\n
 513 * #IMAGE_UTIL_COLORSPACE_RGBA8888\n
 514 * #IMAGE_UTIL_COLORSPACE_BGRX8888\n.
 515 *
 516 * @param[in, out] dest The image buffer for result. Must be allocated by you
 517 * @param[in] x The starting x-axis of crop
 518 * @param[in] y The starting y-axis of crop
 519 * @param[in/out] width  The image width to crop, and cropped width
 520 * @param[in/out] height  The image height to crop, and cropped height
 521 * @param[in] src The image buffer for original image
 522 * @param[in] src_width The original image width
 523 * @param[in] src_height The original image height
 524 * @param[in] colorspace The image colorspace
 525 *
 526 * @return @c 0 on success,
 527 *               otherwise a negative error value
 528 *
 529 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 530 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 531 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 532 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 533 *
 534 * @see image_util_transform_calculate_buffer_size()
 535 */
 536 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);
 537
 538
 539
 540
 541 /**
 542 * @deprecated Deprecated since 3.0. Use image_util_decode_create() instead.
 543 * @brief Decodes the JPEG image to the buffer.
 544 * @since_tizen 2.3
 545 *
 546 * @remarks You must release @a image_buffer using free().\n
 547 *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 548 *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
 549 *                 If you decode the JPEG image which has odd numbered width or height to YUV colorspace, \n
 550 *                 the width or height of decoded data will be rounded down to even numbered width or height.
 551 *
 552 * @param[in] path The image file path
 553 * @param[in] colorspace The decoded image colorspace
 554 * @param[out] image_buffer The image buffer for the decoded image
 555 * @param[out] width The image width
 556 * @param[out] height The image height
 557 * @param[out] size The image buffer size
 558 *
 559 * @return @c 0 on success,
 560 *               otherwise a negative error value
 561 *
 562 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 563 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 564 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 565 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 566 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 567 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 568 *
 569 * @see image_util_supported_jpeg_colorspace_cb()
 570 * @see image_util_decode_jpeg_from_memory()
 571 * @see image_util_foreach_supported_jpeg_colorspace()
 572 */
 573 int image_util_decode_jpeg(const char *path, image_util_colorspace_e colorspace, unsigned char **image_buffer, int *width, int *height, unsigned int *size);
 574
 575 /**
 576 * @deprecated Deprecated since 3.0. Use image_util_decode_create() instead.
 577 * @brief Decodes the JPEG image(in memory) to the buffer.
 578 * @since_tizen 2.3
 579 *
 580 * @remarks You must release @a image_buffer using free().\n
 581 *                  If you decode the JPEG image which has odd numbered width or height to YUV colorspace, \n
 582 *                  the width or height of decoded data will be rounded down to even numbered width or height.
 583 *
 584 * @param[in] jpeg_buffer The JPEG image buffer
 585 * @param[in] jpeg_size The JPEG image buffer size
 586 * @param[in] colorspace The decoded image colorspace
 587 * @param[out] image_buffer The image buffer for the decoded image
 588 * @param[out] width The image width
 589 * @param[out] height The image height
 590 * @param[out] size The image buffer size
 591 *
 592 * @return 0 on success,
 593 *           otherwise a negative error value
 594 *
 595 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 596 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 597 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 598 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 599 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 600 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 601 *
 602 * @see image_util_supported_jpeg_colorspace_cb()
 603 * @see image_util_decode_jpeg()
 604 * @see image_util_foreach_supported_jpeg_colorspace()
 605 */
 606 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);
 607
 608 /**
 609 * @deprecated Deprecated since 3.0. Use image_util_decode_create() instead.
 610 * @brief Decodes the JPEG image to the buffer with downscale decoding option.
 611 * @since_tizen 2.4
 612 *
 613 * @remarks You must release @a image_buffer using free().\n
 614 *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 615 *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
 616 *                 If you decode the JPEG image which has odd numbered width or height to YUV colorspace, \n
 617 *                 the width or height of decoded data will be rounded down to even numbered width or height.
 618 *
 619 * @param[in] path The image file path
 620 * @param[in] colorspace The decoded image colorspace
 621 * @param[in] downscale The downscale value
 622 * @param[out] image_buffer The image buffer for the decoded image
 623 * @param[out] width The image width
 624 * @param[out] height The image height
 625 * @param[out] size The image buffer size
 626 *
 627 * @return @c 0 on success,
 628 *               otherwise a negative error value
 629 *
 630 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 631 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 632 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 633 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 634 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 635 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 636 *
 637 * @see image_util_supported_jpeg_colorspace_cb()
 638 * @see image_util_decode_jpeg_from_memory()
 639 * @see image_util_foreach_supported_jpeg_colorspace()
 640 */
 641 int image_util_decode_jpeg_with_downscale(const char *path, image_util_colorspace_e colorspace, image_util_scale_e downscale, unsigned char **image_buffer, int *width, int *height, unsigned int *size);
 642
 643 /**
 644 * @deprecated Deprecated since 3.0. Use image_util_decode_create() instead.
 645 * @brief Decodes the JPEG image(in memory) to the buffer with downscale decoding option.
 646 * @since_tizen 2.4
 647 *
 648 * @remarks You must release @a image_buffer using free().\n
 649 *                   If you decode the JPEG image which has odd numbered width or height to YUV colorspace, \n
 650 *                   the width or height of decoded data will be rounded down to even numbered width or height.
 651 *
 652 * @param[in] jpeg_buffer The JPEG image buffer
 653 * @param[in] jpeg_size The JPEG image buffer size
 654 * @param[in] colorspace The decoded image colorspace
 655 * @param[in] downscale The downscale value
 656 * @param[out] image_buffer The image buffer for the decoded image
 657 * @param[out] width The image width
 658 * @param[out] height The image height
 659 * @param[out] size The image buffer size
 660 *
 661 * @return @c 0 on success,
 662 *           otherwise a negative error value
 663 *
 664 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 665 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 666 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 667 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 668 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 669 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 670 *
 671 * @see image_util_supported_jpeg_colorspace_cb()
 672 * @see image_util_decode_jpeg()
 673 * @see image_util_foreach_supported_jpeg_colorspace()
 674 */
 675 int image_util_decode_jpeg_from_memory_with_downscale(const unsigned char *jpeg_buffer, int jpeg_size, image_util_colorspace_e colorspace, image_util_scale_e downscale, unsigned char **image_buffer, int *width, int *height, unsigned int *size);
 676
 677 /**
 678 * @deprecated Deprecated since 3.0. Use image_util_encode_create() instead.
 679 * @brief Encodes the image to the JPEG image.
 680 * @since_tizen 2.3
 681 *
 682 * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 683 *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 684 *
 685 * @param[in] buffer The original image buffer
 686 * @param[in] width The original image width
 687 * @param[in] height The original image height
 688 * @param[in] colorspace The original image colorspace
 689 * @param[in] quality The quality for JPEG image encoding(1 ~ 100)
 690 * @param[in] path The file path to be created
 691 *
 692 * @return 0 on success,
 693 *           otherwise a negative error value
 694 *
 695 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 696 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 697 * @retval #IMAGE_UTIL_ERROR_NO_SUCH_FILE No such file
 698 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 699 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 700 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 701 *
 702 * @see image_util_supported_jpeg_colorspace_cb()
 703 * @see image_util_foreach_supported_jpeg_colorspace()
 704 * @see image_util_encode_jpeg_to_memory()
 705 */
 706 int image_util_encode_jpeg(const unsigned char *buffer, int width, int height, image_util_colorspace_e colorspace,  int quality, const char *path);
 707
 708 /**
 709 * @deprecated Deprecated since 3.0. Use image_util_encode_create() instead.
 710 * @brief Encodes the image to the JPEG image
 711 * @since_tizen 2.3
 712 *
 713 * @remarks You must release @a jpeg_buffer using free().
 714 *
 715 * @param[in] image_buffer The original image buffer
 716 * @param[in] width The image width
 717 * @param[in] height The image height
 718 * @param[in] colorspace The original image colorspace
 719 * @param[in] quality The quality for JPEG image encoding(1 ~ 100)
 720 * @param[out] jpeg_buffer The created JPEG image buffer \n
 721 *                         The buffer is created by frameworks
 722 * @param[out] jpeg_size The created jpeg image buffer size
 723 *
 724 * @return 0 on success,
 725 *           otherwise a negative error value
 726 *
 727 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 728 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 729 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 730 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 731 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 732 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 733 *
 734 * @see image_util_supported_jpeg_colorspace_cb()
 735 * @see image_util_foreach_supported_jpeg_colorspace()
 736 * @see image_util_encode_jpeg()
 737 */
 738 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);
 739
 740 /**
 741 * @brief Extracts representative color from an image buffer
 742 * @since_tizen 3.0
 743 * @remarks @a image_buffer should be RGB888 colorspace.
 744 *
 745 * @param[in] image_buffer The original image buffer
 746 * @param[in] width The image width
 747 * @param[in] height The image height
 748 * @param[out] rgb_r The red color in RGB color space
 749 * @param[out] rgb_g The green color in RGB color space
 750 * @param[out] rgb_b The blue color in RGB color space
 751 *
 752 * @return 0 on success,
 753 *           otherwise a negative error value
 754 *
 755 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 756 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 757 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY out of memory
 758 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 759 *
 760 */
 761 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);
 762
 763 /**
 764 * @brief Called once for each supported image encode/decode colorspace.
 765 * @since_tizen 3.0
 766 *
 767 * @param[in] colorspace The colorspace
 768 * @param[in] user_data The user data passed from the foreach function
 769 *
 770 * @return @c true to continue with the next iteration of the loop, \n
 771 *         otherwise @c false to break out of the loop
 772 *
 773 * @pre image_util_foreach_supported_colorspace() invokes this callback.
 774 *
 775 * @see image_util_foreach_supported_colorspace()
 776 * @see image_util_encode_create()
 777 * @see image_util_decode_create()
 778 */
 779 typedef bool(*image_util_supported_colorspace_cb)(image_util_colorspace_e colorspace, void *user_data);
 780
 781 /**
 782 * @brief Retrieves all supported image encoding/decoding colorspace by invoking a callback function once for each one.
 783 * @since_tizen 3.0
 784 *
 785 * @param[in] callback The callback function to invoke
 786 * @param[in] user_data The user data to be passed to the callback function
 787 * @return 0 on success,
 788 *         otherwise a negative error value
 789 *
 790 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 791 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 792 *
 793 * @post This function invokes image_util_supported_colorspace_cb() repeatedly to retrieve each supported image encoding/decoding colorspace.
 794 *
 795 * @see image_util_supported_colorspace_cb()
 796 * @see image_util_encode_create()
 797 * @see image_util_decode_create()
 798 */
 799 int image_util_foreach_supported_colorspace(image_util_type_e image_type, image_util_supported_colorspace_cb callback, void *user_data);
 800
 801 /**
 802 * @brief Creates a handle to image util decoding.
 803 * @since_tizen 3.0
 804 *
 805 * @details This function creates a handle to image util decoding.
 806 *
 807 * @remarks You must release the @a image util handle using image_util_decode_destroy().
 808 *
 809 * @param[out] handle A handle to image util decoding
 810 *
 811 * @return @c 0 on success,
 812 *               otherwise a negative error value
 813 *
 814 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 815 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 816 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 817 *
 818 * @see image_util_decode_destroy()
 819 *
 820 */
 821 int image_util_decode_create(image_util_decode_h *handle);
 822
 823 /**
 824 * @brief Sets the input file path from which to decode.
 825 * @since_tizen 3.0
 826 *
 827 * @remarks One of image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.\n
 828 *          If both are set then the latest input set, is considered.\n
 829 *          http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 830 *          http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
 831 *          Finds out image type by reading the header of the image provided in input path.
 832 *
 833 * @param[in] handle The handle to image util decoding
 834 * @param[in] path The path to input image
 835 *
 836 * @return @c 0 on success,
 837 *               otherwise a negative error value
 838 *
 839 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 840 * @retval #IMAGE_UTIL_ERROR_NO_SUCH_FILE No such file
 841 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 842 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 843 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
 844 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 845 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 846 *
 847 * @pre image_util_decode_create()
 848 *
 849 * @post image_util_decode_run()/image_util_decode_run_async()
 850 * @post image_util_decode_destroy()
 851 *
 852 * @see image_util_decode_create()
 853 * @see image_util_decode_set_output_buffer()
 854 * @see image_util_decode_run()
 855 * @see image_util_decode_run_async()
 856 * @see image_util_decode_destroy()
 857 */
 858 int image_util_decode_set_input_path(image_util_decode_h handle, const char *path);
 859
 860 /**
 861 * @brief Sets the input buffer from which to decode.
 862 * @since_tizen 3.0
 863 *
 864 * @remarks One of image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.\n
 865 *          If both are set then the latest input set, is considered.\n
 866 *          Finds out image type by reading the header of the image provided in input buffer.
 867 *
 868 * @param[in] handle The handle to image util decoding
 869 * @param[in] src_buffer The input image buffer
 870 * @param[in] src_size The input image buffer size
 871 *
 872 * @return @c 0 on success,
 873 *               otherwise a negative error value
 874 *
 875 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 876 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 877 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 878 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 879 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 880 *
 881 * @pre image_util_decode_create()
 882 *
 883 * @post image_util_decode_run()/image_util_decode_run_async()
 884 * @post image_util_decode_destroy()
 885 *
 886 * @see image_util_decode_create()
 887 * @see image_util_decode_set_output_buffer()
 888 * @see image_util_decode_run()
 889 * @see image_util_decode_run_async()
 890 * @see image_util_decode_destroy()
 891 */
 892 int image_util_decode_set_input_buffer(image_util_decode_h handle, const unsigned char *src_buffer, unsigned long long src_size);
 893
 894 /**
 895 * @brief Sets the output buffer to which the decoded buffer will be written to.
 896 * @since_tizen 3.0
 897 *
 898 * @remarks Either image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.\n
 899 *          By default the decoded output buffer colorspace will be IMAGE_UTIL_COLORSPACE_RGBA8888.
 900 *          Use image_util_decode_set_colorspace to change the colorspace.
 901 *
 902 * @param[in] handle The handle to image util decoding
 903 * @param[in] dst_buffer The decoded output buffer
 904 *
 905 * @return @c 0 on success,
 906 *               otherwise a negative error value
 907 *
 908 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 909 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 910 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 911 *
 912 * @pre image_util_decode_create()
 913 *
 914 * @post image_util_decode_run()/image_util_decode_run_async()
 915 * @post image_util_decode_destroy()
 916 *
 917 * @see image_util_decode_create()
 918 * @see image_util_decode_set_input_path()
 919 * @see image_util_decode_set_input_buffer()
 920 * @see image_util_decode_run()
 921 * @see image_util_decode_run_async()
 922 * @see image_util_decode_destroy()
 923 */
 924 int image_util_decode_set_output_buffer(image_util_decode_h handle, unsigned char **dst_buffer);
 925
 926 /**
 927 * @brief Sets the decoded image colorspace format.
 928 * @since_tizen 3.0
 929 *
 930 * @remarks The default colorspace is IMAGE_UTIL_COLORSPACE_RGBA8888.\n
 931 *          Use image_util_foreach_supported_colorspace to get supported colorspaces for each image format.\n
 932 *          Errors would be returned if not supported.
 933 *
 934 * @param[in] handle The handle to image util decoding
 935 * @param[in] colorspace The decoded image colorspace
 936 *
 937 * @return @c 0 on success,
 938 *               otherwise a negative error value
 939 *
 940 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 941 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 942 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 943 *
 944 * @pre image_util_decode_create()
 945 *
 946 * @post image_util_decode_run()/image_util_decode_run_async()
 947 * @post image_util_decode_destroy()
 948 *
 949 * @see image_util_supported_colorspace_cb()
 950 * @see image_util_foreach_supported_colorspace()
 951 * @see image_util_decode_create()
 952 * @see image_util_decode_set_input_path()
 953 * @see image_util_decode_set_input_buffer()
 954 * @see image_util_decode_set_output_buffer()
 955 * @see image_util_decode_run()
 956 * @see image_util_decode_run_async()
 957 * @see image_util_decode_destroy()
 958 */
 959 int image_util_decode_set_colorspace(image_util_encode_h handle, image_util_colorspace_e colorspace);
 960
 961 /**
 962 * @brief Sets the downscale value at which JPEG image should be decoded.
 963 * @since_tizen 3.0
 964 *
 965 * @remarks This is API is supported only for JPEG decoding.
 966 *
 967 * @param[in] handle The handle to image util decoding
 968 * @param[in] down_scale The downscale at which image is to be decoded
 969 *
 970 * @return @c 0 on success,
 971 *               otherwise a negative error value
 972 *
 973 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 974 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 975 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 976 *
 977 * @pre image_util_decode_create()
 978 *
 979 * @post image_util_decode_run()/image_util_decode_run_async()
 980 * @post image_util_decode_destroy()
 981 *
 982 * @see image_util_decode_create()
 983 * @see image_util_decode_set_input_path()
 984 * @see image_util_decode_set_input_buffer()
 985 * @see image_util_decode_set_output_buffer()
 986 * @see image_util_decode_run()
 987 * @see image_util_decode_run_async()
 988 * @see image_util_decode_destroy()
 989 */
 990 int image_util_decode_set_jpeg_downscale(image_util_encode_h handle, image_util_scale_e down_scale);
 991
 992 /**
 993 * @brief Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().
 994 * @since_tizen 3.0
 995 *
 996 * @remarks The output will be stored in the pointer set using image_util_decode_set_output_buffer().\n
 997 *               The function executes synchronously.\n
 998 *               When any of the @pre functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
 999 *
1000 * @param[in] handle The handle to image util decoding
1001 * @param[out] width Width of the decoded image
1002 * @param[out] height Height of the decoded image
1003 * @param[out] size Size of the decoded image
1004 *
1005 * @return @c 0 on success,
1006 *               otherwise a negative error value
1007 *
1008 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1009 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1010 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1011 *
1012 * @pre image_util_decode_create()
1013 * @pre image_util_decode_set_input_buffer()/image_util_decode_set_input_path().
1014 * @pre image_util_decode_set_output_buffer()
1015 *
1016 * @post image_util_decode_destroy()
1017 *
1018 * @see image_util_decode_create()
1019 * @see image_util_decode_set_input_path()
1020 * @see image_util_decode_set_input_buffer()
1021 * @see image_util_decode_set_output_buffer()
1022 * @see image_util_decode_destroy()
1023 */
1024 int image_util_decode_run(image_util_decode_h handle, unsigned long *width, unsigned long *height, unsigned long long *size);
1025
1026 /**
1027 * @brief Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().
1028 * @since_tizen 3.0
1029 *
1030 * @remarks The output will be stored in the pointer set using image_util_decode_set_output_buffer().\n
1031 *               The function executes asynchronously, which contains complete callback.\n
1032 *               When any of the @pre functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
1033 *
1034 * @param[in] handle The handle to image util decoding
1035 * @param[in] callback The callback function to be invoked
1036 * @param[in] user_data The user data to be passed to the callback function
1037 *
1038 * @return @c 0 on success,
1039 *               otherwise a negative error value
1040 *
1041 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1042 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1043 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1044 *
1045 * @pre image_util_decode_create()
1046 * @pre image_util_decode_set_input_buffer()/image_util_decode_set_input_path().
1047 * @pre image_util_decode_set_output_buffer()
1048 *
1049 * @post image_util_decode_destroy()
1050 *
1051 * @see image_util_decode_create()
1052 * @see image_util_decode_set_input_path()
1053 * @see image_util_decode_set_input_buffer()
1054 * @see image_util_decode_set_output_buffer()
1055 * @see image_util_decode_destroy()
1056 */
1057 int image_util_decode_run_async(image_util_decode_h handle, image_util_decode_completed_cb callback, void *user_data);
1058
1059 /**
1060 * @brief Destroys the image decoding handle.
1061 * @since_tizen 3.0
1062 *
1063 * @remarks Any image handle created should be destroyed.
1064 *
1065 * @param[in] handle The handle to image util decoding
1066 *
1067 * @return @c 0 on success,
1068 *               otherwise a negative error value
1069 *
1070 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1071 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1072 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1073 *
1074 * @pre image_util_decode_create()
1075 *
1076 * @see image_util_decode_create()
1077 */
1078 int image_util_decode_destroy(image_util_decode_h handle);
1079
1080 /**
1081 * @brief Creates a handle to image util encoding.
1082 * @since_tizen 3.0
1083 *
1084 * @details This function creates a handle to image util encoding.
1085 *
1086 * @remarks You must release the @a image util handle using image_util_encode_destroy().
1087 *
1088 * @param[in] image_type The type of output image for which to create encode handle.
1089 * @param[out] handle A handle to image util encoding
1090 *
1091 * @return @c 0 on success,
1092 *               otherwise a negative error value
1093 *
1094 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1095 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1096 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
1097 *
1098 * @see image_util_encode_destroy()
1099 *
1100 */
1101 int image_util_encode_create(image_util_type_e image_type, image_util_encode_h *handle);
1102
1103 /**
1104 * @brief Sets the resolution of the encoded image.
1105 * @since_tizen 3.0
1106 *
1107 * @remarks This should be called before calling image_util_encode_run().
1108 *
1109 * @param[in] handle The handle to image util encoding
1110 * @param[in] width Width of the original image
1111 * @param[in] height Height of the original image
1112 *
1113 * @return @c 0 on success,
1114 *               otherwise a negative error value
1115 *
1116 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1117 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1118 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1119 *
1120 * @pre image_util_encode_create()
1121 *
1122 * @post image_util_encode_run()/image_util_encode_run_async()
1123 * @post image_util_encode_destroy()
1124 *
1125 * @see image_util_encode_create()
1126 * @see image_util_encode_set_input_buffer()
1127 * @see image_util_encode_set_output_path()
1128 * @see image_util_encode_set_output_buffer()
1129 * @see image_util_encode_run()
1130 * @see image_util_encode_run_async()
1131 * @see image_util_encode_destroy()
1132 */
1133 int image_util_encode_set_resolution(image_util_encode_h handle, unsigned long width, unsigned long height);
1134
1135 /**
1136 * @brief Sets the colorspace format for image encoding.
1137 * @since_tizen 3.0
1138 *
1139 * @remarks The default colorspace is IMAGE_UTIL_COLORSPACE_RGBA8888.\n
1140 *          Use image_util_foreach_supported_colorspace to get supported colorspaces for each image format.\n
1141 *          Errors would be returned if not supported.
1142 *
1143 * @param[in] handle The handle to image util encoding
1144 * @param[in] colorspace The encoded image colorspace
1145 *
1146 * @return @c 0 on success,
1147 *               otherwise a negative error value
1148 *
1149 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1150 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
1151 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1152 *
1153 * @pre image_util_encode_create()
1154 *
1155 * @post image_util_encode_run()/image_util_encode_run_async()
1156 * @post image_util_encode_destroy()
1157 *
1158 * @see image_util_supported_colorspace_cb()
1159 * @see image_util_foreach_supported_colorspace()
1160 * @see image_util_encode_create()
1161 * @see image_util_encode_set_resolution()
1162 * @see image_util_encode_set_input_buffer()
1163 * @see image_util_encode_set_output_path()
1164 * @see image_util_encode_set_output_buffer()
1165 * @see image_util_encode_run()
1166 * @see image_util_encode_run_async()
1167 * @see image_util_encode_destroy()
1168 */
1169 int image_util_encode_set_colorspace(image_util_encode_h handle, image_util_colorspace_e colorspace);
1170
1171 /**
1172 * @brief Sets the quality for JPEG image encoding.
1173 * @since_tizen 3.0
1174 *
1175 * @remarks If application does not set this, then by default quality of 20 is set.
1176 *
1177 * @param[in] handle The handle to image util encoding
1178 * @param[in] quality Encoding quality from 1~100
1179 *
1180 * @return @c 0 on success,
1181 *               otherwise a negative error value
1182 *
1183 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1184 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
1185 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1186 *
1187 * @pre image_util_encode_create()
1188 *
1189 * @post image_util_encode_run()/image_util_encode_run_async()
1190 * @post image_util_encode_destroy()
1191 *
1192 * @see image_util_encode_create()
1193 * @see image_util_encode_set_resolution()
1194 * @see image_util_encode_set_input_buffer()
1195 * @see image_util_encode_set_output_path()
1196 * @see image_util_encode_set_output_buffer()
1197 * @see image_util_encode_run()
1198 * @see image_util_encode_run_async()
1199 * @see image_util_encode_destroy()
1200 */
1201 int image_util_encode_set_jpeg_quality(image_util_encode_h handle, int quality);
1202
1203 /**
1204 * @brief Sets the compression value of png image encoding(0~9).
1205 * @since_tizen 3.0
1206 *
1207 * @remarks If application does not set this, then default compression of 6 is set.
1208 *
1209 * @param[in] handle The handle to image util encoding
1210 * @param[in] compression The compression value valid from 0~9
1211 *
1212 * @return @c 0 on success,
1213 *               otherwise a negative error value
1214 *
1215 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1216 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
1217 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1218 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1219 *
1220 * @pre image_util_encode_create()
1221 *
1222 * @post image_util_encode_run()/image_util_encode_run_async()
1223 * @post image_util_encode_destroy()
1224 *
1225 * @see image_util_encode_create()
1226 * @see image_util_encode_set_resolution()
1227 * @see image_util_encode_set_input_buffer()
1228 * @see image_util_encode_set_output_path()
1229 * @see image_util_encode_set_output_buffer()
1230 * @see image_util_encode_run()
1231 * @see image_util_encode_run_async()
1232 * @see image_util_encode_destroy()
1233 */
1234 int image_util_encode_set_png_compression(image_util_encode_h handle, image_util_png_compression_e compression);
1235
1236 /**
1237 * @brief Sets the input buffer from which to encode.
1238 * @since_tizen 3.0
1239 *
1240 * @remarks Either image_util_encode_set_output_path() or image_util_encode_set_output_buffer() should be set.\n
1241 *          By default the input buffer colorspace will be considered as IMAGE_UTIL_COLORSPACE_RGBA8888.\n
1242 *          Use image_util_encode_set_colorspace to change the colorspace.
1243 *
1244 * @param[in] handle The handle to image util decoding
1245 * @param[in] src_buffer The input image buffer
1246 *
1247 * @return @c 0 on success,
1248 *               otherwise a negative error value
1249 *
1250 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1251 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1252 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1253 *
1254 * @pre image_util_encode_create()
1255 *
1256 * @post image_util_encode_run()/image_util_encode_run_async()
1257 * @post image_util_encode_destroy()
1258 *
1259 * @see image_util_encode_create()
1260 * @see image_util_encode_set_resolution()
1261 * @see image_util_encode_set_input_buffer()
1262 * @see image_util_encode_set_output_path()
1263 * @see image_util_encode_set_output_buffer()
1264 * @see image_util_encode_run()
1265 * @see image_util_encode_run_async()
1266 * @see image_util_encode_destroy()
1267 */
1268 int image_util_encode_set_input_buffer(image_util_encode_h handle, const unsigned char *src_buffer);
1269
1270 /**
1271 * @brief Sets the output path to which to encoded buffer will be written to.
1272 * @since_tizen 3.0
1273 *
1274 * @remarks One of image_util_encode_set_output_path() or image_util_encode_set_output_buffer() should be set.\n
1275 *          If both are set then the latest output set is considered.\n
1276 *          http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
1277 *          http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
1278 *
1279 * @param[in] handle The handle to image util encoding
1280 * @param[in] path The output file path
1281 *
1282 * @return @c 0 on success,
1283 *               otherwise a negative error value
1284 *
1285 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1286 * @retval #IMAGE_UTIL_ERROR_NO_SUCH_FILE No such file
1287 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1288 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1289 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this funtion
1290 *
1291 * @pre image_util_encode_create()
1292 *
1293 * @post image_util_encode_run()/image_util_encode_run_async()
1294 * @post image_util_encode_destroy()
1295 *
1296 * @see image_util_encode_create()
1297 * @see image_util_encode_set_resolution()
1298 * @see image_util_encode_set_input_buffer()
1299 * @see image_util_encode_run()
1300 * @see image_util_encode_run_async()
1301 * @see image_util_encode_destroy()
1302 */
1303 int image_util_encode_set_output_path(image_util_encode_h handle, const char *path);
1304
1305 /**
1306 * @brief Sets the output buffer to which to encoded buffer will be written to.
1307 * @since_tizen 3.0
1308 *
1309 * @remarks One of image_util_encode_set_output_path() or image_util_encode_set_output_buffer() should be set.\n
1310 *          If both are set then the latest output set is considered.\n
1311 *          Output buffer setting is not supported for bmp. IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT will be returned for bmp.
1312 *
1313 * @param[in] handle The handle to image util encoding
1314 * @param[in] dst_buffer The output image buffer
1315 *
1316 * @return @c 0 on success,
1317 *               otherwise a negative error value
1318 *
1319 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1320 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1321 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1322 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Invalid operation
1323 *
1324 * @pre image_util_encode_create()
1325 *
1326 * @post image_util_encode_run()/image_util_encode_run_async()
1327 * @post image_util_encode_destroy()
1328 *
1329 * @see image_util_encode_create()
1330 * @see image_util_encode_set_resolution()
1331 * @see image_util_encode_set_input_buffer()
1332 * @see image_util_encode_run()
1333 * @see image_util_encode_run_async()
1334 * @see image_util_encode_destroy()
1335 */
1336 int image_util_encode_set_output_buffer(image_util_encode_h handle, unsigned char **dst_buffer);
1337
1338 /**
1339 * @brief 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().
1340 * @since_tizen 3.0
1341 *
1342 * @remarks The output will be stored in the pointer set to image_util_encode_set_output_buffer() or image_util_encode_set_output_path().\n
1343 *               The function executes synchronously.\n
1344 *               When any of the @pre functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
1345 *
1346 * @param[in] handle The handle to image util encoding
1347 * @param[out] size Size of the encoded image
1348 *
1349 * @return @c 0 on success,
1350 *               otherwise a negative error value
1351 *
1352 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1353 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1354 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1355 *
1356 * @pre image_util_encode_create()
1357 * @pre image_util_encode_set_resolution()
1358 * @pre image_util_encode_set_input_buffer()
1359 * @pre image_util_encode_set_output_buffer()/image_util_encode_set_output_path()
1360 *
1361 * @post image_util_encode_destroy()
1362 *
1363 * @see image_util_encode_create()
1364 * @see image_util_encode_set_resolution()
1365 * @see image_util_encode_set_input_buffer()
1366 * @see image_util_encode_set_output_path()
1367 * @see image_util_encode_set_output_buffer()
1368 * @see image_util_encode_destroy()
1369 */
1370 int image_util_encode_run(image_util_encode_h handle, unsigned long long *size);
1371
1372 /**
1373 * @brief 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().
1374 * @since_tizen 3.0
1375 *
1376 * @remarks The output will be stored in the pointer set to image_util_encode_set_output_buffer() or image_util_encode_set_output_path().\n
1377 *               The function executes asynchronously, which contains complete callback.\n
1378 *               When any of the @pre functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
1379 *
1380 * @param[in] handle The handle to image util encoding
1381 * @param[in] callback The callback function to be invoked
1382 * @param[in] user_data The user data to be passed to the callback function
1383 *
1384 * @return @c 0 on success,
1385 *               otherwise a negative error value
1386 *
1387 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1388 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1389 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1390 *
1391 * @pre image_util_encode_create()
1392 * @pre image_util_encode_set_resolution()
1393 * @pre image_util_encode_set_input_buffer()
1394 * @pre image_util_encode_set_output_buffer()/image_util_encode_set_output_path()
1395 *
1396 * @post image_util_encode_destroy()
1397 *
1398 * @see image_util_encode_create()
1399 * @see image_util_encode_set_resolution()
1400 * @see image_util_encode_set_input_buffer()
1401 * @see image_util_encode_set_output_path()
1402 * @see image_util_encode_set_output_buffer()
1403 * @see image_util_encode_destroy()
1404 */
1405 int image_util_encode_run_async(image_util_encode_h handle, image_util_encode_completed_cb callback, void *user_data);
1406
1407 /**
1408 * @brief Destroys the image encoding handle.
1409 * @since_tizen 3.0
1410 *
1411 * @remarks Any image handle created should be destroyed.
1412 *
1413 * @param[in] handle The handle to image util encoding
1414 *
1415 * @return @c 0 on success,
1416 *               otherwise a negative error value
1417 *
1418 * @retval #IMAGE_UTIL_ERROR_NONE Successful
1419 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
1420 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
1421 *
1422 * @pre image_util_encode_create()
1423 *
1424 * @see image_util_encode_create()
1425 */
1426 int image_util_encode_destroy(image_util_encode_h handle);
1427
1428 /**
1429  * @}
1430  */
1431
1432 #ifdef __cplusplus
1433 }
1434 #endif
1435
1436 #endif /* __TIZEN_MEDIA_IMAGE_UTIL_H__ */