libvlc_media_player.h 88.4 KB
 Pierre committed May 25, 2009 1 2 3 /***************************************************************************** * libvlc_media_player.h: libvlc_media_player external API *****************************************************************************  4  * Copyright (C) 1998-2015 VLC authors and VideoLAN  Pierre committed May 25, 2009 5 6 7 8 9  * * Authors: Clément Stenac * Jean-Paul Saman * Pierre d'Herbemont *  Jean-Baptiste Kempf committed Nov 27, 2011 10 11 12  * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation; either version 2.1 of the License, or  Pierre committed May 25, 2009 13 14 15 16  * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of  Jean-Baptiste Kempf committed Nov 27, 2011 17 18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details.  Pierre committed May 25, 2009 19  *  Jean-Baptiste Kempf committed Nov 27, 2011 20 21 22  * You should have received a copy of the GNU Lesser General Public License * along with this program; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.  Pierre committed May 25, 2009 23 24 25 26 27  *****************************************************************************/ #ifndef VLC_LIBVLC_MEDIA_PLAYER_H #define VLC_LIBVLC_MEDIA_PLAYER_H 1  Rémi Duraffort committed Jan 21, 2010 28 29 # ifdef __cplusplus extern "C" {  Rémi Denis-Courmont committed May 10, 2011 30 31 # else # include  Rémi Duraffort committed Jan 21, 2010 32 33 # endif  Rémi Denis-Courmont committed Feb 20, 2010 34 /** \defgroup libvlc_media_player LibVLC media player  Pierre committed May 25, 2009 35  * \ingroup libvlc  Rémi Denis-Courmont committed Feb 20, 2010 36  * A LibVLC media player plays one media (usually in a custom drawable).  Pierre committed May 25, 2009 37  * @{  Rémi Denis-Courmont committed Jun 14, 2015 38 39  * \file * LibVLC simple media player external API  Pierre committed May 25, 2009 40 41 42 43  */ typedef struct libvlc_media_player_t libvlc_media_player_t;  44 /**  Felix Paul Kühne committed Jun 16, 2015 45  * Description for titles  46  */  Felix Paul Kühne committed Dec 21, 2015 47 48 49 50 51 52 enum { libvlc_title_menu = 0x01, libvlc_title_interactive = 0x02 };  53 54 typedef struct libvlc_title_description_t {  Felix Paul Kühne committed Jun 16, 2015 55 56  int64_t i_duration; /**< duration in milliseconds */ char *psz_name; /**< title name */  Felix Paul Kühne committed Dec 21, 2015 57  unsigned i_flags; /**< info if item was recognized as a menu, interactive or plain content by the demuxer */  58 59 } libvlc_title_description_t;  60 /**  Felix Paul Kühne committed Jun 16, 2015 61  * Description for chapters  62 63 64  */ typedef struct libvlc_chapter_description_t {  Felix Paul Kühne committed Jun 16, 2015 65 66 67  int64_t i_time_offset; /**< time-offset of the chapter in milliseconds */ int64_t i_duration; /**< duration of the chapter in milliseconds */ char *psz_name; /**< chapter name */  68 69 } libvlc_chapter_description_t;  Pierre committed May 25, 2009 70 71 72 73 74 75 76 77 78 /** * Description for audio output. It contains * name, description and pointer to next record. */ typedef struct libvlc_audio_output_t { char *psz_name; char *psz_description; struct libvlc_audio_output_t *p_next;  Pierre committed Jan 29, 2010 79   Pierre committed May 25, 2009 80 81 } libvlc_audio_output_t;  Rémi Denis-Courmont committed Aug 15, 2012 82 83 84 85 86 87 88 89 90 91 92 /** * Description for audio output device. */ typedef struct libvlc_audio_output_device_t { struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */ char *psz_device; /**< Device identifier string */ char *psz_description; /**< User-friendly device description */ /* More fields may be added here in later versions */ } libvlc_audio_output_device_t;  Cyril Mathé committed Jun 28, 2009 93 /**  JP Dinger committed Jan 29, 2010 94  * Marq options definition  Cyril Mathé committed Jun 28, 2009 95  */  JP Dinger committed Jan 29, 2010 96 typedef enum libvlc_video_marquee_option_t {  JP Dinger committed Jan 19, 2010 97  libvlc_marquee_Enable = 0,  Jean-Baptiste Kempf committed May 08, 2011 98  libvlc_marquee_Text, /** string argument */  Cyril Mathé committed Jun 28, 2009 99 100 101 102 103 104 105  libvlc_marquee_Color, libvlc_marquee_Opacity, libvlc_marquee_Position, libvlc_marquee_Refresh, libvlc_marquee_Size, libvlc_marquee_Timeout, libvlc_marquee_X,  Pierre committed Jul 05, 2009 106  libvlc_marquee_Y  JP Dinger committed Jan 29, 2010 107 } libvlc_video_marquee_option_t;  Pierre committed May 25, 2009 108   Arnaud Vallat committed Sep 11, 2010 109 110 111 112 113 114 115 116 117 /** * Navigation mode */ typedef enum libvlc_navigate_mode_t { libvlc_navigate_activate = 0, libvlc_navigate_up, libvlc_navigate_down, libvlc_navigate_left,  Petri Hintukainen committed Mar 30, 2016 118 119  libvlc_navigate_right, libvlc_navigate_popup  Arnaud Vallat committed Sep 11, 2010 120 121 } libvlc_navigate_mode_t;  Mark Lee committed Jul 06, 2013 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 /** * Enumeration of values used to set position (e.g. of video title). */ typedef enum libvlc_position_t { libvlc_position_disable=-1, libvlc_position_center, libvlc_position_left, libvlc_position_right, libvlc_position_top, libvlc_position_top_left, libvlc_position_top_right, libvlc_position_bottom, libvlc_position_bottom_left, libvlc_position_bottom_right } libvlc_position_t;  Thomas Guillem committed Mar 27, 2017 138 139 140 141 142 143 144 145 146 147 148 149 /** * Enumeration of teletext keys than can be passed via * libvlc_video_set_teletext() */ typedef enum libvlc_teletext_key_t { libvlc_teletext_key_red = 'r' << 16, libvlc_teletext_key_green = 'g' << 16, libvlc_teletext_key_yellow = 'y' << 16, libvlc_teletext_key_blue = 'b' << 16, libvlc_teletext_key_index = 'i' << 16, } libvlc_teletext_key_t;  Mark Lee committed Jul 24, 2013 150 151 152 153 154 155 156 /** * Opaque equalizer handle. * * Equalizer settings can be applied to a media player. */ typedef struct libvlc_equalizer_t libvlc_equalizer_t;  Pierre committed May 25, 2009 157 158 159 160 161 /** * Create an empty Media Player object * * \param p_libvlc_instance the libvlc instance in which the Media Player * should be created.  Rémi Denis-Courmont committed Jan 31, 2010 162  * \return a new media player object, or NULL on error.  Steve Lhomme committed May 27, 2019 163  * It must be released by libvlc_media_player_release().  Pierre committed May 25, 2009 164  */  Rémi Denis-Courmont committed May 07, 2011 165 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance );  Pierre committed May 25, 2009 166 167 168 169 170 171  /** * Create a Media Player object from a Media * * \param p_md the media. Afterwards the p_md can be safely * destroyed.  Rémi Denis-Courmont committed Jan 31, 2010 172  * \return a new media player object, or NULL on error.  Steve Lhomme committed May 27, 2019 173  * It must be released by libvlc_media_player_release().  Pierre committed May 25, 2009 174  */  Rémi Denis-Courmont committed May 07, 2011 175 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md );  Pierre committed May 25, 2009 176 177 178 179 180 181 182 183 184 185  /** * Release a media_player after use * Decrement the reference count of a media player object. If the * reference count is 0, then libvlc_media_player_release() will * release the media player object. If the media player object * has been released, then it should not be used again. * * \param p_mi the Media Player to free */  Rémi Denis-Courmont committed May 07, 2011 186 LIBVLC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 187 188 189 190 191 192 193  /** * Retain a reference to a media player object. Use * libvlc_media_player_release() to decrement reference count. * * \param p_mi media player object */  Rémi Denis-Courmont committed May 07, 2011 194 LIBVLC_API void libvlc_media_player_retain( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 195 196 197 198 199 200 201 202 203  /** * Set the media that will be used by the media_player. If any, * previous md will be released. * * \param p_mi the Media Player * \param p_md the Media. Afterwards the p_md can be safely * destroyed. */  Rémi Denis-Courmont committed May 07, 2011 204 LIBVLC_API void libvlc_media_player_set_media( libvlc_media_player_t *p_mi,  Rémi Duraffort committed Feb 11, 2010 205  libvlc_media_t *p_md );  Pierre committed May 25, 2009 206 207 208 209 210 211 212 213  /** * Get the media used by the media_player. * * \param p_mi the Media Player * \return the media associated with p_mi, or NULL if no * media is associated */  Rémi Denis-Courmont committed May 07, 2011 214 LIBVLC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 215 216 217 218 219 220 221  /** * Get the Event Manager from which the media player send event. * * \param p_mi the Media Player * \return the event manager associated with p_mi */  Rémi Denis-Courmont committed May 07, 2011 222 LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 223 224 225 226 227  /** * is_playing * * \param p_mi the Media Player  Rémi Denis-Courmont committed May 19, 2019 228 229  * \retval true media player is playing * \retval false media player is not playing  Pierre committed May 25, 2009 230  */  Rémi Denis-Courmont committed May 19, 2019 231 LIBVLC_API bool libvlc_media_player_is_playing(libvlc_media_player_t *p_mi);  Pierre committed May 25, 2009 232 233 234 235 236  /** * Play * * \param p_mi the Media Player  Rémi Denis-Courmont committed Jan 31, 2010 237  * \return 0 if playback started (and was already started), or -1 on error.  Pierre committed May 25, 2009 238  */  Rémi Denis-Courmont committed May 07, 2011 239 LIBVLC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 240   Rémi Denis-Courmont committed Jun 27, 2010 241 242 243 244 245 /** * Pause or resume (no effect if there is no media) * * \param mp the Media Player * \param do_pause play/resume if zero, pause if non-zero  Rémi Denis-Courmont committed Jun 27, 2010 246  * \version LibVLC 1.1.1 or later  Rémi Denis-Courmont committed Jun 27, 2010 247  */  Rémi Denis-Courmont committed May 07, 2011 248 LIBVLC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp,  Rémi Denis-Courmont committed Jun 27, 2010 249 250  int do_pause );  Pierre committed May 25, 2009 251 /**  Rémi Denis-Courmont committed Jan 31, 2010 252  * Toggle pause (no effect if there is no media)  Pierre committed May 25, 2009 253 254 255  * * \param p_mi the Media Player */  Rémi Denis-Courmont committed May 07, 2011 256 LIBVLC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 257 258  /**  Thomas Guillem committed Nov 07, 2019 259 260 261 262 263  * Stop asynchronously * * \note This function is asynchronous. In case of success, the user should * wait for the libvlc_MediaPlayerStopped event to know when the stop is * finished.  Pierre committed May 25, 2009 264 265  * * \param p_mi the Media Player  Thomas Guillem committed Nov 07, 2019 266 267  * \return 0 if the player is being stopped, -1 otherwise (no-op) * \version LibVLC 4.0.0 or later  Pierre committed May 25, 2009 268  */  Thomas Guillem committed Nov 07, 2019 269 LIBVLC_API int libvlc_media_player_stop_async ( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 270   Thomas Guillem committed Sep 20, 2016 271 272 273 274 275 276 277 278 279 280 281 282 283 284 /** * Set a renderer to the media player * * \note must be called before the first call of libvlc_media_player_play() to * take effect. * * \see libvlc_renderer_discoverer_new * * \param p_mi the Media Player * \param p_item an item discovered by libvlc_renderer_discoverer_start() * \return 0 on success, -1 on error. * \version LibVLC 3.0.0 or later */ LIBVLC_API int libvlc_media_player_set_renderer( libvlc_media_player_t *p_mi,  Thomas Guillem committed Dec 01, 2017 285  libvlc_renderer_item_t *p_item );  Thomas Guillem committed Sep 20, 2016 286   Steve Lhomme committed May 11, 2019 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 /** * Enumeration of the Video color primaries. */ typedef enum libvlc_video_color_primaries_t { libvlc_video_primaries_BT601_525 = 1, libvlc_video_primaries_BT601_625 = 2, libvlc_video_primaries_BT709 = 3, libvlc_video_primaries_BT2020 = 4, libvlc_video_primaries_DCI_P3 = 5, libvlc_video_primaries_BT470_M = 6, } libvlc_video_color_primaries_t; /** * Enumeration of the Video color spaces. */ typedef enum libvlc_video_color_space_t { libvlc_video_colorspace_BT601 = 1, libvlc_video_colorspace_BT709 = 2, libvlc_video_colorspace_BT2020 = 3, } libvlc_video_color_space_t; /** * Enumeration of the Video transfer functions. */ typedef enum libvlc_video_transfer_func_t { libvlc_video_transfer_func_LINEAR = 1, libvlc_video_transfer_func_SRGB = 2, libvlc_video_transfer_func_BT470_BG = 3, libvlc_video_transfer_func_BT470_M = 4, libvlc_video_transfer_func_BT709 = 5, libvlc_video_transfer_func_PQ = 6, libvlc_video_transfer_func_SMPTE_240 = 7, libvlc_video_transfer_func_HLG = 8, } libvlc_video_transfer_func_t;  Rémi Denis-Courmont committed Jul 10, 2010 323 /**  Rémi Denis-Courmont committed Nov 20, 2010 324  * Callback prototype to allocate and lock a picture buffer.  Rémi Denis-Courmont committed Jul 10, 2010 325 326 327 328 329 330  * * Whenever a new video frame needs to be decoded, the lock callback is * invoked. Depending on the video chroma, one or three pixel planes of * adequate dimensions must be returned via the second parameter. Those * planes must be aligned on 32-bytes boundaries. *  Rémi Denis-Courmont committed Nov 20, 2010 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345  * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN] * \param planes start address of the pixel planes (LibVLC allocates the array * of void pointers, this callback must initialize the array) [OUT] * \return a private pointer for the display and unlock callbacks to identify * the picture buffers */ typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes); /** * Callback prototype to unlock a picture buffer. * * When the video frame decoding is complete, the unlock callback is invoked. * This callback might not be needed at all. It is only an indication that the * application can now read the pixel values if it needs to. *  Rémi Denis-Courmont committed Sep 15, 2016 346  * \note A picture buffer is unlocked after the picture is decoded,  Rémi Denis-Courmont committed Nov 20, 2010 347 348 349  * but before the picture is displayed. * * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]  Rémi Denis-Courmont committed Nov 20, 2010 350  * \param picture private pointer returned from the @ref libvlc_video_lock_cb  Rémi Denis-Courmont committed Nov 20, 2010 351  * callback [IN]  Rémi Denis-Courmont committed Nov 20, 2010 352 353  * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb * callback (this parameter is only for convenience) [IN]  Rémi Denis-Courmont committed Nov 20, 2010 354 355 356 357 358 359  */ typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture, void *const *planes); /** * Callback prototype to display a picture.  Rémi Denis-Courmont committed Jul 10, 2010 360 361  * * When the video frame needs to be shown, as determined by the media playback  Rémi Denis-Courmont committed Nov 20, 2010 362 363 364  * clock, the display callback is invoked. * * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]  Rémi Denis-Courmont committed Nov 20, 2010 365  * \param picture private pointer returned from the @ref libvlc_video_lock_cb  Rémi Denis-Courmont committed Nov 20, 2010 366 367 368 369  * callback [IN] */ typedef void (*libvlc_video_display_cb)(void *opaque, void *picture);  Rémi Denis-Courmont committed Nov 21, 2010 370 371 372 373 374 375 376 377 378 379 /** * Callback prototype to configure picture buffers format. * This callback gets the format of the video as output by the video decoder * and the chain of video filters (if any). It can opt to change any parameter * as it needs. In that case, LibVLC will attempt to convert the video format * (rescaling and chroma conversion) but these operations can be CPU intensive. * * \param opaque pointer to the private pointer passed to * libvlc_video_set_callbacks() [IN/OUT] * \param chroma pointer to the 4 bytes video format identifier [IN/OUT]  Sergey Radionov committed Apr 30, 2019 380 381  * \param width pointer to the buffer width in pixels[IN/OUT] * \param height pointer to the buffer height in pixels[IN/OUT]  Rémi Denis-Courmont committed Nov 21, 2010 382 383 384 385 386  * \param pitches table of scanline pitches in bytes for each pixel plane * (the table is allocated by LibVLC) [OUT] * \param lines table of scanlines count for each plane [OUT] * \return the number of picture buffers allocated, 0 indicates failure *  Sergey Radionov committed Apr 30, 2019 387 388 389 390  * \version LibVLC 4.0.0 and later. * \param (width+1) - pointer to display width in pixels[IN] * \param (height+1) - pointer to display height in pixels[IN] *  Rémi Denis-Courmont committed Nov 21, 2010 391 392 393 394 395 396  * \note * For each pixels plane, the scanline pitch must be bigger than or equal to * the number of bytes per pixel multiplied by the pixel width. * Similarly, the number of scanlines must be bigger than of equal to * the pixel height. * Furthermore, we recommend that pitches and lines be multiple of 32  Rémi Denis-Courmont committed Sep 17, 2014 397  * to not break assumptions that might be held by optimized code  Rémi Denis-Courmont committed Nov 21, 2010 398 399 400 401 402 403 404 405 406 407  * in the video decoders, video filters and/or video converters. */ typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma, unsigned *width, unsigned *height, unsigned *pitches, unsigned *lines); /** * Callback prototype to configure picture buffers format. *  Steve Lhomme committed Feb 10, 2020 408  * \param opaque private pointer as passed to libvlc_video_set_format_callbacks()  Rémi Denis-Courmont committed Nov 21, 2010 409 410 411 412 413  * (and possibly modified by @ref libvlc_video_format_cb) [IN] */ typedef void (*libvlc_video_cleanup_cb)(void *opaque);  Rémi Denis-Courmont committed Nov 20, 2010 414 415 /** * Set callbacks and private data to render decoded video to a custom area  Rémi Denis-Courmont committed Nov 21, 2010 416 417 418  * in memory. * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks() * to configure the decoded format.  Rémi Denis-Courmont committed Jul 10, 2010 419  *  Rémi Denis-Courmont committed Sep 15, 2016 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443  * \warning Rendering video into custom memory buffers is considerably less * efficient than rendering in a custom window as normal. * * For optimal perfomances, VLC media player renders into a custom window, and * does not use this function and associated callbacks. It is highly * recommended that other LibVLC-based application do likewise. * To embed video in a window, use libvlc_media_player_set_xid() or equivalent * depending on the operating system. * * If window embedding does not fit the application use case, then a custom * LibVLC video output display plugin is required to maintain optimal video * rendering performances. * * The following limitations affect performance: * - Hardware video decoding acceleration will either be disabled completely, * or require (relatively slow) copy from video/DSP memory to main memory. * - Sub-pictures (subtitles, on-screen display, etc.) must be blent into the * main picture by the CPU instead of the GPU. * - Depending on the video format, pixel format conversion, picture scaling, * cropping and/or picture re-orientation, must be performed by the CPU * instead of the GPU. * - Memory copying is required between LibVLC reference picture buffers and * application buffers (between lock and unlock callbacks). *  Rémi Denis-Courmont committed Jul 10, 2010 444  * \param mp the media player  Rémi Denis-Courmont committed Nov 20, 2010 445 446 447  * \param lock callback to lock video memory (must not be NULL) * \param unlock callback to unlock video memory (or NULL if not needed) * \param display callback to display video (or NULL if not needed)  Rémi Denis-Courmont committed Jul 10, 2010 448 449 450  * \param opaque private pointer for the three callbacks (as first parameter) * \version LibVLC 1.1.1 or later */  Rémi Denis-Courmont committed May 07, 2011 451 LIBVLC_API  Rémi Denis-Courmont committed Jul 10, 2010 452 void libvlc_video_set_callbacks( libvlc_media_player_t *mp,  Rémi Denis-Courmont committed Nov 20, 2010 453 454 455 456  libvlc_video_lock_cb lock, libvlc_video_unlock_cb unlock, libvlc_video_display_cb display, void *opaque );  Rémi Denis-Courmont committed Jul 10, 2010 457   Steve Lhomme committed Jan 28, 2019 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 /** * Set decoded video chroma and dimensions. * This only works in combination with libvlc_video_set_callbacks(), * and is mutually exclusive with libvlc_video_set_format_callbacks(). * * \param mp the media player * \param chroma a four-characters string identifying the chroma * (e.g. "RV32" or "YUYV") * \param width pixel width * \param height pixel height * \param pitch line pitch (in bytes) * \version LibVLC 1.1.1 or later * \bug All pixel planes are expected to have the same pitch. * To use the YCbCr color space with chrominance subsampling, * consider using libvlc_video_set_format_callbacks() instead. */ LIBVLC_API void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma, unsigned width, unsigned height, unsigned pitch ); /** * Set decoded video chroma and dimensions. This only works in combination with * libvlc_video_set_callbacks(). * * \param mp the media player * \param setup callback to select the video format (cannot be NULL) * \param cleanup callback to release any allocated resources (or NULL) * \version LibVLC 2.0.0 or later */ LIBVLC_API void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp, libvlc_video_format_cb setup, libvlc_video_cleanup_cb cleanup );  Pierre Lamot committed Aug 21, 2018 493   Steve Lhomme committed Feb 10, 2020 494 495 496 497 498 499 500 501 typedef struct { bool hardware_decoding; /** set if D3D11_CREATE_DEVICE_VIDEO_SUPPORT is needed for D3D11 */ } libvlc_video_setup_device_cfg_t; typedef struct { union {  Steve Lhomme committed Feb 12, 2020 502 503 504 505 506 507 508  struct { void *device_context; /** ID3D11DeviceContext* */ } d3d11; struct { void *device; /** IDirect3D9* */ int adapter; /** Adapter to use with the IDirect3D9* */ } d3d9;  Steve Lhomme committed Feb 10, 2020 509 510 511  }; } libvlc_video_setup_device_info_t;  Pierre Lamot committed Aug 21, 2018 512 513 /** * Callback prototype called to initialize user data.  Steve Lhomme committed Feb 10, 2020 514  * Setup the rendering environment.  Pierre Lamot committed Aug 21, 2018 515  *  Steve Lhomme committed Feb 10, 2020 516 517  * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() * on input. The callback can change this value on output to be  518 519  * passed to all the other callbacks set on @a libvlc_video_set_output_callbacks(). * [IN/OUT]  Steve Lhomme committed Feb 10, 2020 520 521  * \param cfg requested configuration of the video device [IN] * \param out libvlc_video_setup_device_info_t* to fill [OUT]  Pierre Lamot committed Aug 21, 2018 522 523  * \return true on success * \version LibVLC 4.0.0 or later  Steve Lhomme committed Feb 10, 2020 524  *  Steve Lhomme committed Feb 14, 2020 525  * For \ref libvlc_video_engine_d3d9 the output must be a IDirect3D9*.  Steve Lhomme committed Feb 10, 2020 526 527 528  * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called. * the device must be created with D3DPRESENT_PARAMETERS.hDeviceWindow set to 0. *  Steve Lhomme committed Feb 14, 2020 529  * For \ref libvlc_video_engine_d3d11 the output must be a ID3D11DeviceContext*.  Steve Lhomme committed Feb 10, 2020 530 531  * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called. * The ID3D11Device used to create ID3D11DeviceContext must have multithreading enabled.  Pierre Lamot committed Aug 21, 2018 532  */  Steve Lhomme committed Feb 10, 2020 533 typedef bool (*libvlc_video_output_setup_cb)(void **opaque,  Steve Lhomme committed Feb 10, 2020 534 535  const libvlc_video_setup_device_cfg_t *cfg, libvlc_video_setup_device_info_t *out);  Pierre Lamot committed Aug 21, 2018 536 537 538 539 540  /** * Callback prototype called to release user data *  Steve Lhomme committed Feb 10, 2020 541  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]  Pierre Lamot committed Aug 21, 2018 542 543  * \version LibVLC 4.0.0 or later */  Steve Lhomme committed Feb 10, 2020 544 typedef void (*libvlc_video_output_cleanup_cb)(void* opaque);  Pierre Lamot committed Aug 21, 2018 545   Steve Lhomme committed Feb 10, 2020 546 547 548 549 typedef struct { unsigned width; /** rendering video width in pixel */ unsigned height; /** rendering video height in pixel */  Steve Lhomme committed Feb 10, 2020 550 551 552 553 554 555  unsigned bitdepth; /** rendering video bit depth in bits per channel */ bool full_range; /** video is full range or studio/limited range */ libvlc_video_color_space_t colorspace; /** video color space */ libvlc_video_color_primaries_t primaries; /** video color primaries */ libvlc_video_transfer_func_t transfer; /** video transfer function */ void *device; /** device used for rendering, IDirect3DDevice9* for D3D9 */  Steve Lhomme committed Feb 10, 2020 556 557 } libvlc_video_render_cfg_t;  Steve Lhomme committed Feb 10, 2020 558 559 typedef struct {  Steve Lhomme committed Feb 10, 2020 560  union {  Steve Lhomme committed Feb 14, 2020 561  int dxgi_format; /** the rendering DXGI_FORMAT for \ref libvlc_video_engine_d3d11*/  Steve Lhomme committed Feb 14, 2020 562  uint32_t d3d9_format; /** the rendering D3DFORMAT for \ref libvlc_video_engine_d3d9 */  Steve Lhomme committed Feb 10, 2020 563  int opengl_format; /** the rendering GLint GL_RGBA or GL_RGB for \ref libvlc_video_engine_opengl and  Steve Lhomme committed Feb 10, 2020 564 565 566  for \ref libvlc_video_engine_gles2 */ void *p_surface; /** currently unused */ };  Steve Lhomme committed Feb 10, 2020 567 568 569 570 571 572  bool full_range; /** video is full range or studio/limited range */ libvlc_video_color_space_t colorspace; /** video color space */ libvlc_video_color_primaries_t primaries; /** video color primaries */ libvlc_video_transfer_func_t transfer; /** video transfer function */ } libvlc_video_output_cfg_t;  Pierre Lamot committed Aug 21, 2018 573 /**  Steve Lhomme committed Feb 10, 2020 574 575  * Callback prototype called on video size changes. * Update the rendering output setup.  Pierre Lamot committed Aug 21, 2018 576  *  Steve Lhomme committed Feb 10, 2020 577  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]  Steve Lhomme committed Feb 10, 2020 578  * \param cfg configuration of the video that will be rendered [IN]  Steve Lhomme committed Feb 10, 2020 579  * \param output configuration describing with how the rendering is setup [OUT]  Pierre Lamot committed Aug 21, 2018 580  * \version LibVLC 4.0.0 or later  Steve Lhomme committed Feb 10, 2020 581 582 583 584 585 586 587 588  * * \note the configuration device for Direct3D9 is the IDirect3DDevice9 that VLC * uses to render. The host must set a Render target and call Present() * when it needs the drawing from VLC to be done. This object is not valid * anymore after Cleanup is called. * * Tone mapping, range and color conversion will be done depending on the values * set in the output structure.  Pierre Lamot committed Aug 21, 2018 589  */  Steve Lhomme committed Feb 10, 2020 590 typedef bool (*libvlc_video_update_output_cb)(void* opaque, const libvlc_video_render_cfg_t *cfg,  Steve Lhomme committed Feb 10, 2020 591  libvlc_video_output_cfg_t *output );  Pierre Lamot committed Aug 21, 2018 592 593 594 595 596  /** * Callback prototype called after performing drawing calls. *  Steve Lhomme committed Aug 27, 2020 597 598 599  * This callback is called outside of libvlc_video_makeCurrent_cb current/not-current * calls. *  Steve Lhomme committed Feb 10, 2020 600  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]  Pierre Lamot committed Aug 21, 2018 601 602  * \version LibVLC 4.0.0 or later */  Steve Lhomme committed Jan 16, 2019 603 typedef void (*libvlc_video_swap_cb)(void* opaque);  Pierre Lamot committed Aug 21, 2018 604 605  /**  Steve Lhomme committed Feb 10, 2020 606 607  * Callback prototype to set up the OpenGL context for rendering. * Tell the host the rendering is about to start/has finished.  Pierre Lamot committed Aug 21, 2018 608  *  Steve Lhomme committed Feb 10, 2020 609  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]  Pierre Lamot committed Aug 21, 2018 610 611 612  * \param enter true to set the context as current, false to unset it [IN] * \return true on success * \version LibVLC 4.0.0 or later  Steve Lhomme committed Feb 10, 2020 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627  * * On Direct3D11 the following may change on the provided ID3D11DeviceContext* * between \ref enter being true and \ref enter being false: * - IASetPrimitiveTopology() * - IASetInputLayout() * - IASetVertexBuffers() * - IASetIndexBuffer() * - VSSetConstantBuffers() * - VSSetShader() * - PSSetSamplers() * - PSSetConstantBuffers() * - PSSetShaderResources() * - PSSetShader() * - RSSetViewports() * - DrawIndexed()  Pierre Lamot committed Aug 21, 2018 628  */  Steve Lhomme committed Jan 16, 2019 629 typedef bool (*libvlc_video_makeCurrent_cb)(void* opaque, bool enter);  Pierre Lamot committed Aug 21, 2018 630 631 632 633  /** * Callback prototype to load opengl functions *  Steve Lhomme committed Feb 10, 2020 634  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]  Pierre Lamot committed Aug 21, 2018 635 636 637 638  * \param fct_name name of the opengl function to load * \return a pointer to the named OpenGL function the NULL otherwise * \version LibVLC 4.0.0 or later */  Steve Lhomme committed Jan 16, 2019 639 typedef void* (*libvlc_video_getProcAddress_cb)(void* opaque, const char* fct_name);  Pierre Lamot committed Aug 21, 2018 640   Steve Lhomme committed Feb 10, 2020 641 642 643 644 645 646 647 648 649 650 651 typedef struct { /* similar to SMPTE ST 2086 mastering display color volume */ uint16_t RedPrimary[2]; uint16_t GreenPrimary[2]; uint16_t BluePrimary[2]; uint16_t WhitePoint[2]; unsigned int MaxMasteringLuminance; unsigned int MinMasteringLuminance; uint16_t MaxContentLightLevel; uint16_t MaxFrameAverageLightLevel;  Steve Lhomme committed Feb 10, 2020 652 } libvlc_video_frame_hdr10_metadata_t;  Steve Lhomme committed Feb 10, 2020 653 654  typedef enum libvlc_video_metadata_type_t {  Steve Lhomme committed Feb 10, 2020 655  libvlc_video_metadata_frame_hdr10, /**< libvlc_video_frame_hdr10_metadata_t */  Steve Lhomme committed Feb 10, 2020 656 657 658 659 660 661 662 663 664 665 666 667 } libvlc_video_metadata_type_t; /** * Callback prototype to receive metadata before rendering. * * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN] * \param type type of data passed in metadata [IN] * \param metadata the type of metadata [IN] * \version LibVLC 4.0.0 or later */ typedef void (*libvlc_video_frameMetadata_cb)(void* opaque, libvlc_video_metadata_type_t type, const void *metadata);  Pierre Lamot committed Aug 21, 2018 668 /**  669 670  * Enumeration of the Video engine to be used on output. * can be passed to @a libvlc_video_set_output_callbacks  Pierre Lamot committed Aug 21, 2018 671  */  672 typedef enum libvlc_video_engine_t {  Steve Lhomme committed Mar 13, 2020 673 674  /** Disable rendering engine */ libvlc_video_engine_disable,  675 676  libvlc_video_engine_opengl, libvlc_video_engine_gles2,  677  /** Direct3D11 rendering engine */  Steve Lhomme committed Feb 14, 2020 678  libvlc_video_engine_d3d11,  679  /** Direct3D9 rendering engine */  Steve Lhomme committed Feb 14, 2020 680  libvlc_video_engine_d3d9,  681 } libvlc_video_engine_t;  Pierre Lamot committed Aug 21, 2018 682   Steve Lhomme committed Feb 10, 2020 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 /** Set the callback to call when the host app resizes the rendering area. * * This allows text rendering and aspect ratio to be handled properly when the host * rendering size changes. * * It may be called before the \ref libvlc_video_output_setup_cb callback. * * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN] * \param report_size_change callback which must be called when the host size changes. [IN] * The callback is valid until another call to \ref libvlc_video_output_set_resize_cb * is done. This may be called from any thread. * \param report_opaque private pointer to pass to the \ref report_size_change callback. [IN] */ typedef void( *libvlc_video_output_set_resize_cb )( void *opaque, void (*report_size_change)(void *report_opaque, unsigned width, unsigned height), void *report_opaque );  Steve Lhomme committed Feb 10, 2020 700 701 702 703 704 705 706 /** Tell the host the rendering for the given plane is about to start * * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN] * \param plane number of the rendering plane to select * \return true on success * \version LibVLC 4.0.0 or later *  Steve Lhomme committed Feb 14, 2020 707  * \note This is only used with \ref libvlc_video_engine_d3d11.  Steve Lhomme committed Feb 10, 2020 708 709  * * The host should call OMSetRenderTargets for Direct3D11. If this callback is  710  * not used (set to NULL in @a libvlc_video_set_output_callbacks()) OMSetRenderTargets  Steve Lhomme committed Feb 10, 2020 711 712 713 714 715 716  * has to be set during the @a libvlc_video_makeCurrent_cb() * entering call. * * The number of planes depend on the DXGI_FORMAT returned during the * \ref LIBVLC_VIDEO_UPDATE_OUTPUT call. It's usually one plane except for * semi-planar formats like DXGI_FORMAT_NV12 or DXGI_FORMAT_P010.  Steve Lhomme committed Aug 27, 2020 717 718 719  * * This callback is called between libvlc_video_makeCurrent_cb current/not-current * calls.  Steve Lhomme committed Feb 10, 2020 720 721 722  */ typedef bool( *libvlc_video_output_select_plane_cb )( void *opaque, size_t plane );  Pierre Lamot committed Aug 21, 2018 723 /**  724  * Set callbacks and data to render decoded video to a custom texture  Pierre Lamot committed Aug 21, 2018 725 726 727 728 729  * * \warning VLC will perform video rendering in its own thread and at its own rate, * You need to provide your own synchronisation mechanism. * * \param mp the media player  730  * \param engine the GPU engine to use  Pierre Lamot committed Aug 21, 2018 731 732  * \param setup_cb callback called to initialize user data * \param cleanup_cb callback called to clean up user data  Steve Lhomme committed Feb 10, 2020 733  * \param resize_cb callback to set the resize callback  Steve Lhomme committed Feb 10, 2020 734  * \param update_output_cb callback to get the rendering format of the host (cannot be NULL)  Pierre Lamot committed Aug 21, 2018 735  * \param swap_cb callback called after rendering a video frame (cannot be NULL)  Steve Lhomme committed Feb 12, 2020 736  * \param makeCurrent_cb callback called to enter/leave the rendering context (cannot be NULL)  Steve Lhomme committed Jan 18, 2019 737  * \param getProcAddress_cb opengl function loading callback (cannot be NULL for \ref libvlc_video_engine_opengl and for \ref libvlc_video_engine_gles2)  Steve Lhomme committed Feb 10, 2020 738 739  * \param metadata_cb callback to provide frame metadata (D3D11 only) * \param select_plane_cb callback to select different D3D11 rendering targets  Pierre Lamot committed Aug 21, 2018 740  * \param opaque private pointer passed to callbacks  Rémi Denis-Courmont committed May 19, 2019 741 742 743  * * \retval true engine selected and callbacks set * \retval false engine type unknown, callbacks not set  Pierre Lamot committed Aug 21, 2018 744 745 746  * \version LibVLC 4.0.0 or later */ LIBVLC_API  Rémi Denis-Courmont committed May 19, 2019 747 bool libvlc_video_set_output_callbacks( libvlc_media_player_t *mp,  748  libvlc_video_engine_t engine,  Steve Lhomme committed Feb 10, 2020 749  libvlc_video_output_setup_cb setup_cb,  Steve Lhomme committed Feb 10, 2020 750  libvlc_video_output_cleanup_cb cleanup_cb,  Steve Lhomme committed Feb 10, 2020 751  libvlc_video_output_set_resize_cb resize_cb,  Steve Lhomme committed Jan 16, 2019 752 753 754 755  libvlc_video_update_output_cb update_output_cb, libvlc_video_swap_cb swap_cb, libvlc_video_makeCurrent_cb makeCurrent_cb, libvlc_video_getProcAddress_cb getProcAddress_cb,  Steve Lhomme committed Feb 10, 2020 756 757  libvlc_video_frameMetadata_cb metadata_cb, libvlc_video_output_select_plane_cb select_plane_cb,  Pierre Lamot committed Aug 21, 2018 758 759  void* opaque );  Pierre committed May 25, 2009 760 /**  Olivier Aubert committed Dec 21, 2009 761 762  * Set the NSView handler where the media player should render its video output. *  763 764  * Use the vout called "macosx". *  Marvin Scholz committed Feb 25, 2019 765  * The drawable is an NSObject that follow the VLCVideoViewEmbedding  766  * protocol:  Pierre committed Jan 29, 2010 767  *  Rémi Denis-Courmont committed Jun 14, 2015 768  * @code{.m}  Marvin Scholz committed Oct 11, 2019 769  * @protocol VLCVideoViewEmbedding  Olivier Aubert committed Dec 21, 2009 770 771  * - (void)addVoutSubview:(NSView *)view; * - (void)removeVoutSubview:(NSView *)view;  Marvin Scholz committed Oct 11, 2019 772  * @end  Rémi Denis-Courmont committed Feb 20, 2010 773  * @endcode  Pierre committed Dec 24, 2009 774  *  775 776  * Or it can be an NSView object. *  Jean-Baptiste Kempf committed Feb 27, 2016 777  * If you want to use it along with Qt see the QMacCocoaViewContainer. Then  778  * the following code should work:  Rémi Denis-Courmont committed Jun 14, 2015 779  * @code{.mm}  780 781 782 783 784 785 786 787  * { * NSView *video = [[NSView alloc] init]; * QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent); * libvlc_media_player_set_nsobject(mp, video); * [video release]; * } * @endcode *  Olivier Aubert committed Dec 21, 2009 788  * You can find a live example in VLCVideoView in VLCKit.framework.  Pierre committed Jan 29, 2010 789  *  Pierre committed May 25, 2009 790  * \param p_mi the Media Player  791  * \param drawable the drawable that is either an NSView or an object following  Marvin Scholz committed Feb 25, 2019 792  * the VLCVideoViewEmbedding protocol.  Pierre committed May 25, 2009 793  */  Rémi Denis-Courmont committed May 07, 2011 794 LIBVLC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable );  Pierre committed May 25, 2009 795 796  /**  Olivier Aubert committed Dec 21, 2009 797  * Get the NSView handler previously set with libvlc_media_player_set_nsobject().  Pierre committed May 25, 2009 798  *  799  * \param p_mi the Media Player  Olivier Aubert committed Dec 21, 2009 800  * \return the NSView handler or 0 if none where set  Pierre committed May 25, 2009 801  */  Rémi Denis-Courmont committed May 07, 2011 802 LIBVLC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );  Pierre committed Jan 29, 2010 803   Pierre committed May 25, 2009 804 805 /** * Set an X Window System drawable where the media player should render its  Rémi Denis-Courmont committed Jul 20, 2015 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825  * video output. The call takes effect when the playback starts. If it is * already started, it might need to be stopped before changes apply. * If LibVLC was built without X11 output support, then this function has no * effects. * * By default, LibVLC will capture input events on the video rendering area. * Use libvlc_video_set_mouse_input() and libvlc_video_set_key_input() to * disable that and deliver events to the parent window / to the application * instead. By design, the X11 protocol delivers input events to only one * recipient. * * \warning * The application must call the XInitThreads() function from Xlib before * libvlc_new(), and before any call to XOpenDisplay() directly or via any * other library. Failure to call XInitThreads() will seriously impede LibVLC * performance. Calling XOpenDisplay() before XInitThreads() will eventually * crash the process. That is a limitation of Xlib. * * \param p_mi media player * \param drawable X11 window ID  Pierre committed May 25, 2009 826  *  Rémi Denis-Courmont committed Jul 20, 2015 827  * \note  Pierre committed May 25, 2009 828  * The specified identifier must correspond to an existing Input/Output class  Rémi Denis-Courmont committed Jul 20, 2015 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845  * X11 window. Pixmaps are not currently supported. The default X11 * server is assumed, i.e. that specified in the DISPLAY environment variable. * * \warning * LibVLC can deal with invalid X11 handle errors, however some display drivers * (EGL, GLX, VA and/or VDPAU) can unfortunately not. Thus the window handle * must remain valid until playback is stopped, otherwise the process may * abort or crash. * * \bug * No more than one window handle per media player instance can be specified. * If the media has multiple simultaneously active video tracks, extra tracks * will be rendered into external windows beyond the control of the * application. */ LIBVLC_API void libvlc_media_player_set_xwindow(libvlc_media_player_t *p_mi, uint32_t drawable);  Pierre committed May 25, 2009 846 847 848 849 850 851 852  /** * Get the X Window System window identifier previously set with * libvlc_media_player_set_xwindow(). Note that this will return the identifier * even if VLC is not currently using it (for instance if it is playing an * audio-only input). *  853  * \param p_mi the Media Player  Pierre committed May 25, 2009 854 855  * \return an X window ID, or 0 if none where set. */  Rémi Denis-Courmont committed May 07, 2011 856 LIBVLC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 857 858 859 860 861 862 863 864 865  /** * Set a Win32/Win64 API window handle (HWND) where the media player should * render its video output. If LibVLC was built without Win32/Win64 API output * support, then this has no effects. * * \param p_mi the Media Player * \param drawable windows handle of the drawable */  Rémi Denis-Courmont committed May 07, 2011 866 LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );  Pierre committed May 25, 2009 867 868 869 870 871 872  /** * Get the Windows API window handle (HWND) previously set with * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC * is not currently outputting any video to it. *  873  * \param p_mi the Media Player  Pierre committed May 25, 2009 874 875  * \return a window handle or NULL if there are none. */  Rémi Denis-Courmont committed May 07, 2011 876 LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 877   Thomas Guillem committed Jun 25, 2015 878 879 880 881 882 883 /** * Set the android context. * * \version LibVLC 3.0.0 and later. * * \param p_mi the media player  Thomas Guillem committed Dec 20, 2016 884 885  * \param p_awindow_handler org.videolan.libvlc.AWindow jobject owned by the * org.videolan.libvlc.MediaPlayer class from the libvlc-android project.  Thomas Guillem committed Jun 25, 2015 886 887 888 889  */ LIBVLC_API void libvlc_media_player_set_android_context( libvlc_media_player_t *p_mi, void *p_awindow_handler );  Rémi Denis-Courmont committed May 10, 2011 890 891 /** * Callback prototype for audio playback.  Rémi Denis-Courmont committed Mar 28, 2016 892 893 894 895 896 897 898 899 900 901 902 903 904  * * The LibVLC media player decodes and post-processes the audio signal * asynchronously (in an internal thread). Whenever audio samples are ready * to be queued to the output, this callback is invoked. * * The number of samples provided per invocation may depend on the file format, * the audio coding algorithm, the decoder plug-in, the post-processing * filters and timing. Application must not assume a certain number of samples. * * The exact format of audio samples is determined by libvlc_audio_set_format() * or libvlc_audio_set_format_callbacks() as is the channels layout. * * Note that the number of samples is per channel. For instance, if the audio  Hugo Beauzée-Luyssen committed Jun 02, 2017 905 906  * track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds * of audio signal - regardless of the number of audio channels.  Rémi Denis-Courmont committed Mar 28, 2016 907  *  Rémi Denis-Courmont committed May 10, 2011 908  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]  Rémi Denis-Courmont committed Mar 28, 2016 909  * \param samples pointer to a table of audio samples to play back [IN]  Rémi Denis-Courmont committed May 10, 2011 910 911 912 913  * \param count number of audio samples to play back * \param pts expected play time stamp (see libvlc_delay()) */ typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,  Rémi Denis-Courmont committed May 10, 2011 914  unsigned count, int64_t pts);  Rémi Denis-Courmont committed May 10, 2011 915   Rémi Denis-Courmont committed Aug 04, 2011 916 917 /** * Callback prototype for audio pause.  Rémi Denis-Courmont committed Mar 28, 2016 918 919 920  * * LibVLC invokes this callback to pause audio playback. *  Rémi Denis-Courmont committed Aug 04, 2011 921 922 923 924 925 926 927  * \note The pause callback is never called if the audio is already paused. * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] * \param pts time stamp of the pause request (should be elapsed already) */ typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts); /**  Rémi Denis-Courmont committed Mar 28, 2016 928 929 930 931 932  * Callback prototype for audio resumption. * * LibVLC invokes this callback to resume audio playback after it was * previously paused. *  Rémi Denis-Courmont committed Aug 04, 2011 933 934 935 936 937 938 939  * \note The resume callback is never called if the audio is not paused. * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] * \param pts time stamp of the resumption request (should be elapsed already) */ typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts); /**  Rémi Denis-Courmont committed Mar 28, 2016 940 941 942 943 944 945  * Callback prototype for audio buffer flush. * * LibVLC invokes this callback if it needs to discard all pending buffers and * stop playback as soon as possible. This typically occurs when the media is * stopped. *  Rémi Denis-Courmont committed Aug 04, 2011 946 947 948 949 950  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] */ typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts); /**  Rémi Denis-Courmont committed Mar 28, 2016 951 952 953 954 955 956  * Callback prototype for audio buffer drain. * * LibVLC may invoke this callback when the decoded audio track is ending. * There will be no further decoded samples for the track, but playback should * nevertheless continue until all already pending buffers are rendered. *  Rémi Denis-Courmont committed Aug 04, 2011 957 958 959 960  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] */ typedef void (*libvlc_audio_drain_cb)(void *data);  Rémi Denis-Courmont committed May 10, 2011 961 962 963 /** * Callback prototype for audio volume change. * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]  Rémi Denis-Courmont committed Aug 04, 2011 964  * \param volume software volume (1. = nominal, 0. = mute)  Rémi Denis-Courmont committed May 10, 2011 965 966 967 968 969 970  * \param mute muted flag */ typedef void (*libvlc_audio_set_volume_cb)(void *data, float volume, bool mute); /**  Rémi Denis-Courmont committed Mar 28, 2016 971 972  * Sets callbacks and private data for decoded audio. *  Rémi Denis-Courmont committed May 10, 2011 973 974 975  * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() * to configure the decoded audio format. *  Rémi Denis-Courmont committed Mar 28, 2016 976 977 978  * \note The audio callbacks override any other audio output mechanism. * If the callbacks are set, LibVLC will not output audio in any way. *  Rémi Denis-Courmont committed May 10, 2011 979 980  * \param mp the media player * \param play callback to play audio samples (must not be NULL)  Rémi Denis-Courmont committed Aug 04, 2011 981 982 983 984 985  * \param pause callback to pause playback (or NULL to ignore) * \param resume callback to resume playback (or NULL to ignore) * \param flush callback to flush audio buffers (or NULL to ignore) * \param drain callback to drain audio buffers (or NULL to ignore) * \param opaque private pointer for the audio callbacks (as first parameter)  Rafaël Carré committed Feb 05, 2012 986  * \version LibVLC 2.0.0 or later  Rémi Denis-Courmont committed May 10, 2011 987 988 989 990  */ LIBVLC_API void libvlc_audio_set_callbacks( libvlc_media_player_t *mp, libvlc_audio_play_cb play,  Rémi Denis-Courmont committed Aug 04, 2011 991 992 993 994  libvlc_audio_pause_cb pause, libvlc_audio_resume_cb resume, libvlc_audio_flush_cb flush, libvlc_audio_drain_cb drain,  Rémi Denis-Courmont committed May 10, 2011 995 996  void *opaque );  Rémi Denis-Courmont committed Aug 04, 2011 997 /**  Rémi Denis-Courmont committed Oct 30, 2014 998 999  * Set callbacks and private data for decoded audio. This only works in * combination with libvlc_audio_set_callbacks().  Rémi Denis-Courmont committed Aug 04, 2011 1000 1001 1002 1003 1004 1005  * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() * to configure the decoded audio format. * * \param mp the media player * \param set_volume callback to apply audio volume, * or NULL to apply volume in software  Rafaël Carré committed Feb 05, 2012 1006  * \version LibVLC 2.0.0 or later  Rémi Denis-Courmont committed Aug 04, 2011 1007 1008 1009 1010 1011  */ LIBVLC_API void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp, libvlc_audio_set_volume_cb set_volume );  Rémi Denis-Courmont committed May 10, 2011 1012 1013 /** * Callback prototype to setup the audio playback.  Rémi Denis-Courmont committed Mar 28, 2016 1014  *  Rémi Denis-Courmont committed May 10, 2011 1015 1016 1017 1018 1019 1020 1021 1022  * This is called when the media player needs to create a new audio output. * \param opaque pointer to the data pointer passed to * libvlc_audio_set_callbacks() [IN/OUT] * \param format 4 bytes sample format [IN/OUT] * \param rate sample rate [IN/OUT] * \param channels channels count [IN/OUT] * \return 0 on success, anything else to skip audio playback */  Steve Lhomme committed May 10, 2019 1023 typedef int (*libvlc_audio_setup_cb)(void **opaque, char *format, unsigned *rate,  Rémi Denis-Courmont committed May 10, 2011 1024 1025 1026 1027  unsigned *channels); /** * Callback prototype for audio playback cleanup.  Rémi Denis-Courmont committed Mar 28, 2016 1028  *  Rémi Denis-Courmont committed May 10, 2011 1029 1030 1031 1032  * This is called when the media player no longer needs an audio output. * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN] */ typedef void (*libvlc_audio_cleanup_cb)(void *data);  Pierre committed May 25, 2009 1033   Rémi Denis-Courmont committed May 10, 2011 1034 /**  Rémi Denis-Courmont committed Mar 28, 2016 1035 1036 1037  * Sets decoded audio format via callbacks. * * This only works in combination with libvlc_audio_set_callbacks().  Rémi Denis-Courmont committed May 10, 2011 1038 1039 1040 1041  * * \param mp the media player * \param setup callback to select the audio format (cannot be NULL) * \param cleanup callback to release any allocated resources (or NULL)  Rafaël Carré committed Feb 05, 2012 1042  * \version LibVLC 2.0.0 or later  Rémi Denis-Courmont committed May 10, 2011 1043 1044 1045 1046 1047 1048 1049  */ LIBVLC_API void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp, libvlc_audio_setup_cb setup, libvlc_audio_cleanup_cb cleanup ); /**  Rémi Denis-Courmont committed Mar 28, 2016 1050 1051  * Sets a fixed decoded audio format. *  Rémi Denis-Courmont committed May 10, 2011 1052 1053 1054 1055  * This only works in combination with libvlc_audio_set_callbacks(), * and is mutually exclusive with libvlc_audio_set_format_callbacks(). * * \param mp the media player  Rémi Duraffort committed Jul 17, 2011 1056  * \param format a four-characters string identifying the sample format  Rémi Denis-Courmont committed Jan 18, 2019 1057  * (e.g. "S16N" or "f32l")  Rémi Denis-Courmont committed May 10, 2011 1058 1059  * \param rate sample rate (expressed in Hz) * \param channels channels count  Rafaël Carré committed Feb 05, 2012 1060  * \version LibVLC 2.0.0 or later  Rémi Denis-Courmont committed May 10, 2011 1061 1062 1063 1064  */ LIBVLC_API void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format, unsigned rate, unsigned channels );  Pierre committed May 25, 2009 1065 1066 1067 1068 1069 1070 1071  /** \bug This might go away ... to be replaced by a broader system */ /** * Get the current movie length (in ms). * * \param p_mi the Media Player  Rémi Denis-Courmont committed Jan 31, 2010 1072  * \return the movie length (in ms), or -1 if there is no media.  Pierre committed May 25, 2009 1073  */  Rémi Denis-Courmont committed May 07, 2011 1074 LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 1075 1076 1077 1078 1079  /** * Get the current movie time (in ms). * * \param p_mi the Media Player  Rémi Denis-Courmont committed Jan 31, 2010 1080  * \return the movie time (in ms), or -1 if there is no media.  Pierre committed May 25, 2009 1081  */  Rémi Denis-Courmont committed May 07, 2011 1082 LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 1083 1084  /**  Rémi Denis-Courmont committed Jan 31, 2010 1085 1086  * Set the movie time (in ms). This has no effect if no media is being played. * Not all formats and protocols support this.  Pierre committed May 25, 2009 1087 1088  * * \param p_mi the Media Player  Zhao Zhili committed Jun 29, 2018 1089  * \param b_fast prefer fast seeking or precise seeking  Rémi Duraffort committed Feb 11, 2010 1090  * \param i_time the movie time (in ms).  Zhao Zhili committed Jun 29, 2018 1091  * \return 0 on success, -1 on error  Pierre committed May 25, 2009 1092  */  Zhao Zhili committed Jun 29, 2018 1093 1094 LIBVLC_API int libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time, bool b_fast );  Pierre committed May 25, 2009 1095 1096  /**  Olivier Aubert committed Nov 18, 2012 1097  * Get movie position as percentage between 0.0 and 1.0.  Pierre committed May 25, 2009 1098 1099  * * \param p_mi the Media Player  Rémi Denis-Courmont committed Jan 31, 2010 1100  * \return movie position, or -1. in case of error  Pierre committed May 25, 2009 1101  */  Rémi Denis-Courmont committed May 07, 2011 1102 LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi );  Pierre committed May 25, 2009 1103 1104  /**  Hugo Beauzée-Luyssen committed Jun 02, 2017 1105  * Set movie position as percentage between 0.0 and 1.0.  Olivier Aubert committed Nov 18, 2012 1106  * This has no effect if playback is not enabled.  Rémi Denis-Courmont committed Jan 31, 2010 1107  * This might not work depending on the underlying input format and protocol.  Pierre committed May 25, 2009 1108 1109  * * \param p_mi the Media Player  Zhao Zhili committed Jun 29, 2018 1110  * \param b_fast prefer fast seeking or precise seeking  Olivier Aubert committed Jul 30, 2009 1111  * \param f_pos the position  Zhao Zhili committed Jun 29, 2018 1112  * \return 0 on success, -1 on error  Pierre committed May 25, 2009 1113  */  Zhao Zhili committed Jun 29, 2018 1114 1115 LIBVLC_API int libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos, bool b_fast );  Pierre committed May 25, 2009 1116 1117  /**  Rémi Denis-Courmont committed Jan 31, 2010 1118  * Set movie chapter (if applicable).  Pierre committed May 25, 2009 1119 1120 1121 1122  * * \param p_mi the Media Player * \param i_chapter chapter number to play */  Rémi Denis-Courmont committed May 07, 2011 1123 LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter );  Pierre committed May 25, 2009 1124 1125  /**  Rémi Denis-Courmont committed Jan 31, 2010 1126  * Get movie chapter.