VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
/**
- * Try to start a user interface for the libvlc instance, and wait until the
- * user exits.
+ * Try to start a user interface for the libvlc instance.
*
* \param p_instance the instance
* \param name interface name, or NULL for default
*/
VLC_PUBLIC_API struct vlc_object_t *libvlc_get_vlc_instance(libvlc_instance_t *);
+/**
+ * Frees an heap allocation (char *) returned by a LibVLC API.
+ * If you know you're using the same underlying C run-time as the LibVLC
+ * implementation, then you can call ANSI C free() directly instead.
+ */
+VLC_PUBLIC_API void libvlc_free( void *ptr );
+
/** @}*/
/*****************************************************************************
/** \defgroup libvlc_media_player libvlc_media_player
* \ingroup libvlc
* LibVLC Media Player, object that let you play a media
- * in a libvlc_drawable_t
+ * in a custom drawable
* @{
*/
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 agl handler 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.
+ * \param p_mi the Media Player
+ * \param drawable the agl handler
+ * \param p_e an initialized exception pointer
+ */
+VLC_PUBLIC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable, libvlc_exception_t *p_e );
+
+/**
+ * Get the agl handler previously set with libvlc_media_player_set_agl().
*
- * On OSX, a CGrafPort is expected.
+ * \return the agl handler or 0 if none where set
+ */
+VLC_PUBLIC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );
+
+/**
+ * Set an X Window System drawable where the media player should render its
+ * video output. If LibVLC was built without X11 output support, then this has
+ * no effects.
*
- * 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.
+ * The specified identifier must correspond to an existing Input/Output class
+ * X11 window. Pixmaps are <b>not</b> 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 <b>not</b> 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 libvlc_drawable_t where the media player
- * should render its video
+ * \param drawable the ID of the X window
* \param p_e an initialized exception pointer
*/
-VLC_PUBLIC_API void libvlc_media_player_set_drawable ( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
+VLC_PUBLIC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable, libvlc_exception_t *p_e );
+
+/**
+ * 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).
+ *
+ * \return an X window ID, or 0 if none where set.
+ */
+VLC_PUBLIC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );
/**
- * Get the drawable where the media player should render its video output
+ * 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
* \param p_e an initialized exception pointer
- * \return the libvlc_drawable_t where the media player
- * should render its video
*/
-VLC_PUBLIC_API libvlc_drawable_t
- libvlc_media_player_get_drawable ( libvlc_media_player_t *, libvlc_exception_t * );
+VLC_PUBLIC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable, libvlc_exception_t *p_e );
+
+/**
+ * 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.
+ *
+ * \return a window handle or NULL if there are none.
+ */
+VLC_PUBLIC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
+
+
/** \bug This might go away ... to be replaced by a broader system */
*/
VLC_PUBLIC_API void libvlc_video_resize( libvlc_media_player_t *, int, int, libvlc_exception_t *);
-/**
- * Change the parent for the current the video output.
- *
- * \param p_instance libvlc instance
- * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
- * \param p_e an initialized exception pointer
- * \return the success status (boolean)
- */
-VLC_PUBLIC_API int libvlc_video_reparent( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
-
/**
* Tell windowless video output to redraw rectangular area (MacOS X only).
*