docs: update plugin documentation

Update all the documentation of elements of the vaapi plugin.

Signed-off-by: Víctor Manuel Jáquez Leal <victorx.jaquez@intel.com>

11 files changed, 279 insertions, 13 deletions

diff --git a/docs/plugins/gstreamer-vaapi-plugins-docs.xml.in b/docs/plugins/gstreamer-vaapi-plugins-docs.xml.in
index 99332e67..5070eb6e 100644
--- a/docs/plugins/gstreamer-vaapi-plugins-docs.xml.in
+++ b/docs/plugins/gstreamer-vaapi-plugins-docs.xml.in
@@ -10,10 +10,21 @@
   </bookinfo>
 
   <chapter>
+    <title>gstreamer-vaapi Elements</title>
+    <xi:include href="xml/element-vaapidecode.xml"/>
+    <xi:include href="xml/element-vaapidecodebin.xml"/>
+    <xi:include href="xml/element-vaapipostproc.xml"/>
+    <xi:include href="xml/element-vaapisink.xml"/>
+    <xi:include href="xml/element-vaapiencode_h264.xml"/>
+    <xi:include href="xml/element-vaapiencode_h265.xml"/>
+    <xi:include href="xml/element-vaapiencode_jpeg.xml"/>
+    <xi:include href="xml/element-vaapiencode_mpeg2.xml"/>
+    <xi:include href="xml/element-vaapiencode_vp8.xml"/>
+  </chapter>
+
+  <chapter>
     <title>gstreamer-vaapi Plugins</title>
-    <xi:include href="xml/gstvaapidecode.xml"/>
-    <xi:include href="xml/gstvaapipostproc.xml"/>
-    <xi:include href="xml/gstvaapisink.xml"/>
+    <xi:include href="xml/plugin-vaapi.xml"/>
   </chapter>
 
   <chapter id="object-tree">
