include/player_internal.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_PLAYER_INTERNAL_H__
  18 #define __TIZEN_MEDIA_PLAYER_INTERNAL_H__
  19 #include <player.h>
  20 #include <glib.h>
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * @file player_internal.h
  27  */
  28
  29 /**
  30  * @addtogroup CAPI_MEDIA_PLAYER_MODULE
  31  * @{
  32  */
  33 typedef enum {
  34         ELM_WAYLAND_WIN = 1,
  35         ECORE_WAYLAND_WIN
  36 } wl_window_type;
  37
  38 /**
  39  * @brief Enumeration for video codec type.
  40  * @since_tizen 4.0
  41  */
  42 typedef enum
  43 {
  44         PLAYER_VIDEO_CODEC_TYPE_DEFAULT = 0,  /**< This is an optional flag for using codec which has higher priority */
  45         PLAYER_VIDEO_CODEC_TYPE_HW,           /**< This is an optional flag for using the h/w codec */
  46         PLAYER_VIDEO_CODEC_TYPE_SW,           /**< This is an optional flag for using the s/w codec */
  47 } player_video_codec_type_e;
  48
  49 /**
  50  * @brief This file contains the media player API for custom features.
  51  * @since_tizen 2.4
  52  */
  53 typedef struct {
  54         void *data;          /**< PCM data */
  55         int size;            /**< Data Size */
  56         int channel;         /**< Channel */
  57         int rate;            /**<  Samplerate */
  58         int depth;           /**< Depth */
  59         bool little_endian;  /**< Endianness */
  60         unsigned long long channel_mask;        /**< channel_mask */
  61 } player_audio_raw_data_s;
  62
  63 /**
  64  * @brief Information about packet.
  65  * @since_tizen @if TV 3.0 @endif
  66  */
  67 typedef struct {
  68         guint32 len;
  69         guint64 pts;
  70         player_stream_type_e streamtype;
  71 } player_submit_packet_t;
  72
  73
  74 /**
  75  * @brief Video stream info in external demux case
  76  * @since_tizen @if TV 3.0 @endif
  77  */
  78 typedef struct _video_stream_info_s {
  79         const char *mime;
  80         unsigned int framerate_num;
  81         unsigned int framerate_den;
  82         int format3D;
  83         unsigned int width;
  84         unsigned int height;
  85         unsigned int pixelAspectRatioX;
  86         unsigned int pixelAspectRatioY;
  87         unsigned char *codec_extradata;
  88         unsigned int extradata_size;
  89         unsigned int version;
  90         unsigned int colordepth;
  91         unsigned int max_width;
  92         unsigned int max_height;
  93         unsigned int drm_type;
  94         unsigned int buffer_type;
  95 } player_video_stream_info_s;
  96
  97 /**
  98  * @brief Audio stream info in external demux case
  99  * @since_tizen @if TV 3.0 @endif
 100  */
 101 typedef struct _audio_stream_info_s {
 102         const char *mime;
 103         unsigned int channels;
 104         unsigned int sample_rate;
 105         unsigned int bit_rate;
 106         unsigned int block_align;
 107         unsigned char *codec_extradata;
 108         unsigned int extradata_size;
 109         unsigned int version;
 110         unsigned int user_info;
 111
 112         /* for pcm, eg. CODEC_ID_PCM_S16LE, width=16,depth=16,endianness=1234,signedness=true */
 113         unsigned int width;
 114         unsigned int depth;
 115         unsigned int endianness;        /* LE:1234, BE:4321 */
 116         bool signedness;                        /* S:true, U:false */
 117         unsigned int drm_type;
 118         unsigned int buffer_type;
 119 } player_audio_stream_info_s;
 120
 121
 122 /**
 123  * @brief Called when the audio frame is decoded.
 124  * @since_tizen 2.4
 125  * @param[in] audio_raw_frame The decoded audio frame data type
 126  * @param[in] user_data          The user data passed from the callback registration function
 127  * @see player_set_audio_frame_decoded_cb()
 128  * @see player_unset_audio_frame_decoded_cb()
 129  */
 130 typedef void (*player_audio_pcm_extraction_cb)(player_audio_raw_data_s *audio_raw_frame, void *user_data);
 131
 132 /**
 133  * @brief Called when the buffer level drops below the min size or exceeds the max size.
 134  * @since_tizen 3.0
 135  * @remarks This API is used for media stream playback only.
 136  * @param[in] status The buffer status
 137  * @param[in] bytes The current buffer level bytes
 138  * @param[in] user_data The user data passed from the callback registration function
 139  * @see player_set_media_stream_buffer_status_cb_ex()
 140  * @see player_set_media_stream_buffer_max_size()
 141  * @see player_set_media_stream_buffer_min_threshold()
 142  */
 143 typedef void (*player_media_stream_buffer_status_cb_ex) (player_media_stream_buffer_status_e status, unsigned long long bytes, void *user_data);
 144
 145 /**
 146  * @brief Registers a callback function to be invoked when audio frame is decoded. Audio only contents is possible. If included video, error happens.
 147  * @since_tizen 2.4
 148  * @param[in] player    The handle to the media player
 149  * @param[in] sync      Sync on the clock
 150  * @param[in] callback  The callback function to register
 151  * @param[in] user_data The user data to be passed to the callback function
 152  * @return @c 0 on success,
 153  *         otherwise a negative error value
 154  * @retval #PLAYER_ERROR_NONE Successful
 155  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 156  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 157  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 158  * @pre The player state must be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
 159  * @post player_audio_pcm_extraction_cb() will be invoked.
 160  */
 161 int player_set_pcm_extraction_mode(player_h player, bool sync, player_audio_pcm_extraction_cb callback, void *user_data);
 162
 163 /**
 164  * @brief Set pcm mode spec. Samplerate, channel is needed.
 165  * @since_tizen 2.4
 166  * @param[in] player     The handle to the media player
 167  * @param[in] format     Audio format
 168  * @param[in] samplerate Samplerate
 169  * @param[in] channel    Channel
 170  * @return @c 0 on success,
 171  *         otherwise a negative error value
 172  * @retval #PLAYER_ERROR_NONE Successful
 173  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 174  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 175  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 176  * @pre The player state must be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
 177  * @see player_set_pcm_extraction_mode()
 178  */
 179 int player_set_pcm_spec(player_h player, const char *format, int samplerate, int channel);
 180
 181 /**
 182  * @brief Sets the playback rate include streaming mode.
 183  * @since_tizen 3.0
 184  * @details The default value is @c 1.0.
 185  * @remarks No operation is performed, if @a rate is @c 0.
 186  * @remarks The sound is muted, when playback rate is under @c 0.0 and over @c 2.0.
 187  * @param[in]   player The handle to the media player
 188  * @param[in]   rate The playback rate
 189  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 190  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 191  * @pre The player state must be set to #PLAYER_STATE_READY by calling player_prepare() or set to #PLAYER_STATE_PLAYING by calling player_start() or set to #PLAYER_STATE_PAUSED by calling player_pause().
 192  */
 193 int player_set_streaming_playback_rate(player_h player, float rate);
 194
 195 /**
 196  * @brief Registers a callback function to be invoked when buffer underrun or overflow is occurred.
 197  * @since_tizen 3.0
 198  * @remarks This API is used for media stream playback only.
 199  * @remarks The registered callback is issued in the internal thread of the player.
 200  * @param[in] player   The handle to the media player
 201  * @param[in] type     The type of target stream
 202  * @param[in] callback The buffer status callback function to register
 203  * @param[in] user_data The user data to be passed to the callback function
 204  * @return @c 0 on success,
 205  *         otherwise a negative error value
 206  * @retval #PLAYER_ERROR_NONE Successful
 207  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 208  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 209  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
 210  * @post player_media_stream_buffer_status_cb_ex() will be invoked.
 211  * @see player_unset_media_stream_buffer_status_cb_ex()
 212  * @see player_media_stream_buffer_status_cb_ex()
 213  */
 214 int player_set_media_stream_buffer_status_cb_ex(player_h player, player_stream_type_e type, player_media_stream_buffer_status_cb_ex callback, void *user_data);
 215
 216 /**
 217  * @brief Unregisters the buffer status callback function.
 218  * @since_tizen 3.0
 219  * @remarks This API is used for media stream playback only.
 220  * @param[in] player The handle to the media player
 221  * @param[in] type   The type of target stream
 222  * @return @c 0 on success,
 223  *         otherwise a negative error value
 224  * @retval #PLAYER_ERROR_NONE Successful
 225  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 226  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 227  * @see player_set_media_stream_buffer_status_cb()
 228  */
 229 int player_unset_media_stream_buffer_status_cb_ex(player_h player, player_stream_type_e type);
 230
 231 /**
 232  * @brief Sets DRC(dynamic resolution change) information of media stream data.
 233  * @since_tizen 3.0
 234  * @remarks This API is used for media stream playback only.
 235  *          If the hw codec can not support drc, app have to set DRC information before calling player_prepare().
 236  * @param[in] player The handle to the media player
 237  * @param[in] drc The drc status: (@c true = drc, @c false = non drc)
 238  * @return @c 0 on success,
 239  *         otherwise a negative error value
 240  * @retval #PLAYER_ERROR_NONE Successful
 241  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 242  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 243  * @pre The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
 244  */
 245 int player_set_media_stream_dynamic_resolution(player_h player, bool drc);
 246
 247 /**
 248  * @brief Sets the ecore wayland video display.
 249  * @since_tizen 3.0
 250  * @remarks This API support PLAYER_DISPLAY_TYPE_OVERLAY type only.
 251  * @param[in]   player The handle to the media player
 252  * @param[in]   type The display type
 253  * @param[in]   ecore_wl_window The ecore wayland window handle
 254  * @param[in]   x the x coordinate of window
 255  * @param[in]   y the y coordinate of window
 256  * @param[in]   width the width of window
 257  * @param[in]   height the height of window
 258  * @return @c 0 on success,
 259  *         otherwise a negative error value
 260  * @retval #PLAYER_ERROR_NONE Successful
 261  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 262  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 263  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 264  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 265  * @see player_set_display_rotation
 266  */
 267 int player_set_ecore_wl_display(player_h player, player_display_type_e type, void *ecore_wl_window, int x, int y, int width, int height);
 268
 269 /**
 270  * @brief Called when no free space in buffer.
 271  * @since_tizen @if TV 3.0 @endif
 272  * @param[in] user_data    The user data passed from the callback registration function
 273  * @see player_set_buffer_enough_video_data_cb()
 274  * @see player_set_buffer_enough_audio_data_cb()
 275  */
 276 typedef void (*player_buffer_enough_data_cb) (void *user_data);
 277
 278 /**
 279  * @brief Called when the buffer level drops below the threshold.
 280  * @since_tizen @if TV 3.0 @endif
 281  * @param[in] size         Required data size
 282  * @param[in] user_data    The user data passed from the callback registration function
 283  * @see player_set_buffer_need_video_data_cb()
 284  * @see player_set_buffer_need_audio_data_cb()
 285  */
 286 typedef void (*player_buffer_need_data_cb) (unsigned int size, void *user_data);
 287
 288 /**
 289  * @brief Submits packet to appsrc, used in external demux mode
 290  * @since_tizen @if TV 3.0 @endif
 291  * @param[in]  player   The handle to media player
 292  * @param[in]  buf      the buf want to submit to appsrc, usually one buffer one frame
 293  * @param[in]  len      the size of buf
 294  * @param[in]  pts      pts of the submit buf(frame)
 295  * @param[in]  streamtype   true for video, false for audio
 296  * @return 0 on success, otherwise a negative error value.
 297  */
 298 int player_submit_packet(player_h player, guint8 *buf, guint32 len, guint64 pts, player_stream_type_e streamtype);
 299
 300 /**
 301  * @brief Sets video stream info, especially used in external demux mode
 302  * @since_tizen @if TV 3.0 @endif
 303  * @param[in]  player   The handle to media player
 304  * @param[in]  info     the info of video stream set by external demux
 305  * @return 0 on success, otherwise a negative error value.
 306  */
 307 int player_set_video_stream_info(player_h player, player_video_stream_info_s *info);
 308
 309 /**
 310  * @brief Sets audio stream info, especially used in external demux mode
 311  * @since_tizen @if TV 3.0 @endif
 312  * @param[in]  player   The handle to media player
 313  * @param[in]  info     the info of audio stream set by external demux
 314  * @return 0 on success, otherwise a negative error value.
 315  */
 316 int player_set_audio_stream_info(player_h player, player_audio_stream_info_s *info);
 317
 318 /**
 319  * @brief Registers the callback function.
 320  * @since_tizen @if TV 3.0 @endif
 321  * @remarks The registered callback is issued in the internal thread of the player.
 322  * @param[in] player The handle to media player
 323  * @param[in] callback  The callback function to register
 324  * @param[in] user_data The user data to be passed to the callback function
 325  * @return 0 on success, otherwise a negative error value.
 326  * @retval #PLAYER_ERROR_NONE Successful
 327  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 328  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 329  */
 330 int player_set_buffer_enough_video_data_cb(player_h player, player_buffer_enough_data_cb callback, void *user_data);
 331
 332 /**
 333  * @brief Registers the callback function.
 334  * @since_tizen @if TV 3.0 @endif
 335  * @remarks The registered callback is issued in the internal thread of the player.
 336  * @param[in] player The handle to media player
 337  * @param[in] callback  The callback function to register
 338  * @param[in] user_data The user data to be passed to the callback function
 339  * @return 0 on success, otherwise a negative error value.
 340  * @retval #PLAYER_ERROR_NONE Successful
 341  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 343  */
 344 int player_set_buffer_enough_audio_data_cb(player_h player, player_buffer_enough_data_cb callback, void *user_data);
 345
 346 /**
 347  * @brief Registers the callback function.
 348  * @since_tizen @if TV 3.0 @endif
 349  * @remarks The registered callback is issued in the internal thread of the player.
 350  * @param[in] player The handle to media player
 351  * @param[in] callback  The callback function to register
 352  * @param[in] user_data The user data to be passed to the callback function
 353  * @return 0 on success, otherwise a negative error value.
 354  * @retval #PLAYER_ERROR_NONE Successful
 355  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 356  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 357  */
 358 int player_set_buffer_need_video_data_cb(player_h player, player_buffer_need_data_cb callback, void *user_data);
 359
 360 /**
 361  * @brief Registers the callback function.
 362  * @since_tizen @if TV 3.0 @endif
 363  * @remarks The registered callback is issued in the internal thread of the player.
 364  * @param[in] player The handle to media player
 365  * @param[in] callback  The callback function to register
 366  * @param[in] user_data The user data to be passed to the callback function
 367  * @return 0 on success, otherwise a negative error value.
 368  * @retval #PLAYER_ERROR_NONE Successful
 369  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 370  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 371  */
 372 int player_set_buffer_need_audio_data_cb(player_h player, player_buffer_need_data_cb callback, void *user_data);
 373
 374 /**
 375  * @brief Display the first video frame at the player_prepare() function to improve the playback performance.
 376  * @since_tizen @if TV 3.0 @endif
 377  * @details This is only availble when you want to start playback from 0 position.
 378  *              1. Normal play : player_create() -> player_display_video_at_paused_state() -> player_prepare()[unmute] -> player_start()
 379  *                      2. Resume play : player_create() -> player_prepare() -> player_set_position() -> player_start()[unmute]
 380  * @param[in] player    The handle to media player
 381  * @param[in] visible   The visibility of the display (@c true = visible, @c false = non-visible )
 382  * @pre The player state must be : #PLAYER_STATE_IDLE
 383 */
 384 int player_display_video_at_paused_state(player_h player, bool visible);
 385
 386 /**
 387  * @brief Sets the win_ind to player
 388  * @since_tizen @if TV 3.0 @endif
 389  * @param[in] player    The handle to media player
 390  * @param[in] win_id    windows handle
 391  * @pre The player state must be : #PLAYER_STATE_IDLE
 392  */
 393 int player_set_display_parent_win_id(player_h player, int win_id);
 394
 395 /**
 396  * @brief Sets the data source (http or local file) to transite.
 397  * @since_tizen @if TV @else 3.0 @endif
 398  *
 399  * @details Player will transite the media source as seamlessly as possible after finishing current playback.
 400  *          If the function call is successful, the uri will be added at the end of uri list.
 401  *          You can add several uris and the set of uris will be played repeatedly if you call the player_set_looping().
 402  *          The first uri in the list is the original uri which is set by player_set_uri().
 403  *
 404  * @remarks Uri list will be cleared except first one when the player_unprepare() is called.
 405  *          If you call the player_set_uri(), you can change the first uri too.
 406  *
 407  * @param[in]   player The handle to the media player
 408  * @param[in]   uri Specifies the data location.
 409  *
 410  * @return @c 0 on success,
 411  *         otherwise a negative error value
 412  * @retval #PLAYER_ERROR_NONE Successful
 413  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 414  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 415  * @pre The original uri must be set first by player_set_uri().
 416  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 417  * @see player_set_uri(), player_set_looping()
 418  */
 419 int player_set_next_uri(player_h player, const char *uri);
 420
 421 /**
 422  * @brief Gets the data source path.
 423  * @since_tizen @if TV @else 3.0 @endif
 424  *
 425  * @param[in]   player The handle to the media player
 426  * @param[out]  uri Specifies the next data location.
 427  *
 428  * @return @c 0 on success,
 429  *         otherwise a negative error value
 430  * @retval #PLAYER_ERROR_NONE Successful
 431  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 432  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 433  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 434  * @see player_set_uri()
 435  */
 436 int player_get_next_uri(player_h player, char **uri);
 437
 438 /**
 439  * @brief Sets the gapless playback status
 440  * @since_tizen @if TV @else 3.0 @endif
 441  * @details If it is @c true, player will play next content without(or with minimized) gap.
 442  *          If it is @c false, it won't. The default value is @c false.
 443  * @param[in] player   The handle to the media player
 444  * @param[in] gapless  The new gapless status : (@c true = gapless, @c false = non-gapless )
 445  * @return @c 0 on success,
 446  *         otherwise a negative error value
 447  * @retval #PLAYER_ERROR_NONE Successful
 448  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 449  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
 450  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 451  * @see player_is_gapless()
 452  */
 453 int player_set_gapless(player_h player, bool gapless);
 454
 455 /**
 456  * @brief Gets the player's gapless status.
 457  * @since_tizen @if TV @else 3.0 @endif
 458  * @details If it is @c true, player will play next content without(or with minimized) gap.
 459  *          If it is @c false, it won't. The default value is @c false.
 460  * @param[in]   player The handle to the media player
 461  * @param[out]  gapless The gapless status: (@c true = gapless, @c false = non-gapless )
 462  * @return @c 0 on success,
 463  *         otherwise a negative error value
 464  * @retval #PLAYER_ERROR_NONE Successful
 465  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 466  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 467  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 468  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 469  * @see player_set_gapless()
 470  */
 471 int player_is_gapless(player_h player, bool *gapless);
 472
 473 /**
 474  * @brief Enables the tbm surface pool.
 475  * @since_tizen @if TV @else 3.0 @endif
 476  * @details If it is @c true, tbm surface will be enabled to share the video frame.
 477  *          If it is @c false, it won't. The default value is @c false.
 478  * @param[in] player  The handle to the media player
 479  * @param[in] enable  The new tbm surface status
 480  * @return @c 0 on success,
 481  *         otherwise a negative error value
 482  * @retval #PLAYER_ERROR_NONE Successful
 483  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 484  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
 485  * @pre The player state must be #PLAYER_STATE_IDLE.
 486  * @see player_is_enabled_tsurf_pool()
 487  */
 488 int player_enable_tsurf_pool(player_h player, bool enable);
 489
 490 /**
 491  * @brief Gets the player's tbm surface pool enable status.
 492  * @since_tizen @if TV @else 3.0 @endif
 493  * @details If it is @c true, tbm surface pool is enabled to share the video frame.
 494  *          If it is @c false, it won't. The default value is @c false.
 495  * @param[in]   player The handle to the media player
 496  * @param[out]  enabled The tbm surface enable status
 497  * @return @c 0 on success,
 498  *         otherwise a negative error value
 499  * @retval #PLAYER_ERROR_NONE Successful
 500  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 501  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 502  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 503  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 504  * @see player_enable_tsurf_pool()
 505  */
 506 int player_is_enabled_tsurf_pool(player_h player, bool *enabled);
 507
 508 /**
 509  * @brief Gets the size of video frame pool.
 510  * @since_tizen @if TV @else 3.0 @endif
 511  * @details App gets the video frame pool size which will be reused during playback.
 512  * @param[in] player The handle to the media player
 513  * @param[out] size The size of surface pool
 514  * @return @c 0 on success,
 515  *         otherwise a negative error value
 516  * @retval #PLAYER_ERROR_NONE Successful
 517  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 518  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 519  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 520  * @pre The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED
 521  * @see player_set_media_packet_video_frame_decoded_cb()
 522  */
 523 int player_get_media_packet_video_frame_pool_size(player_h player, int *size);
 524
 525  /**
 526  * @brief Enables media_packet callback
 527  * @since_tizen @if TV @else 3.0 @endif
 528  * @details If it is @c true, media_packet callback will be activated.
 529  *          If it is @c false, it will be deactivated. The default value is @c false.
 530  * @param[in] player   The handle to the media player
 531  * @param[in] enable   The active status : (@c true = send media_packet, @c false = render through overlay surface)
 532  * @return @c 0 on success,
 533  *         otherwise a negative error value
 534  * @retval #PLAYER_ERROR_NONE Successful
 535  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 536  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 537  * @pre display_type must be set to PLAYER_DISPLAY_TYPE_OVERLAY by player_set_display.
 538  * @pre player_media_packet_video_decoded_cb must be set.
 539  * @see player_set_display()
 540  * @see player_set_media_packet_video_frame_decoded_cb()
 541  */
 542 int player_enable_media_packet_video_frame_decoded_cb(player_h player, bool enable);
 543
 544 /**
 545  * @brief Enables/disables 360 video mode.
 546  * @since_tizen 4.0
 547  * @details If it is @c true, the content will be displayed with 360 video mode.
 548  *          If it is @c false, the content will be displayed with full panorama mode. The default value is @c true.
 549  * @param[in] player   The handle to the media player
 550  * @param[in] enable   The 360 video display status: @c true = display with 360 video mode,
 551                        @c false = display with full panorama mode
 552  * @return @c 0 on success,
 553  *                otherwise a negative error value
 554  * @retval #PLAYER_ERROR_NONE              Successful
 555  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 556  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 557  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 558  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 559  * @see player_360_is_enabled()
 560  */
 561 int player_360_set_enable(player_h player, bool enable);
 562
 563 /**
 564  * @brief Gets the 360 video display status.
 565  * @since_tizen 4.0
 566  * @param[in]   player    The handle to the media player
 567  * @param[out]  enabled   Pointer to store current 360 video display status:
 568  *                        (@c true = display with 360 video mode,
 569                           @c false = display with full panorama mode)
 570  * @return @c 0 on success,
 571  *         otherwise a negative error value
 572  * @retval #PLAYER_ERROR_NONE              Successful
 573  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 574  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 575  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 576  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 577  * @see player_360_set_enable()
 578  */
 579 int player_360_is_enabled(player_h player, bool *enabled);
 580
 581 /**
 582  * @brief Sets the 360 video direction of view.
 583  * @since_tizen 4.0
 584  * @details This function is to set horizontal (yaw) and vertical (pitch) angles
 585  *          of current direction of view in radians. Default direction of view
 586  *          is taken from meta-data stored in the media. If meta-data omits
 587  *          these values zeros are assumed that is equal to the centre of the
 588  *          panorama image.
 589  * @param[in] player   The handle to the media player
 590  * @param[in] yaw      The angle value around vertical axis. Valid values are in
 591  *                     range +/- PI.
 592  * @param[in] pitch    The angle value around lateral axis. Valid values are in
 593  *                     range +/- PI/2.
 594  * @return @c 0 on success,
 595  *         otherwise a negative error value
 596  * @retval #PLAYER_ERROR_NONE              Successful
 597  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 598  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 599  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 600  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 601  * @see player_360_get_direction_of_view()
 602  */
 603 int player_360_set_direction_of_view(player_h player, float yaw, float pitch);
 604
 605 /**
 606  * @brief Gets the 360 video direction of view.
 607  * @since_tizen 4.0
 608  * @details This function is to get horizontal (yaw) and vertical (pitch) angles
 609  *          of current direction of view in radians.
 610  * @param[in]  player   The handle to the media player
 611  * @param[out] yaw      Pointer to store current value of direction of view
 612  *                      angle around vertical axis
 613  * @param[out] pitch    Pointer to store current value of direction of view
 614  *                      angle around lateral axis
 615  * @return @c 0 on success,
 616  *         otherwise a negative error value
 617  * @retval #PLAYER_ERROR_NONE              Successful
 618  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 619  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 620  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 621  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 622  * @see player_360_set_direction_of_view()
 623  */
 624 int player_360_get_direction_of_view(player_h player, float *yaw, float *pitch);
 625
 626 /**
 627  * @brief Sets the zoom level of 360 video.
 628  * @since_tizen 4.0
 629  * @details  The zoom means scaling of the flat image cutted from the panorama.
 630  *           The valid range is from 1.0 to 10.0. Where 1.0 is actual image and
 631  *           values above are zoom-in factor. Default value is 1.0 - no zoom.
 632  * @param[in] player    The handle to the media player
 633  * @param[in] level     The zoom level
 634  * @return @c 0 on success,
 635  *         otherwise a negative error value
 636  * @retval #PLAYER_ERROR_NONE              Successful
 637  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 638  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 639  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 640  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 641  * @see player_360_get_zoom()
 642  */
 643 int player_360_set_zoom(player_h player, float level);
 644
 645 /**
 646  * @brief Gets the current zoom level of 360 video.
 647  * @since_tizen 4.0
 648  * @details  The zoom means scaling of the flat image cutted from the panorama.
 649  *           The valid range is from 1.0 to 10.0. Where 1.0 is actual image and
 650  *           values above are zoom-in factor. Default value is 1.0 - no zoom.
 651  * @param[in]  player    The handle to the media player
 652  * @param[out] level     Pointer to store current value of zoom level
 653  * @return @c 0 on success,
 654  *         otherwise a negative error value
 655  * @retval #PLAYER_ERROR_NONE              Successful
 656  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 657  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 658  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 659  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 660  * @see player_360_set_zoom()
 661  */
 662 int player_360_get_zoom(player_h player, float *level);
 663
 664 /**
 665  * @brief Sets the field of view information of 360 video.
 666  * @since_tizen 4.0
 667  * @details This function is to set the field of view to decide the output frame size.
 668  *          Note: values above the default ones extends field of view to significantly
 669  *          distorted areas and thus don't make real sense.
 670  * @param[in] player              The handle to the media player
 671  * @param[in] horizontal_degrees  The horizontal field of view to display in degrees.
 672  *                                Valid range is 1-360 degrees. Default value is 120 degrees.
 673  * @param[in] vertical_degrees    The vertical  field of view to display in degrees.
 674  *                                Valid range is 1-180 degrees. Default value is 67 degrees.
 675  * @return @c 0 on success,
 676  *         otherwise a negative error value
 677  * @retval #PLAYER_ERROR_NONE              Successful
 678  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 679  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 680  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 681  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 682  * @see player_360_get_field_of_view()
 683  */
 684 int player_360_set_field_of_view(player_h player, int horizontal_degrees, int vertical_degrees);
 685
 686 /**
 687  * @brief Gets the field of view information of 360 video.
 688  * @since_tizen 4.0
 689  * @details This function is to get the field of view information.
 690  * @param[in]  player              The handle to the media player
 691  * @param[out] horizontal_degrees  Pointer to store current value of horizontal
 692  *                                 field of view to display in degrees.
 693  * @param[out] vertical_degrees    Pointer to store current value of vertical
 694  *                                 field of view to display in degrees.
 695  * @return @c 0 on success,
 696  *         otherwise a negative error value
 697  * @retval #PLAYER_ERROR_NONE              Successful
 698  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 699  * @retval #PLAYER_ERROR_INVALID_OPERATION Not a spherical media
 700  * @retval #PLAYER_ERROR_INVALID_STATE     Player isn't prepared
 701  * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED.
 702  * @see player_360_set_field_of_view()
 703  */
 704 int player_360_get_field_of_view(player_h player, int *horizontal_degrees, int *vertical_degrees);
 705
 706 /**
 707  * @brief Set video codec type as h/w codec or s/w codec.
 708  * @since_tizen 4.0
 709  * @details The default video codec type of the player is #PLAYER_VIDEO_CODEC_TYPE_DEFAULT.
 710  *          Usually the H/W codec has higher priority than S/W codec if it exist.
 711  * @param[in] player The handle to the media player
 712  * @param[in] type   The video codec type
 713  * @return @c 0 on success,
 714  *         otherwise a negative error value
 715  * @retval #PLAYER_ERROR_NONE Successful
 716  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 717  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 718  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 719  * @pre The player state must be #PLAYER_STATE_IDLE by player_create() or player_unprepare().
 720  * @see player_get_video_codec_type()
 721  */
 722 int player_set_video_codec_type(player_h player, player_video_codec_type_e type);
 723
 724 /**
 725  * @brief Get video codec type.
 726  * @since_tizen 4.0
 727  * @param[in]  player The handle to the media player
 728  * @param[out] ptype  The video codec type
 729  * @return @c 0 on success,
 730  *         otherwise a negative error value
 731  * @retval #PLAYER_ERROR_NONE Successful
 732  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 733  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
 734  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
 735  * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
 736  * @see player_set_video_codec_type()
 737  */
 738 int player_get_video_codec_type(player_h player, player_video_codec_type_e *ptype);
 739
 740 /**
 741  * @}
 742  */
 743
 744 #ifdef __cplusplus
 745 }
 746 #endif
 747
 748 #endif /*__TIZEN_MEDIA_PLAYER_INTERNAL_H__*/