Improve libvlc drawable documentation

[vlc] / include / vlc / libvlc.h

diff --git a/include/vlc/libvlc.h b/include/vlc/libvlc.h
index 182bfca467e36f08f1bfbfbbd90595e561513287..baab65f0be7ab298072966d5560eec7a41b9ea8a 100644 (file)
--- a/include/vlc/libvlc.h
+++ b/include/vlc/libvlc.h
@@ -278,6 +278,24 @@ VLC_PUBLIC_API void libvlc_media_add_option(
                                    libvlc_media_t * p_md,
                                    const char * ppsz_options,
                                    libvlc_exception_t * p_e );
+/**
+ * Add an option to the media from an untrusted source.
+ *
+ * This option will be used to determine how the media_player will
+ * read the media. This allows to use VLC's advanced
+ * reading/streaming options on a per-media basis.
+ *
+ * The options are detailed in vlc --long-help, for instance "--sout-all"
+ *
+ * \param p_instance the instance
+ * \param ppsz_options the options (as a string)
+ * \param p_e an initialized exception pointer
+ */
+VLC_PUBLIC_API void libvlc_media_add_option_untrusted(
+                                   libvlc_media_t * p_md,
+                                   const char * ppsz_options,
+                                   libvlc_exception_t * p_e );
+
 
 /**
  * Retain a reference to a media descriptor object (libvlc_media_t). Use
@@ -498,6 +516,15 @@ VLC_PUBLIC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_play
  */
 VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *, libvlc_exception_t * );
 
+/**
+ * is_playing
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return 1 if the media player is playing, 0 otherwise
+ */
+VLC_PUBLIC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *, libvlc_exception_t * );
+
 /**
  * Play
  *
@@ -523,7 +550,18 @@ VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t *, libvlc_
 VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *, libvlc_exception_t * );
 
 /**
- * Set the drawable where the media player should render its video output
+ * Set the drawable where the media player should render its video output.
+ *
+ * On Windows 32-bits, a window handle (HWND) is expected.
+ * On Windows 64-bits, this function will always fail.
+ *
+ * On OSX, a CGrafPort is expected.
+ *
+ * Otherwise, this shall be the identifier of an existing X11 drawable (window
+ * or pixmap). It is assumed that the X11 server is the same as the one in
+ * x11-display if configured. If XVideo is <b>not</b> supported, it is assumed
+ * that the drawable has the same pixmap format as the default X11 screen
+ * (especially depth, scan line pad, black pixel); this is a bug.
  *
  * \param p_mi the Media Player
  * \param drawable the libvlc_drawable_t where the media player