va: Complete library and plugin documentation.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/1025>

subprojects/gst-plugins-bad/docs/libs/va/index.md

@@ -0,0 +1,11 @@
+# VA library
+
+Library for sharing and handling VADisplay inside GStreamer's pipelines.
+
+This library should be linked to by getting cflags and libs from
+gstreamer-va{{ gst_api_version.md }}.pc
+
+More information about VA-API
+[http://intel.github.io/libva/index.html](http://intel.github.io/libva/index.html)
+
+> NOTE: This library API is considered *unstable*

subprojects/gst-plugins-bad/docs/libs/va/sitemap.txt

@@ -0,0 +1 @@
+gi-index

subprojects/gst-plugins-bad/gst-libs/gst/va/gstva.h

@@ -25,6 +25,14 @@
 #pragma message ("You can define GST_USE_UNSTABLE_API to avoid this warning.")
 #endif
 
+/**
+ * GstVaFeature:
+ * @GST_VA_FEATURE_DISABLED: The feature is disabled.
+ * @GST_VA_FEATURE_ENABLED: The feature is enabled.
+ * @GST_VA_FEATURE_AUTO: The feature is enabled automatically.
+ *
+ * Since: 1.22
+ */
 typedef enum
 {
   GST_VA_FEATURE_DISABLED,

subprojects/gst-plugins-bad/gst-libs/gst/va/gstvaallocator.c

@@ -18,6 +18,19 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstvaallocator
+ * @title: VA allocators
+ * @short_description: VA allocators
+ * @sources:
+ * - gstvaallocator.h
+ *
+ * There are two types of VA allocators:
+ *
+ * * #GstVaAllocator
+ * * #GstVaDmabufAllocator
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -236,6 +249,15 @@ gst_va_memory_pool_surface_inc (GstVaMemoryPool * self)
 
 /*=========================== GstVaDmabufAllocator ===========================*/
 
+/**
+ * GstVaDmabufAllocator:
+ *
+ * A pooled memory allocator backed by the DMABufs exported from a
+ * VASurfaceID. Also it is possible to import DMAbufs into a
+ * VASurfaceID.
+ *
+ * Since: 1.22
+ */
 typedef struct _GstVaDmabufAllocator GstVaDmabufAllocator;
 typedef struct _GstVaDmabufAllocatorClass GstVaDmabufAllocatorClass;
 
@@ -445,6 +467,17 @@ gst_va_dmabuf_allocator_init (GstVaDmabufAllocator * self)
   gst_va_memory_pool_init (&self->pool);
 }
 
+/**
+ * gst_va_dmabuf_allocator_new:
+ * @display: a #GstVaDisplay
+ *
+ * Instanciate a new pooled allocator backed with both DMABuf and
+ * VASurfaceID.
+ *
+ * Returns: a new allocated #GstAllocator
+ *
+ * Since: 1.22
+ */
 GstAllocator *
 gst_va_dmabuf_allocator_new (GstVaDisplay * display)
 {
@@ -502,7 +535,7 @@ gst_va_dmabuf_memory_release (GstMiniObject * mini_object)
   return FALSE;
 }
 
-/* Creates an exported VASurface and adds it as @buffer's memories
+/* Creates an exported VASurfaceID and adds it as @buffer's memories
  * qdata
  *
  * If @info is not NULL, a dummy (non-pooled) buffer is created to
@@ -661,6 +694,18 @@ failed:
   }
 }
 
+/**
+ * gst_va_dmabuf_allocator_setup_buffer:
+ * @allocator: a #GstAllocator
+ * @buffer: an empty #GstBuffer
+ *
+ * This funciton creates a new VASurfaceID and exposes its DMABufs,
+ * later it populates the @buffer with those DMABufs.
+ *
+ * Return: %TRUE if @buffer is populated correctly; %FALSE otherwise.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_dmabuf_allocator_setup_buffer (GstAllocator * allocator,
     GstBuffer * buffer)
@@ -750,6 +795,19 @@ gst_va_dmabuf_allocator_prepare_buffer_unlocked (GstVaDmabufAllocator * self,
   return buf->surface;
 }
 
+/**
+ * gst_va_dmabuf_allocator_prepare_buffer:
+ * @allocator: a #GstAllocator
+ * @buffer: an empty #GstBuffer
+ *
+ * This method will populate @buffer with pooled VASurfaceID/DMABuf
+ * memories. It doesn't allocate new VASurfacesID.
+ *
+ * Returns: %TRUE if @buffer was populated correctly; %FALSE
+ * otherwise.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_dmabuf_allocator_prepare_buffer (GstAllocator * allocator,
     GstBuffer * buffer)
@@ -768,6 +826,14 @@ gst_va_dmabuf_allocator_prepare_buffer (GstAllocator * allocator,
   return (surface != VA_INVALID_ID);
 }
 
+/**
+ * gst_va_dmabuf_allocator_flush:
+ * @allocator: a #GstAllocator
+ *
+ * Removes all the memories in @allocator's pool.
+ *
+ * Since: 1.22
+ */
 void
 gst_va_dmabuf_allocator_flush (GstAllocator * allocator)
 {
@@ -780,6 +846,17 @@ gst_va_dmabuf_allocator_flush (GstAllocator * allocator)
   gst_va_memory_pool_flush (&self->pool, self->display);
 }
 
+/**
+ * gst_va_dmabuf_allocator_try:
+ * @allocator: a #GstAllocator
+ *
+ * Try to allocate a test buffer in order to verify that the
+ * allocator's configuration is valid.
+ *
+ * Returns: %TRUE if the configuration is valid; %FALSE otherwise.
+ *
+ * Since: 1.22
+ */
 static gboolean
 gst_va_dmabuf_allocator_try (GstAllocator * allocator)
 {
@@ -803,6 +880,25 @@ gst_va_dmabuf_allocator_try (GstAllocator * allocator)
   return ret;
 }
 
+/**
+ * gst_va_dmabuf_allocator_set_format:
+ * @allocator: a #GstAllocator
+ * @info: a #GstVideoInfo
+ * @usage_hint: VA usage hint
+ *
+ * Sets the configuration defined by @info and @usage_hint for
+ * @allocator, and it tries the configuration, if @allocator has not
+ * allocated memories yet.
+ *
+ * If @allocator has memory allocated already, and frame size and
+ * format in @info are the same as currently configured in @allocator,
+ * the rest of @info parameters are updated internally.
+ *
+ * Returns: %TRUE if the configuration is valid or updated; %FALSE if
+ * configuration is not valid or not updated.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_dmabuf_allocator_set_format (GstAllocator * allocator,
     GstVideoInfo * info, guint usage_hint)
@@ -839,6 +935,19 @@ gst_va_dmabuf_allocator_set_format (GstAllocator * allocator,
   return ret;
 }
 
+/**
+ * gst_va_dmabuf_allocator_get_format:
+ * @allocator: a #GstAllocator
+ * @info: (out) (optional): a #GstVideoInfo
+ * @usage_hint: (out) (optional): VA usage hint
+ *
+ * Gets current internal configuration of @allocator.
+ *
+ * Returns: %TRUE if @allocator is already configured; %FALSE
+ * otherwise.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_dmabuf_allocator_get_format (GstAllocator * allocator,
     GstVideoInfo * info, guint * usage_hint)
@@ -856,7 +965,29 @@ gst_va_dmabuf_allocator_get_format (GstAllocator * allocator,
   return TRUE;
 }
 
+/**
+ * gst_va_dmabuf_memories_setup:
+ * @display: a #GstVaDisplay
+ * @info: a #GstVideoInfo
+ * @n_planes: number of planes
+ * @mem: (array fixed-size=4) (element-type GstMemory): Memories. One
+ *     per plane.
+ * @fds: (array length=n_planes) (element-type uintptr_t): array of
+ *     DMABuf file descriptors.
+ * @offset: (array fixed-size=4) (element-type gsize): array of memory
+ *     offsets.
+ * @usage_hint: VA usage hint.
+ *
+ * It imports the array of @mem, representing a single frame, into a
+ * VASurfaceID and it's attached into every @mem.
+ *
+ * Returns: %TRUE if frame is imported correctly into a VASurfaceID;
+ * %FALSE otherwise.
+ *
+ * Since: 1.22
+ */
 /* XXX: use a surface pool to control the created surfaces */
+/* XXX: remove n_planes argument and use GST_VIDEO_INFO_N_PLANES (info) */
 gboolean
 gst_va_dmabuf_memories_setup (GstVaDisplay * display, GstVideoInfo * info,
     guint n_planes, GstMemory * mem[GST_VIDEO_MAX_PLANES],
@@ -929,6 +1060,13 @@ gst_va_dmabuf_memories_setup (GstVaDisplay * display, GstVideoInfo * info,
 
 /*===================== GstVaAllocator / GstVaMemory =========================*/
 
+/**
+ * GstVaAllocator:
+ *
+ * A pooled memory allocator backed by VASurfaceID.
+ *
+ * Since: 1.22
+ */
 typedef struct _GstVaAllocator GstVaAllocator;
 typedef struct _GstVaAllocatorClass GstVaAllocatorClass;
 
@@ -1423,6 +1561,16 @@ gst_va_memory_release (GstMiniObject * mini_object)
   return FALSE;
 }
 
+/**
+ * gst_va_allocator_alloc:
+ * @allocator: a #GstAllocator
+ *
+ * Allocate a new VASurfaceID backed #GstMemory.
+ *
+ * Returns: a #GstMemory backed with a VASurfaceID; %NULL, otherwise.
+ *
+ * Since: 1.22
+ */
 GstMemory *
 gst_va_allocator_alloc (GstAllocator * allocator)
 {
@@ -1461,6 +1609,18 @@ gst_va_allocator_alloc (GstAllocator * allocator)
   return GST_MEMORY_CAST (mem);
 }
 
+/**
+ * gst_va_allocator_new:
+ * @display: a #GstVaDisplay
+ * @surface_formats: (element-type guint) (transfer full): a #GArray
+ *     of valid #GstVideoFormat for surfaces in current VA context.
+ *
+ * Instanciate a new pooled #GstAllocator backed by VASurfaceID.
+ *
+ * Returns: a #GstVaDisplay
+ *
+ * Since: 1.22
+ */
 GstAllocator *
 gst_va_allocator_new (GstVaDisplay * display, GArray * surface_formats)
 {
@@ -1476,6 +1636,17 @@ gst_va_allocator_new (GstVaDisplay * display, GArray * surface_formats)
   return GST_ALLOCATOR (self);
 }
 
+/**
+ * gst_va_allocator_setup_buffer:
+ * @allocator: a #GstAllocator
+ * @buffer: a #GstBuffer
+ *
+ * Populates an empty @buffer with a VASuface backed #GstMemory.
+ *
+ * Returns: %TRUE if @buffer is populated; %FALSE otherwise.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_allocator_setup_buffer (GstAllocator * allocator, GstBuffer * buffer)
 {
@@ -1507,6 +1678,19 @@ gst_va_allocator_prepare_buffer_unlocked (GstVaAllocator * self,
   return surface;
 }
 
+/**
+ * gst_va_allocator_prepare_buffer:
+ * @allocator: a #GstAllocator
+ * @buffer: an empty #GstBuffer
+ *
+ * This method will populate @buffer with pooled VASurfaceID
+ * memories. It doesn't allocate new VASurfacesID.
+ *
+ * Returns: %TRUE if @buffer was populated correctly; %FALSE
+ * otherwise.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_allocator_prepare_buffer (GstAllocator * allocator, GstBuffer * buffer)
 {
@@ -1524,6 +1708,14 @@ gst_va_allocator_prepare_buffer (GstAllocator * allocator, GstBuffer * buffer)
   return (surface != VA_INVALID_ID);
 }
 
+/**
+ * gst_va_allocator_flush:
+ * @allocator: a #GstAllocator
+ *
+ * Removes all the memories in @allocator's pool.
+ *
+ * Since: 1.22
+ */
 void
 gst_va_allocator_flush (GstAllocator * allocator)
 {
@@ -1536,6 +1728,17 @@ gst_va_allocator_flush (GstAllocator * allocator)
   gst_va_memory_pool_flush (&self->pool, self->display);
 }
 
+/**
+ * gst_va_allocator_try:
+ * @allocator: a #GstAllocator
+ *
+ * Try to allocate a test buffer in order to verify that the
+ * allocator's configuration is valid.
+ *
+ * Returns: %TRUE if the configuration is valid; %FALSE otherwise.
+ *
+ * Since: 1.22
+ */
 static gboolean
 gst_va_allocator_try (GstAllocator * allocator)
 {
@@ -1585,6 +1788,26 @@ gst_va_allocator_try (GstAllocator * allocator)
   return TRUE;
 }
 
+/**
+ * gst_va_allocator_set_format:
+ * @allocator: a #GstAllocator
+ * @info: (inout): a #GstVideoInfo
+ * @usage_hint: VA usage hint
+ * @use_derived: a #GstVaFeature
+ *
+ * Sets the configuration defined by @info, @usage_hint and
+ * @use_derived for @allocator, and it tries the configuration, if
+ * @allocator has not allocated memories yet.
+ *
+ * If @allocator has memory allocated already, and frame size and
+ * format in @info are the same as currently configured in @allocator,
+ * the rest of @info parameters are updated internally.
+ *
+ * Returns: %TRUE if the configuration is valid or updated; %FALSE if
+ * configuration is not valid or not updated.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_allocator_set_format (GstAllocator * allocator, GstVideoInfo * info,
     guint usage_hint, GstVaFeature use_derived)
@@ -1622,6 +1845,21 @@ gst_va_allocator_set_format (GstAllocator * allocator, GstVideoInfo * info,
   return ret;
 }
 
+/**
+ * gst_va_allocator_get_format:
+ * @allocator: a #GstAllocator
+ * @info: (out) (optional): a #GstVideoInfo
+ * @usage_hint: (out) (optional): VA usage hint
+ * @use_derived: (out) (optional): a #GstVaFeature if derived images
+ *     are used for buffer mapping.
+ *
+ * Gets current internal configuration of @allocator.
+ *
+ * Returns: %TRUE if @allocator is already configured; %FALSE
+ * otherwise.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_allocator_get_format (GstAllocator * allocator, GstVideoInfo * info,
     guint * usage_hint, GstVaFeature * use_derived)
@@ -1644,6 +1882,15 @@ gst_va_allocator_get_format (GstAllocator * allocator, GstVideoInfo * info,
   return TRUE;
 }
 
+/**
+ * gst_va_allocator_set_hacks: (skip)
+ * @allocator: a #GstAllocator
+ * @hacks: hacks id to set
+ *
+ * Internal method to set allocator specific logic changes.
+ *
+ * Since: 1.22
+ */
 void
 gst_va_allocator_set_hacks (GstAllocator * allocator, guint32 hacks)
 {
@@ -1657,6 +1904,14 @@ gst_va_allocator_set_hacks (GstAllocator * allocator, guint32 hacks)
 
 /*============ Utilities =====================================================*/
 
+/**
+ * gst_va_memory_get_surface:
+ * @mem: a #GstMemory
+ *
+ * Returns: (type guint): the VASurfaceID in @mem.
+ *
+ * Since: 1.22
+ */
 VASurfaceID
 gst_va_memory_get_surface (GstMemory * mem)
 {
@@ -1680,6 +1935,14 @@ gst_va_memory_get_surface (GstMemory * mem)
   return surface;
 }
 
+/**
+ * gst_va_buffer_get_surface:
+ * @buffer: a #GstBuffer
+ *
+ * Returns: (type guint): the VASurfaceID in @buffer.
+ *
+ * Since: 1.22
+ */
 VASurfaceID
 gst_va_buffer_get_surface (GstBuffer * buffer)
 {
@@ -1692,6 +1955,20 @@ gst_va_buffer_get_surface (GstBuffer * buffer)
   return gst_va_memory_get_surface (mem);
 }
 
+/**
+ * gst_va_buffer_create_aux_surface:
+ * @buffer: a #GstBuffer
+ *
+ * Creates a new VASurfaceID with @buffer's allocator and attached it
+ * to it.
+ *
+ * *This method is used only by plugin's internal VA decoder.*
+ *
+ * Returns: %TRUE if the new VASurfaceID is attached to @buffer
+ *     correctly; %FALSE, otherwise.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_buffer_create_aux_surface (GstBuffer * buffer)
 {
@@ -1706,7 +1983,7 @@ gst_va_buffer_create_aux_surface (GstBuffer * buffer)
   if (!mem)
     return FALSE;
 
-  /* Already created it. */
+  /* Already created. */
   surface_buffer = gst_mini_object_get_qdata (GST_MINI_OBJECT (mem),
       gst_va_buffer_aux_surface_quark ());
   if (surface_buffer)
@@ -1771,6 +2048,15 @@ gst_va_buffer_create_aux_surface (GstBuffer * buffer)
   return TRUE;
 }
 
+/**
+ * gst_va_buffer_get_aux_surface:
+ * @buffer: a #GstBuffer
+ *
+ * Returns: (type guint): the VASurfaceID attached to
+ *     @buffer.
+ *
+ * Since: 1.22
+ */
 VASurfaceID
 gst_va_buffer_get_aux_surface (GstBuffer * buffer)
 {

subprojects/gst-plugins-bad/gst-libs/gst/va/gstvaallocator.h

@@ -72,8 +72,22 @@ gboolean              gst_va_dmabuf_memories_setup        (GstVaDisplay * displa
 #define GST_IS_VA_ALLOCATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GST_TYPE_VA_ALLOCATOR))
 #define GST_VA_ALLOCATOR_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), GST_TYPE_VA_ALLOCATOR, GstVaAllocatorClass))
 
+/**
+ * GST_ALLOCATOR_VASURFACE:
+ *
+ * Since: 1.22
+ */
 #define GST_ALLOCATOR_VASURFACE   "VAMemory"
 
+/**
+ * GST_MAP_VA:
+ *
+ * Flag indicating that we should map the VASurfaceID instead of to
+ * system memory, so users can use libva primitives to operate with
+ * that surface.
+ *
+ * Since: 1.22
+ */
 #define GST_MAP_VA (GST_MAP_FLAG_LAST << 1)
 
 GST_VA_API

subprojects/gst-plugins-bad/gst-libs/gst/va/gstvadisplay.c

@@ -23,6 +23,7 @@
  * @title: GstVaDisplay
  * @short_description: Generic VADisplay wrapper.
  * @sources:
+ * - gstva.h
  * - gstvadisplay.h
  *
  * It is a generic wrapper for VADisplay. To create new instances

subprojects/gst-plugins-bad/gst-libs/gst/va/gstvapool.c

@@ -18,6 +18,18 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstvapool
+ * @title: GstVaPool
+ * @short_description: VA Buffer pool
+ * @sources:
+ * - gstvapool.h
+ *
+ * @GstVaPool is a buffer pool for VA allocators.
+ *
+ * Since: 1.22
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -27,6 +39,14 @@
 GST_DEBUG_CATEGORY_STATIC (gst_va_pool_debug);
 #define GST_CAT_DEFAULT gst_va_pool_debug
 
+/**
+ * GstVaPool:
+ *
+ * A buffer pool that uses either #GstVaAllocator or
+ * #GstVaDmabufAllocator to pre-allocate and recycle #GstBuffers.
+ *
+ * Since: 1.22
+ */
 typedef struct _GstVaPool GstVaPool;
 typedef struct _GstVaPoolClass GstVaPoolClass;
 
@@ -340,6 +360,13 @@ gst_va_pool_init (GstVaPool * self)
 {
 }
 
+/**
+ * gst_va_pool_new:
+ *
+ * Returns: A new #GstBufferPool for VA allocators.
+ *
+ * Since: 1.22
+ */
 GstBufferPool *
 gst_va_pool_new (void)
 {
@@ -353,6 +380,17 @@ gst_va_pool_new (void)
   return GST_BUFFER_POOL_CAST (pool);
 }
 
+/**
+ * gst_buffer_pool_config_set_va_allocation_params:
+ * @config: the #GstStructure with the pool's configuration.
+ * @usage_hint: the VA usage hint for new VASurfaceID.
+ * @use_derived: a #GstVaFeature for derived mapping (only used when
+ *     VA allocator).
+ *
+ * Sets the usage hint for the buffers handled by the buffer pool.
+ *
+ * Since: 1.22
+ */
 void
 gst_buffer_pool_config_set_va_allocation_params (GstStructure * config,
     guint usage_hint, GstVaFeature use_derived)
@@ -361,6 +399,19 @@ gst_buffer_pool_config_set_va_allocation_params (GstStructure * config,
       "use-derived", GST_TYPE_VA_FEATURE, use_derived, NULL);
 }
 
+/**
+ * gst_buffer_pool_config_set_va_alignment:
+ * @config: the #GstStructure with the pool's configuration.
+ * @align: a #GstVideoAlignment
+ *
+ * Video alignment is not handled as expected by VA since it uses
+ * opaque surfaces, not directly mappable memory. Still, decoders
+ * might need to request bigger surfaces for coded size rather than
+ * display sizes. This method will set the coded size to bufferpool's
+ * configuration, out of the typical video aligment.
+ *
+ * Since: 1.20.2
+ */
 void
 gst_buffer_pool_config_set_va_alignment (GstStructure * config,
     const GstVideoAlignment * align)
@@ -372,6 +423,15 @@ gst_buffer_pool_config_set_va_alignment (GstStructure * config,
       "va-padding-right", G_TYPE_UINT, align->padding_right, NULL);
 }
 
+/**
+ * gst_va_pool_requires_video_meta:
+ * @pool: the #GstBufferPool
+ *
+ * Retuns: %TRUE if @pool always add #GstVideoMeta to its
+ *     buffers. Otherwise, %FALSE.
+ *
+ * Since: 1.22
+ */
 gboolean
 gst_va_pool_requires_video_meta (GstBufferPool * pool)
 {
@@ -381,6 +441,24 @@ gst_va_pool_requires_video_meta (GstBufferPool * pool)
   return GST_VA_POOL (pool)->force_videometa;
 }
 
+/**
+ * gst_va_pool_new_with_config:
+ * @caps: the #GstCaps of the buffers handled by the new pool.
+ * @size: the size of the frames to hold.
+ * @min_buffers: minimum number of frames to create.
+ * @max_buffers: maximum number of frames to create.
+ * @usage_hint: VA usage hint
+ * @use_derived: a #GstVaFeature for derived mapping (only used when
+ *     VA allocator).
+ * @allocator: the VA allocator to use.
+ * @alloc_params: #GstAllocationParams to use.
+ *
+ * Returns: a new #GstBufferPool that handles VASurfacesID-backed
+ *     buffers. If the pool cannot be configured correctly, %NULL is
+ *     returned.
+ *
+ * Since: 1.22
+ */
 GstBufferPool *
 gst_va_pool_new_with_config (GstCaps * caps, guint size, guint min_buffers,
     guint max_buffers, guint usage_hint, GstVaFeature use_derived,

subprojects/gst-plugins-bad/gst-libs/gst/va/gstvasurfacecopy.h

@@ -28,6 +28,8 @@
 G_BEGIN_DECLS
 
 /**
+ * GstVaSurfaceCopy:
+ *
  * Opaque object helper for copying surfaces.
  *
  * It's purpose is to avoid circular dependencies.

subprojects/gst-plugins-bad/gst-libs/gst/va/gstvautils.c

@@ -18,6 +18,14 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstvautils
+ * @title: GstVaUtils
+ * @short_description: Utility functions for context handling
+ * @sources:
+ * - gstvautils.h
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -244,11 +252,11 @@ done:
  * @render_device_path: the #gchar string of render device path
  * @display_ptr: (out) (transfer full): The #GstVaDisplay to set
  *
- * Called by elements in their GstElement::set_context() vmehtods.
+ * Called by elements in their #GstElementClass::set_context vmethod.
  * It gets a valid #GstVaDisplay if @context has it.
  *
- * Returns: whether the @display_ptr could be successfully set to
- * a valid #GstVaDisplay in the @context
+ * Returns: whether the @display_ptr could be successfully set to a
+ * valid #GstVaDisplay in the @context
  *
  * Since: 1.22
  **/

subprojects/gst-plugins-bad/gst-libs/gst/va/gstvavideoformat.c

@@ -229,9 +229,9 @@ get_format_map_from_va_image_format (const VAImageFormat * va_format)
 }
 
 GstVideoFormat
-gst_va_video_format_from_va_fourcc (guint va_fourcc)
+gst_va_video_format_from_va_fourcc (guint fourcc)
 {
-  const struct FormatMap *map = get_format_map_from_va_fourcc (va_fourcc);
+  const struct FormatMap *map = get_format_map_from_va_fourcc (fourcc);
 
   return map ? map->format : GST_VIDEO_FORMAT_UNKNOWN;
 }
@@ -276,6 +276,14 @@ gst_va_video_format_from_va_image_format (const VAImageFormat * va_format)
   return map ? map->format : GST_VIDEO_FORMAT_UNKNOWN;
 }
 
+/*
+ * XXX: Not all the surfaces formats can be converted into every image
+ * format when mapped. This funtion will return the #GstVideoFormat
+ * that a surface will map when it is asked for a @image_format.
+ *
+ * Current implementation only seeks for @image_format in
+ * @surface_formats.
+ */
 GstVideoFormat
 gst_va_video_surface_format_from_image_format (GstVideoFormat image_format,
     GArray * surface_formats)

subprojects/gst-plugins-bad/gst-libs/gst/va/meson.build

@@ -4,8 +4,11 @@ va_sources = files(
   'gstvadisplay_drm.c',
   'gstvadisplay_wrapped.c',
   'gstvapool.c',
-  'gstvasurfacecopy.c',
   'gstvautils.c',
+)
+
+va_sources_priv = files(
+  'gstvasurfacecopy.c',
   'gstvavideoformat.c',
   'vasurfaceimage.c',
 )
@@ -54,7 +57,7 @@ va_enumtypes_h = va_enums[1]
 va_gen_sources = [va_enumtypes_h]
 
 gstva = library('gstva-' + api_version,
-  va_sources, va_enums,
+  va_sources, va_sources_priv, va_enums,
   c_args : gst_plugins_bad_args + ['-DGST_USE_UNSTABLE_API', '-DBUILDING_GST_VA', '-DG_LOG_DOMAIN="GStreamer-VA"'],
   include_directories : [configinc, libsinc],
   version : libversion,

subprojects/gst-plugins-bad/sys/va/gstjpegdecoder.c

@@ -17,12 +17,6 @@
  * Boston, MA 02110-1301, USA.
  */
 
-/**
- * SECTION:gstjpegdecoder
- * @title: GstJpegDecoder
- * @short_description: Base class to implement stateless JPEG decoders
- */
-
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -60,6 +54,13 @@ struct _GstJpegDecoderPrivate
 GST_DEBUG_CATEGORY (gst_jpeg_decoder_debug);
 #define GST_CAT_DEFAULT gst_jpeg_decoder_debug
 
+/**
+ * GstJpegDecoder:
+ *
+ * Base class to implement statelesss JPEG decoders
+ *
+ * Since: 1.22
+ */
 #define parent_class gst_jpeg_decoder_parent_clas
 G_DEFINE_ABSTRACT_TYPE_WITH_CODE (GstJpegDecoder, gst_jpeg_decoder,
     GST_TYPE_VIDEO_DECODER, G_ADD_PRIVATE (GstJpegDecoder);
@@ -81,6 +82,8 @@ gst_jpeg_decoder_class_init (GstJpegDecoderClass * klass)
   decoder_class->set_format = GST_DEBUG_FUNCPTR (gst_jpeg_decoder_set_format);
   decoder_class->handle_frame =
       GST_DEBUG_FUNCPTR (gst_jpeg_decoder_handle_frame);
+
+  gst_type_mark_as_plugin_api (GST_TYPE_JPEG_DECODER, 0);
 }
 
 static void

subprojects/gst-plugins-bad/sys/va/gstjpegdecoder.h

@@ -61,6 +61,8 @@ struct _GstJpegDecoderScan
  * GstJpegDecoder:
  *
  * The opaque #GstJpegDecoder data structure.
+ *
+ * Since: 1.22
  */
 struct _GstJpegDecoder
 {

subprojects/gst-plugins-bad/sys/va/gstvabasetransform.c

@@ -629,6 +629,13 @@ gst_va_base_transform_class_init (GstVaBaseTransformClass * klass)
   element_class->change_state =
       GST_DEBUG_FUNCPTR (gst_va_base_transform_change_state);
 
+  /**
+   * GstVaBaseTransform:device-path:
+   *
+   * It shows the DRM device path used for the VA operation, if any.
+   *
+   * Since: 1.22
+   */
   properties[PROP_DEVICE_PATH] = g_param_spec_string ("device-path",
       "Device Path", "DRM device path", NULL,
       G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);

subprojects/gst-plugins-bad/sys/va/gstvacompositor.c

@@ -57,10 +57,18 @@
 GST_DEBUG_CATEGORY_STATIC (gst_va_compositor_debug);
 #define GST_CAT_DEFAULT gst_va_compositor_debug
 
+/**
+ * GstVaCompositorPad:
+ *
+ * VA aggregator pad.
+ *
+ * Since: 1.22
+ */
 struct _GstVaCompositorPad
 {
   GstVideoAggregatorPad parent;
 
+  /*< private> */
   GstBufferPool *pool;
 
   gint xpos;
@@ -1352,6 +1360,7 @@ gst_va_compositor_class_init (gpointer g_class, gpointer class_data)
   gst_element_class_add_pad_template (element_class, sink_pad_templ);
   gst_pad_template_set_documentation_caps (sink_pad_templ,
       gst_caps_ref (doc_caps));
+  gst_type_mark_as_plugin_api (GST_TYPE_VA_COMPOSITOR_PAD, 0);
 
   src_pad_templ = gst_pad_template_new_with_gtype ("src", GST_PAD_SRC,
       GST_PAD_ALWAYS, caps, GST_TYPE_AGGREGATOR_PAD);
@@ -1388,6 +1397,8 @@ gst_va_compositor_class_init (gpointer g_class, gpointer class_data)
       "Scale Method", "Scale method to use", GST_TYPE_VA_SCALE_METHOD,
       VA_FILTER_SCALING_DEFAULT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 
+  gst_type_mark_as_plugin_api (GST_TYPE_VA_SCALE_METHOD, 0);
+
   g_object_class_install_properties (object_class, N_PROPERTIES, properties);
 
   g_free (long_name);

subprojects/gst-plugins-bad/sys/va/gstvafilter.c

@@ -1913,6 +1913,11 @@ gst_va_filter_has_video_format (GstVaFilter * self, GstVideoFormat format,
   return FALSE;
 }
 
+/**
+ * GstVaScaleMethod:
+ *
+ * Since: 1.22
+ */
 GType
 gst_va_scale_method_get_type (void)
 {

subprojects/gst-plugins-bad/sys/va/gstvah264enc.c

@@ -3556,16 +3556,6 @@ gst_va_h264_enc_class_init (gpointer g_klass, gpointer class_data)
   }
 
   g_object_class_install_properties (object_class, n_props, properties);
-
-  /**
-   * GstVaFeature:
-   * @GST_VA_FEATURE_DISABLED: The feature is disabled.
-   * @GST_VA_FEATURE_ENABLED: The feature is enabled.
-   * @GST_VA_FEATURE_AUTO: The feature is enabled automatically.
-   *
-   * Since: 1.22
-   */
-  gst_type_mark_as_plugin_api (GST_TYPE_VA_FEATURE, 0);
 }
 
 static GstCaps *