libs: va: Documentation and annotations.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-bad/-/merge_requests/2196>

4 files changed, 87 insertions, 11 deletions

diff --git a/gst-libs/gst/va/gstvadisplay.c b/gst-libs/gst/va/gstvadisplay.c
index 65a0511aa..4d6c73974 100644
--- a/gst-libs/gst/va/gstvadisplay.c
+++ b/gst-libs/gst/va/gstvadisplay.c
@@ -18,6 +18,24 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstvadisplay
+ * @title: GstVaDisplay
+ * @short_description: Generic VADisplay wrapper.
+ * @sources:
+ * - gstvadisplay.h
+ *
+ * It is a generic wrapper for VADisplay. To create new instances
+ * subclasses are required, depending on the display type to use
+ * (v.gr. DRM, X11, Wayland, etc.).
+ *
+ * The purpose of this class is to be shared among pipelines via
+ * #GstContext so all the VA processing elements will use the same
+ * display entry. Application developers can create their own
+ * subclass, based on their display, and shared it via the synced bus
+ * message for the application.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst-libs/gst/va/gstvadisplay.h b/gst-libs/gst/va/gstvadisplay.h
index 09def14da..a4f4fcb2a 100644
--- a/gst-libs/gst/va/gstvadisplay.h
+++ b/gst-libs/gst/va/gstvadisplay.h
@@ -60,6 +60,8 @@ typedef enum
  *
  * Check whether the display is the implementation of the specified
  * #GstVaImplementation type.
+ *
+ * Since: 1.20
  */
 #define GST_VA_DISPLAY_IS_IMPLEMENTATION(display, impl) \
   (gst_va_display_is_implementation (display, G_PASTE (GST_VA_IMPLEMENTATION_, impl)))
@@ -73,6 +75,7 @@ typedef enum
 
 /**
  * GstVaDisplay:
+ * @parent: parent #GstObject
  *
  * The common VA display object structure.
  *
@@ -80,24 +83,30 @@ typedef enum
  */
 struct _GstVaDisplay
 {
-  /*< private > */
   GstObject parent;
 };
 
 /**
  * GstVaDisplayClass:
+ * @parent_class: parent #GstObjectClass
  *
  * The common VA display object class structure.
- * @create_va_display: The function to create the real VA display.
  *
  * Since: 1.20
  */
 struct _GstVaDisplayClass
 {
-  /*< private > */
   GstObjectClass parent_class;
 
-  /*< public > */
+  /**
+   * GstVaDisplayClass::create_va_display:
+   * @self: a #GstVaDisplay instance
+   *
+   * This is called when the subclass has to create the internal
+   * VADisplay.
+   *
+   * Returns: The created VADisplay
+   */
   gpointer (*create_va_display) (GstVaDisplay * self);
 };
 
diff --git a/gst-libs/gst/va/gstvadisplay_drm.c b/gst-libs/gst/va/gstvadisplay_drm.c
index 092bab58b..d2a32fb52 100644
--- a/gst-libs/gst/va/gstvadisplay_drm.c
+++ b/gst-libs/gst/va/gstvadisplay_drm.c
@@ -18,6 +18,16 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstvadisplaydrm
+ * @title: GstVaDisplayDrm
+ * @short_description: VADisplay from a DRM device
+ * @sources:
+ * - gstvadisplay_drm.h
+ *
+ * This is a #GstVaDisplay subclass to instantiate with DRM devices.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -33,17 +43,29 @@
 #include <xf86drm.h>
 #endif
 
+/**
+ * GstVaDisplayDrm:
+ * @parent: parent #GstVaDisplay
+ *
+ * Since: 1.20
+ */
 struct _GstVaDisplayDrm
 {
   GstVaDisplay parent;
 
+  /* <private> */
   gchar *path;
   gint fd;
 };
 
+/**
+ * GstVaDisplayDrmClass:
+ * @parent_class: parent #GstVaDisplayClass
+ *
+ * Since: 1.20
+ */
 struct _GstVaDisplayDrmClass
 {
-  /*< private > */
   GstVaDisplayClass parent_class;
 };
 
@@ -173,9 +195,9 @@ gst_va_display_drm_init (GstVaDisplayDrm * self)
  * Creates a new #GstVaDisplay from a DRM device . It will try to open
  * and operate the device in @path.
  *
- * Returns: a newly allocated #GstVaDisplay if the specified DRM
- *     render device could be opened and initialized; otherwise %NULL
- *     is returned.
+ * Returns: (transfer full): a newly allocated #GstVaDisplay if the
+ *     specified DRM render device could be opened and initialized;
+ *     otherwise %NULL is returned.
  *
  * Since: 1.20
  **/
diff --git a/gst-libs/gst/va/gstvadisplay_wrapped.c b/gst-libs/gst/va/gstvadisplay_wrapped.c
index 4626a2f79..a153871e3 100644
--- a/gst-libs/gst/va/gstvadisplay_wrapped.c
+++ b/gst-libs/gst/va/gstvadisplay_wrapped.c
@@ -18,20 +18,42 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstvadisplaywrapped
+ * @title: GstVaDisplayWrapped
+ * @short_description: User's custom VADisplay
+ * @sources:
+ * - gstvadisplay_wrapped.h
+ *
+ * This is a #GstVaDisplay instantiaton subclass for custom created
+ * VADisplay, such as X11 or Wayland, wrapping it.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
 
 #include "gstvadisplay_wrapped.h"
 
+/**
+ * GstVaDisplayWrapped:
+ * @parent: parent #GstVaDisplay
+ *
+ * Since: 1.20
+ */
 struct _GstVaDisplayWrapped
 {
   GstVaDisplay parent;
 };
 
+/**
+ * GstVaDisplayWrappedClass:
+ * @parent_class: parent #GstVaDisplayClass
+ *
+ * Since: 1.20
+ */
 struct _GstVaDisplayWrappedClass
 {
-  /*< private > */
   GstVaDisplayClass parent_class;
 };
 
@@ -51,12 +73,17 @@ gst_va_display_wrapped_init (GstVaDisplayWrapped * self)
 
 /**
  * gst_va_display_wrapped_new:
- * @handle: a #VADisplay to wrap
+ * @handle: a VADisplay to wrap
  *
  * Creates a #GstVaDisplay wrapping an already created and initialized
  * VADisplay.
  *
- * Returns: a new #GstVaDisplay if @handle is valid, Otherwise %NULL.
+ * The lifetime of @handle must be hold by the provider while the
+ * pipeline is instantiated. Do not call vaTerminate on it while the
+ * pipeline is not in NULL state.
+ *
+ * Returns: (transfer full): a new #GstVaDisplay if @handle is valid,
+ *     Otherwise %NULL.
  *
  * Since: 1.20
  **/