include/image_util_decode.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_DECODE_H__
  18 #define __TIZEN_MULTIMEDIA_IMAGE_UTIL_DECODE_H__
  19
  20 #include <image_util_type.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27 /**
  28 * @addtogroup CAPI_MEDIA_IMAGE_UTIL_ENCODE_DECODE_MODULE
  29 * @{
  30 */
  31
  32 /**
  33 * @brief Creates a handle to image util decoding.
  34 * @details This function creates a handle to image util decoding.
  35 * @since_tizen 3.0
  36 *
  37 * @remarks The @a handle should be released using image_util_decode_destroy().
  38 *
  39 * @param[out] handle A handle to image util decoding
  40 *
  41 * @return @c 0 on success,
  42 *             otherwise a negative error value
  43 *
  44 * @retval #IMAGE_UTIL_ERROR_NONE Successful
  45 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  46 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
  47 *
  48 * @see image_util_decode_destroy()
  49 *
  50 */
  51 int image_util_decode_create(image_util_decode_h *handle);
  52
  53 /**
  54 * @brief Sets the input file path from which to decode.
  55 * @since_tizen 3.0
  56 *
  57 * @remarks One of image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.\n
  58 *             If both are set then the latest input set, is considered.\n
  59 *             http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
  60 *             http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
  61 *             Finds out image type by reading the header of the image provided in input path.
  62 *
  63 * @param[in] handle The handle to image util decoding
  64 * @param[in] path The path to input image
  65 *
  66 * @return @c 0 on success,
  67 *            otherwise a negative error value
  68 *
  69 * @retval #IMAGE_UTIL_ERROR_NONE Successful
  70 * @retval #IMAGE_UTIL_ERROR_NO_SUCH_FILE No such file
  71 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  72 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
  73 * @retval #IMAGE_UTIL_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  74 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
  75 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
  76 *
  77 * @pre image_util_decode_create()
  78 *
  79 * @post image_util_decode_run() / image_util_decode_run_async()
  80 * @post image_util_decode_destroy()
  81 *
  82 * @see image_util_decode_create()
  83 * @see image_util_decode_set_output_buffer()
  84 * @see image_util_decode_run()
  85 * @see image_util_decode_run_async()
  86 * @see image_util_decode_destroy()
  87 */
  88 int image_util_decode_set_input_path(image_util_decode_h handle, const char *path);
  89
  90 /**
  91 * @brief Sets the input buffer from which to decode.
  92 * @since_tizen 3.0
  93 *
  94 * @remarks One of image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.\n
  95 *              If both are set then the latest input set, is considered.\n
  96 *              Finds out image type by reading the header of the image provided in input buffer.
  97 *
  98 * @param[in] handle The handle to image util decoding
  99 * @param[in] src_buffer The input image buffer
 100 * @param[in] src_size The input image buffer size
 101 *
 102 * @return @c 0 on success,
 103 *             otherwise a negative error value
 104 *
 105 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 106 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 107 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 108 * @retval #IMAGE_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 109 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 110 *
 111 * @pre image_util_decode_create()
 112 *
 113 * @post image_util_decode_run() / image_util_decode_run_async()
 114 * @post image_util_decode_destroy()
 115 *
 116 * @see image_util_decode_create()
 117 * @see image_util_decode_set_output_buffer()
 118 * @see image_util_decode_run()
 119 * @see image_util_decode_run_async()
 120 * @see image_util_decode_destroy()
 121 */
 122 int image_util_decode_set_input_buffer(image_util_decode_h handle, const unsigned char *src_buffer, unsigned long long src_size);
 123
 124 /**
 125 * @brief Sets the output buffer to which the decoded buffer will be written to.
 126 * @since_tizen 3.0
 127 *
 128 * @remarks Either image_util_decode_set_input_path() or image_util_decode_set_input_buffer() should be set.\n
 129 *             By default the decoded output buffer colorspace will be IMAGE_UTIL_COLORSPACE_RGBA8888.
 130 *             Use image_util_decode_set_colorspace to change the colorspace.
 131 *             @a dst_buffer should be released after @c image_util_decode_run() or @c image_util_decode_run_async().
 132 *
 133 * @param[in] handle The handle to image util decoding
 134 * @param[in] dst_buffer The decoded output buffer
 135 *
 136 * @return @c 0 on success,
 137 *                 otherwise a negative error value
 138 *
 139 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 140 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 141 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 142 *
 143 * @pre image_util_decode_create()
 144 *
 145 * @post image_util_decode_run() / image_util_decode_run_async()
 146 * @post image_util_decode_destroy()
 147 *
 148 * @see image_util_decode_create()
 149 * @see image_util_decode_set_input_path()
 150 * @see image_util_decode_set_input_buffer()
 151 * @see image_util_decode_run()
 152 * @see image_util_decode_run_async()
 153 * @see image_util_decode_destroy()
 154 */
 155 int image_util_decode_set_output_buffer(image_util_decode_h handle, unsigned char **dst_buffer);
 156
 157 /**
 158 * @brief Sets the decoded image colorspace format.
 159 * @since_tizen 3.0
 160 *
 161 * @remarks The default colorspace is IMAGE_UTIL_COLORSPACE_RGBA8888.\n
 162 *             Use image_util_foreach_supported_colorspace to get supported colorspaces for each image format.\n
 163 *             Errors would be returned if not supported.
 164 *
 165 * @param[in] handle The handle to image util decoding
 166 * @param[in] colorspace The decoded image colorspace
 167 *
 168 * @return @c 0 on success,
 169 *                 otherwise a negative error value
 170 *
 171 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 172 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 173 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 174 *
 175 * @pre image_util_decode_create()
 176 * @pre image_util_decode_set_input_path() / image_util_decode_set_input_buffer()
 177 *
 178 * @post image_util_decode_run() / image_util_decode_run_async()
 179 * @post image_util_decode_destroy()
 180 *
 181 * @see image_util_supported_colorspace_cb()
 182 * @see image_util_foreach_supported_colorspace()
 183 * @see image_util_decode_create()
 184 * @see image_util_decode_set_input_path()
 185 * @see image_util_decode_set_input_buffer()
 186 * @see image_util_decode_set_output_buffer()
 187 * @see image_util_decode_run()
 188 * @see image_util_decode_run_async()
 189 * @see image_util_decode_destroy()
 190 */
 191 int image_util_decode_set_colorspace(image_util_decode_h handle, image_util_colorspace_e colorspace);
 192
 193 /**
 194 * @brief Sets the downscale value at which JPEG image should be decoded.
 195 * @since_tizen 3.0
 196 *
 197 * @remarks This is API is supported only for JPEG decoding.
 198 *
 199 * @param[in] handle The handle to image util decoding
 200 * @param[in] down_scale The downscale at which image is to be decoded
 201 *
 202 * @return @c 0 on success,
 203 *                 otherwise a negative error value
 204 *
 205 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 206 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 207 * @retval #IMAGE_UTIL_ERROR_NOT_SUPPORTED_FORMAT Format not supported
 208 *
 209 * @pre image_util_decode_create()
 210 * @pre image_util_decode_set_input_path() / image_util_decode_set_input_buffer()
 211 *
 212 * @post image_util_decode_run() / image_util_decode_run_async()
 213 * @post image_util_decode_destroy()
 214 *
 215 * @see image_util_decode_create()
 216 * @see image_util_decode_set_input_path()
 217 * @see image_util_decode_set_input_buffer()
 218 * @see image_util_decode_set_output_buffer()
 219 * @see image_util_decode_run()
 220 * @see image_util_decode_run_async()
 221 * @see image_util_decode_destroy()
 222 */
 223 int image_util_decode_set_jpeg_downscale(image_util_decode_h handle, image_util_scale_e down_scale);
 224
 225 /**
 226 * @brief Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().
 227 * @since_tizen 3.0
 228 *
 229 * @remarks The output will be stored in the pointer set using image_util_decode_set_output_buffer().\n
 230 *          The function executes synchronously.\n
 231 *          When any of the @pre functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
 232 *
 233 * @param[in] handle The handle to image util decoding
 234 * @param[out] width Width of the decoded image
 235 * @param[out] height Height of the decoded image
 236 * @param[out] size Size of the decoded image
 237 *
 238 * @return @c 0 on success,
 239 *                 otherwise a negative error value
 240 *
 241 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 242 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 243 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 244 *
 245 * @pre image_util_decode_create()
 246 * @pre image_util_decode_set_input_buffer() / image_util_decode_set_input_path().
 247 * @pre image_util_decode_set_output_buffer()
 248 *
 249 * @post image_util_decode_destroy()
 250 *
 251 * @see image_util_decode_create()
 252 * @see image_util_decode_set_input_path()
 253 * @see image_util_decode_set_input_buffer()
 254 * @see image_util_decode_set_output_buffer()
 255 * @see image_util_decode_destroy()
 256 */
 257 int image_util_decode_run(image_util_decode_h handle, unsigned long *width, unsigned long *height, unsigned long long *size);
 258
 259 /**
 260 * @brief Starts decoding of the image and fills the output buffer set using image_util_decode_set_output_buffer().
 261 * @since_tizen 3.0
 262 *
 263 * @remarks The output will be stored in the pointer set using image_util_decode_set_output_buffer().\n
 264 *          The function executes asynchronously, which contains complete callback.\n
 265 *          When any of the @pre functions are not called, IMAGE_UTIL_ERROR_INVALID_PARAMETER is returned.
 266 *
 267 * @param[in] handle The handle to image util decoding
 268 * @param[in] callback The callback function to be invoked
 269 * @param[in] user_data The user data to be passed to the callback function
 270 *
 271 * @return @c 0 on success,
 272 *                 otherwise a negative error value
 273 *
 274 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 275 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 276 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 277 *
 278 * @pre image_util_decode_create()
 279 * @pre image_util_decode_set_input_buffer() / image_util_decode_set_input_path().
 280 * @pre image_util_decode_set_output_buffer()
 281 *
 282 * @post image_util_decode_destroy()
 283 *
 284 * @see image_util_decode_create()
 285 * @see image_util_decode_set_input_path()
 286 * @see image_util_decode_set_input_buffer()
 287 * @see image_util_decode_set_output_buffer()
 288 * @see image_util_decode_destroy()
 289 */
 290 int image_util_decode_run_async(image_util_decode_h handle, image_util_decode_completed_cb callback, void *user_data);
 291
 292 /**
 293 * @brief Destroys the image decoding handle.
 294 * @since_tizen 3.0
 295 *
 296 * @remarks Any image handle created should be destroyed.
 297 *
 298 * @param[in] handle The handle to image util decoding
 299 *
 300 * @return @c 0 on success,
 301 *                 otherwise a negative error value
 302 *
 303 * @retval #IMAGE_UTIL_ERROR_NONE Successful
 304 * @retval #IMAGE_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 305 * @retval #IMAGE_UTIL_ERROR_INVALID_OPERATION Invalid operation
 306 *
 307 * @pre image_util_decode_create()
 308 *
 309 * @see image_util_decode_create()
 310 */
 311 int image_util_decode_destroy(image_util_decode_h handle);
 312
 313 /**
 314  * @}
 315  */
 316
 317 #ifdef __cplusplus
 318 }
 319 #endif
 320
 321 #endif /* __TIZEN_MULTIMEDIA_IMAGE_UTIL_DECODE_H__ */