Further doxygenization.

include/osd.h

@@ -2,7 +2,7 @@
  * osd.h : Constants for use with osd modules
  *****************************************************************************
  * Copyright (C) 2003 VideoLAN
- * $Id: osd.h,v 1.3 2003/08/10 10:22:52 gbazin Exp $
+ * $Id: osd.h,v 1.4 2003/10/04 15:51:22 sigmunau Exp $
  *
  * Authors: Sigmund Augdal <sigmunau@idi.ntnu.no>
  *
@@ -21,10 +21,20 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
+/**
+ * \file
+ * Stucts and function prototypes to place text on the video
+ */
+
 #define OSD_ALIGN_LEFT 0x1
 #define OSD_ALIGN_RIGHT 0x2
 #define OSD_ALIGN_TOP 0x4
 #define OSD_ALIGN_BOTTOM 0x8
+
+/**
+ * Text style information.
+ * This struct is currently ignored
+ */
 struct text_style_t
 {
     int i_size;

include/video_output.h

 /*****************************************************************************
  * video_output.h : video output thread
- * This module describes the programming interface for video output threads.
- * It includes functions allowing to open a new thread, send pictures to a
- * thread, and destroy a previously opened video output thread.
  *****************************************************************************
  * Copyright (C) 1999, 2000 VideoLAN
- * $Id: video_output.h,v 1.98 2003/08/28 21:11:54 gbazin Exp $
+ * $Id: video_output.h,v 1.99 2003/10/04 15:51:22 sigmunau Exp $
  *
  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  *          Samuel Hocevar <sam@via.ecp.fr>
@@ -25,33 +22,41 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
-/*****************************************************************************
- * vout_chroma_t: Chroma conversion function
- *****************************************************************************
+/**
+ * \defgroup video_output Video Output
+ * This module describes the programming interface for video output threads.
+ * It includes functions allowing to open a new thread, send pictures to a
+ * thread, and destroy a previously opened video output thread.
+ * @{
+ */
+
+/**
+ * Chroma conversion function
+ *
  * This is the prototype common to all conversion functions.
- * Parameters:
- *      p_source                        source picture
- *      p_dest                          destination picture
+ * \param p_vout video output thread
+ * \param p_source source picture
+ * \param p_dest destination picture
  * Picture width and source dimensions must be multiples of 16.
- *****************************************************************************/
+ */
 typedef void (vout_chroma_convert_t)( vout_thread_t *,
                                       picture_t *, picture_t * );
 
 typedef struct vout_chroma_t
 {
-    /* conversion functions */
+    /** conversion functions */
     vout_chroma_convert_t *pf_convert;
 
-    /* Private module-dependant data */
+    /** Private module-dependant data */
     chroma_sys_t *      p_sys;                               /* private data */
 
-    /* Plugin used and shortcuts to access its capabilities */
+    /** Plugin used and shortcuts to access its capabilities */
     module_t * p_module;
 
 } vout_chroma_t;
 
 /**
- * \brief video output thread descriptor
+ * Video output thread descriptor
  *
  * Any independant video output device, such as an X11 window or a GGI device,
  * is represented by a video output thread, and described using the following
@@ -71,7 +76,8 @@ struct vout_thread_t
     
     /** \name Current display properties */
     /**@{*/
-    uint16_t            i_changes;           /**< changes made to the thread */
+    uint16_t            i_changes;          /**< changes made to the thread.
+                                                      \see \ref vout_changes */
     float               f_gamma;                                  /**< gamma */
     vlc_bool_t          b_grayscale;         /**< color or grayscale display */
     vlc_bool_t          b_info;            /**< print additional information */
@@ -144,18 +150,32 @@ struct vout_thread_t
 #define I_RENDERPICTURES p_vout->render.i_pictures
 #define PP_RENDERPICTURE p_vout->render.pp_picture
 
-/* Flags for changes - these flags are set in the i_changes field when another
- * thread changed a variable */
-#define VOUT_INFO_CHANGE        0x0001                     /* b_info changed */
-#define VOUT_GRAYSCALE_CHANGE   0x0002                /* b_grayscale changed */
-#define VOUT_INTF_CHANGE        0x0004                /* b_interface changed */
-#define VOUT_SCALE_CHANGE       0x0008                    /* b_scale changed */
-#define VOUT_GAMMA_CHANGE       0x0010                      /* gamma changed */
-#define VOUT_CURSOR_CHANGE      0x0020                   /* b_cursor changed */
-#define VOUT_FULLSCREEN_CHANGE  0x0040               /* b_fullscreen changed */
-#define VOUT_SIZE_CHANGE        0x0200                       /* size changed */
-#define VOUT_DEPTH_CHANGE       0x0400                      /* depth changed */
-#define VOUT_CHROMA_CHANGE      0x0800               /* change chroma tables */
+/** \defgroup vout_changes Flags for changes
+ * These flags are set in the vout_thread_t::i_changes field when another
+ * thread changed a variable
+ * @{
+ */
+/** b_info changed */
+#define VOUT_INFO_CHANGE        0x0001                   
+/** b_grayscale changed */
+#define VOUT_GRAYSCALE_CHANGE   0x0002              
+/** b_interface changed */
+#define VOUT_INTF_CHANGE        0x0004              
+/** b_scale changed */
+#define VOUT_SCALE_CHANGE       0x0008                  
+/** gamma changed */
+#define VOUT_GAMMA_CHANGE       0x0010
+/** b_cursor changed */
+#define VOUT_CURSOR_CHANGE      0x0020
+/** b_fullscreen changed */
+#define VOUT_FULLSCREEN_CHANGE  0x0040
+/** size changed */
+#define VOUT_SIZE_CHANGE        0x0200
+/** depth changed */
+#define VOUT_DEPTH_CHANGE       0x0400
+/** change chroma tables */
+#define VOUT_CHROMA_CHANGE      0x0800
+/**@}*/
 
 /* Alignment flags */
 #define VOUT_ALIGN_LEFT         0x0001
@@ -190,7 +210,10 @@ VLC_EXPORT( void,            vout_UnlinkPicture,  ( vout_thread_t *, picture_t *
 VLC_EXPORT( void,            vout_PlacePicture,   ( vout_thread_t *, unsigned int, unsigned int, unsigned int *, unsigned int *, unsigned int *, unsigned int * ) );
 picture_t *     vout_RenderPicture  ( vout_thread_t *, picture_t *,
                                                        subpicture_t * );
-
+/**
+ * \addtogroup subpicture
+ * @{
+ */
 VLC_EXPORT( subpicture_t *,  vout_CreateSubPicture,   ( vout_thread_t *, int ) );
 VLC_EXPORT( void,            vout_DestroySubPicture,  ( vout_thread_t *, subpicture_t * ) );
 VLC_EXPORT( void,            vout_DisplaySubPicture,  ( vout_thread_t *, subpicture_t * ) );
@@ -198,3 +221,7 @@ VLC_EXPORT( void,            vout_DisplaySubPicture,  ( vout_thread_t *, subpict
 subpicture_t *  vout_SortSubPictures    ( vout_thread_t *, mtime_t );
 void            vout_RenderSubPictures  ( vout_thread_t *, picture_t *,
                                                            subpicture_t * );
+/** @}*/
+/**
+ * @}
+ */

include/vlc_video.h

@@ -4,7 +4,7 @@
  * includes all common video types and constants.
  *****************************************************************************
  * Copyright (C) 1999, 2000 VideoLAN
- * $Id: vlc_video.h,v 1.2 2003/07/15 18:12:05 sigmunau Exp $
+ * $Id: vlc_video.h,v 1.3 2003/10/04 15:51:22 sigmunau Exp $
  *
  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  *
@@ -23,90 +23,102 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
-/*****************************************************************************
- * plane_t: description of a planar graphic field
- *****************************************************************************/
+/**
+ * Description of a planar graphic field
+ */
 typedef struct plane_t
 {
-    uint8_t *p_pixels;                          /* Start of the plane's data */
+    uint8_t *p_pixels;                        /**< Start of the plane's data */
 
     /* Variables used for fast memcpy operations */
-    int i_lines;                                          /* Number of lines */
-    int i_pitch;             /* Number of bytes in a line, including margins */
+    int i_lines;                                        /**< Number of lines */
+    int i_pitch;           /**< Number of bytes in a line, including margins */
 
-    /* Size of a macropixel, defaults to 1 */
+    /** Size of a macropixel, defaults to 1 */
     int i_pixel_pitch;
 
     /* Variables used for pictures with margins */
-    int i_visible_pitch;              /* How many visible pixels are there ? */
+    int i_visible_pitch;            /**< How many visible pixels are there ? */
 
 } plane_t;
 
-/*****************************************************************************
- * picture_t: video picture
- *****************************************************************************
+/**
+ * Video picture
+ *
  * Any picture destined to be displayed by a video output thread should be
  * stored in this structure from it's creation to it's effective display.
  * Picture type and flags should only be modified by the output thread. Note
  * that an empty picture MUST have its flags set to 0.
- *****************************************************************************/
+ */
 struct picture_t
 {
-    /* Picture data - data can always be freely modified, but p_data may
+    /** Picture data - data can always be freely modified, but p_data may
      * NEVER be modified. A direct buffer can be handled as the plugin
      * wishes, it can even swap p_pixels buffers. */
     uint8_t        *p_data;
-    void           *p_data_orig;                  /* pointer before memalign */
-    plane_t         p[ VOUT_MAX_PLANES ];       /* description of the planes */
-    int             i_planes;                  /* number of allocated planes */
-
-    /* Type and flags - should NOT be modified except by the vout thread */
-    int             i_status;                               /* picture flags */
-    int             i_type;                  /* is picture a direct buffer ? */
-    int             i_matrix_coefficients;     /* in YUV type, encoding type */
-
-    /* Picture management properties - these properties can be modified using
-     * the video output thread API, but should never be written directly */
-    int             i_refcount;                    /* link reference counter */
-    mtime_t         date;                                    /* display date */
-    vlc_bool_t      b_force;
+    void           *p_data_orig;                /**< pointer before memalign */
+    plane_t         p[ VOUT_MAX_PLANES ];     /**< description of the planes */
+    int             i_planes;                /**< number of allocated planes */
 
-    /* Picture dynamic properties - those properties can be changed by the
-     * decoder */
-    vlc_bool_t      b_progressive;            /* is it a progressive frame ? */
-    unsigned int    i_nb_fields;                    /* # of displayed fields */
-    vlc_bool_t      b_top_field_first;               /* which field is first */
+    /** \name Type and flags
+     * Should NOT be modified except by the vout thread
+     * @{*/
+    int             i_status;                             /**< picture flags */
+    int             i_type;                /**< is picture a direct buffer ? */
+    int             i_matrix_coefficients;   /**< in YUV type, encoding type */
+    /**@}*/
 
-    /* The picture heap we are attached to */
+    /** \name Picture management properties
+     * These properties can be modified using the video output thread API,
+     * but should never be written directly */
+    /**@{*/
+    int             i_refcount;                  /**< link reference counter */
+    mtime_t         date;                                  /**< display date */
+    vlc_bool_t      b_force;
+    /**@}*/
+
+    /** \name Picture dynamic properties
+     * Those properties can be changed by the decoder
+     * @{
+     */
+    vlc_bool_t      b_progressive;          /**< is it a progressive frame ? */
+    unsigned int    i_nb_fields;                  /**< # of displayed fields */
+    vlc_bool_t      b_top_field_first;             /**< which field is first */
+    /**@}*/
+    
+    /** The picture heap we are attached to */
     picture_heap_t* p_heap;
 
     /* Some vouts require the picture to be locked before it can be modified */
     int (* pf_lock) ( vout_thread_t *, picture_t * );
     int (* pf_unlock) ( vout_thread_t *, picture_t * );
 
-    /* Private data - the video output plugin might want to put stuff here to
+    /** Private data - the video output plugin might want to put stuff here to
      * keep track of the picture */
     picture_sys_t * p_sys;
 };
 
-/*****************************************************************************
- * picture_heap_t: video picture heap, either render (to store pictures used
+/**
+ * Video picture heap, either render (to store pictures used
  * by the decoder) or output (to store pictures displayed by the vout plugin)
- *****************************************************************************/
+ */
 struct picture_heap_t
 {
-    int i_pictures;                                     /* current heap size */
-
-    /* Picture static properties - those properties are fixed at initialization
-     * and should NOT be modified */
-    unsigned int i_width;                                   /* picture width */
-    unsigned int i_height;                                 /* picture height */
-    vlc_fourcc_t i_chroma;                                 /* picture chroma */
-    unsigned int i_aspect;                                   /* aspect ratio */
+    int i_pictures;                                   /**< current heap size */
+
+    /* \name Picture static properties
+     * Those properties are fixed at initialization and should NOT be modified
+     * @{
+     */
+    unsigned int i_width;                                 /**< picture width */
+    unsigned int i_height;                               /**< picture height */
+    vlc_fourcc_t i_chroma;                               /**< picture chroma */
+    unsigned int i_aspect;                                 /**< aspect ratio */
+    /**@}*/
 
     /* Real pictures */
-    picture_t*      pp_picture[VOUT_MAX_PICTURES];               /* pictures */
-    int             i_last_used_pic;                /* last used pic in heap */
+    picture_t*      pp_picture[VOUT_MAX_PICTURES];             /**< pictures */
+    int             i_last_used_pic;              /**< last used pic in heap */
     vlc_bool_t      b_allow_modify_pics;
 
     /* Stuff used for truecolor RGB planes */
@@ -114,7 +126,7 @@ struct picture_heap_t
     int i_gmask, i_rgshift, i_lgshift;
     int i_bmask, i_rbshift, i_lbshift;
 
-    /* Stuff used for palettized RGB planes */
+    /** Stuff used for palettized RGB planes */
     void (* pf_setpalette) ( vout_thread_t *, uint16_t *, uint16_t *, uint16_t * );
 };
 
@@ -153,6 +165,14 @@ struct picture_heap_t
 #define V_PIXELS     p[V_PLANE].p_pixels
 #define V_PITCH      p[V_PLANE].i_pitch
 
+/**
+ * \defgroup subpicture Video Subpictures
+ * Subpictures are pictures that should be displayed on top of the video, like
+ * subtitles and OSD
+ * \ingroup video_output
+ * @{
+ */
+
 /**
  * Video subtitle
  *
@@ -226,3 +246,4 @@ struct subpicture_t
 #define RESERVED_SUBPICTURE    1                   /* allocated and reserved */
 #define READY_SUBPICTURE       2                        /* ready for display */
 
+/**@}*/