Document surface & image pools. Drop obsolete gst_vaapi_video_pool_new() function.

gst-libs/gst/vaapi/gstvaapiimagepool.c

@@ -18,6 +18,11 @@
  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  */
 
+/**
+ * SECTION:gst-vaapi-image-pool
+ * @short_description:
+ */
+
 #include "config.h"
 #include "gstvaapiimagepool.h"
 
@@ -101,6 +106,16 @@ gst_vaapi_image_pool_init(GstVaapiImagePool *pool)
     priv->height        = 0;
 }
 
+/**
+ * gst_vaapi_image_pool_new:
+ * @display: a #GstVaapiDisplay
+ * @caps: a #GstCaps
+ *
+ * Creates a new #GstVaapiVideoPool of #GstVaapiImage with the
+ * specified dimensions in @caps.
+ *
+ * Return value: the newly allocated #GstVaapiVideoPool
+ */
 GstVaapiVideoPool *
 gst_vaapi_image_pool_new(GstVaapiDisplay *display, GstCaps *caps)
 {

gst-libs/gst/vaapi/gstvaapiimagepool.h

@@ -54,13 +54,24 @@ typedef struct _GstVaapiImagePool               GstVaapiImagePool;
 typedef struct _GstVaapiImagePoolPrivate        GstVaapiImagePoolPrivate;
 typedef struct _GstVaapiImagePoolClass          GstVaapiImagePoolClass;
 
+/**
+ * GstVaapiImagePool:
+ *
+ * A pool of lazily allocated #GstVaapiImage objects.
+ */
 struct _GstVaapiImagePool {
     /*< private >*/
     GstVaapiVideoPool parent_instance;
 
+    /*< private >*/
     GstVaapiImagePoolPrivate *priv;
 };
 
+/**
+ * GstVaapiImagePoolClass:
+ *
+ * A pool of lazily allocated #GstVaapiImage objects.
+ */
 struct _GstVaapiImagePoolClass {
     /*< private >*/
     GstVaapiVideoPoolClass parent_class;

gst-libs/gst/vaapi/gstvaapisurfacepool.c

@@ -18,6 +18,11 @@
  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  */
 
+/**
+ * SECTION:gst-vaapi-surface-pool
+ * @short_description:
+ */
+
 #include "config.h"
 #include "gstvaapisurfacepool.h"
 
@@ -101,6 +106,16 @@ gst_vaapi_surface_pool_init(GstVaapiSurfacePool *pool)
     priv->height        = 0;
 }
 
+/**
+ * gst_vaapi_surface_pool_new:
+ * @display: a #GstVaapiDisplay
+ * @caps: a #GstCaps
+ *
+ * Creates a new #GstVaapiVideoPool of #GstVaapiSurface with the
+ * specified dimensions in @caps.
+ *
+ * Return value: the newly allocated #GstVaapiVideoPool
+ */
 GstVaapiVideoPool *
 gst_vaapi_surface_pool_new(GstVaapiDisplay *display, GstCaps *caps)
 {

gst-libs/gst/vaapi/gstvaapisurfacepool.h

@@ -54,13 +54,24 @@ typedef struct _GstVaapiSurfacePool             GstVaapiSurfacePool;
 typedef struct _GstVaapiSurfacePoolPrivate      GstVaapiSurfacePoolPrivate;
 typedef struct _GstVaapiSurfacePoolClass        GstVaapiSurfacePoolClass;
 
+/**
+ * GstVaapiSurfacePool:
+ *
+ * A pool of lazily allocated #GstVaapiSurface objects.
+ */
 struct _GstVaapiSurfacePool {
     /*< private >*/
     GstVaapiVideoPool parent_instance;
 
+    /*< private >*/
     GstVaapiSurfacePoolPrivate *priv;
 };
 
+/**
+ * GstVaapiSurfacePoolClass:
+ *
+ * A pool of lazily allocated #GstVaapiSurface objects.
+ */
 struct _GstVaapiSurfacePoolClass {
     /*< private >*/
     GstVaapiVideoPoolClass parent_class;

gst-libs/gst/vaapi/gstvaapivideopool.c

@@ -18,6 +18,11 @@
  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  */
 
+/**
+ * SECTION:gst-vaapi-video-pool
+ * @short_description:
+ */
+
 #include "config.h"
 #include "gstvaapivideopool.h"
 
@@ -149,21 +154,32 @@ gst_vaapi_video_pool_class_init(GstVaapiVideoPoolClass *klass)
     object_class->set_property  = gst_vaapi_video_pool_set_property;
     object_class->get_property  = gst_vaapi_video_pool_get_property;
 
+    /**
+     * GstVaapiVideoPool:display:
+     *
+     * The #GstVaapiDisplay this pool is bound to.
+     */
     g_object_class_install_property
         (object_class,
          PROP_DISPLAY,
          g_param_spec_object("display",
-                             "display",
-                             "Gstreamer/VA display",
+                             "Display",
+                             "The GstVaapiDisplay this pool is bound to",
                              GST_VAAPI_TYPE_DISPLAY,
                              G_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
 
+    /**
+     * GstVaapiVidePool:caps:
+     *
+     * The video object capabilities represented as a #GstCaps. This
+     * shall hold at least the "width" and "height" properties.
+     */
     g_object_class_install_property
         (object_class,
          PROP_CAPS,
          g_param_spec_pointer("caps",
                               "caps",
-                              "Caps",
+                              "The video object capabilities",
                               G_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
 }
 
@@ -180,15 +196,15 @@ gst_vaapi_video_pool_init(GstVaapiVideoPool *pool)
     g_queue_init(&priv->free_objects);
 }
 
-GstVaapiVideoPool *
-gst_vaapi_video_pool_new(GstVaapiDisplay *display, GstCaps *caps)
-{
-    return g_object_new(GST_VAAPI_TYPE_VIDEO_POOL,
-                        "display", display,
-                        "caps",    caps,
-                        NULL);
-}
-
+/**
+ * gst_vaapi_video_pool_get_caps:
+ * @pool: a #GstVaapiVideoPool
+ *
+ * Retrieves the #GstCaps the @pool was created with. The @pool owns
+ * the returned object and it shall not be unref'ed.
+ *
+ * Return value: the #GstCaps the @pool was created with
+ */
 GstCaps *
 gst_vaapi_video_pool_get_caps(GstVaapiVideoPool *pool)
 {
@@ -197,6 +213,13 @@ gst_vaapi_video_pool_get_caps(GstVaapiVideoPool *pool)
     return pool->priv->caps;
 }
 
+/*
+ * gst_vaapi_video_pool_set_caps:
+ * @pool: a #GstVaapiVideoPool
+ * @caps: a #GstCaps
+ *
+ * Binds new @caps to the @pool and notify the sub-classes.
+ */
 void
 gst_vaapi_video_pool_set_caps(GstVaapiVideoPool *pool, GstCaps *caps)
 {
@@ -208,6 +231,17 @@ gst_vaapi_video_pool_set_caps(GstVaapiVideoPool *pool, GstCaps *caps)
         klass->set_caps(pool, caps);
 }
 
+/**
+ * gst_vaapi_video_pool_get_object:
+ * @pool: a #GstVaapiVideoPool
+ *
+ * Retrieves a new object from the @pool, or allocates a new one if
+ * none was found. The @pool holds a reference on the returned object
+ * and thus shall be released through gst_vaapi_video_pool_put_object()
+ * when it's no longer needed.
+ *
+ * Return value: a possibly newly allocated object, or %NULL on error
+ */
 gpointer
 gst_vaapi_video_pool_get_object(GstVaapiVideoPool *pool)
 {
@@ -229,6 +263,15 @@ gst_vaapi_video_pool_get_object(GstVaapiVideoPool *pool)
     return g_object_ref(object);
 }
 
+/**
+ * gst_vaapi_video_pool_put_object:
+ * @pool: a #GstVaapiVideoPool
+ * @object: the object to add to the pool
+ *
+ * Pushes the @object back into the pool. The @object shall be
+ * previously allocated from the @pool. Calling this function with an
+ * arbitrary object yields undefined behaviour.
+ */
 void
 gst_vaapi_video_pool_put_object(GstVaapiVideoPool *pool, gpointer object)
 {

gst-libs/gst/vaapi/gstvaapivideopool.h

@@ -54,13 +54,27 @@ typedef struct _GstVaapiVideoPool               GstVaapiVideoPool;
 typedef struct _GstVaapiVideoPoolPrivate        GstVaapiVideoPoolPrivate;
 typedef struct _GstVaapiVideoPoolClass          GstVaapiVideoPoolClass;
 
+/**
+ * GstVaapiVideoPool:
+ *
+ * A pool of lazily allocated video objects. e.g. surfaces, images.
+ */
 struct _GstVaapiVideoPool {
     /*< private >*/
     GObject parent_instance;
 
+    /*< private >*/
     GstVaapiVideoPoolPrivate *priv;
 };
 
+/**
+ * GstVaapiVideoPoolClass:
+ * @set_caps: virtual function for notifying the subclass of the
+ *   negotiated caps
+ * @alloc_object: virtual function for allocating a video pool object
+ *
+ * A pool base class used to hold video objects. e.g. surfaces, images.
+ */
 struct _GstVaapiVideoPoolClass {
     /*< private >*/
     GObjectClass parent_class;