diff --git a/docs/plugins/gstreamer-vaapi-plugins-sections.txt b/docs/plugins/gstreamer-vaapi-plugins-sections.txt
new file mode 100644
index 00000000..c18e4621
--- /dev/null
+++ b/docs/plugins/gstreamer-vaapi-plugins-sections.txt
@@ -0,0 +1,135 @@
+<SECTION>
+<FILE>element-vaapidecode</FILE>
+<TITLE>vaapidecode</TITLE>
+<SUBSECTION Standard>
+GST_IS_VAAPIDECODE
+GST_IS_VAAPIDECODE_CLASS
+GST_TYPE_VAAPIDECODE
+GST_VAAPIDECODE
+GST_VAAPIDECODE_CLASS
+GST_VAAPIDECODE_GET_CLASS
+GstVaapiDecode
+GstVaapiDecodeClass
+gst_vaapidecode_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapidecodebin</FILE>
+<TITLE>vaapidecodebin</TITLE>
+<SUBSECTION Standard>
+GST_IS_AUTO_DETECT
+GST_IS_AUTO_DETECT_CLASS
+GST_TYPE_VAAPI_DECODE_BIN
+GST_VAAPI_DECODE_BIN
+GST_VAAPI_DECODE_BIN_CLASS
+GST_VAAPI_DECODE_BIN_GET_CLASS
+GstVaapiDecodeBin
+GstVaapiDecodeBinClass
+gst_vaapi_decode_bin_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapipostproc</FILE>
+<TITLE>vaapipostproc</TITLE>
+GstVaapiDeinterlaceMode
+<SUBSECTION Standard>
+GST_IS_VAAPIPOSTPROC
+GST_IS_VAAPIPOSTPROC_CLASS
+GST_TYPE_VAAPIPOSTPROC
+GST_VAAPIPOSTPROC
+GST_VAAPIPOSTPROC_CLASS
+GST_VAAPIPOSTPROC_GET_CLASS
+GstVaapiPostproc
+GstVaapiPostprocClass
+gst_vaapipostproc_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapisink</FILE>
+<TITLE>vaapisink</TITLE>
+<SUBSECTION Standard>
+GST_IS_VAAPISINK
+GST_IS_VAAPISINK_CLASS
+GST_TYPE_VAAPISINK
+GST_VAAPISINK
+GST_VAAPISINK_CLASS
+GST_VAAPISINK_GET_CLASS
+GstVaapiSink
+GstVaapiSinkClass
+gst_vaapisink_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapiencode_h264</FILE>
+<TITLE>vaapiencode_h264</TITLE>
+<SUBSECTION Standard>
+GST_IS_VAAPIENCODE_H264
+GST_IS_VAAPIENCODE_H264_CLASS
+GST_TYPE_VAAPIENCODE_H264
+GST_VAAPIENCODE_H264
+GST_VAAPIENCODE_H264_CLASS
+GST_VAAPIENCODE_H264_GET_CLASS
+GstVaapiEncodeH264
+GstVaapiEncodeH264Class
+gst_vaapiencode_h264_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapiencode_h265</FILE>
+<TITLE>vaapiencode_h265</TITLE>
+<SUBSECTION Standard>
+GST_IS_VAAPIENCODE_H265
+GST_IS_VAAPIENCODE_H265_CLASS
+GST_TYPE_VAAPIENCODE_H265
+GST_VAAPIENCODE_H265
+GST_VAAPIENCODE_H265_CLASS
+GST_VAAPIENCODE_H265_GET_CLASS
+GstVaapiEncodeH265
+GstVaapiEncodeH265Class
+gst_vaapiencode_h265_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapiencode_jpeg</FILE>
+<TITLE>vaapiencode_jpeg</TITLE>
+<SUBSECTION Standard>
+GST_IS_VAAPIENCODE_JPEG
+GST_IS_VAAPIENCODE_JPEG_CLASS
+GST_TYPE_VAAPIENCODE_JPEG
+GST_VAAPIENCODE_JPEG
+GST_VAAPIENCODE_JPEG_CLASS
+GST_VAAPIENCODE_JPEG_GET_CLASS
+GstVaapiEncodeJpeg
+GstVaapiEncodeJpegClass
+gst_vaapiencode_jpeg_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapiencode_mpeg2</FILE>
+<TITLE>vaapiencode_mpeg2</TITLE>
+<SUBSECTION Standard>
+GST_IS_VAAPIENCODE_MPEG2
+GST_IS_VAAPIENCODE_MPEG2_CLASS
+GST_TYPE_VAAPIENCODE_MPEG2
+GST_VAAPIENCODE_MPEG2
+GST_VAAPIENCODE_MPEG2_CLASS
+GST_VAAPIENCODE_MPEG2_GET_CLASS
+GstVaapiEncodeMpeg2
+GstVaapiEncodeMpeg2Class
+gst_vaapiencode_mpeg2_get_type
+</SECTION>
+
+<SECTION>
+<FILE>element-vaapiencode_vp8</FILE>
+<TITLE>vaapiencode_vp8</TITLE>
+<SUBSECTION Standard>
+GST_IS_VAAPIENCODE_VP8
+GST_IS_VAAPIENCODE_VP8_CLASS
+GST_TYPE_VAAPIENCODE_VP8
+GST_VAAPIENCODE_VP8
+GST_VAAPIENCODE_VP8_CLASS
+GST_VAAPIENCODE_VP8_GET_CLASS
+GstVaapiEncodeVP8
+GstVaapiEncodeVP8Class
+gst_vaapiencode_vp8_get_type
+</SECTION>
diff --git a/gst/vaapi/gstvaapidecode.c b/gst/vaapi/gstvaapidecode.c
index de61d14c..3fa3c175 100644
--- a/gst/vaapi/gstvaapidecode.c
+++ b/gst/vaapi/gstvaapidecode.c
@@ -23,11 +23,28 @@
 */
 
 /**
- * SECTION:gstvaapidecode
+ * SECTION:element-vaapidecode
  * @short_description: A VA-API based video decoder
  *
  * vaapidecode decodes from raw bitstreams to surfaces suitable for
- * the vaapisink element.
+ * the vaapisink or vaapipostproc elements using the installed <ulink
+ * url="https://wiki.freedesktop.org/www/Software/vaapi/">VA-API</ulink>
+ * back-end.
+ *
+ * In the case of OpenGL based elements, the buffers have the
+ * #GstVideoGLTextureUploadMeta meta, which efficiently copies the
+ * content of the VA-API surface into a GL texture.
+ *
+ * Also it can deliver normal video buffers that can be rendered or
+ * processed by other elements, but the performance would be rather
+ * bad.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch-1.0 filesrc location=~/big_buck_bunny.mov ! qtdemux ! h264parse ! vaapidecode ! vaapisink
+ * ]|
+ * </refsect2>
  */
 
 #include "gstcompat.h"
