X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media_player.h;h=435bb4f9df3b981457ea5cb63c9fd7345127b0e3;hb=4faa38ecba8274d50fb03ff070ff18df9f4f9875;hp=b812a5f8b1a622c6089256fdd685197578014b2c;hpb=0d430a21861588a033bf1ce258cd4974924f28d5;p=vlc diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h index b812a5f8b1..435bb4f9df 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). * @{ */ @@ -177,6 +176,15 @@ 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 + */ +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) * @@ -194,18 +202,36 @@ VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi ); /** * 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 ); @@ -409,10 +435,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 +458,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 +484,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 +492,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 ); @@ -482,9 +513,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 +528,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_xid() 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 +560,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. @@ -545,9 +573,9 @@ void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on ); * handled. This is needed for DVD menus to work, as well as a few video * filters such as "puzzle". * - * \note See also \func libvlc_video_set_key_input(). + * \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. @@ -588,6 +616,32 @@ int libvlc_video_get_height( libvlc_media_player_t *p_mi ); VLC_DEPRECATED_API int libvlc_video_get_width( libvlc_media_player_t *p_mi ); +/** + * Get the mouse pointer coordinates over a video. + * Coordinates are expressed in terms of the decoded video resolution, + * not in terms of pixels on the screen/viewport (to get the latter, + * you can query your windowing system directly). + * + * Either of the coordinates may be negative or larger than the corresponding + * dimension of the video, if the cursor is outside the rendering area. + * + * @warning The coordinates may be out-of-date if the pointer is not located + * on the video rendering area. LibVLC does not track the pointer if it is + * outside of the video widget. + * + * @note LibVLC does not support multiple pointers (it does of course support + * multiple input devices sharing the same pointer) at the moment. + * + * \param p_mi media player + * \param num number of the video (starting from, and most commonly 0) + * \param px pointer to get the abscissa [OUT] + * \param py pointer to get the ordinate [OUT] + * \return 0 on success, -1 if the specified video does not exist + */ +VLC_PUBLIC_API +int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num, + int *px, int *py ); + /** * Get the current video scaling factor. * See also libvlc_video_set_scale(). @@ -616,7 +670,7 @@ VLC_PUBLIC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f * * \param p_mi the media player * \return the video aspect ratio or NULL if unspecified - * (the result must be released with free() or libvlc_free()). + * (the result must be released with free()). */ VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi ); @@ -880,11 +934,61 @@ 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 + */ +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 + */ +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 + */ +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 + */ +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 * @{ */