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_MULTIMEDIA_IMAGE_UTIL_H__
  18 #define __TIZEN_MULTIMEDIA_IMAGE_UTIL_H__
  19
  20 #include <image_util_type.h>
  21 #include <image_util_decode.h>
  22 #include <image_util_encode.h>
  23
  24 #ifdef __cplusplus
  25 extern "C"
  26 {
  27 #endif
  28
  29 /**
  30  * @file image_util.h
  31  * @brief This file contains the image util API.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_MEDIA_IMAGE_UTIL_MODULE
  36  * @{
  37  */
  38
  39 /**
  40 * @deprecated Deprecated since 5.5.
  41 * @brief Calculates the size of the image buffer for the specified resolution and colorspace.
  42 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  43 *
  44 * @param[in] width The image width
  45 * @param[in] height The image height
  46 * @param[in] colorspace The image colorspace
  47 * @param[out] size The Calculated buffer size
  48 *
  49 * @return @c 0 on success,
  50 *               otherwise a negative error value
  51 *
  52 * @retval #IMAGE_UTIL_ERROR_NONE Successful
  53 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  54 *
  55 * @see image_util_transform_run()
  56 */
  57 int image_util_calculate_buffer_size(int width, int height, image_util_colorspace_e colorspace , unsigned int *size) TIZEN_DEPRECATED_API;
  58
  59 /**
  60 * @brief Extracts representative color from an image buffer.
  61 * @since_tizen 3.0
  62 * @remarks @a image_buffer should be RGB888 colorspace.
  63 *
  64 * @param[in] image_buffer The original image buffer
  65 * @param[in] width The image width
  66 * @param[in] height The image height
  67 * @param[out] rgb_r The red color in RGB color space
  68 * @param[out] rgb_g The green color in RGB color space
  69 * @param[out] rgb_b The blue color in RGB color space
  70 *
  71 * @return 0 on success,
  72 *           otherwise a negative error value
  73 *
  74 * @retval #IMAGE_UTIL_ERROR_NONE Successful
  75 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  76 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
  77 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
  78 *
  79 */
  80 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);
  81
  82 /**
  83  * @}
  84  */
  85
  86 /**
  87  * @addtogroup CAPI_MEDIA_IMAGE_UTIL_TRANSFORM_MODULE
  88  * @{
  89  */
  90
  91 /**
  92 * @brief Creates a handle to image util transform.
  93 * @details This function creates a handle to image util transform.
  94 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  95 *
  96 * @remarks The @a handle should be released using image_util_transform_destroy().
  97 *
  98 * @param[out] handle A handle to image util transform
  99 *
 100 * @return @c 0 on success,
 101 *               otherwise a negative error value
 102 *
 103 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 104 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 105 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 106 *
 107 * @see image_util_transform_destroy()
 108 *
 109 */
 110 int image_util_transform_create(transformation_h *handle);
 111
 112 /**
 113 * @deprecated Deprecated since 5.0.
 114 * @brief Sets the image util's accurate mode.
 115 * @details This function set if you use hardware acceleration or not.
 116 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 117 *
 118 *
 119 * @remarks The value returned will be IMAGE_UTIL_ERROR_NOT_SUPPORTED, if H/W acceleration doesn't support on the device.
 120 *
 121 * @param[in] handle The handle to image util
 122 * @param[in] mode Set @c true, user can use the hardware acceleration\n
 123 *                               otherwise set @c false if user can only software image processing
 124 *
 125 * @return @c 0 on success,
 126 *               otherwise a negative error value
 127 *
 128 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 129 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 130 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 131 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED The application does not have the hardware acceleration
 132 *
 133 * @pre image_util_transform_create().
 134 *
 135 * @see image_util_transform_create()
 136 * @see image_util_transform_destroy()
 137 */
 138 int image_util_transform_set_hardware_acceleration(transformation_h handle, bool mode) TIZEN_DEPRECATED_API;
 139
 140 /**
 141 * @brief Sets the information of the converting.
 142 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 143 *
 144 * @param[in] handle The handle to image util transform
 145 * @param[in] colorspace The colorspace of the image buffer
 146 *
 147 * @return @c 0 on success,
 148 *               otherwise a negative error value
 149 *
 150 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 151 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 152 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 153 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 154 *
 155 * @pre image_util_transform_create().
 156 *
 157 * @see image_util_transform_create()
 158 * @see image_util_transform_run()
 159 * @see image_util_transform_destroy()
 160 */
 161 int image_util_transform_set_colorspace(transformation_h handle, image_util_colorspace_e colorspace);
 162
 163 /**
 164 * @brief Sets the information of the resizing.
 165 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 166 *
 167 * @remarks image_util_transform_set_resolution and image_util_transform_set_crop_area can't do that at the same time.
 168 *
 169 * @param[in] handle The handle to image util transform
 170 * @param[in] width The width of image buffer
 171 * @param[in] height The height of 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 *
 180 * @pre image_util_transform_create().
 181 *
 182 * @see image_util_transform_create()
 183 * @see image_util_transform_run()
 184 * @see image_util_transform_destroy()
 185 */
 186 int image_util_transform_set_resolution(transformation_h handle, unsigned int width, unsigned int height);
 187
 188 /**
 189 * @brief Sets the information of the rotating.
 190 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 191 *
 192 * @param[in] handle The handle to image util transform
 193 * @param[in] rotation The rotation value of image buffer
 194 *
 195 * @return @c 0 on success,
 196 *               otherwise a negative error value
 197 *
 198 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 199 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 200 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 201 *
 202 * @pre image_util_transform_create().
 203 *
 204 * @see image_util_transform_create()
 205 * @see image_util_transform_run()
 206 * @see image_util_transform_destroy()
 207 */
 208 int image_util_transform_set_rotation(transformation_h handle, image_util_rotation_e rotation);
 209
 210 /**
 211 * @brief Sets the information of the cropping.
 212 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 213 *
 214 * @remarks image_util_transform_set_resolution and image_util_transform_set_crop_area can't do that at the same time.
 215 *
 216 * @param[in] handle The handle to image util transform
 217 * @param[in] start_x The start x position of cropped image buffer
 218 * @param[in] start_y The start y position of cropped image buffer
 219 * @param[in] end_x The end x position of cropped image buffer
 220 * @param[in] end_y The end y position of cropped image buffer
 221 *
 222 * @return @c 0 on success,
 223 *               otherwise a negative error value
 224 *
 225 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 226 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 227 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 228 *
 229 * @pre image_util_transform_create().
 230 *
 231 * @see image_util_transform_create()
 232 * @see image_util_transform_run()
 233 * @see image_util_transform_destroy()
 234 */
 235 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);
 236
 237 /**
 238 * @brief Gets the colorspace of the image buffer.
 239 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 240 *
 241 * @param[in] handle The handle to image util transform
 242 * @param[in,out] colorspace The colorspace of the image buffer
 243 *
 244 * @return @c 0 on success,
 245 *               otherwise a negative error value
 246 *
 247 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 248 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 249 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 250 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 251 *
 252 * @pre image_util_transform_create().\n
 253 *            image_util_transform_set_crop_area().
 254 *
 255 * @see image_util_transform_create()
 256 * @see image_util_transform_destroy()
 257 */
 258 int image_util_transform_get_colorspace(transformation_h handle, image_util_colorspace_e *colorspace);
 259
 260 /**
 261 * @brief Gets the resolution of the image buffer.
 262 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 263 *
 264 * @param[in] handle The handle to image util transform
 265 * @param[in,out] width The width of source image buffer
 266 * @param[in,out] height The height of source image buffer
 267 *
 268 * @return @c 0 on success,
 269 *               otherwise a negative error value
 270 *
 271 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 272 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 273 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 274 *
 275 * @pre image_util_transform_create().\n
 276 *            image_util_transform_set_resolution().
 277 *
 278 * @see image_util_transform_create()
 279 * @see image_util_transform_destroy()
 280 */
 281 int image_util_transform_get_resolution(transformation_h handle, unsigned int *width, unsigned int *height);
 282
 283 /**
 284 * @brief Gets the information of the rotating.
 285 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 286 *
 287 * @param[in] handle The handle to image util transform
 288 * @param[in,out] rotation The rotation value of image buffer
 289 *
 290 * @return @c 0 on success,
 291 *               otherwise a negative error value
 292 *
 293 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 294 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 295 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 296 *
 297 * @pre image_util_transform_create().\n
 298 *            image_util_transform_set_rotation().
 299 *
 300 * @see image_util_transform_create()
 301 * @see image_util_transform_destroy()
 302 */
 303 int image_util_transform_get_rotation(transformation_h handle, image_util_rotation_e *rotation);
 304
 305 /**
 306 * @brief Gets the information of the cropping.
 307 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 308 *
 309 * @param[in] handle The handle to image util transform
 310 * @param[in,out] start_x The start x position of cropped source image buffer
 311 * @param[in,out] start_y The start y position of cropped source image buffer
 312 * @param[in,out] end_x The end x position of cropped source image buffer
 313 * @param[in,out] end_y The end y position of cropped source image buffer
 314 *
 315 * @return @c 0 on success,
 316 *               otherwise a negative error value
 317 *
 318 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 319 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 320 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 321 *
 322 * @pre image_util_transform_create().\n
 323 *            image_util_transform_set_crop_area().
 324 *
 325 * @see image_util_transform_create()
 326 * @see image_util_transform_destroy()
 327 */
 328 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);
 329
 330 /**
 331 * @brief Transforms the image for given image util handle.
 332 * @details The function execute asynchronously, which contains complete callback \n
 333 *          If you set more than two transforming, the order of running is crop or resolution, colorspace converting, rotation. \n
 334 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 335 *
 336 * @remarks If H/W acceleration is not set, transformation is done via S/W acceleration.
 337 *
 338 * @param[in] handle The handle of transform
 339 * @param[in] src The handle to image util transform
 340 * @param[in] callback The callback function to be invoked
 341 * @param[in] user_data The user data to be passed to the callback function
 342 *
 343 * @return @c 0 on success,
 344 *               otherwise a negative error value
 345 *
 346 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 347 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 348 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 349 *
 350 * @see image_util_transform_create()
 351 * @see image_util_transform_destroy()
 352 */
 353 int image_util_transform_run(transformation_h handle, media_packet_h src, image_util_transform_completed_cb callback, void *user_data);
 354
 355 /**
 356 * @brief Destroys a handle to image util.
 357 * @details The function frees all resources related to the image util handle. The image util
 358 *               handle no longer can be used to perform any operations. A new image util handle
 359 *               has to be created before the next usage.
 360 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 361 *
 362 * @param[in] handle The handle to image util transform
 363 *
 364 * @return @c 0 on success,
 365 *               otherwise a negative error value
 366 *
 367 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 368 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 369 *
 370 * @see image_util_transform_create()
 371 *
 372 */
 373 int image_util_transform_destroy(transformation_h handle);
 374
 375 /**
 376  * @}
 377  */
 378
 379 /**
 380 * @addtogroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE
 381 * @{
 382 */
 383
 384 /**
 385 * @brief Called once for each supported image encode/decode colorspace.
 386 * @since_tizen 3.0
 387 *
 388 * @param[in] colorspace The colorspace
 389 * @param[in] user_data The user data passed from the foreach function
 390 *
 391 * @return @c true to continue with the next iteration of the loop, \n
 392 *         otherwise @c false to break out of the loop
 393 *
 394 * @pre image_util_foreach_supported_colorspace() invokes this callback.
 395 *
 396 * @see image_util_foreach_supported_colorspace()
 397 * @see image_util_encode_create()
 398 * @see image_util_decode_create()
 399 */
 400 typedef bool(*image_util_supported_colorspace_cb)(image_util_colorspace_e colorspace, void *user_data);
 401
 402 /**
 403 * @brief Retrieves all supported image encoding/decoding colorspace by invoking a callback function once for each one.
 404 * @since_tizen 3.0
 405 *
 406 * @param[in] image_type The type of supported image for which to create encode/decode handle
 407 * @param[in] callback The callback function to invoke
 408 * @param[in] user_data The user data to be passed to the callback function
 409 * @return 0 on success,
 410 *         otherwise a negative error value
 411 *
 412 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 413 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 414 *
 415 * @post This function invokes image_util_supported_colorspace_cb() repeatedly to retrieve each supported image encoding/decoding colorspace.
 416 *
 417 * @see image_util_supported_colorspace_cb()
 418 * @see image_util_encode_create()
 419 * @see image_util_decode_create()
 420 */
 421 int image_util_foreach_supported_colorspace(image_util_type_e image_type, image_util_supported_colorspace_cb callback, void *user_data);
 422
 423 /**
 424  * @}
 425  */
 426
 427 #ifdef __cplusplus
 428 }
 429 #endif
 430
 431 #endif /* __TIZEN_MULTIMEDIA_IMAGE_UTIL_H__ */