X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media_player.h;h=105090eafc13e384e06fbeee2935c4c595a5958a;hb=57a4f916876060dc51583f40483522a0ad1de8bc;hp=029ddb17f1441dfa72e998a48bdf39ea626c7713;hpb=e22624799da7c67a3cfa6ab366927d2ddc985a01;p=vlc diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h index 029ddb17f1..105090eafc 100644 --- a/include/vlc/libvlc_media_player.h +++ b/include/vlc/libvlc_media_player.h @@ -38,10 +38,9 @@ extern "C" { /***************************************************************************** * Media Player *****************************************************************************/ -/** \defgroup libvlc_media_player libvlc_media_player +/** \defgroup libvlc_media_player LibVLC media player * \ingroup libvlc - * LibVLC Media Player, object that let you play a media - * in a custom drawable + * A LibVLC media player plays one media (usually in a custom drawable). * @{ */ @@ -96,6 +95,18 @@ typedef enum libvlc_video_marquee_option_t { libvlc_marquee_Y } libvlc_video_marquee_option_t; +/** + * Navigation mode + */ +typedef enum libvlc_navigate_mode_t +{ + libvlc_navigate_activate = 0, + libvlc_navigate_up, + libvlc_navigate_down, + libvlc_navigate_left, + libvlc_navigate_right, +} libvlc_navigate_mode_t; + /** * Create an empty Media Player object * @@ -177,6 +188,16 @@ VLC_PUBLIC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *p_mi */ VLC_PUBLIC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi ); +/** + * 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 + * \version LibVLC 1.1.1 or later + */ +VLC_PUBLIC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp, + int do_pause ); + /** * Toggle pause (no effect if there is no media) * @@ -191,21 +212,86 @@ VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi ); */ VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi ); +/** + * Set callbacks and private data to render decoded video to a custom area + * in memory. Use libvlc_video_set_format() to configure the decoded format. + * + * 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. + * + * When the video frame is decoded, the unlock callback is invoked. The + * second parameter to the callback corresponds is the return value of the + * lock callback. The third parameter conveys the pixel planes for convenience. + * + * When the video frame needs to be shown, as determined by the media playback + * clock, the display callback is invoked. The second parameter also conveys + * the return value from the lock callback. + * + * \param mp the media player + * \param lock callback to allocate video memory + * \param unlock callback to release video memory + * \param opaque private pointer for the three callbacks (as first parameter) + * \version LibVLC 1.1.1 or later + */ +VLC_PUBLIC_API +void libvlc_video_set_callbacks( libvlc_media_player_t *mp, + void *(*lock) (void *opaque, void **plane), + void (*unlock) (void *opaque, void *picture, void *const *plane), + void (*display) (void *opaque, void *picture), + void *opaque ); + +/** + * Set decoded video chroma and dimensions. This only works in combination with + * libvlc_video_set_callbacks(). + * + * \param mp the media player + * \param chroma a four-characters string identifying the chroma + * (e.g. "RV32" or "I420") + * \param width pixel width + * \param height pixel height + * \param pitch line pitch (in bytes) + * \version LibVLC 1.1.1 or later + */ +VLC_PUBLIC_API +void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma, + unsigned width, unsigned height, + unsigned pitch ); + /** * Set the NSView handler where the media player should render its video output. * - * The object minimal_macosx expects is of kind NSObject and should - * respect the protocol: + * Use the vout called "macosx". + * + * The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding + * protocol: * - * @protocol VLCOpenGLVideoViewEmbedding + * @begincode + * \@protocol VLCOpenGLVideoViewEmbedding * - (void)addVoutSubview:(NSView *)view; * - (void)removeVoutSubview:(NSView *)view; - * @end + * \@end + * @endcode + * + * Or it can be an NSView object. + * + * If you want to use it along with Qt4 see the QMacCocoaViewContainer. Then + * the following code should work: + * @begincode + * { + * NSView *video = [[NSView alloc] init]; + * QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent); + * libvlc_media_player_set_nsobject(mp, video); + * [video release]; + * } + * @endcode * * You can find a live example in VLCVideoView in VLCKit.framework. * * \param p_mi the Media Player - * \param drawable the NSView handler + * \param drawable the drawable that is either an NSView or an object following + * the VLCOpenGLVideoViewEmbedding protocol. */ VLC_PUBLIC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable ); @@ -242,9 +328,6 @@ VLC_PUBLIC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_m * X11 window. Pixmaps are not supported. The caller shall ensure that * the X11 server is the same as the one the VLC instance has been configured * with. - * If XVideo is not used, it is assumed that the drawable has the - * following properties in common with the default X11 screen: depth, scan line - * pad, black pixel. This is a bug. * * \param p_mi the Media Player * \param drawable the ID of the X window @@ -409,10 +492,12 @@ VLC_PUBLIC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t VLC_PUBLIC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi ); /** - * Get movie play rate + * Get the requested movie play rate. + * @warning Depending on the underlying media, the requested rate may be + * different from the real playback rate. * * \param p_mi the Media Player - * \return movie play rate, or zero in case of error + * \return movie play rate */ VLC_PUBLIC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi ); @@ -430,6 +515,7 @@ VLC_PUBLIC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, fl * Get current movie state * * \param p_mi the Media Player + * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t */ VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi ); @@ -455,6 +541,7 @@ VLC_PUBLIC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_m * Is this media player seekable? * * \param p_mi the media player + * \return true if the media player can seek */ VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi ); @@ -462,6 +549,7 @@ VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi * Can this media player be paused? * * \param p_mi the media player + * \return true if the media player can pause */ VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi ); @@ -473,7 +561,15 @@ VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi ); */ VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi ); - +/** + * Navigate through DVD Menu + * + * \param p_mi the Media Player + * \param navigate the Navigation mode + * \version libVLC 1.2.0 or later + */ +VLC_PUBLIC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi, + unsigned navigate ); /** * Release (free) libvlc_track_description_t @@ -482,9 +578,7 @@ VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi */ VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description ); -/** \defgroup libvlc_video libvlc_video - * \ingroup libvlc_media_player - * LibVLC Video handling +/** \defgroup libvlc_video LibVLC video controls * @{ */ @@ -499,15 +593,14 @@ VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi ); /** - * Enable or disable fullscreen on non-embedded video outputs. + * Enable or disable fullscreen. * - * @warning With most window managers, only a top-level windows can switch to + * @warning With most window managers, only a top-level windows can be in * full-screen mode. Hence, this function will not operate properly if - * libvlc_media_player_set_xid() or libvlc_media_player_set_hwnd() was - * used to embed the video in a non-LibVLC widget. If you want to to render an - * embedded LibVLC video full-screen, the parent embedding widget must expanded - * to full screen (LibVLC cannot take care of that). - * LibVLC will then automatically resize the video as appropriate. + * libvlc_media_player_set_xwindow() was used to embed the video in a + * non-top-level window. In that case, the embedding window must be reparented + * to the root window before fullscreen mode is enabled. You will want + * to reparent it back to its normal parent when disabling fullscreen. * * \param p_mi the media player * \param b_fullscreen boolean for fullscreen status @@ -532,7 +625,7 @@ VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi ); * for the X window ID of the video widget, then LibVLC will not be able to * handle key presses and mouse clicks in any case. * - * \warning This function is only implemented for X11 at the moment. + * \warning This function is only implemented for X11 and Win32 at the moment. * * \param p_mi the media player * \param on true to handle key press events, false to ignore them. @@ -547,7 +640,7 @@ void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on ); * * \note See also libvlc_video_set_key_input(). * - * \warning This function is only implemented for X11 at the moment. + * \warning This function is only implemented for X11 and Win32 at the moment. * * \param p_mi the media player * \param on true to handle mouse click events, false to ignore them. @@ -906,11 +999,65 @@ VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi, unsigned option, const char *psz_value ); +/** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */ +enum libvlc_video_adjust_option_t { + libvlc_adjust_Enable = 0, + libvlc_adjust_Contrast, + libvlc_adjust_Brightness, + libvlc_adjust_Hue, + libvlc_adjust_Saturation, + libvlc_adjust_Gamma, +}; + +/** + * Get integer adjust option. + * + * \param p_mi libvlc media player instance + * \param option adjust option to get, values of libvlc_video_adjust_option_t + * \version LibVLC 1.1.1 and later. + */ +VLC_PUBLIC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi, + unsigned option ); + +/** + * Set adjust option as integer. Options that take a different type value + * are ignored. + * Passing libvlc_adjust_enable as option value has the side effect of + * starting (arg !0) or stopping (arg 0) the adjust filter. + * + * \param p_mi libvlc media player instance + * \param option adust option to set, values of libvlc_video_adjust_option_t + * \param value adjust option value + * \version LibVLC 1.1.1 and later. + */ +VLC_PUBLIC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi, + unsigned option, int value ); + +/** + * Get float adjust option. + * + * \param p_mi libvlc media player instance + * \param option adjust option to get, values of libvlc_video_adjust_option_t + * \version LibVLC 1.1.1 and later. + */ +VLC_PUBLIC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi, + unsigned option ); + +/** + * Set adjust option as float. Options that take a different type value + * are ignored. + * + * \param p_mi libvlc media player instance + * \param option adust option to set, values of libvlc_video_adjust_option_t + * \param value adjust option value + * \version LibVLC 1.1.1 and later. + */ +VLC_PUBLIC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi, + unsigned option, float value ); + /** @} video */ -/** \defgroup libvlc_audio libvlc_audio - * \ingroup libvlc_media_player - * LibVLC Audio handling +/** \defgroup libvlc_audio LibVLC audio controls * @{ */ @@ -1129,6 +1276,25 @@ VLC_PUBLIC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi ); */ VLC_PUBLIC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel ); +/** + * Get current audio delay. + * + * \param p_mi media player + * \return the audio delay (microseconds) + * \version LibVLC 1.1.1 or later + */ +VLC_PUBLIC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi ); + +/** + * Set current audio delay. The audio delay will be reset to zero each time the media changes. + * + * \param p_mi media player + * \param i_delay the audio delay (microseconds) + * \return 0 on success, -1 on error + * \version LibVLC 1.1.1 or later + */ +VLC_PUBLIC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay ); + /** @} audio */ /** @} media_player */