From dabb75745850f83aca9ca84750ccd4ef61ed7053 Mon Sep 17 00:00:00 2001 From: gb Date: Fri, 19 Mar 2010 16:08:48 +0000 Subject: [PATCH] Document surface & image pools. Drop obsolete gst_vaapi_video_pool_new() function. --- gst-libs/gst/vaapi/gstvaapiimagepool.c | 15 +++++++ gst-libs/gst/vaapi/gstvaapiimagepool.h | 11 ++++++ gst-libs/gst/vaapi/gstvaapisurfacepool.c | 15 +++++++ gst-libs/gst/vaapi/gstvaapisurfacepool.h | 11 ++++++ gst-libs/gst/vaapi/gstvaapivideopool.c | 67 ++++++++++++++++++++++++++------ gst-libs/gst/vaapi/gstvaapivideopool.h | 14 +++++++ 6 files changed, 121 insertions(+), 12 deletions(-) diff --git a/gst-libs/gst/vaapi/gstvaapiimagepool.c b/gst-libs/gst/vaapi/gstvaapiimagepool.c index 8a6a27c..435140b 100644 --- a/gst-libs/gst/vaapi/gstvaapiimagepool.c +++ b/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) { diff --git a/gst-libs/gst/vaapi/gstvaapiimagepool.h b/gst-libs/gst/vaapi/gstvaapiimagepool.h index 67d0086..8e03277 100644 --- a/gst-libs/gst/vaapi/gstvaapiimagepool.h +++ b/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; diff --git a/gst-libs/gst/vaapi/gstvaapisurfacepool.c b/gst-libs/gst/vaapi/gstvaapisurfacepool.c index 4fd8695..1b6f0e9 100644 --- a/gst-libs/gst/vaapi/gstvaapisurfacepool.c +++ b/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) { diff --git a/gst-libs/gst/vaapi/gstvaapisurfacepool.h b/gst-libs/gst/vaapi/gstvaapisurfacepool.h index 16b2bc1..b1e5f71 100644 --- a/gst-libs/gst/vaapi/gstvaapisurfacepool.h +++ b/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; diff --git a/gst-libs/gst/vaapi/gstvaapivideopool.c b/gst-libs/gst/vaapi/gstvaapivideopool.c index 5b41e42..fb78dab 100644 --- a/gst-libs/gst/vaapi/gstvaapivideopool.c +++ b/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) { diff --git a/gst-libs/gst/vaapi/gstvaapivideopool.h b/gst-libs/gst/vaapi/gstvaapivideopool.h index 1d3b91a..69a257b 100644 --- a/gst-libs/gst/vaapi/gstvaapivideopool.h +++ b/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; -- 2.7.4