From 075acbb6ff5740b2eea1bb7dd3afbc8e66e2ebf8 Mon Sep 17 00:00:00 2001
From: Vittorio Giovara <vittorio.giovara@gmail.com>
Date: Thu, 10 Nov 2016 14:26:18 -0500
Subject: [PATCH] lavu: Add a video section to Doxygen documentation

Fill it with AVStereo3D and AVDisplayMatrix documentation.
Apply the necessary changes to make verbatim code look good in doxygen.

Signed-off-by: Vittorio Giovara <vittorio.giovara@gmail.com>
---
 libavutil/avutil.h   |  6 ++++++
 libavutil/display.h  | 27 +++++++++++++++++++++++++++
 libavutil/stereo3d.h | 39 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+)

diff --git a/libavutil/avutil.h b/libavutil/avutil.h
index c49685aecf..2339fe3c9c 100644
--- a/libavutil/avutil.h
+++ b/libavutil/avutil.h
@@ -115,6 +115,12 @@
  *
  * @}
  *
+ * @defgroup lavu_video Video related
+ *
+ * @{
+ *
+ * @}
+ *
  * @defgroup lavu_audio Audio related
  *
  * @{
diff --git a/libavutil/display.h b/libavutil/display.h
index dba3b1e60d..2d869fcd16 100644
--- a/libavutil/display.h
+++ b/libavutil/display.h
@@ -18,21 +18,37 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * @file
+ * Display matrix
+ */
+
 #ifndef AVUTIL_DISPLAY_H
 #define AVUTIL_DISPLAY_H
 
 #include <stdint.h>
 
 /**
+ * @addtogroup lavu_video
+ * @{
+ *
+ * @defgroup lavu_video_display Display transformation matrix functions
+ * @{
+ */
+
+/**
+ * @addtogroup lavu_video_display
  * The display transformation matrix specifies an affine transformation that
  * should be applied to video frames for correct presentation. It is compatible
  * with the matrices stored in the ISO/IEC 14496-12 container format.
  *
  * The data is a 3x3 matrix represented as a 9-element array:
  *
+ * @code{.unparsed}
  *                                  | a b u |
  *   (a, b, u, c, d, v, x, y, w) -> | c d v |
  *                                  | x y w |
+ * @endcode
  *
  * All numbers are stored in native endianness, as 16.16 fixed-point values,
  * except for u, v and w, which are stored as 2.30 fixed-point values.
@@ -40,15 +56,21 @@
  * The transformation maps a point (p, q) in the source (pre-transformation)
  * frame to the point (p', q') in the destination (post-transformation) frame as
  * follows:
+ *
+ * @code{.unparsed}
  *               | a b u |
  *   (p, q, 1) . | c d v | = z * (p', q', 1)
  *               | x y w |
+ * @endcode
  *
  * The transformation can also be more explicitly written in components as
  * follows:
+ *
+ * @code{.unparsed}
  *   p' = (a * p + c * q + x) / z;
  *   q' = (b * p + d * q + y) / z;
  *   z  =  u * p + v * q + w
+ * @endcode
  */
 
 /**
@@ -83,4 +105,9 @@ void av_display_rotation_set(int32_t matrix[9], double angle);
  */
 void av_display_matrix_flip(int32_t matrix[9], int hflip, int vflip);
 
+/**
+ * @}
+ * @}
+ */
+
 #endif /* AVUTIL_DISPLAY_H */
diff --git a/libavutil/stereo3d.h b/libavutil/stereo3d.h
index 28156fc710..0fa9f63a2c 100644
--- a/libavutil/stereo3d.h
+++ b/libavutil/stereo3d.h
@@ -18,6 +18,11 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * @file
+ * Stereoscopic video
+ */
+
 #ifndef AVUTIL_STEREO3D_H
 #define AVUTIL_STEREO3D_H
 
@@ -25,6 +30,21 @@
 
 #include "frame.h"
 
+/**
+ * @addtogroup lavu_video
+ * @{
+ *
+ * @defgroup lavu_video_stereo3d Stereo3D types and functions
+ * @{
+ */
+
+/**
+ * @addtogroup lavu_video_stereo3d
+ * A stereoscopic video file consists in multiple views embedded in a single
+ * frame, usually describing two views of a scene. This file describes all
+ * possible codec-independent view arrangements.
+ * */
+
 /**
  * List of possible 3D Types
  */
@@ -37,41 +57,49 @@ enum AVStereo3DType {
     /**
      * Views are next to each other.
      *
+     * @code{.unparsed}
      *    LLLLRRRR
      *    LLLLRRRR
      *    LLLLRRRR
      *    ...
+     * @endcode
      */
     AV_STEREO3D_SIDEBYSIDE,
 
     /**
      * Views are on top of each other.
      *
+     * @code{.unparsed}
      *    LLLLLLLL
      *    LLLLLLLL
      *    RRRRRRRR
      *    RRRRRRRR
+     * @endcode
      */
     AV_STEREO3D_TOPBOTTOM,
 
     /**
      * Views are alternated temporally.
      *
+     * @code{.unparsed}
      *     frame0   frame1   frame2   ...
      *    LLLLLLLL RRRRRRRR LLLLLLLL
      *    LLLLLLLL RRRRRRRR LLLLLLLL
      *    LLLLLLLL RRRRRRRR LLLLLLLL
      *    ...      ...      ...
+     * @endcode
      */
     AV_STEREO3D_FRAMESEQUENCE,
 
     /**
      * Views are packed in a checkerboard-like structure per pixel.
      *
+     * @code{.unparsed}
      *    LRLRLRLR
      *    RLRLRLRL
      *    LRLRLRLR
      *    ...
+     * @endcode
      */
     AV_STEREO3D_CHECKERBOARD,
 
@@ -79,30 +107,36 @@ enum AVStereo3DType {
      * Views are next to each other, but when upscaling
      * apply a checkerboard pattern.
      *
+     * @code{.unparsed}
      *     LLLLRRRR          L L L L    R R R R
      *     LLLLRRRR    =>     L L L L  R R R R
      *     LLLLRRRR          L L L L    R R R R
      *     LLLLRRRR           L L L L  R R R R
+     * @endcode
      */
     AV_STEREO3D_SIDEBYSIDE_QUINCUNX,
 
     /**
      * Views are packed per line, as if interlaced.
      *
+     * @code{.unparsed}
      *    LLLLLLLL
      *    RRRRRRRR
      *    LLLLLLLL
      *    ...
+     * @endcode
      */
     AV_STEREO3D_LINES,
 
     /**
      * Views are packed per column.
      *
+     * @code{.unparsed}
      *    LRLRLRLR
      *    LRLRLRLR
      *    LRLRLRLR
      *    ...
+     * @endcode
      */
     AV_STEREO3D_COLUMNS,
 };
@@ -167,4 +201,9 @@ const char *av_stereo3d_type_name(unsigned int type);
  */
 int av_stereo3d_from_name(const char *name);
 
+/**
+ * @}
+ * @}
+ */
+
 #endif /* AVUTIL_STEREO3D_H */