gl/docs: document new API added in 1.10

GstGLRenderbuffer
GstGLFramebuffer
GstGLQuery
GstEGLImage
GstGLMemoryEGL

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 16441e10f..07f246dae 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 2d2e0758f..7136c0f2d 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 2af22882b..3079e53d9 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 c05ef8226..bf62beb3d 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
 {
+  /* <private> */
   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
 {
+  /* <private> */
+
   GstGLMemoryAllocator parent;
 };
 
 /**
- * GstGLAllocatorClass:
+ * GstGLMemoryEGLAllocatorClass:
  *
- * The #GstGLAllocatorClass only contains private data
+ * The #GstGLMemoryEGLAllocatorClass only contains private data
  */
 struct _GstGLMemoryEGLAllocatorClass
 {
+  /* <private> */
   GstGLMemoryAllocatorClass parent_class;
 };
 
diff --git a/gst-libs/gst/gl/gstglframebuffer.c b/gst-libs/gst/gl/gstglframebuffer.c
index 67f860e1f..70c2e6199 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 99ea4ea63..240477f12 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
 {
+  /* <private> */
   GstObject             object;
 
   GstGLContext *context;
 
-  /* <private> */
   guint fbo_id;
   GArray *attachments;
 
@@ -61,8 +66,14 @@ struct _GstGLFramebuffer
   GstGLFramebufferPrivate  *priv;
 };
 
+/**
+ * GstGLFramebufferClass:
+ *
+ * Opaque #GstGLFramebufferClass struct
+ */
 struct _GstGLFramebufferClass
 {
+  /* <private> */
   GstObjectClass object_class;
 
   gpointer          _padding[GST_PADDING];
diff --git a/gst-libs/gst/gl/gstglquery.c b/gst-libs/gst/gl/gstglquery.c
index c59c19f43..fd71eb844 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 c364a0b7b..0b057421f 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
 {
   /* <private> */
diff --git a/gst-libs/gst/gl/gstglrenderbuffer.c b/gst-libs/gst/gl/gstglrenderbuffer.c
index 0cabad9d8..f21ef54a4 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)