include/media_codec.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_CODEC_H__
  18 #define __TIZEN_MEDIA_CODEC_H__
  19
  20 #include <tizen.h>
  21 #include <stdint.h>
  22 #include <media_packet.h>
  23 #include <media_packet_pool.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30 * @file media_codec.h
  31 * @brief This file contains the capi media codec API.
  32 */
  33
  34 /**
  35 * @addtogroup CAPI_MEDIA_CODEC_MODULE
  36 * @{
  37 */
  38
  39 /**
  40  * @brief Media Codec type handle.
  41  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  42  */
  43 typedef struct mediacodec_s *mediacodec_h;
  44
  45 /**
  46  * @brief Enumeration of  media codec support  type
  47  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  48  * @remarks If this codec is to be used as an encoder or decoder, the codec flag must be set to #MEDIACODEC_ENCODER or
  49  *          #MEDIACODEC_DECODER. If user doesn't set optional flag, default flags will be set to #MEDIACODEC_SUPPORT_TYPE_SW.
  50  */
  51 typedef enum {
  52         MEDIACODEC_ENCODER          = 0x1,      /**< This flag is for using the encoder */
  53         MEDIACODEC_DECODER          = 0x2,      /**< This flag is for using the decoder */
  54         MEDIACODEC_SUPPORT_TYPE_HW  = 0x4,      /**< This is an optional flag for using the h/w codec */
  55         MEDIACODEC_SUPPORT_TYPE_SW  = 0x8,      /**< This is an optional flag for using the s/w codec */
  56 } mediacodec_support_type_e;
  57
  58 /**
  59  * @brief Enumerations of  media codec type
  60  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  61  */
  62 typedef enum {
  63         MEDIACODEC_NONE         = 0x0,      /**< NONE*/
  64         MEDIACODEC_L16          = 0x1010,   /**< L16*/
  65         MEDIACODEC_ALAW         = 0x1020,   /**< ALAW*/
  66         MEDIACODEC_ULAW         = 0x1030,   /**< ULAW*/
  67         MEDIACODEC_AMR          = 0x1040,   /**< MEDIACDEC_AMR indicates AMR-NB (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  68         MEDIACODEC_AMR_NB       = 0x1040,   /**< AMR-NB (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  69         MEDIACODEC_AMR_WB       = 0x1041,   /**< AMR-WB (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  70         MEDIACODEC_G729         = 0x1050,   /**< G729*/
  71         MEDIACODEC_AAC          = 0x1060,   /**< MEDIACDEC_AAC indicates AAC-LC (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  72         MEDIACODEC_AAC_LC       = 0x1060,   /**< AAC-LC (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  73         MEDIACODEC_AAC_HE       = 0x1061,   /**< HE-AAC (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  74         MEDIACODEC_AAC_HE_PS    = 0x1062,   /**< HE-AAC-PS (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  75         MEDIACODEC_MP3          = 0x1070,   /**< MP3*/
  76         MEDIACODEC_VORBIS       = 0x1080,   /**< VORBIS (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  77         MEDIACODEC_FLAC         = 0x1090,   /**< FLAC (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  78         MEDIACODEC_WMAV1        = 0x10A0,   /**< WMA version 1 (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  79         MEDIACODEC_WMAV2        = 0x10A1,   /**< WMA version 2  (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  80         MEDIACODEC_WMAPRO       = 0x10A2,   /**< WMA Professional (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  81         MEDIACODEC_WMALSL       = 0x10A3,   /**< WMA Lossless (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  82
  83         MEDIACODEC_H261         = 0x2010,   /**< H.261*/
  84         MEDIACODEC_H263         = 0x2020,   /**< H.263*/
  85         MEDIACODEC_H264         = 0x2030,   /**< H.264*/
  86         MEDIACODEC_MJPEG        = 0x2040,   /**< MJPEG*/
  87         MEDIACODEC_MPEG1        = 0x2050,   /**< MPEG1*/
  88         MEDIACODEC_MPEG2        = 0x2060,   /**< MPEG2*/
  89         MEDIACODEC_MPEG4        = 0x2070,   /**< MPEG4*/
  90         MEDIACODEC_HEVC         = 0x2080,   /**< HEVC (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  91         MEDIACODEC_VP8          = 0x2090,   /**< VP8 (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  92         MEDIACODEC_VP9          = 0x20A0,   /**< VP9 (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  93         MEDIACODEC_VC1          = 0x20B0,   /**< VC1 (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
  94 } mediacodec_codec_type_e;
  95
  96 /**
  97  * @brief Enumeration of  media codec error
  98  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  99  */
 100 typedef enum {
 101         MEDIACODEC_ERROR_NONE                       = TIZEN_ERROR_NONE,                     /**< Successful */
 102         MEDIACODEC_ERROR_OUT_OF_MEMORY              = TIZEN_ERROR_OUT_OF_MEMORY,            /**< Out of memory */
 103         MEDIACODEC_ERROR_INVALID_PARAMETER          = TIZEN_ERROR_INVALID_PARAMETER,        /**< Invalid parameter */
 104         MEDIACODEC_ERROR_INVALID_OPERATION          = TIZEN_ERROR_INVALID_OPERATION,        /**< Invalid operation */
 105         MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE    = TIZEN_ERROR_NOT_SUPPORTED,            /**< Not supported */
 106         MEDIACODEC_ERROR_PERMISSION_DENIED          = TIZEN_ERROR_PERMISSION_DENIED,        /**< Permission denied */
 107         MEDIACODEC_ERROR_INVALID_STATE              = TIZEN_ERROR_MEDIACODEC | 0x01,        /**< Invalid state */
 108         MEDIACODEC_ERROR_INVALID_INBUFFER           = TIZEN_ERROR_MEDIACODEC | 0x02,        /**< Invalid input buffer */
 109         MEDIACODEC_ERROR_INVALID_OUTBUFFER          = TIZEN_ERROR_MEDIACODEC | 0x03,        /**< Invalid output buffer */
 110         MEDIACODEC_ERROR_INTERNAL                   = TIZEN_ERROR_MEDIACODEC | 0x04,        /**< Internal error */
 111         MEDIACODEC_ERROR_NOT_INITIALIZED            = TIZEN_ERROR_MEDIACODEC | 0x05,        /**< Not initialized mediacodec */
 112         MEDIACODEC_ERROR_INVALID_STREAM             = TIZEN_ERROR_MEDIACODEC | 0x06,        /**< Invalid stream */
 113         MEDIACODEC_ERROR_CODEC_NOT_FOUND            = TIZEN_ERROR_MEDIACODEC | 0x07,        /**< Not supported format */
 114         MEDIACODEC_ERROR_DECODE                     = TIZEN_ERROR_MEDIACODEC | 0x08,        /**< Error while decoding data */
 115         MEDIACODEC_ERROR_NO_FREE_SPACE              = TIZEN_ERROR_MEDIACODEC | 0x09,        /**< Out of storage */
 116         MEDIACODEC_ERROR_STREAM_NOT_FOUND           = TIZEN_ERROR_MEDIACODEC | 0x0a,        /**< Cannot find stream */
 117         MEDIACODEC_ERROR_NOT_SUPPORTED_FORMAT       = TIZEN_ERROR_MEDIACODEC | 0x0b,        /**< Not supported format */
 118         MEDIACODEC_ERROR_BUFFER_NOT_AVAILABLE       = TIZEN_ERROR_MEDIACODEC | 0x0c,        /**< Not available buffer */
 119         MEDIACODEC_ERROR_OVERFLOW_INBUFFER          = TIZEN_ERROR_MEDIACODEC | 0x0d,        /**< Overflow input buffer (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
 120         MEDIACODEC_ERROR_RESOURCE_OVERLOADED        = TIZEN_ERROR_MEDIACODEC | 0x0e,        /**< Exceed the instance limits (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)*/
 121 } mediacodec_error_e;
 122
 123 /**
 124  * @brief Enumeration of buffer status
 125  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 126  */
 127 typedef enum {
 128         MEDIACODEC_NEED_DATA,
 129         MEDIACODEC_ENOUGH_DATA
 130 } mediacodec_status_e;
 131
 132 /**
 133  * @brief Called when the input buffer(pkt) used up.
 134  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 135  * @details It will be invoked when mediacodec has used input buffer.
 136  * @param[in] pkt       The media packet handle
 137  * @param[in] user_data The user data passed from the callback registration function
 138  * @pre It will be invoked when input buffer process completed if you register this callback using mediacodec_set_input_buffer_used_cb().
 139  * @see mediacodec_set_input_buffer_used_cb()
 140  * @see mediacodec_unset_input_buffer_used_cb()
 141  */
 142 typedef void (*mediacodec_input_buffer_used_cb)(media_packet_h pkt, void *user_data);
 143
 144 /**
 145  * @brief Called when the output buffer is available.
 146  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 147  * @details It will be invoked when mediacodec has output buffer.
 148  * @param[in] pkt       The media packet handle
 149  * @param[in] user_data The user data passed from the callback registration function
 150  * @pre It will be invoked when mediacodec process completed(had output buffer) if you register this callback using mediacodec_set_fill_buffer_cb().
 151  * @see mediacodec_set_output_buffer_available_cb()
 152  * @see mediacodec_unset_output_buffer_available_cb()
 153  */
 154 typedef void (*mediacodec_output_buffer_available_cb)(media_packet_h pkt, void *user_data);
 155
 156 /**
 157  * @brief Called when the error has occured
 158  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 159  * @details It will be invoked when the error has occured.
 160  * @param[in] error_code The error code
 161  * @param[in] user_data  The user data passed from the callback registration function
 162  * @pre It will be invoked when the error has occured if you register this callback using mediacodec_set_error_cb().
 163  * @see mediacodec_set_error_cb()
 164  * @see mediacodec_unset_error_cb()
 165  */
 166 typedef void (*mediacodec_error_cb)(mediacodec_error_e error, void *user_data);
 167
 168 /**
 169  * @brief Called when there is no data to decode/encode
 170  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 171  * @details It will be invoked when the end-of-stream is reached.
 172  * @param[in] user_data The user data passed from the callback registration function
 173  * @pre It will be invoked when the eos event generate if you register this callback using mediacodec_set_eos_cb().
 174  * @see mediacodec_set_eos_cb()
 175  * @see mediacodec_unset_eos_cb()
 176  */
 177 typedef void (*mediacodec_eos_cb)(void *user_data);
 178
 179 /**
 180  * @brief Called when the mediacodec needs more data or has enough data.
 181  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 182  * @details It is recommended that the application stops calling mediacodec_process_input() when MEDIACODEC_ENOUGH_DATA
 183  * is invoked.
 184  * @param[in] user_data The user data passed from the callback registration function
 185  * @see mediacodec_set_buffer_status_cb()
 186  * @see mediacodec_unset_buffer_status_cb()
 187  */
 188 typedef void (*mediacodec_buffer_status_cb)(mediacodec_status_e status, void *user_data);
 189
 190 /**
 191  * @brief Called once for each supported codec types.
 192  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 193  * @param[in] codec_type  The codec type
 194  * @param[in] user_data   The user data passed from the foreach function
 195  * @return  @c true to continue with the next iteration of the loop, @c false to break out of the loop.
 196  * @pre mediacodec_foreach_supported_codec() will invoke this callback.
 197  * @see mediacodec_foreach_supported_codec()
 198  */
 199 typedef bool (*mediacodec_supported_codec_cb)(mediacodec_codec_type_e codec_type, void *user_data);
 200
 201 /**
 202  * @brief Creates a mediacodec handle for decoding/encoding
 203  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 204  * @remarks you must release @a mediacodec using mediacodec_destroy().\n
 205  *          Although you can create multiple mediacodec handles at the same time,
 206  *          the mediacodec cannot guarantee proper operation because of limited resources, like
 207  *          audio or display device.
 208  *
 209  * @param[out] mediacodec  A new handle to mediacodec
 210  * @return @c 0 on success, otherwise a negative error value
 211  * @retval #MEDIACODEC_ERROR_NONE Successful
 212  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 213  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 214  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 215  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 216  */
 217 int mediacodec_create(mediacodec_h *mediacodec);
 218
 219 /**
 220  * @brief Destroys the mediacodec handle and releases all its resources.
 221  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 222  * @remarks To completely shutdown the mediacodec operation, call this function with a valid player handle from any
 223  *          mediacodec
 224  *
 225  * @param[in] mediacodec The handle to mediacodec to be destroyed.
 226  * @return @c 0 on success, otherwise a negative error value
 227  * @retval #MEDIACODEC_ERROR_NONE Successful
 228  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 230  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 231  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 232  */
 233 int mediacodec_destroy(mediacodec_h mediacodec);
 234
 235 /**
 236  * @brief Sets the codec type and decoder/encoder.
 237  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 238  * @remarks If this codec is to be used as a decoder, pass the #MEDIACODEC_DECODER flag.
 239  *          If this codec is to be used as an encoder, pass the #MEDIACODEC_ENCODER flag.\n
 240  *          The software codec is used as default setting(#MEDIACODEC_SUPPORT_TYPE_SW) if user doesn't set hardware flag.
 241  *          If user wants to use h/w decoder, user needs to pass the #MEDIACODEC_DECODER | #MEDIACODEC_SUPPORT_TYPE_HW.
 242  * @param[in] mediacodec  The handle of mediacodec
 243  * @param[in] codec_type  The identifier of the codec type of the decoder/encoder
 244  * @param[in] flags  The encoding/decoding scheme, defined by #mediacodec_support_type_e
 245  * @return @c 0 on success, otherwise a negative error value
 246  * @retval #MEDIACODEC_ERROR_NONE Successful
 247  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 248  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 249  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 250  * @retval #MEDIACODEC_ERROR_CODEC_NOT_FOUND Codec not found
 251  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 252  */
 253 int mediacodec_set_codec(mediacodec_h mediacodec, mediacodec_codec_type_e codec_type, int flags);
 254
 255 /**
 256  * @brief Sets the default info for the video decoder
 257  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 258  * @param[in] mediacodec The handle to mediacodec
 259  * @param[in] width      The width for video decoding.
 260  * @param[in] height     The height for video decoding.
 261  * @return @c 0 on success, otherwise a negative error value
 262  * @retval #MEDIACODEC_ERROR_NONE Successful
 263  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 264  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 265  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 266  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 267  */
 268 int mediacodec_set_vdec_info(mediacodec_h mediacodec, int width, int height);
 269
 270 /**
 271  * @brief Sets the default info for the video encoder
 272  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 273  * @remarks The frame rate is the speed of recording and the speed of playback.
 274  *          If user wants the default setting for ratecontrol, set @a target_bits to @c 0.
 275  * @param[in] mediacodec  The handle to mediacodec
 276  * @param[in] width  The width for video encoding.
 277  * @param[in] height  The height for video encoding.
 278  * @param[in] fps  The frame rate in frames per second.
 279  * @param[in] target_bits The target bitrates in bits per second.(a unit of kbit)
 280  * @return @c 0 on success, otherwise a negative error value
 281  * @retval #MEDIACODEC_ERROR_NONE Successful
 282  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 283  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 284  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 285  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 286  */
 287 int mediacodec_set_venc_info(mediacodec_h mediacodec, int width, int height, int fps, int target_bits);
 288
 289 /**
 290  * @brief Sets the default info for the audio decoder
 291  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 292  * @param[in] mediacodec The handle to mediacodec
 293  * @param[in] samplerate The samplerate for audio decoding.
 294  * @param[in] channel    The channels for audio decoding.
 295  * @param[in] bit        The bits resolution for audio decoding.
 296  * @return @c 0 on success, otherwise a negative error value
 297  * @retval #MEDIACODEC_ERROR_NONE Successful
 298  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 299  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 300  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 301  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 302  */
 303 int mediacodec_set_adec_info(mediacodec_h mediacodec, int samplerate, int channel, int bit);
 304
 305 /**
 306  * @brief Sets the default info for the audio encoder
 307  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 308  * @param[in] mediacodec The handle to mediacodec
 309  * @param[in] samplerate The samplerate for audio encoding.
 310  * @param[in] channel    The channels for audio encoding.
 311  * @param[in] bit        The bits resolution for audio encoding.
 312  * @param[in] bitrate  The bitrate for audio encoding.
 313  * @return @c 0 on success, otherwise a negative error value
 314  * @retval #MEDIACODEC_ERROR_NONE Successful
 315  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 316  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 317  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 318  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 319  */
 320 int mediacodec_set_aenc_info(mediacodec_h mediacodec, int samplerate, int channel, int bit, int bitrate);
 321
 322 /**
 323  * @brief Sets the codec type and codec default info via media format.
 324  * @details Sets the value via media format instead of mediacodec_set_codec(), mediacodec_set_venc_info(),
 325  *          mediacodec_set_vdec_info(), mediacodec_set_aenc_info(), and mediacodec_set_adec_info().
 326  * @since_tizen 4.0
 327  * @remarks When using the @a format parameter from the output of the media demuxer, you can use media format via media_packet_get_format().
 328  *          Otherwise, you must set the following values after creating media format.
 329  *          Set the audio or video codec type via media_format_set_video_mime() or media_format_set_audio_mime().
 330  *          For video decoding, width, height must be set via media_format_set_video_width() and media_format_set_video_height().
 331  *          For video encoding, width, height, target bitrate, and frame rate must be set via media_format_set_video_avg_bps() and media_format_set_video_frame_rate().
 332  *          For audio decoding, samplerate, channel, and bit must be set via media_format_set_audio_samplerate(), media_format_set_audio_channel() and media_format_set_audio_bit().
 333  *          For audio encoding, samplerate, channel, bit, and bitrate must be set via media_format_set_audio_avg_bps().\n
 334  *          If this codec is to be used as a decoder, pass the #MEDIACODEC_DECODER flag.
 335  *          If this codec is to be used as an encoder, pass the #MEDIACODEC_ENCODER flag.\n
 336  *          The software codec is used as default setting (#MEDIACODEC_SUPPORT_TYPE_SW) if user doesn't set hardware flag.
 337  *          If you wants to use h/w decoder, you needs to pass the #MEDIACODEC_DECODER | #MEDIACODEC_SUPPORT_TYPE_HW.
 338  * @param[in] mediacodec The mediacodec handle
 339  * @param[in] format     The #media_format_h of input data
 340  * @param[in] flags      The encoding/decoding scheme,
 341  *                       values of #mediacodec_support_type_e combined with bitwise 'or'
 342  * @return @c 0 on success, otherwise a negative error value
 343  * @retval #MEDIACODEC_ERROR_NONE Successful
 344  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 345  * @retval #MEDIACODEC_ERROR_CODEC_NOT_FOUND Unsupported codec
 346  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 347  * @pre The media format has been created and the required values for configuration have been set.
 348  * @see media_format_set_video_mime()
 349  * @see media_format_set_audio_mime()
 350  * @see media_format_set_video_width()
 351  * @see media_format_set_video_height()
 352  * @see media_format_set_video_avg_bps()
 353  * @see media_format_set_video_frame_rate()
 354  * @see media_format_set_audio_channel()
 355  * @see media_format_set_audio_samplerate()
 356  * @see media_format_set_audio_bit()
 357  * @see media_format_set_audio_avg_bps()
 358  */
 359 int mediacodec_configure_from_media_format(mediacodec_h mediacodec, media_format_h format, int flags);
 360
 361 /**
 362  * @brief Prepares @a mediacodec for encoding/decoding.
 363  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 364  * @param[in] mediacodec The handle to mediacodec
 365  * @return @c 0 on success, otherwise a negative error value
 366  * @retval #MEDIACODEC_ERROR_NONE Successful
 367  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 368  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 369  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 370  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 371  * @pre The mediacodec should call mediacodec_set_codec()and mediacodec_set_vdec_info()/mediacodec_set_venc_info() before calling mediacodec_prepare()
 372  *      If the decoder is set by mediacodec_set_codec(), mediacodec_set_vdec_info() should be called. If the encoder is set by
 373  *      mediacodec_set_codec(), mediacodec_set_venc_info() should be called.
 374  */
 375 int mediacodec_prepare(mediacodec_h mediacodec);
 376
 377 /**
 378  * @brief Unprepares @a mediacodec for encoding/decoding.
 379  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 380  * @param[in] mediacodec The handle to mediacodec
 381  * @return @c 0 on success, otherwise a negative error value
 382  * @retval #MEDIACODEC_ERROR_NONE Successful
 383  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 384  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 385  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 386  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 387  */
 388 int mediacodec_unprepare(mediacodec_h mediacodec);
 389
 390 /**
 391  * @brief Decodes/Encodes a packet. The function passed undecoded/unencoded packet to the input queue and decode/encode a
 392  *        frame sequentially.
 393  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 394  * @param[in] mediacodec The handle to mediacodec
 395  * @param[in] inbuf      The current input format for the decoder/encoder
 396  * @param[in] timeOutUs  The timeout in microseconds. \n
 397  *                       The input buffer wait up to "timeOutUs" microseconds.
 398  * @return @c 0 on success, otherwise a negative error value
 399  * @retval #MEDIACODEC_ERROR_NONE Successful
 400  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 401  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 402  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 403  * @retval #MEDIACODEC_ERROR_OVERFLOW_INBUFFER Overflow inputbuffer
 404  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 405  */
 406 int mediacodec_process_input(mediacodec_h mediacodec, media_packet_h inbuf, uint64_t timeOutUs);
 407
 408 /**
 409  * @brief Gets the decoded or encoded packet from the output queue.
 410  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 411  * @param[in] mediacodec The handle to mediacodec
 412  * @param[out] outbuf    The current output of the decoder/encoder.
 413  *                       this function passed decoded/encoded frame to output queue.
 414  * @param[in] timeOutUs  The timeout in microseconds. \n
 415  *                       The input buffer wait up to "timeOutUs" microseconds.
 416  * @return @c 0 on success, otherwise a negative error value
 417  * @retval #MEDIACODEC_ERROR_NONE Successful
 418  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 419  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY Out of memory
 420  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION Invalid operation
 421  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 422  */
 423 int mediacodec_get_output(mediacodec_h mediacodec, media_packet_h *outbuf, uint64_t timeOutUs);
 424
 425 /**
 426  * @brief Flushes both input and output buffers.
 427  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 428  * @param[in] mediacodec The handle to mediacodec
 429  * @return @c 0 on success, otherwise a negative error value
 430  * @retval #MEDIACODEC_ERROR_NONE Successful
 431  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 432  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 433  */
 434 int mediacodec_flush_buffers(mediacodec_h mediacodec);
 435
 436 /**
 437  * @brief set empty buffer callback the media codec for process, asynchronously.
 438  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 439  * @param[in] mediacodec The handle to mediacodec
 440  * @param[in] callback   The callback function to register
 441  * @param[in] user_data  The user data to be passed to the callback function
 442  * @return @c 0 on success, otherwise a negative error value
 443  * @retval #MEDIACODEC_ERROR_NONE Successful
 444  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 445  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 446  * @pre mediacodec_set_input_buffer_used_cb should be called before mediacodec_preare().
 447  * @post mediacodec_input_buffer_used_cb will be invoked.
 448  * @see mediacodec_set_input_buffer_used_cb()
 449  * @see mediacodec_unset_input_buffer_used_cb()
 450  */
 451 int mediacodec_set_input_buffer_used_cb(mediacodec_h mediacodec, mediacodec_input_buffer_used_cb callback, void* user_data);
 452
 453 /**
 454  * @brief unset input buffer used callback the media codec for process, asynchronously.
 455  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 456  * @param[in] mediacodec The handle to mediacodec
 457  * @return @c 0 on success, otherwise a negative error value
 458  * @retval #MEDIACODEC_ERROR_NONE Successful
 459  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 460  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 461  * @see mediacodec_set_input_buffer_used_cb()
 462  */
 463 int mediacodec_unset_input_buffer_used_cb(mediacodec_h mediacodec);
 464
 465 /**
 466  * @brief set output buffer available callback the media codec for process, asynchronously.
 467  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 468  * @param[in] mediacodec The handle to mediacodec
 469  * @param[in] callback   The callback function to register
 470  * @param[in] user_data  The user data to be passed to the callback function
 471  * @return @c 0 on success, otherwise a negative error value
 472  * @retval #MEDIACODEC_ERROR_NONE Successful
 473  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 474  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 475  * @pre mediacodec_set_output_buffer_available_cb should be called before mediacodec_preare().
 476  * @post mediacodec_output_buffer_available_cb will be invoked.
 477  * @see mediacodec_set_output_buffer_available_cb()
 478  * @see mediacodec_unset_output_buffer_available_cb()
 479  */
 480 int mediacodec_set_output_buffer_available_cb(mediacodec_h mediacodec, mediacodec_output_buffer_available_cb callback, void* user_data);
 481
 482 /**
 483  * @brief unset output buffer available callback the media codec for process, asynchronously.
 484  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 485  * @param[in] mediacodec The handle to mediacodec
 486  * @return @c 0 on success, otherwise a negative error value
 487  * @retval #MEDIACODEC_ERROR_NONE Successful
 488  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 489  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 490  * @see mediacodec_set_output_buffer_available_cb()
 491  */
 492 int mediacodec_unset_output_buffer_available_cb(mediacodec_h mediacodec);
 493
 494 /**
 495  * @brief set error callback the media codec for process, asynchronously.
 496  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 497  * @param[in] mediacodec The handle to mediacodec
 498  * @param[in] callback   The callback function to register
 499  * @param[in] user_data  The user data to be passed to the callback function
 500  * @return @c 0 on success, otherwise a negative error value
 501  * @retval #MEDIACODEC_ERROR_NONE Successful
 502  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 503  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 504  * @pre mediacodec_set_error_cb should be called before mediacodec_preare().
 505  * @post mediacodec_error_cb will be invoked.
 506  * @see mediacodec_set_error_cb()
 507  * @see mediacodec_unset_error_cb()
 508  */
 509 int mediacodec_set_error_cb(mediacodec_h mediacodec, mediacodec_error_cb callback, void* user_data);
 510
 511 /**
 512  * @brief unset error callback the media codec for process, asynchronously.
 513  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 514  * @param[in] mediacodec The handle to mediacodec
 515  * @return @c 0 on success, otherwise a negative error value
 516  * @retval #MEDIACODEC_ERROR_NONE Successful
 517  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 518  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 519  * @see mediacodec_set_error_cb()
 520  */
 521 int mediacodec_unset_error_cb(mediacodec_h mediacodec);
 522
 523 /**
 524  * @brief set eos callback the media codec for process, asynchronously.
 525  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 526  * @param[in] mediacodec The handle to mediacodec
 527  * @param[in] callback   The callback function to register
 528  * @param[in] user_data  The user data to be passed to the callback function
 529  * @return @c 0 on success, otherwise a negative error value
 530  * @retval #MEDIACODEC_ERROR_NONE Successful
 531  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 532  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 533  * @pre mediacodec_set_eos_cb should be called before mediacodec_preare().
 534  * @post mediacodec_eos_cb will be invoked.
 535  * @see mediacodec_set_eos_cb()
 536  * @see mediacodec_unset_eos_cb()
 537  */
 538 int mediacodec_set_eos_cb(mediacodec_h mediacodec, mediacodec_eos_cb callback, void* user_data);
 539
 540 /**
 541  * @brief unset eos callback the media codec for process, asynchronously.
 542  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 543  * @param[in] mediacodec The handle to mediacodec
 544  * @return @c 0 on success, otherwise a negative error value
 545  * @retval #MEDIACODEC_ERROR_NONE Successful
 546  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 547  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 548  * @see mediacodec_set_event_handler_cb()
 549  */
 550 int mediacodec_unset_eos_cb(mediacodec_h mediacodec);
 551
 552 /**
 553  * @brief Registers a callback function to be invoked when the mediacodec needs more data or has enough data.
 554  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 555  * @param[in] mediacodec The handle to mediacodec
 556  * @param[in] callback   The callback function to register
 557  * @param[in] user_data  The user data to be passed to the callback function
 558  * @return @c 0 on success, otherwise a negative error value
 559  * @retval #MEDIACODEC_ERROR_NONE Successful
 560  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 561  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 562  * @pre mediacodec_set_buffer_status_cb should be called before mediacodec_preare().
 563  * @post mediacodec_buffer_status_cb will be invoked.
 564  * @see mediacodec_set_buffer_status_cb()
 565  * @see mediacodec_unset_buffer_status_cb()
 566  */
 567 int mediacodec_set_buffer_status_cb(mediacodec_h mediacodec, mediacodec_buffer_status_cb callback, void* user_data);
 568
 569 /**
 570  * @brief Unregisters the callback function.
 571  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 572  * @param[in] mediacodec The handle to mediacodec
 573  * @return @c 0 on success, otherwise a negative error value
 574  * @retval #MEDIACODEC_ERROR_NONE Successful
 575  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 576  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 577  */
 578 int mediacodec_unset_buffer_status_cb(mediacodec_h mediacodec);
 579
 580 /**
 581  * @brief Retrieves all supported codecs by invoking callback function once for each supported codecs.
 582  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 583  * @param[in] mediacodec The handle to mediacodec
 584  * @param[in] callback   The callback function to invoke
 585  * @param[in] user_data  The user data to be passed to the callback function
 586  * @return @c 0 on success, otherwise a negative error value
 587  * @retval #MEDIACODEC_ERROR_NONE Successful
 588  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 589  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 590  * @see mediacodec_foreach_supported_codec()
 591  */
 592 int mediacodec_foreach_supported_codec(mediacodec_h mediacodec, mediacodec_supported_codec_cb callback, void *user_data);
 593
 594 /**
 595  * @brief Verifies whether encoding can be performed with codec_type or not.
 596  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 597  * @param[in]  mediacodec   The handle to mediacodec
 598  * @param[in]  codec_type   The identifier of the codec type of the encoder.
 599  * @param[in]  encoder      Whether the encoder or decoder : (@c true = encoder, @c false = decoder).
 600  * @param[out] support_type (@c MEDIACODEC_SUPPORT_TYPE_HW = mediacodec can be performed with hardware codec, @c MEDIACODEC_SUPPORT_TYPE_SW = mediacodec can be performed with software codec)
 601  * @return @c 0 on success, otherwise a negative error value
 602  * @retval #MEDIACODEC_ERROR_NONE Successful
 603  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 604  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 605  @code
 606  #include <media_codec.h>
 607  mediacodec_h mediacodec;
 608  mediacodec_support_type_e type;
 609  mediacodec_codec_type_e codec_type = MEDIACODEC_H264;
 610
 611  mediacodec_create(&mediacodec);
 612  mediacodec_get_supported_type(mediacodec, codec_type, 1, &type);
 613
 614  if(type == MEDIACODEC_SUPPORT_TYPE_HW)
 615      // only h/w supported
 616  else if (type == MEDIACODEC_SUPPORT_TYPE_SW)
 617      // only s/w supported
 618  else if (type == (MEDIACODEC_SUPPORT_TYPE_HW|MEDIACODEC_SUPPORT_TYPE_SW)
 619      // both supported
 620
 621  mediacodec_set_codec(mediacodec, codec_type, MEDIACODEC_ENCODER | MEDIACODEC_SUPPORT_TYPE_HW);
 622  @endcode
 623  */
 624 int mediacodec_get_supported_type(mediacodec_h mediacodec, mediacodec_codec_type_e codec_type, bool encoder, int *support_type);
 625
 626 /**
 627  * @brief Gets the media packet pool allocated for recycling media packets.
 628  * @details The user can get the pool allocated with the number of packets are required to be used in codecs.\n
 629  *          It is recommended to use media packet pool for better stability and performance.
 630  * @since_tizen 3.0
 631  * @remarks The @a pool should be released using media_packet_pool_deallocate() and destroyed using media_packet_pool_destroy().
 632  * @param[in]  mediacodec The mediacodec handle
 633  * @param[out] pool       The allocated pool handle
 634  * @return @c 0 on success, otherwise a negative error value
 635  * @retval #MEDIACODEC_ERROR_NONE Successful
 636  * @retval #MEDIACODEC_ERROR_INVALID_PARAMETER Invalid parameter
 637  * @retval #MEDIACODEC_ERROR_OUT_OF_MEMORY  Out of memory
 638  * @retval #MEDIACODEC_ERROR_INVALID_OPERATION The user calls mediacodec_get_packet_pool() before calling mediacodec_prepare().
 639  * @retval #MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE Not supported on device (Since 4.0)
 640  * @pre mediacodec_get_packet_pool() should be called after calling mediacodec_prepare().
 641  * @post If the pool is used, media_packet_pool_deallocate() and media_packet_pool_destroy() should be called.
 642  * @see media_packet_pool_acquire_packet()
 643  * @see media_packet_pool_release_packet()
 644  * @see media_packet_pool_deallocate()
 645  * @see media_packet_pool_destroy()
 646  */
 647 int mediacodec_get_packet_pool(mediacodec_h mediacodec, media_packet_pool_h *pool);
 648
 649 /**
 650  * @}
 651  */
 652
 653 #ifdef __cplusplus
 654 }
 655 #endif
 656
 657 #endif /* __TIZEN_MEDIA_CODEC_H__ */
 658