diff --git a/gst/vaapi/gstvaapidecodebin.c b/gst/vaapi/gstvaapidecodebin.c
index 9ab354f9..5eaee5e7 100644
--- a/gst/vaapi/gstvaapidecodebin.c
+++ b/gst/vaapi/gstvaapidecodebin.c
@@ -21,6 +21,26 @@
  *  Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:element-vaapidecodebin
+ * @short_description: A VA-API based video decoder with a
+ * post-processor
+ *
+ * vaapidecodebin is similar #GstVaapiDecode, but it is composed by
+ * the vaapidecode, a #GstQueue, and the #GstVaapiPostproc, if it is
+ * available and functional in the setup.
+ *
+ * It offers the functionality of #GstVaapiDecode and the many options
+ * of #GstVaapiPostproc.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch-1.0 filesrc location=~/big_buck_bunny.mov ! qtdemux ! h264parse ! vaapidecodebin ! vaapisink
+ * ]|
+ * </refsect2>
+ */
+
 #include "gstcompat.h"
 #include <stdio.h>
 #include <string.h>
@@ -32,7 +52,7 @@
 #include "gstvaapipluginbase.h"
 
 #define GST_PLUGIN_NAME "vaapidecodebin"
-#define GST_PLUGIN_DESC "A Bin of VA-API elements: vaapidecode ! queue ! vaapipostproc"
+#define GST_PLUGIN_DESC "A VA-API based bin with a decoder and a postprocessor"
 
 GST_DEBUG_CATEGORY_STATIC (gst_debug_vaapi_decode_bin);
 #define GST_CAT_DEFAULT gst_debug_vaapi_decode_bin
diff --git a/gst/vaapi/gstvaapiencode_h264.c b/gst/vaapi/gstvaapiencode_h264.c
index 78007861..1c37ca7b 100644
--- a/gst/vaapi/gstvaapiencode_h264.c
+++ b/gst/vaapi/gstvaapiencode_h264.c
@@ -21,6 +21,20 @@
  *  Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:element-vaapiencode_h264
+ * @short_description: A VA-API based H.264 video encoder
+ *
+ * Encodes raw video streams into H.264 bitstreams.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapiencode_h264 ! mp4mux ! filesink location=test.mp4
+ * ]|
+ * </refsect2>
+ */
+
 #include "gstcompat.h"
 #include <gst/vaapi/gstvaapidisplay.h>
 #include <gst/vaapi/gstvaapiencoder_h264.h>
diff --git a/gst/vaapi/gstvaapiencode_h265.c b/gst/vaapi/gstvaapiencode_h265.c
index 964048a5..f7324451 100644
--- a/gst/vaapi/gstvaapiencode_h265.c
+++ b/gst/vaapi/gstvaapiencode_h265.c
@@ -20,6 +20,20 @@
  *  Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:element-vaapiencode_h265
+ * @short_description: A VA-API based HEVC video encoder
+ *
+ * Encodes raw video streams into HEVC bitstreams.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapiencode_h265 ! matroskamux ! filesink location=test.mkv
+ * ]|
+ * </refsect2>
+ */
+
 #include "gstcompat.h"
 #include <gst/vaapi/gstvaapidisplay.h>
 #include <gst/vaapi/gstvaapiencoder_h265.h>
diff --git a/gst/vaapi/gstvaapiencode_jpeg.c b/gst/vaapi/gstvaapiencode_jpeg.c
index d9dd3451..086d155c 100644
--- a/gst/vaapi/gstvaapiencode_jpeg.c
+++ b/gst/vaapi/gstvaapiencode_jpeg.c
@@ -20,6 +20,20 @@
  *  Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:element-vaapiencode_jpeg
+ * @short_description: A VA-API based JPEG image encoder
+ *
+ * Encodes raw images into JPEG images.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ *  gst-launch-1.0 -ev videotestsrc num-buffers=1 ! timeoverlay ! vaapiencode_jpeg ! filesink location=test.jpg
+ * ]|
+ * </refsect2>
+ */
+
 #include "gstcompat.h"
 #include <gst/vaapi/gstvaapidisplay.h>
 #include <gst/vaapi/gstvaapiencoder_jpeg.h>
