vout: Rename vout_Destroy to vout_CloseAndDestroy.

[vlc] / include / vlc_vout.h

diff --git a/include/vlc_vout.h b/include/vlc_vout.h
index 0e1a1650397546d398e4e437cf613973f85d38d3..a016575ab5b21c59de6c03424c3dfb24d4f5e647 100644 (file)
--- a/include/vlc_vout.h
+++ b/include/vlc_vout.h
@@ -23,10 +23,6 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
-#if !defined( __LIBVLC__ )
-  #error You are not libvlc or one of its plugins. You cannot include this file
-#endif
-
 #ifndef _VLC_VOUT_H_
 #define _VLC_VOUT_H_ 1
 
@@ -403,8 +399,7 @@ struct vout_thread_t
     unsigned int        i_par_num;           /**< monitor pixel aspect-ratio */
     unsigned int        i_par_den;           /**< monitor pixel aspect-ratio */
 
-    intf_thread_t       *p_parent_intf;   /**< parent interface for embedded
-                                                               vout (if any) */
+    struct vout_window_t *p_window;   /**< window for embedded vout (if any) */
     /**@}*/
 
     /** \name Plugin used and shortcuts to access its capabilities */
@@ -529,12 +524,65 @@ struct vout_thread_t
 /*****************************************************************************
  * Prototypes
  *****************************************************************************/
+
+/**
+ * This function will
+ *  - returns a suitable vout (if requested by a non NULL p_fmt)
+ *  - recycles an old vout (if given) by either destroying it or by saving it
+ *  for latter usage.
+ *
+ * The purpose of this function is to avoid unnecessary creation/destruction of
+ * vout (and to allow optional vout reusing).
+ *
+ * You can call vout_Request on a vout created by vout_Create or by a previous
+ * call to vout_Request.
+ * You can release the returned value either by vout_Request or vout_Close()
+ * followed by a vlc_object_release() or shorter vout_CloseAndRelease()
+ *
+ * \param p_this a vlc object
+ * \param p_vout a vout candidate
+ * \param p_fmt the video format requested or NULL
+ * \return a vout if p_fmt is non NULL and the request is successfull, NULL
+ * otherwise
+ */
 #define vout_Request(a,b,c) __vout_Request(VLC_OBJECT(a),b,c)
-VLC_EXPORT( vout_thread_t *, __vout_Request,    ( vlc_object_t *, vout_thread_t *, video_format_t * ) );
+VLC_EXPORT( vout_thread_t *, __vout_Request,    ( vlc_object_t *p_this, vout_thread_t *p_vout, video_format_t *p_fmt ) );
+
+/**
+ * This function will create a suitable vout for a given p_fmt. It will never
+ * reuse an already existing unused vout.
+ *
+ * You have to call either vout_Destroy or vout_Request on the returned value
+ * \param p_this a vlc object to which the returned vout will be attached
+ * \param p_fmt the video format requested
+ * \return a vout if the request is successfull, NULL otherwise
+ */
 #define vout_Create(a,b) __vout_Create(VLC_OBJECT(a),b)
-VLC_EXPORT( vout_thread_t *, __vout_Create,       ( vlc_object_t *, video_format_t * ) );
-VLC_EXPORT( int, vout_VarCallback, ( vlc_object_t *, const char *, vlc_value_t, vlc_value_t, void * ) );
+VLC_EXPORT( vout_thread_t *, __vout_Create,       ( vlc_object_t *p_this, video_format_t *p_fmt ) );
+
+/**
+ * This function will close a vout created by vout_Create or vout_Request.
+ * The associated vout module is closed.
+ * Note: It is not released yet, you'll have to call vlc_object_release()
+ * or use the convenient vout_CloseAndRelease().
+ *
+ * \param p_vout the vout to close
+ */
+VLC_EXPORT( void,            vout_Close,        ( vout_thread_t *p_vout ) );
+
+/**
+ * This function will close a vout created by vout_Create
+ * and then release it.
+ *
+ * \param p_vout the vout to close and release
+ */
+static inline void vout_CloseAndRelease( vout_thread_t *p_vout )
+{
+    vout_Close( p_vout );
+    vlc_object_release( p_vout );
+}
 
+/* */
 VLC_EXPORT( int,             vout_ChromaCmp,      ( uint32_t, uint32_t ) );
 
 VLC_EXPORT( picture_t *,     vout_CreatePicture,  ( vout_thread_t *, bool, bool, unsigned int ) );