[vlc-commits] vout: fix/improve vout_display_cfg_t documentation

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Wed Nov 13 18:29:30 2019 +0200| [a3d65dae4a28e535700f338a37899f19ef0e6243] | committer: Rémi Denis-Courmont

vout: fix/improve vout_display_cfg_t documentation

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=a3d65dae4a28e535700f338a37899f19ef0e6243
---

 include/vlc_vout_display.h | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/include/vlc_vout_display.h b/include/vlc_vout_display.h
index cf702ad6cf..675bd9d431 100644
--- a/include/vlc_vout_display.h
+++ b/include/vlc_vout_display.h
@@ -62,7 +62,16 @@ typedef struct vlc_video_align {
 } vlc_video_align_t;
 
 /**
- * Initial/Current configuration for a vout_display_t
+ * User configuration for a video output display (\ref vout_display_t)
+ *
+ * This primarily controls the size of the display area within the video
+ * window, as follows:
+ * - If \ref is_display_filled is set,
+ *   the display size is fitted to the actual window size.
+ * - Otherwise, if width and/or height are set within \ref display,
+ *   the display is sized accordingly.
+ * - Lastly, by default, the display size is the product of the zoom
+ *   and the original video format size.
  */
 typedef struct vout_display_cfg {
     struct vout_window_t *window; /**< Window */
@@ -70,25 +79,20 @@ typedef struct vout_display_cfg {
     bool is_fullscreen VLC_DEPRECATED;  /* Is the display fullscreen */
 #endif
 
-    /* Display properties */
+    /** Display properties */
     struct {
-        /* Display size */
-        unsigned  width;
-        unsigned  height;
-
-        /* Display SAR */
-        vlc_rational_t sar;
+        unsigned width; /**< Requested display pixel width (0 by default). */
+        unsigned height; /**< Requested display pixel height (0 by default). */
+        vlc_rational_t sar; /**< Requested sample aspect ratio */
     } display;
 
-    /* Alignment of the picture inside the display */
+    /** Alignment of the video within the window */
     vlc_video_align_t align;
 
-    /* Do we fill up the display with the video */
+    /** Automatic scaling/fitting flag */
     bool is_display_filled;
 
-    /* Zoom to use
-     * It will be applied to the whole display if b_display_filled is set, otherwise
-     * only on the video source */
+    /** Zoom ratio */
     struct {
         unsigned num;
         unsigned den;