diff --git a/gst/vaapi/gstvaapiencode_mpeg2.c b/gst/vaapi/gstvaapiencode_mpeg2.c
index 5584c601..9f2a23bb 100644
--- a/gst/vaapi/gstvaapiencode_mpeg2.c
+++ b/gst/vaapi/gstvaapiencode_mpeg2.c
@@ -21,6 +21,20 @@
  *  Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:element-vaapiencode_mpeg2
+ * @short_description: A VA-API based MPEG2 video encoder
+ *
+ * Encodes raw video streams into MPEG2 bitstreams.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapiencode_mpeg2 ! matroskamux ! filesink location=test.mkv
+ * ]|
+ * </refsect2>
+ */
+
 #include "gstcompat.h"
 #include <gst/vaapi/gstvaapidisplay.h>
 #include <gst/vaapi/gstvaapiencoder_mpeg2.h>
diff --git a/gst/vaapi/gstvaapiencode_vp8.c b/gst/vaapi/gstvaapiencode_vp8.c
index 366cdfd8..276a5840 100644
--- a/gst/vaapi/gstvaapiencode_vp8.c
+++ b/gst/vaapi/gstvaapiencode_vp8.c
@@ -20,6 +20,20 @@
  *  Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:element-vaapiencode_vp8
+ * @short_description: A VA-API based VP8 video encoder
+ *
+ * Encodes raw video streams into VP8 bitstreams.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ *  gst-launch-1.0 -ev videotestsrc num-buffers=60 ! timeoverlay ! vaapiencode_vp8 ! matroskamux ! filesink location=test.mkv
+ * ]|
+ * </refsect2>
+ */
+
 #include "gstcompat.h"
 #include <gst/vaapi/gstvaapidisplay.h>
 #include <gst/vaapi/gstvaapiencoder_vp8.h>
diff --git a/gst/vaapi/gstvaapipostproc.c b/gst/vaapi/gstvaapipostproc.c
index 9583c27e..7d968a4a 100644
--- a/gst/vaapi/gstvaapipostproc.c
+++ b/gst/vaapi/gstvaapipostproc.c
@@ -21,12 +21,18 @@
  */
 
 /**
- * SECTION:gstvaapipostproc
- * @short_description: A video postprocessing filter
+ * SECTION:element-vaapipostproc
+ * @short_description: A VA-API base video postprocessing filter
  *
  * vaapipostproc consists in various postprocessing algorithms to be
- * applied to VA surfaces. So far, only basic bob deinterlacing is
- * implemented.
+ * applied to VA surfaces.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch-1.0 videotestsrc ! vaapipostproc ! video/x-raw width=1920, height=1080 ! vaapisink
+ * ]|
+ * </refsect2>
  */
 
 #include "gstcompat.h"
@@ -39,7 +45,7 @@
 #include "gstvaapivideomemory.h"
 
 #define GST_PLUGIN_NAME "vaapipostproc"
-#define GST_PLUGIN_DESC "A video postprocessing filter"
+#define GST_PLUGIN_DESC "A VA-API video postprocessing filter"
 
 GST_DEBUG_CATEGORY_STATIC (gst_debug_vaapipostproc);
 #define GST_CAT_DEFAULT gst_debug_vaapipostproc
diff --git a/gst/vaapi/gstvaapisink.c b/gst/vaapi/gstvaapisink.c
index f7fb5a2f..c73b2bb7 100644
--- a/gst/vaapi/gstvaapisink.c
+++ b/gst/vaapi/gstvaapisink.c
@@ -23,12 +23,19 @@
  */
 
 /**
- * SECTION:gstvaapisink
- * @short_description: A VA-API based videosink
+ * SECTION:element-vaapisink
+ * @short_description: A VA-API based video sink
  *
  * vaapisink renders video frames to a drawable (X #Window) on a local
  * display using the Video Acceleration (VA) API. The element will
  * create its own internal window and render into it.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch-1.0 videotestsrc ! vaapisink
+ * ]|
+ * </refsect2>
  */
 
 #include "gstcompat.h"