From 1296741d3d8d8cdf7a18fec3c35dda467250c922 Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Wed, 2 Nov 2016 21:21:33 +1100 Subject: [PATCH] gl/docs: document new API added in 1.10 GstGLRenderbuffer GstGLFramebuffer GstGLQuery GstEGLImage GstGLMemoryEGL --- gst-libs/gst/gl/egl/gsteglimage.c | 46 ++++++++++++ gst-libs/gst/gl/egl/gsteglimage.h | 9 ++- gst-libs/gst/gl/egl/gstglmemoryegl.c | 34 +++++++++ gst-libs/gst/gl/egl/gstglmemoryegl.h | 14 ++-- gst-libs/gst/gl/gstglframebuffer.c | 106 +++++++++++++++++++++++++++ gst-libs/gst/gl/gstglframebuffer.h | 17 ++++- gst-libs/gst/gl/gstglquery.c | 79 ++++++++++++++++++++ gst-libs/gst/gl/gstglquery.h | 11 +++ gst-libs/gst/gl/gstglrenderbuffer.c | 12 +-- 9 files changed, 313 insertions(+), 15 deletions(-) diff --git a/gst-libs/gst/gl/egl/gsteglimage.c b/gst-libs/gst/gl/egl/gsteglimage.c index 16441e10fd..07f246dae3 100644 --- a/gst-libs/gst/gl/egl/gsteglimage.c +++ b/gst-libs/gst/gl/egl/gsteglimage.c @@ -21,6 +21,19 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:gsteglimage + * @short_description: EGLImage abstraction + * @title: GstEGLImage + * @see_also: #GstGLMemoryEGL, #GstGLContext + * + * #GstEGLImage represents and holds an #EGLImage handle. + * + * A #GstEGLImage can be created from a dmabuf with gst_egl_image_from_dmabuf() + * or #GstGLMemoryEGL provides a #GstAllocator to allocate #EGLImage's bound to + * and OpenGL texture. + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -90,6 +103,12 @@ gst_egl_image_ensure_debug_category (void) #endif /* GST_DISABLE_GST_DEBUG */ #endif /* GST_GL_HAVE_DMABUF */ +/** + * gst_egl_image_get_image: + * @image: a #GstEGLImage + * + * Returns: the #EGLImageKHR of @image + */ EGLImageKHR gst_egl_image_get_image (GstEGLImage * image) { @@ -98,6 +117,12 @@ gst_egl_image_get_image (GstEGLImage * image) return image->image; } +/** + * gst_egl_image_get_orientation: + * @image: a #GstEGLImage + * + * Returns: the orientation of @image + */ GstVideoGLTextureOrientation gst_egl_image_get_orientation (GstEGLImage * image) { @@ -132,6 +157,17 @@ _gst_egl_image_copy (GstMiniObject * obj) return gst_mini_object_ref (obj); } +/** + * gst_egl_image_new_wrapped: + * @context: a #GstGLContext (must be an EGL context) + * @image: the image to wrap + * @type: the #GstVideoGLTextureType + * @orientation: the #GstVideoGLTextureOrientation + * @user_data: user data + * @user_data_destroy: called when @user_data is no longer needed + * + * Returns: a new #GstEGLImage wrapping @image + */ GstEGLImage * gst_egl_image_new_wrapped (GstGLContext * context, EGLImageKHR image, GstVideoGLTextureType type, GstVideoGLTextureOrientation orientation, @@ -236,6 +272,16 @@ _destroy_egl_image (GstEGLImage * image, gpointer user_data) image->context->eglDestroyImage (image->context->egl_display, image->image); } +/** + * gst_egl_image_from_dmabuf: + * @context: a #GstGLContext (must be an EGL context) + * @dmabuf: the DMA-Buf file descriptor + * @in_info: the #GstVideoInfo in @dmabuf + * @plane: the plane in @in_info to create and #GstEGLImage for + * @offset: the byte-offset in the data + * + * Returns: a #GstEGLImage wrapping @dmabuf or %NULL on failure + */ GstEGLImage * gst_egl_image_from_dmabuf (GstGLContext * context, gint dmabuf, GstVideoInfo * in_info, gint plane, gsize offset) diff --git a/gst-libs/gst/gl/egl/gsteglimage.h b/gst-libs/gst/gl/egl/gsteglimage.h index 2d2e0758fe..7136c0f2d9 100644 --- a/gst-libs/gst/gl/egl/gsteglimage.h +++ b/gst-libs/gst/gl/egl/gsteglimage.h @@ -42,6 +42,11 @@ typedef struct _GstEGLImage GstEGLImage; typedef void (*GstEGLImageDestroyNotify) (GstEGLImage * image, gpointer data); +/** + * GstEGLImage: + * + * Opaque #GstEGLImage struct. + */ struct _GstEGLImage { GstMiniObject parent; @@ -89,8 +94,8 @@ gst_egl_image_ref (GstEGLImage * image) } /** - * gst_buffer_unref: - * @buf: (transfer full): a #GstBuffer. + * gst_egl_image_unref: + * @image: (transfer full): a #GstEGLImage. * * Decreases the refcount of the image. If the refcount reaches 0, the image * with the associated metadata and memory will be freed. diff --git a/gst-libs/gst/gl/egl/gstglmemoryegl.c b/gst-libs/gst/gl/egl/gstglmemoryegl.c index 2af22882bb..3079e53d99 100644 --- a/gst-libs/gst/gl/egl/gstglmemoryegl.c +++ b/gst-libs/gst/gl/egl/gstglmemoryegl.c @@ -39,6 +39,14 @@ GST_DEBUG_CATEGORY_STATIC (GST_CAT_GL_MEMORY); G_DEFINE_TYPE (GstGLMemoryEGLAllocator, gst_gl_memory_egl_allocator, GST_TYPE_GL_MEMORY_ALLOCATOR); +/** + * gst_is_gl_memory_egl: + * @mem: a #GstMemory to test + * + * Returns: whether @mem is a #GstGLMemoryEGL + * + * Since: 1.10 + */ gboolean gst_is_gl_memory_egl (GstMemory * mem) { @@ -54,6 +62,14 @@ _gl_mem_get_parent (GstGLMemoryEGL * gl_mem) return parent ? parent : gl_mem; } +/** + * gst_gl_memory_egl_get_image: + * @mem: a #GstGLMemoryEGL + * + * Returns: The EGLImage held by @mem + * + * Since: 1.10 + */ EGLImageKHR gst_gl_memory_egl_get_image (GstGLMemoryEGL * mem) { @@ -62,6 +78,14 @@ gst_gl_memory_egl_get_image (GstGLMemoryEGL * mem) return gst_egl_image_get_image (_gl_mem_get_parent (mem)->image); } +/** + * gst_gl_memory_egl_get_display: + * @mem: a #GstGLMemoryEGL + * + * Returns: The EGLDisplay @mem is associated with + * + * Since: 1.10 + */ EGLDisplay gst_gl_memory_egl_get_display (GstGLMemoryEGL * mem) { @@ -70,6 +94,14 @@ gst_gl_memory_egl_get_display (GstGLMemoryEGL * mem) context)->egl_display; } +/** + * gst_gl_memory_egl_get_orientation: + * @mem: a #GstGLMemoryEGL + * + * Returns: The orientation of @mem + * + * Since: 1.10 + */ GstVideoGLTextureOrientation gst_gl_memory_egl_get_orientation (GstGLMemoryEGL * mem) { @@ -225,6 +257,8 @@ gst_gl_memory_egl_allocator_init (GstGLMemoryEGLAllocator * allocator) * * Initializes the GL Memory allocator. It is safe to call this function * multiple times. This must be called before any other GstGLMemoryEGL operation. + * + * Since: 1.10 */ void gst_gl_memory_egl_init_once (void) diff --git a/gst-libs/gst/gl/egl/gstglmemoryegl.h b/gst-libs/gst/gl/egl/gstglmemoryegl.h index c05ef82264..bf62beb3d9 100644 --- a/gst-libs/gst/gl/egl/gstglmemoryegl.h +++ b/gst-libs/gst/gl/egl/gstglmemoryegl.h @@ -53,13 +53,14 @@ GType gst_gl_memory_egl_allocator_get_type(void); */ struct _GstGLMemoryEGL { + /* */ GstGLMemory mem; GstEGLImage *image; }; /** - * GST_GL_MEMORY_EGL_ALLOCATOR: + * GST_GL_MEMORY_EGL_ALLOCATOR_NAME: * * The name of the GL Memory EGL allocator */ @@ -75,22 +76,25 @@ GstVideoGLTextureOrientation gst_gl_memory_egl_get_orientation (GstGLMemoryEGL * mem); /** - * GstGLAllocator + * GstGLMemoryEGLAllocator * - * Opaque #GstGLAllocator struct + * Opaque #GstGLMemoryEGLAllocator struct */ struct _GstGLMemoryEGLAllocator { + /* */ + GstGLMemoryAllocator parent; }; /** - * GstGLAllocatorClass: + * GstGLMemoryEGLAllocatorClass: * - * The #GstGLAllocatorClass only contains private data + * The #GstGLMemoryEGLAllocatorClass only contains private data */ struct _GstGLMemoryEGLAllocatorClass { + /* */ GstGLMemoryAllocatorClass parent_class; }; diff --git a/gst-libs/gst/gl/gstglframebuffer.c b/gst-libs/gst/gl/gstglframebuffer.c index 67f860e1f5..70c2e61992 100644 --- a/gst-libs/gst/gl/gstglframebuffer.c +++ b/gst-libs/gst/gl/gstglframebuffer.c @@ -17,6 +17,27 @@ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301, USA. */ + +/** + * SECTION:gstglframebuffer + * @short_description: OpenGL framebuffer abstraction + * @title: GstGLFramebuffer + * @see_also: #GstGLBaseMemory, #GstGLMemory, #GstGLContext + * + * A #GstGLFramebuffer represents and holds an OpenGL framebuffer object with + * it's associated attachments. + * + * A #GstGLFramebuffer can be created with gst_gl_framebuffer_new() or + * gst_gl_framebuffer_new_with_default_depth() and bound with + * gst_gl_framebuffer_bind(). Other resources can be bound with + * gst_gl_framebuffer_attach() + * + * Note: OpenGL framebuffers are not shareable resources so cannot be used + * between multiple OpenGL contexts. + * + * Since: 1.10 + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -139,6 +160,14 @@ gst_gl_framebuffer_finalize (GObject * object) G_OBJECT_CLASS (gst_gl_framebuffer_parent_class)->finalize (object); } +/** + * gst_gl_framebuffer_new: + * @context: a #GstGLContext + * + * Returns: a new #GstGLFramebuffer + * + * Since: 1.10 + */ GstGLFramebuffer * gst_gl_framebuffer_new (GstGLContext * context) { @@ -162,6 +191,16 @@ gst_gl_framebuffer_new (GstGLContext * context) return fb; } +/** + * gst_gl_framebuffer_new_with_default_depth: + * @context: a #GstGLContext + * @width: width for the depth buffer + * @height: for the depth buffer + * + * Returns: a new #GstGLFramebuffer with a depth buffer of @width and @height + * + * Since: 1.10 + */ GstGLFramebuffer * gst_gl_framebuffer_new_with_default_depth (GstGLContext * context, guint width, guint height) @@ -205,6 +244,20 @@ gst_gl_framebuffer_new_with_default_depth (GstGLContext * context, guint width, return fb; } +/** + * gst_gl_framebuffer_draw_to_texture: + * @fb: a #GstGLFramebuffer + * @mem: the #GstGLMemory to draw to + * @func: the function to run + * @user_data: data to pass to @func + * + * Perform the steps necessary to have the output of a glDraw* command in + * @func update the contents of @mem. + * + * Returns: the result of executing @func + * + * Since: 1.10 + */ gboolean gst_gl_framebuffer_draw_to_texture (GstGLFramebuffer * fb, GstGLMemory * mem, GstGLFramebufferFunc func, gpointer user_data) @@ -243,6 +296,14 @@ gst_gl_framebuffer_draw_to_texture (GstGLFramebuffer * fb, GstGLMemory * mem, return ret; } +/** + * gst_gl_framebuffer_bind: + * @fb: a #GstGLFramebuffer + * + * Bind @fb into the current thread + * + * Since: 1.10 + */ void gst_gl_framebuffer_bind (GstGLFramebuffer * fb) { @@ -257,6 +318,14 @@ gst_gl_framebuffer_bind (GstGLFramebuffer * fb) gl->BindFramebuffer (GL_FRAMEBUFFER, fb->fbo_id); } +/** + * gst_gl_context_clear_framebuffer: + * @context: a #GstGLContext + * + * Unbind the current framebuffer + * + * Since: 1.10 + */ void gst_gl_context_clear_framebuffer (GstGLContext * context) { @@ -362,6 +431,16 @@ _attach_renderbuffer (GstGLFramebuffer * fb, guint attachment_point, fb->attachments = g_array_append_val (fb->attachments, attach); } +/** + * gst_gl_framebuffer_attach: + * @fb: a #GstGLFramebuffer + * @attachment_point: the OpenGL attachment point to bind @mem to + * @mem: the memory object to bind to @attachment_point + * + * attach @mem to @attachment_point + * + * Since: 1.10 + */ void gst_gl_framebuffer_attach (GstGLFramebuffer * fb, guint attachment_point, GstGLBaseMemory * mem) @@ -396,6 +475,17 @@ gst_gl_framebuffer_attach (GstGLFramebuffer * fb, guint attachment_point, _update_effective_dimensions (fb); } +/** + * gst_gl_framebuffer_get_effective_dimensions: + * @fb: a #GstGLFramebuffer + * @width: (out) (allow-none): output width + * @height: (out) (allow-none): output height + * + * Retreive the effective dimensions from the current attachments attached to + * @fb. + * + * Since: 1.10 + */ void gst_gl_framebuffer_get_effective_dimensions (GstGLFramebuffer * fb, guint * width, guint * height) @@ -408,6 +498,14 @@ gst_gl_framebuffer_get_effective_dimensions (GstGLFramebuffer * fb, *height = fb->priv->effective_height; } +/** + * gst_gl_context_check_framebuffer_status: + * @context: a #GstGLContext + * + * Returns: whether whether the current framebuffer is complete + * + * Since: 1.10 + */ gboolean gst_gl_context_check_framebuffer_status (GstGLContext * context) { @@ -443,6 +541,14 @@ gst_gl_context_check_framebuffer_status (GstGLContext * context) return FALSE; } +/** + * gst_gl_framebuffer_get_id: + * @fb: a #GstGLFramebuffer + * + * Returns: the OpenGL id for @fb + * + * Since: 1.10 + */ guint gst_gl_framebuffer_get_id (GstGLFramebuffer * fb) { diff --git a/gst-libs/gst/gl/gstglframebuffer.h b/gst-libs/gst/gl/gstglframebuffer.h index 99ea4ea631..240477f12a 100644 --- a/gst-libs/gst/gl/gstglframebuffer.h +++ b/gst-libs/gst/gl/gstglframebuffer.h @@ -40,19 +40,24 @@ typedef struct _GstGLFramebufferPrivate GstGLFramebufferPrivate; /** * GstGLFramebufferFunc: - * @data: user data + * @stuff: user data * - * callback definition for operating through a Framebuffer object + * callback definition for operating through a #GstGLFramebuffer object */ typedef gboolean (*GstGLFramebufferFunc) (gpointer stuff); +/** + * GstGLFramebuffer: + * + * Opaque #GstGLFramebuffer struct + */ struct _GstGLFramebuffer { + /* */ GstObject object; GstGLContext *context; - /* */ guint fbo_id; GArray *attachments; @@ -61,8 +66,14 @@ struct _GstGLFramebuffer GstGLFramebufferPrivate *priv; }; +/** + * GstGLFramebufferClass: + * + * Opaque #GstGLFramebufferClass struct + */ struct _GstGLFramebufferClass { + /* */ GstObjectClass object_class; gpointer _padding[GST_PADDING]; diff --git a/gst-libs/gst/gl/gstglquery.c b/gst-libs/gst/gl/gstglquery.c index c59c19f437..fd71eb8447 100644 --- a/gst-libs/gst/gl/gstglquery.c +++ b/gst-libs/gst/gl/gstglquery.c @@ -18,6 +18,18 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:gstglquery + * @short_description: OpenGL query abstraction + * @title: GstGLQuery + * @see_also: + * + * A #GstGLQuery represents and holds an OpenGL query object. Various types of + * queries can be run or counters retrieved. + * + * Since: 1.10 + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -110,6 +122,14 @@ _log_time (gpointer user_data) return gst_info_strdup_printf ("%" GST_TIME_FORMAT, GST_TIME_ARGS (result)); } +/** + * gst_gl_query_init: + * @query: a #GstGLQuery + * @context: a #GstGLContext + * @query_type: the #GstGLQueryType + * + * Since: 1.10 + */ void gst_gl_query_init (GstGLQuery * query, GstGLContext * context, GstGLQueryType query_type) @@ -136,6 +156,14 @@ gst_gl_query_init (GstGLQuery * query, GstGLContext * context, query->debug.user_data = query; } +/** + * gst_gl_query_unset: + * @query: a #GstGLQuery + * + * Free any dynamically allocated resources + * + * Since: 1.10 + */ void gst_gl_query_unset (GstGLQuery * query) { @@ -159,6 +187,17 @@ gst_gl_query_unset (GstGLQuery * query) gst_object_unref (query->context); } +/** + * gst_gl_query_new: + * @context: a #GstGLContext + * @query_type: the #GstGLQueryType to create + * + * Free with gst_gl_query_free() + * + * Returns: a new #GstGLQuery + * + * Since: 1.10 + */ GstGLQuery * gst_gl_query_new (GstGLContext * context, GstGLQueryType query_type) { @@ -169,6 +208,14 @@ gst_gl_query_new (GstGLContext * context, GstGLQueryType query_type) return query; } +/** + * gst_gl_query_free: + * @query: a #GstGLQuery + * + * Frees a #GstGLQuery + * + * Since: 1.10 + */ void gst_gl_query_free (GstGLQuery * query) { @@ -178,6 +225,14 @@ gst_gl_query_free (GstGLQuery * query) g_free (query); } +/** + * gst_gl_query_start: + * @query: a #GstGLQuery + * + * Start counting the query + * + * Since: 1.10 + */ void gst_gl_query_start (GstGLQuery * query) { @@ -199,6 +254,14 @@ gst_gl_query_start (GstGLQuery * query) gl->BeginQuery (query->query_type, query->query_id); } +/** + * gst_gl_query_end: + * @query: a #GstGLQuery + * + * End counting the query + * + * Since: 1.10 + */ void gst_gl_query_end (GstGLQuery * query) { @@ -220,6 +283,14 @@ gst_gl_query_end (GstGLQuery * query) query->start_called = FALSE; } +/** + * gst_gl_query_counter: + * @query: a #GstGLQuery + * + * Record the result of a counter + * + * Since: 1.10 + */ void gst_gl_query_counter (GstGLQuery * query) { @@ -240,6 +311,14 @@ gst_gl_query_counter (GstGLQuery * query) gl->QueryCounter (query->query_id, query->query_type); } +/** + * gst_gl_query_result: + * @query: a #GstGLQuery + * + * Returns: the result of the query + * + * Since: 1.10 + */ guint64 gst_gl_query_result (GstGLQuery * query) { diff --git a/gst-libs/gst/gl/gstglquery.h b/gst-libs/gst/gl/gstglquery.h index c364a0b7bf..0b057421fd 100644 --- a/gst-libs/gst/gl/gstglquery.h +++ b/gst-libs/gst/gl/gstglquery.h @@ -25,6 +25,12 @@ G_BEGIN_DECLS +/** + * GstGLQueryType: + * @GST_GL_QUERY_NONE: no query + * @GST_GL_QUERY_TIME_ELAPSED: query the time elapsed + * @GST_GL_QUERY_TIMESTAMP: query the current time + */ typedef enum { GST_GL_QUERY_NONE, @@ -32,6 +38,11 @@ typedef enum GST_GL_QUERY_TIMESTAMP, } GstGLQueryType; +/** + * GstGLQuery: + * + * Opaque #GstGLQuery struct + */ struct _GstGLQuery { /* */ diff --git a/gst-libs/gst/gl/gstglrenderbuffer.c b/gst-libs/gst/gl/gstglrenderbuffer.c index 0cabad9d80..f21ef54a49 100644 --- a/gst-libs/gst/gl/gstglrenderbuffer.c +++ b/gst-libs/gst/gl/gstglrenderbuffer.c @@ -39,6 +39,8 @@ * * #GstGLRenderbuffer is created or wrapped through gst_gl_base_memory_alloc() * with #GstGLRenderbufferAllocationParams. + * + * Since: 1.10 */ #define USING_OPENGL(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL, 1, 0)) @@ -227,7 +229,7 @@ gst_gl_renderbuffer_allocator_init (GstGLRenderbufferAllocator * allocator) * * Returns: the configured width of @gl_mem * - * Since: 1.8 + * Since: 1.10 */ gint gst_gl_renderbuffer_get_width (GstGLRenderbuffer * gl_mem) @@ -243,7 +245,7 @@ gst_gl_renderbuffer_get_width (GstGLRenderbuffer * gl_mem) * * Returns: the configured height of @gl_mem * - * Since: 1.8 + * Since: 1.10 */ gint gst_gl_renderbuffer_get_height (GstGLRenderbuffer * gl_mem) @@ -259,7 +261,7 @@ gst_gl_renderbuffer_get_height (GstGLRenderbuffer * gl_mem) * * Returns: the #GstVideoGLTextureType of @gl_mem * - * Since: 1.8 + * Since: 1.10 */ GstVideoGLTextureType gst_gl_renderbuffer_get_type (GstGLRenderbuffer * gl_mem) @@ -275,7 +277,7 @@ gst_gl_renderbuffer_get_type (GstGLRenderbuffer * gl_mem) * * Returns: the OpenGL renderbuffer handle of @gl_mem * - * Since: 1.8 + * Since: 1.10 */ guint gst_gl_renderbuffer_get_id (GstGLRenderbuffer * gl_mem) @@ -291,7 +293,7 @@ gst_gl_renderbuffer_get_id (GstGLRenderbuffer * gl_mem) * Initializes the GL Base Texture allocator. It is safe to call this function * multiple times. This must be called before any other GstGLRenderbuffer operation. * - * Since: 1.4 + * Since: 1.10 */ void gst_gl_renderbuffer_init_once (void)