gl/docs: massive update

- add Since: markers where necessary.
- document structs
- add documentation headers for each module (short_description,
  see_also, etc)
- reduce the number of warnings gtk-doc outputs
- fix spelling mistakes

docs/libs/gst-plugins-bad-libs-docs.sgml

@@ -72,6 +72,10 @@
 
     <chapter id="gl">
       <title>OpenGL Helper Library</title>
+      <para>
+        This library should be linked to by getting cflags and libs from
+        <filename>gstreamer-gl-&GST_API_VERSION;.pc</filename>
+      </para>
       <xi:include href="xml/gstglapi.xml"/>
       <xi:include href="xml/gstglbasefilter.xml"/>
       <xi:include href="xml/gstglbasememory.xml"/>
@@ -79,20 +83,22 @@
       <xi:include href="xml/gstglbufferpool.xml"/>
       <xi:include href="xml/gstglcolorconvert.xml"/>
       <xi:include href="xml/gstglcontext.xml"/>
-<!--      <xi:include href="xml/gstglcontextcocoa.xml"/>
+      <!-- Not exposed as public API
+      <xi:include href="xml/gstglcontextcocoa.xml"/>
       <xi:include href="xml/gstglcontexteagl.xml"/>
       <xi:include href="xml/gstglcontextegl.xml"/>
       <xi:include href="xml/gstglcontextglx.xml"/>
-      <xi:include href="xml/gstglcontextwgl.xml"/>-->
+      <xi:include href="xml/gstglcontextwgl.xml"/>
-      <xi:include href="xml/gstgldebug.xml"/>
+      -->
       <xi:include href="xml/gstgldisplay.xml"/>
-<!--      <xi:include href="xml/gstgldisplaycocoa.xml"/>
+      <!-- Not exposed as public API
-      <xi:include href="xml/gstgldisplayegl.xml"/>-->
+      <xi:include href="xml/gstgldisplaycocoa.xml"/>
+      <xi:include href="xml/gstgldisplayegl.xml"/>
+      -->
       <xi:include href="xml/gstgldisplaywayland.xml"/>
       <xi:include href="xml/gstgldisplayx11.xml"/>
       <xi:include href="xml/gsteglimage.xml"/>
       <xi:include href="xml/gstglfilter.xml"/>
-      <xi:include href="xml/gstglformat.xml"/>
       <xi:include href="xml/gstglframebuffer.xml"/>
       <xi:include href="xml/gstglmemory.xml"/>
       <xi:include href="xml/gstglmemoryegl.xml"/>
@@ -107,13 +113,18 @@
       <xi:include href="xml/gstglupload.xml"/>
       <xi:include href="xml/gstglviewconvert.xml"/>
       <xi:include href="xml/gstglwindow.xml"/>
-<!--      <xi:include href="xml/gstglwindowandroid.xml"/>
+      <!-- Not exposed as public API
+      <xi:include href="xml/gstglwindowandroid.xml"/>
       <xi:include href="xml/gstglwindowcocoa.xml"/>
       <xi:include href="xml/gstglwindowdispmanx.xml"/>
       <xi:include href="xml/gstglwindoweagl.xml"/>
       <xi:include href="xml/gstglwindowwayland.xml"/>
       <xi:include href="xml/gstglwindowwin32.xml"/>
-      <xi:include href="xml/gstglwindowx11.xml"/>-->
+      <xi:include href="xml/gstglwindowx11.xml"/>
+      -->
+      <!-- Some utilities -->
+      <xi:include href="xml/gstgldebug.xml"/>
+      <xi:include href="xml/gstglformat.xml"/>
       <xi:include href="xml/gstglutils.xml"/>
     </chapter>
 

docs/libs/gst-plugins-bad-libs-sections.txt

@@ -1081,7 +1081,7 @@ gst_gl_display_egl_get_type
 
 <SECTION>
 <FILE>gstgldisplaywayland</FILE>
-<TITLE>GstGLDIsplayWayland</TITLE>
+<TITLE>GstGLDisplayWayland</TITLE>
 gst_gl_display_wayland_new
 gst_gl_display_wayland_new_with_display
 <SUBSECTION Standard>
@@ -1093,7 +1093,7 @@ GST_GL_DISPLAY_WAYLAND_CLASS
 
 <SECTION>
 <FILE>gstgldisplayx11</FILE>
-<TITLE>GstGLDIsplayX11</TITLE>
+<TITLE>GstGLDisplayX11</TITLE>
 gst_gl_display_x11_new
 gst_gl_display_x11_new_with_display
 <SUBSECTION Standard>
@@ -1525,11 +1525,10 @@ GST_GLSL_STAGE_GET_CLASS
 <FILE>gstglsyncmeta</FILE>
 <TITLE>GstGLSyncMeta</TITLE>
 GstGLSyncMeta
+gst_gl_sync_meta_get_info
 gst_buffer_add_gl_sync_meta
 gst_buffer_add_gl_sync_meta_full
 gst_buffer_get_gl_sync_meta
-gst_gl_sync_meta_api_get_type
-gst_gl_sync_meta_get_info
 gst_gl_sync_meta_set_sync_point
 gst_gl_sync_meta_wait
 gst_gl_sync_meta_wait_cpu
@@ -1537,6 +1536,7 @@ GST_BUFFER_POOL_OPTION_GL_SYNC_META
 <SUBSECTION Standard>
 GST_GL_SYNC_META_API_TYPE
 GST_GL_SYNC_META_INFO
+gst_gl_sync_meta_api_get_type
 </SECTION>
 
 <SECTION>

gst-libs/gst/gl/egl/gstglcontext_egl.h

@@ -38,7 +38,14 @@ GType gst_gl_context_egl_get_type     (void);
 #define GST_IS_GL_CONTEXT_EGL_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE((k), GST_GL_TYPE_CONTEXT_EGL))
 #define GST_GL_CONTEXT_EGL_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS((o), GST_GL_TYPE_CONTEXT_EGL, GstGLContextEGLClass))
 
-struct _GstGLContextEGL {
+/**
+ * GstGLContextEGL:
+ *
+ * Opaque #GstGLContextEGL struct
+ */
+struct _GstGLContextEGL
+{
+  /* <private> */
   GstGLContext context;
 
   EGLContext egl_context;
@@ -63,7 +70,14 @@ struct _GstGLContextEGL {
   EGLNativeWindowType window_handle;
 };
 
-struct _GstGLContextEGLClass {
+/**
+ * GstGLContextEGLCLass:
+ *
+ * Opaque #GstGLContextEGLClass struct
+ */
+struct _GstGLContextEGLClass
+{
+  /* <private> */
   GstGLContextClass parent;
 };
 

gst-libs/gst/gl/egl/gstgldisplay_egl.c

@@ -69,10 +69,8 @@ gst_gl_display_egl_finalize (GObject * object)
 
 /**
  * gst_gl_display_egl_new:
- * @name: (allow-none): a display name
  *
- * Create a new #GstGLDisplayEGL from the x11 display name.  See XOpenDisplay()
+ * Create a new #GstGLDisplayEGL using the default EGL_DEFAULT_DISPLAY.
- * for details on what is a valid name.
  *
  * Returns: (transfer full): a new #GstGLDisplayEGL or %NULL
  */
@@ -95,9 +93,9 @@ gst_gl_display_egl_new (void)
 
 /**
  * gst_gl_display_egl_new_with_display:
- * @display: an existing, x11 display
+ * @display: an existing and connected EGLDisplay
  *
- * Creates a new display connection from a X11 Display.
+ * Creates a new display connection from a EGLDisplay.
  *
  * Returns: (transfer full): a new #GstGLDisplayEGL
  */

gst-libs/gst/gl/egl/gstglmemoryegl.c

@@ -22,6 +22,15 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstglmemoryegl
+ * @short_description: memory subclass for EGLImage's
+ * @see_also: #GstGLMemory, #GstGLAllocator, #GstGLBufferPool
+ *
+ * #GstGLMemoryEGL is created or wrapped through gst_gl_base_memory_alloc()
+ * with #GstGLVideoAllocationParams.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

gst-libs/gst/gl/gstglapi.c

@@ -17,6 +17,15 @@
  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  * Boston, MA 02110-1301, USA.
  */
+
+/**
+ * SECTION:gstglapi
+ * @short_description: OpenGL API specific functionality
+ * @see_also: #GstGLDisplay, #GstGLContext
+ *
+ * Provides some helper API for dealing with OpenGL API's and platforms
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

gst-libs/gst/gl/gstglbasefilter.c

@@ -28,7 +28,7 @@
 
 /**
  * SECTION:gstglbasefilter
- * @short_description: #GstBaseTransform subclass for transformin OpenGL resources
+ * @short_description: #GstBaseTransform subclass for transforming OpenGL resources
  * @title: GstGLBaseFilter
  * @see_also: #GstBaseTransform
  *

gst-libs/gst/gl/gstglbasememory.h

@@ -332,12 +332,12 @@ struct _GstGLBaseMemoryAllocatorClass
   GstGLBaseMemoryAllocatorUnmapFunction         unmap;
   GstGLBaseMemoryAllocatorCopyFunction          copy;
   GstGLBaseMemoryAllocatorDestroyFunction       destroy;
+  /* <private> */
 #if 0
   GstGLBaseMemoryAllocatorFlushFunction         flush;        /* make CPU writes visible to the GPU */
   GstGLBaseMemoryAllocatorInvalidateFunction    invalidate;   /* make GPU writes visible to the CPU */
 #endif
 
-  /* <private> */
   gpointer                                      _padding[GST_PADDING];
 };
 

gst-libs/gst/gl/gstglbuffer.h

@@ -43,7 +43,6 @@ GType gst_gl_buffer_allocator_get_type(void);
 /**
  * GstGLBuffer:
  * @mem: the parent object
- * @context: the #GstGLContext to use for GL operations
  * @id: the buffer id for this memory
  * @target: the OpenGL target of this texture for binding purposes
  * @usage_hints: the OpenGL usage hints this buffer was created with

gst-libs/gst/gl/gstglbufferpool.c

@@ -28,15 +28,17 @@
 
 /**
  * SECTION:gstglbufferpool
- * @short_description: buffer pool for #GstGLMemory objects
+ * @short_description: buffer pool for #GstGLBaseMemory objects
- * @see_also: #GstBufferPool, #GstGLMemory
+ * @see_also: #GstBufferPool, #GstGLBaseMemory, #GstGLMemory
  *
- * a #GstGLBufferPool is an object that allocates buffers with #GstGLMemory
+ * a #GstGLBufferPool is an object that allocates buffers with #GstGLBaseMemory
  *
  * A #GstGLBufferPool is created with gst_gl_buffer_pool_new()
  *
  * #GstGLBufferPool implements the VideoMeta buffer pool option 
- * #GST_BUFFER_POOL_OPTION_VIDEO_META
+ * %GST_BUFFER_POOL_OPTION_VIDEO_META, the VideoAligment buffer pool option
+ * %GST_BUFFER_POOL_OPTION_VIDEO_ALIGNMENT as well as the OpenGL specific
+ * %GST_BUFFER_POOL_OPTION_GL_SYNC_META buffer pool option.
  */
 
 /* bufferpool */

gst-libs/gst/gl/gstglcolorconvert.c

@@ -31,13 +31,18 @@
 
 /**
  * SECTION:gstglcolorconvert
- * @short_description: an object that converts between color spaces/formats
+ * @short_description: convert between video color spaces and formats
  * @see_also: #GstGLUpload, #GstGLMemory, #GstGLBaseMemory
  *
  * #GstGLColorConvert is an object that converts between color spaces and/or
  * formats using OpenGL Shaders.
  *
- * A #GstGLColorConvert can be created with gst_gl_color_convert_new().
+ * A #GstGLColorConvert can be created with gst_gl_color_convert_new(), the
+ * configuration negotiated with gst_gl_color_convert_transform_caps() and the
+ * conversion performed with gst_gl_color_convert_perform().
+ *
+ * The glcolorconvertelement provides a GStreamer element that uses
+ * #GstGLColorConvert to convert between video formats and color spaces.
  */
 
 #define USING_OPENGL(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL, 1, 0))
@@ -464,6 +469,8 @@ gst_gl_color_convert_init (GstGLColorConvert * convert)
  * @context: a #GstGLContext
  *
  * Returns: a new #GstGLColorConvert object
+ *
+ * Since: 1.4
  */
 GstGLColorConvert *
 gst_gl_color_convert_new (GstGLContext * context)
@@ -731,6 +738,8 @@ _gst_gl_color_convert_set_caps_unlocked (GstGLColorConvert * convert,
  * @out_caps: output #GstCaps
  *
  * Initializes @convert with the information required for conversion.
+ *
+ * Since: 1.6
  */
 gboolean
 gst_gl_color_convert_set_caps (GstGLColorConvert * convert,
@@ -745,6 +754,17 @@ gst_gl_color_convert_set_caps (GstGLColorConvert * convert,
   return ret;
 }
 
+/**
+ * gst_gl_color_convert_decide_allocation:
+ * @convert: a #GstGLColorConvert
+ * @query: a completed ALLOCATION #GstQuery
+ *
+ * Provides an implementation of #GstBaseTransfromClass::decide_allocation()
+ *
+ * Returns: whether the allocation parameters were successfully chosen
+ *
+ * Since: 1.8
+ */
 gboolean
 gst_gl_color_convert_decide_allocation (GstGLColorConvert * convert,
     GstQuery * query)
@@ -926,8 +946,21 @@ gst_gl_color_convert_caps_transform_format_info (GstCaps * caps)
   return res;
 }
 
+/**
+ * gst_gl_color_convert_transform_caps:
+ * @context: a #GstGLContext to use for transforming @caps
+ * @direction: a #GstPadDirection
+ * @caps: (transfer none): the #GstCaps to transform
+ * @filter: (transfer none): a set of filter #GstCaps
+ *
+ * Provides an implementation of #GstBaseTransformClass::transform_caps()
+ *
+ * Returns: (transfer full): the converted #GstCaps
+ *
+ * Since: 1.6
+ */
 GstCaps *
-gst_gl_color_convert_transform_caps (GstGLContext * convert,
+gst_gl_color_convert_transform_caps (GstGLContext * context,
     GstPadDirection direction, GstCaps * caps, GstCaps * filter)
 {
   caps = gst_gl_color_convert_caps_transform_format_info (caps);
@@ -1151,8 +1184,21 @@ gst_gl_color_convert_fixate_format_target (GstCaps * caps, GstCaps * result)
         gst_gl_texture_target_to_string (target), NULL);
 }
 
+/**
+ * gst_gl_color_convert_fixate_caps:
+ * @context: a #GstGLContext to use for transforming @caps
+ * @direction: a #GstPadDirection
+ * @caps: (transfer none): the #GstCaps of @direction
+ * @other: (transfer full): the #GstCaps to fixate
+ *
+ * Provides an implementation of #GstBaseTransformClass::fixate_caps()
+ *
+ * Returns: (transfer full): the fixated #GstCaps
+ *
+ * Since: 1.8
+ */
 GstCaps *
-gst_gl_color_convert_fixate_caps (GstGLContext * convert,
+gst_gl_color_convert_fixate_caps (GstGLContext * context,
     GstPadDirection direction, GstCaps * caps, GstCaps * other)
 {
   GstCaps *result;
@@ -1182,12 +1228,14 @@ gst_gl_color_convert_fixate_caps (GstGLContext * convert,
 /**
  * gst_gl_color_convert_perform:
  * @convert: a #GstGLColorConvert
- * @inbuf: the texture ids for input formatted according to in_info
+ * @inbuf: (transfer none): the #GstGLMemory filled #GstBuffer to convert
  *
  * Converts the data contained by @inbuf using the formats specified by the
- * #GstVideoInfo<!--  -->s passed to gst_gl_color_convert_set_caps() 
+ * #GstCaps passed to gst_gl_color_convert_set_caps() 
  *
- * Returns: a converted #GstBuffer or %NULL%
+ * Returns: (transfer full): a converted #GstBuffer or %NULL
+ *
+ * Since: 1.4
  */
 GstBuffer *
 gst_gl_color_convert_perform (GstGLColorConvert * convert, GstBuffer * inbuf)

gst-libs/gst/gl/gstglcolorconvert.h

@@ -76,9 +76,9 @@ struct _GstGLColorConvert
  */
 struct _GstGLColorConvertClass
 {
+  /* <private> */
   GstObjectClass object_class;
 
-  /* <private> */
   gpointer _padding[GST_PADDING];
 };
 
@@ -117,12 +117,12 @@ GST_EXPORT
 GstGLColorConvert * gst_gl_color_convert_new (GstGLContext * context);
 
 GST_EXPORT
-GstCaps *   gst_gl_color_convert_transform_caps (GstGLContext * convert,
+GstCaps *   gst_gl_color_convert_transform_caps (GstGLContext * context,
                                                  GstPadDirection direction,
                                                  GstCaps * caps,
                                                  GstCaps * filter);
 GST_EXPORT
-GstCaps *   gst_gl_color_convert_fixate_caps    (GstGLContext * convert,
+GstCaps *   gst_gl_color_convert_fixate_caps    (GstGLContext * context,
                                                  GstPadDirection direction,
                                                  GstCaps * caps,
                                                  GstCaps * other);

gst-libs/gst/gl/gstglcontext.c

@@ -371,6 +371,10 @@ gst_gl_context_new (GstGLDisplay * display)
  *
  * Wraps an existing OpenGL context into a #GstGLContext.  
  *
+ * Note: The caller is responsible for ensuring that the OpenGL context
+ * represented by @handle stays alive while the returned #GstGLContext is
+ * active.
+ *
  * Returns: a #GstGLContext wrapping @handle
  *
  * Since: 1.4
@@ -493,6 +497,21 @@ gst_gl_context_get_current_gl_context (GstGLPlatform context_type)
   return handle;
 }
 
+/**
+ * gst_gl_context_get_proc_address_with_platform:
+ * @context_type: a #GstGLPlatform
+ * @gl_api: a #GstGLAPI
+ * @name: the name of the function to retrieve
+ *
+ * Attempts to use the @context_type specific GetProcAddress implementations
+ * to retreive @name.
+ *
+ * See also gst_gl_context_get_proc_address().
+ *
+ * Returns: a function pointer for @name, or %NULL
+ *
+ * Since: 1.6
+ */
 gpointer
 gst_gl_context_get_proc_address_with_platform (GstGLPlatform context_type,
     GstGLAPI gl_api, const gchar * name)
@@ -522,10 +541,10 @@ gst_gl_context_get_proc_address_with_platform (GstGLPlatform context_type,
 /**
  * gst_gl_context_get_current_gl_api:
  * @platform: the #GstGLPlatform to retrieve the API for
- * @major: (out): (allow-none): the major version
+ * @major: (out) (allow-none): the major version
- * @minor: (out): (allow-none): the minor version
+ * @minor: (out) (allow-none): the minor version
  *
- * If an error occurs, @major and @minor aren't modified and %GST_GL_API_NONE is
+ * If an error occurs, @major and @minor are not modified and %GST_GL_API_NONE is
  * returned.
  *
  * Returns: The version supported by the OpenGL context current in the calling
@@ -778,7 +797,17 @@ gst_gl_context_get_gl_api (GstGLContext * context)
  * Platform specfic functions (names starting 'egl', 'glX', 'wgl', etc) can also
  * be retrieved using this method.
  *
- * Returns: a function pointer or NULL
+ * Note: This function may return valid function pointers that may not be valid
+ * to call in @context.  The caller is responsible for ensuring that the
+ * returned function is a valid function to call in @context by either checking
+ * the OpenGL API and version or for an appropriate OpenGL extension.
+ *
+ * Note: On success, you need to cast the returned function pointer to the
+ * correct type to be able to call it correctly.  On 32-bit Windows, this will
+ * include the %GSTGLAPI identifier to use the correct calling convention.
+ * e.g. void (GSTGLAPI *PFN_glGetIntegerv) (GLenum name, GLint * ret)
+ *
+ * Returns: a function pointer or %NULL
  *
  * Since: 1.4
  */
@@ -799,6 +828,20 @@ gst_gl_context_get_proc_address (GstGLContext * context, const gchar * name)
   return ret;
 }
 
+/**
+ * gst_gl_context_default_get_proc_address:
+ * @gl_api: a #GstGLAPI
+ * @name: then function to get the address of
+ *
+ * A default implementation of the various GetProcAddress functions that looks
+ * for @name in the OpenGL shared libraries or in the current process.
+ *
+ * See also: gst_gl_context_get_proc_address()
+ *
+ * Returns: an address pointing to @name or %NULL
+ *
+ * Since: 1.4
+ */
 gpointer
 gst_gl_context_default_get_proc_address (GstGLAPI gl_api, const gchar * name)
 {
@@ -920,9 +963,9 @@ gst_gl_context_can_share (GstGLContext * context, GstGLContext * other_context)
  * @other_context: (allow-none): a #GstGLContext to share OpenGL objects with
  * @error: (allow-none): a #GError
  *
- * Creates an OpenGL context in the current thread with the specified
+ * Creates an OpenGL context with the specified @other_context as a context
- * @other_context as a context to share shareable OpenGL objects with.  See the
+ * to share shareable OpenGL objects with.  See the OpenGL specification for
- * OpenGL specification for what is shared between contexts.
+ * what is shared between OpenGL contexts.
  *
  * If an error occurs, and @error is not %NULL, then error will contain details
  * of the error and %FALSE will be returned.
@@ -1291,6 +1334,7 @@ gst_gl_context_destroy (GstGLContext * context)
 /**
  * gst_gl_context_fill_info:
  * @context: a #GstGLContext:
+ * @error: (allow-none): a #GError to fill on failure
  *
  * Fills @context's info (version, extensions, vtable, etc) from the GL
  * context in the current thread.  Typically used with wrapped contexts to
@@ -1434,7 +1478,7 @@ gst_gl_context_get_gl_platform (GstGLContext * context)
  * gst_gl_context_get_display:
  * @context: a #GstGLContext:
  *
- * Returns: the #GstGLDisplay associated with this @context
+ * Returns: (transfer full): the #GstGLDisplay associated with this @context
  *
  * Since: 1.4
  */
@@ -1567,8 +1611,11 @@ gst_gl_context_check_gl_version (GstGLContext * context, GstGLAPI api,
  * @context: a #GstGLContext
  * @feature: a platform specific feature
  *
- * Some features require that the context be created before it is possible to
+ * Check for an OpenGL @feature being supported.
- * determine their existence and so will fail if that is not the case.
+ *
+ * Note: Most features require that the context be created before it is
+ * possible to determine their existence and so will fail if that is not the
+ * case.
  *
  * Returns: Whether @feature is supported by @context
  *

gst-libs/gst/gl/gstglcontext.h

@@ -55,6 +55,17 @@ typedef void (*GstGLContextThreadFunc) (GstGLContext * context, gpointer data);
 #define GST_GL_CONTEXT_TYPE_WGL "gst.gl.context.WGL"
 #define GST_GL_CONTEXT_TYPE_EAGL "gst.gl.context.EAGL"
 
+/**
+ * GstGLContextError:
+ * @GST_GL_CONTEXT_ERROR_FAILED: Failed for an unspecified reason
+ * @GST_GL_CONTEXT_ERROR_WRONG_CONFIG: The configuration requested is not correct
+ * @GST_GL_CONTEXT_ERROR_WRONG_API: The OpenGL API requested is not correct
+ * @GST_GL_CONTEXT_ERROR_OLD_LIBS: The OpenGL libraries are too old
+ * @GST_GL_CONTEXT_ERROR_CREATE_CONTEXT: glXCreateContext (or similar) failed
+ * @GST_GL_CONTEXT_ERROR_RESOURCE_UNAVAILABLE: A resource is not available
+ *
+ * OpenGL context errors.
+ */
 typedef enum
 {
   GST_GL_CONTEXT_ERROR_FAILED,
@@ -67,15 +78,18 @@ typedef enum
 
 /**
  * GstGLContext:
+ * @gl_vtable: a list of OpenGL function pointers
  *
  * Opaque #GstGLContext object
  */
 struct _GstGLContext {
+  /*< private >*/
   GstObject parent;
 
   GstGLDisplay *display;
   GstGLWindow  *window;
 
+  /*< public >*/
   GstGLFuncs *gl_vtable;
 
   /*< private >*/

gst-libs/gst/gl/gstgldebug.c

@@ -163,7 +163,6 @@ gst_gl_async_debug_unset (GstGLAsyncDebug * ad)
 
 /**
  * gst_gl_async_debug_new:
- * @ad: a #GstGLAsyncDebug
  *
  * Free with gst_gl_async_debug_free()
  *

gst-libs/gst/gl/gstgldisplay.c

@@ -223,6 +223,14 @@ gst_gl_display_new (void)
   return display;
 }
 
+/**
+ * gst_gl_display_get_handle:
+ * @display: a #GstGLDisplay
+ *
+ * Returns: the native handle for the display
+ *
+ * Since: 1.4
+ */
 guintptr
 gst_gl_display_get_handle (GstGLDisplay * display)
 {

gst-libs/gst/gl/gstglfilter.c

@@ -20,6 +20,15 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstglfilter
+ * @short_description: GstBaseTransform subclass for dealing with RGBA textures
+ * @see_also: #GstBaseTransform, #GstGLContext, #GstGLFramebuffer
+ *
+ * #GstGLFilter helps to implement simple OpenGL filter elements taking a
+ * single input and producing a single output with a #GstGLFramebuffer
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -896,6 +905,8 @@ gst_gl_filter_decide_allocation (GstBaseTransform * trans, GstQuery * query)
  * automatic download if needed.
  *
  * Returns: whether the transformation succeeded
+ *
+ * Since: 1.4
  */
 gboolean
 gst_gl_filter_filter_texture (GstGLFilter * filter, GstBuffer * inbuf,
@@ -1023,6 +1034,8 @@ _glcb (gpointer data)
  * Transforms @input into @output using @func on through FBO.
  *
  * Returns: the return value of @func
+ *
+ * Since: 1.10
  */
 gboolean
 gst_gl_filter_render_to_target (GstGLFilter * filter, GstGLMemory * input,
@@ -1101,6 +1114,8 @@ _draw_with_shader_cb (GstGLFilter * filter, GstGLMemory * in_tex,
  * Transforms @input into @output using @shader with a FBO.
  *
  * See also: gst_gl_filter_render_to_target()
+ *
+ * Since: 1.4
  */
 /* attach target to a FBO, use shader, pass input as "tex" uniform to
  * the shader, render input to a quad */
@@ -1171,6 +1186,8 @@ _unbind_buffer (GstGLFilter * filter)
  * modifies is the necessary vertex/index buffers and, if necessary, a
  * Vertex Array Object for drawing a fullscreen quad.  Framebuffer state,
  * any shaders, viewport state, etc must be setup by the caller.
+ *
+ * Since: 1.10
  */
 void
 gst_gl_filter_draw_fullscreen_quad (GstGLFilter * filter)

gst-libs/gst/gl/gstglfilter.h

@@ -39,23 +39,25 @@ GType gst_gl_filter_get_type(void);
 #define GST_IS_GL_FILTER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass) ,GST_TYPE_GL_FILTER))
 #define GST_GL_FILTER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj) ,GST_TYPE_GL_FILTER,GstGLFilterClass))
 
+/**
+ * GstGLFilterRenderFunc:
+ * @filter: the #GstGLFIlter
+ * @in_tex: the input #GstGLMemory to render
+ * @user_data: user data
+ *
+ * Returns: whether the render succeeded
+ *
+ * Since: 1.10
+ */
 typedef gboolean (*GstGLFilterRenderFunc) (GstGLFilter * filter, GstGLMemory * in_tex, gpointer user_data);
 
 /**
  * GstGLFilter:
- * @base_transform: parent #GstBaseTransform
+ * @parent: parent #GstGLBaseFilter
- * @pool: the currently configured #GstBufferPool
- * @display: the currently configured #GstGLDisplay
  * @in_info: the video info for input buffers
  * @out_info: the video info for output buffers
- * @fbo: GL Framebuffer object used for transformations
+ * @out_caps: the output #GstCaps
- * @depthbuffer: GL renderbuffer attached to @fbo
+ * @fbo: #GstGLFramebuffer object used for transformations
- * @upload: the object used for uploading data, if needed
- * @download: the object used for downloading data, if needed
- *
- * #GstGLFilter is a base class that provides the logic of getting the GL context
- * from downstream and automatic upload/download for non-#GstGLMemory
- * #GstBuffer<!--  -->s.
  */
 struct _GstGLFilter
 {
@@ -88,7 +90,7 @@ struct _GstGLFilter
 
 /**
  * GstGLFilterClass:
- * @base_transform_class: parent class
+ * @parent_class: parent #GstGLBaseFilterClass
  * @set_caps: mirror from #GstBaseTransform
  * @filter: perform operations on the input and output buffers.  In general,
  *          you should avoid using this method if at all possible. One valid
@@ -118,6 +120,7 @@ struct _GstGLFilterClass
   void (*display_init_cb)       (GstGLFilter *filter);
   void (*display_reset_cb)      (GstGLFilter *filter);
 
+  /* <private> */
   gpointer                      _padding[GST_PADDING];
 };
 

gst-libs/gst/gl/gstglformat.c

@@ -18,6 +18,15 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstglformat
+ * @short_description: utilities for dealing with OpenGL formats
+ * @see_also: #GstGLBaseMemory, #GstGLMemory, #GstGLFramebuffer, #GstGLBuffer
+ *
+ * Some useful utilities for converting between various formats and OpenGL
+ * formats.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -333,7 +342,7 @@ gst_gl_texture_target_to_string (GstGLTextureTarget target)
 }
 
 /**
- * gst_gl_texture_target_to_string:
+ * gst_gl_texture_target_from_string:
  * @str: a string equivalant to one of the GST_GL_TEXTURE_TARGET_*_STR values
  *
  * Returns: the #GstGLTextureTarget represented by @str or

gst-libs/gst/gl/gstglframebuffer.h

@@ -109,7 +109,7 @@ gboolean                gst_gl_context_check_framebuffer_status     (GstGLContex
 GST_EXPORT
 gboolean                gst_gl_framebuffer_draw_to_texture          (GstGLFramebuffer * fb,
                                                                      GstGLMemory * mem,
-                                                                     GstGLFramebufferFunc cb,
+                                                                     GstGLFramebufferFunc func,
                                                                      gpointer user_data);
 
 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC

gst-libs/gst/gl/gstglmemory.c

@@ -260,6 +260,7 @@ _gl_tex_create (GstGLMemory * gl_mem, GError ** error)
  * @parent: (allow-none): the parent #GstMemory to initialize with
  * @context: the #GstGLContext to initialize with
  * @target: the #GstGLTextureTarget for this #GstGLMemory
+ * @tex_type: the #GstVideoGLTextureType for this #GstGLMemory
  * @params: (allow-none): the @GstAllocationParams to initialize with
  * @info: the #GstVideoInfo for this #GstGLMemory
  * @plane: the plane number (starting from 0) for this #GstGLMemory
@@ -1129,7 +1130,7 @@ gst_gl_video_allocation_params_init_full (GstGLVideoAllocationParams * params,
  * @plane: the video plane of @v_info to allocate
  * @valign: (allow-none): any #GstVideoAlignment applied to symem mappings of the texture
  * @target: the #GstGLTextureTarget for the created textures
- * @target: the #GstVideoGLTextureType for the created textures
+ * @tex_type: the #GstVideoGLTextureType for the created textures
  *
  * Returns: a new #GstGLVideoAllocationParams for allocating #GstGLMemory's
  *
@@ -1335,6 +1336,8 @@ gst_gl_video_allocation_params_copy_data (GstGLVideoAllocationParams * src_vid,
  * @buffer: a #GstBuffer to setup
  * @params: the #GstGLVideoAllocationParams to allocate with
  * @tex_types: (allow-none): a list of #GstVideoGLTextureType's to allocate with.
+ * @wrapped_data: a list of wrapped data pointers
+ * @n_wrapped_pointers: the number of elements in @tex_types and @wrapped_data
  *
  * Returns: whether the buffer was correctly setup
  *

gst-libs/gst/gl/gstglmemory.h

@@ -51,8 +51,7 @@ GType gst_gl_memory_allocator_get_type(void);
 
 /**
  * GstGLMemory:
- * @mem: the parent object
+ * @mem: the parent #GstGLBaseMemory object
- * @context: the #GstGLContext to use for GL operations
  * @tex_id: the GL texture id for this memory
  * @tex_target: the GL texture target for this memory
  * @tex_type: the texture type
@@ -88,6 +87,15 @@ typedef struct _GstGLVideoAllocationParams GstGLVideoAllocationParams;
 
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_VIDEO (1 << 3)
 
+/**
+ * GstGLVideoAllocationParams:
+ * @parent: the parent #GstGLAllocationParams structure
+ * @v_info: the #GstVideoInfo to allocate
+ * @plane: the video plane index to allocate
+ * @valign: the #GstVideoAlignment to align the system representation to (may be %NULL for the default)
+ * @target: the #GstGLTextureTarget to allocate
+ * @tex_type: the #GstVideoGLTextureType to allocate
+ */
 struct _GstGLVideoAllocationParams
 {
   GstGLAllocationParams  parent;
@@ -178,21 +186,24 @@ void            gst_gl_video_allocation_params_copy_data    (GstGLVideoAllocatio
  */
 struct _GstGLMemoryAllocator
 {
+  /* <private> */
   GstGLBaseMemoryAllocator parent;
 
-  /* <private> */
   gpointer _padding[GST_PADDING];
 };
 
 /**
  * GstGLMemoryAllocatorClass:
- *
+ * @map: provide a custom map implementation
- * The #GstGLMemoryAllocatorClass only contains private data
+ * @copy: provide a custom copy implementation
+ * @unmap: provide a custom unmap implementation
  */
 struct _GstGLMemoryAllocatorClass
 {
+  /* <private> */
   GstGLBaseMemoryAllocatorClass             parent_class;
 
+  /* <public> */
   GstGLBaseMemoryAllocatorMapFunction       map;
   GstGLBaseMemoryAllocatorCopyFunction      copy;
   GstGLBaseMemoryAllocatorUnmapFunction     unmap;

gst-libs/gst/gl/gstglmemorypbo.c

@@ -37,9 +37,6 @@
  * #GstGLMemoryPBO is created or wrapped through gst_gl_base_memory_alloc()
  * with #GstGLVideoAllocationParams.
  *
- * #GstGLMemoryPBO is created through gst_gl_memory_pbo_alloc() or system memory can
- * be wrapped through gst_gl_memory_pbo_wrapped().
- *
  * Data is uploaded or downloaded from the GPU as is necessary.
  */
 
@@ -803,7 +800,7 @@ _upload_transfer (GstGLContext * context, GstGLMemoryPBO * gl_mem)
 }
 
 /**
- * gst_gl_memory_pbo_download_transfer:
+ * gst_gl_memory_pbo_upload_transfer:
  * @gl_mem: a #GstGLMemoryPBO
  *
  * Transfer the texture data from the PBO into the texture if necessary.

gst-libs/gst/gl/gstglmemorypbo.h

@@ -49,12 +49,11 @@ GType gst_gl_memory_pbo_allocator_get_type(void);
  */
 struct _GstGLMemoryPBO
 {
+  /* <private> */
   GstGLMemory      mem;
 
-  /* <private> */
   GstGLBuffer          *pbo;
 
-  /* <private> */
   gpointer                  _padding[GST_PADDING];
 };
 

gst-libs/gst/gl/gstgloverlaycompositor.c

@@ -18,6 +18,12 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstgloverlaycompositor
+ * @short_description: Composite multiple overlays using OpenGL
+ * @see_also: #GstGLMemory, #GstGLContext
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

gst-libs/gst/gl/gstglsl.h

@@ -29,12 +29,46 @@ GST_EXPORT
 GQuark gst_glsl_error_quark (void);
 #define GST_GLSL_ERROR (gst_glsl_error_quark ())
 
+/**
+ * GstGLSLError:
+ * @GST_GLSL_ERROR_COMPILE: Compilation error occured
+ * @GST_GLSL_ERROR_LINK: Link error occured
+ * @GST_GLSL_ERROR_PROGRAM: General program error occured
+ *
+ * Compilation stage that caused an error
+ *
+ * Since: 1.8
+ */
 typedef enum {
   GST_GLSL_ERROR_COMPILE,
   GST_GLSL_ERROR_LINK,
   GST_GLSL_ERROR_PROGRAM,
 } GstGLSLError;
 
+/**
+ * GstGLSLVersion:
+ * @GST_GLSL_VERSION_NONE: no version
+ * @GST_GLSL_VERSION_100: #version 100 (only valid for ES)
+ * @GST_GLSL_VERSION_110: #version 110 (only valid for compatibility desktop GL)
+ * @GST_GLSL_VERSION_120: #version 120 (only valid for compatibility desktop GL)
+ * @GST_GLSL_VERSION_130: #version 130 (only valid for compatibility desktop GL)
+ * @GST_GLSL_VERSION_140: #version 140 (only valid for compatibility desktop GL)
+ * @GST_GLSL_VERSION_150: #version 150 (valid for compatibility/core desktop GL)
+ * @GST_GLSL_VERSION_300: #version 300 (only valid for ES)
+ * @GST_GLSL_VERSION_310: #version 310 (only valid for ES)
+ * @GST_GLSL_VERSION_320: #version 320 (only valid for ES)
+ * @GST_GLSL_VERSION_330: #version 330 (valid for compatibility/core desktop GL)
+ * @GST_GLSL_VERSION_400: #version 400 (valid for compatibility/core desktop GL)
+ * @GST_GLSL_VERSION_410: #version 410 (valid for compatibility/core desktop GL)
+ * @GST_GLSL_VERSION_420: #version 420 (valid for compatibility/core desktop GL)
+ * @GST_GLSL_VERSION_430: #version 430 (valid for compatibility/core desktop GL)
+ * @GST_GLSL_VERSION_440: #version 440 (valid for compatibility/core desktop GL)
+ * @GST_GLSL_VERSION_450: #version 450 (valid for compatibility/core desktop GL)
+ *
+ * GLSL version list
+ *
+ * Since: 1.8
+ */
 typedef enum
 {
   GST_GLSL_VERSION_NONE = 0,
@@ -55,10 +89,20 @@ typedef enum
   GST_GLSL_VERSION_430 = 430, /* GL */
   GST_GLSL_VERSION_440 = 440, /* GL */
   GST_GLSL_VERSION_450 = 450, /* GL */
-
-  GST_GLSL_VERSION_ANY = -1,
 } GstGLSLVersion;
 
+/**
+ * GstGLSLProfile:
+ * @GST_GLSL_PROFILE_NONE: no profile supported/available
+ * @GST_GLSL_PROFILE_ES: OpenGL|ES profile
+ * @GST_GLSL_PROFILE_CORE: OpenGL core profile
+ * @GST_GLSL_PROFILE_COMPATIBILITY: OpenGL compatibility profile
+ * @GST_GLSL_PROFILE_ANY: any OpenGL/OpenGL|ES profile
+ *
+ * GLSL profiles
+ *
+ * Since: 1.8
+ */
 typedef enum
 {
   /* XXX: maybe make GstGLAPI instead */

gst-libs/gst/gl/gstglslstage.c

@@ -200,6 +200,8 @@ _ensure_shader (GstGLSLStage * stage)
  * @str: an array of strings concatted together to produce a shader
  *
  * Returns: (transfer full): a new #GstGLSLStage of the specified @type
+ *
+ * Since: 1.8
  */
 GstGLSLStage *
 gst_glsl_stage_new_with_strings (GstGLContext * context, guint type,
@@ -237,6 +239,8 @@ gst_glsl_stage_new_with_strings (GstGLContext * context, guint type,
  * @str: a shader string
  *
  * Returns: (transfer full): a new #GstGLSLStage of the specified @type
+ *
+ * Since: 1.8
  */
 GstGLSLStage *
 gst_glsl_stage_new_with_string (GstGLContext * context, guint type,
@@ -252,6 +256,8 @@ gst_glsl_stage_new_with_string (GstGLContext * context, guint type,
  * @type: the GL enum shader stage type
  *
  * Returns: (transfer full): a new #GstGLSLStage of the specified @type
+ *
+ * Since: 1.8
  */
 GstGLSLStage *
 gst_glsl_stage_new (GstGLContext * context, guint type)
@@ -265,6 +271,8 @@ gst_glsl_stage_new (GstGLContext * context, guint type)
  * @context: a #GstGLContext
  *
  * Returns: (transfer full): a new #GstGLSLStage with the default vertex shader
+ *
+ * Since: 1.8
  */
 GstGLSLStage *
 gst_glsl_stage_new_default_vertex (GstGLContext * context)
@@ -280,6 +288,8 @@ gst_glsl_stage_new_default_vertex (GstGLContext * context)
  * @context: a #GstGLContext
  *
  * Returns: (transfer full): a new #GstGLSLStage with the default fragment shader
+ *
+ * Since: 1.8
  */
 GstGLSLStage *
 gst_glsl_stage_new_default_fragment (GstGLContext * context)
@@ -299,6 +309,8 @@ gst_glsl_stage_new_default_fragment (GstGLContext * context)
  * @str: (transfer none): a GLSL shader string
  *
  * Replaces the current shader string with @str.
+ *
+ * Since: 1.8
  */
 gboolean
 gst_glsl_stage_set_strings (GstGLSLStage * stage, GstGLSLVersion version,
@@ -344,6 +356,8 @@ gst_glsl_stage_set_strings (GstGLSLStage * stage, GstGLSLVersion version,
  * @stage: a #GstGLSLStage
  *
  * Returns: The GL shader type for this shader stage
+ *
+ * Since: 1.8
  */
 guint
 gst_glsl_stage_get_shader_type (GstGLSLStage * stage)
@@ -358,6 +372,8 @@ gst_glsl_stage_get_shader_type (GstGLSLStage * stage)
  * @stage: a #GstGLSLStage
  *
  * Returns: The GL handle for this shader stage
+ *
+ * Since: 1.8
  */
 guint
 gst_glsl_stage_get_handle (GstGLSLStage * stage)
@@ -373,6 +389,8 @@ gst_glsl_stage_get_handle (GstGLSLStage * stage)
  * @stage: a #GstGLSLStage
  *
  * Returns: The GLSL version for the current shader stage
+ *
+ * Since: 1.8
  */
 GstGLSLVersion
 gst_glsl_stage_get_version (GstGLSLStage * stage)
@@ -387,6 +405,8 @@ gst_glsl_stage_get_version (GstGLSLStage * stage)
  * @stage: a #GstGLSLStage
  *
  * Returns: The GLSL profile for the current shader stage
+ *
+ * Since: 1.8
  */
 GstGLSLProfile
 gst_glsl_stage_get_profile (GstGLSLStage * stage)
@@ -503,6 +523,8 @@ _compile_shader (GstGLContext * context, struct compile *data)
  * @error: a #GError to use on failure
  *
  * Returns: whether the compilation suceeded
+ *
+ * Since: 1.8
  */
 gboolean
 gst_glsl_stage_compile (GstGLSLStage * stage, GError ** error)

gst-libs/gst/gl/gstglslstage.h

@@ -39,11 +39,11 @@ G_BEGIN_DECLS
  */
 struct _GstGLSLStage
 {
+  /*< private >*/
   GstObject parent;
 
   GstGLContext *context;
 
-  /*< private >*/
   GstGLSLStagePrivate *priv;
 
   gpointer _padding[GST_PADDING];
@@ -56,9 +56,9 @@ struct _GstGLSLStage
  */
 struct _GstGLSLStageClass
 {
+  /* <private> */
   GstObjectClass parent;
 
-  /* <private> */
   gpointer _padding[GST_PADDING];
 };
 

gst-libs/gst/gl/gstglsyncmeta.c

@@ -18,6 +18,15 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstglsyncmeta
+ * @short_description: synchronization primitives
+ * @see_also: #GstGLBaseMemory, #GstGLContext
+ *
+ * #GstGLSyncMeta provides the ability to synchronize the OpenGL command stream
+ * with the CPU or with other OpenGL contexts.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -112,6 +121,16 @@ _default_free_gl (GstGLSyncMeta * sync_meta, GstGLContext * context)
   }
 }
 
+/**
+ * gst_buffer_add_gl_sync_meta_full:
+ * @context: a #GstGLContext
+ * @buffer: a #GstBuffer
+ * @data: sync data to hold
+ *
+ * Returns: (transfer none): the #GstGLSyncMeta added to #GstBuffer
+ *
+ * Since: 1.8
+ */
 GstGLSyncMeta *
 gst_buffer_add_gl_sync_meta_full (GstGLContext * context, GstBuffer * buffer,
     gpointer data)
@@ -133,6 +152,15 @@ gst_buffer_add_gl_sync_meta_full (GstGLContext * context, GstBuffer * buffer,
   return meta;
 }
 
+/**
+ * gst_buffer_add_gl_sync_meta:
+ * @context: a #GstGLContext
+ * @buffer: a #GstBuffer
+ *
+ * Returns: (transfer none): the #GstGLSyncMeta added to #GstBuffer
+ *
+ * Since: 1.6
+ */
 GstGLSyncMeta *
 gst_buffer_add_gl_sync_meta (GstGLContext * context, GstBuffer * buffer)
 {
@@ -158,6 +186,15 @@ _set_sync_point (GstGLContext * context, GstGLSyncMeta * sync_meta)
   sync_meta->set_sync_gl (sync_meta, context);
 }
 
+/**
+ * gst_gl_sync_meta_set_sync_point:
+ * @sync_meta: a #GstGLSyncMeta
+ * @context: a #GstGLContext
+ *
+ * Set a sync point to possibly wait on at a later time.
+ *
+ * Since: 1.6
+ */
 void
 gst_gl_sync_meta_set_sync_point (GstGLSyncMeta * sync_meta,
     GstGLContext * context)
@@ -178,6 +215,16 @@ _wait (GstGLContext * context, GstGLSyncMeta * sync_meta)
   sync_meta->wait_gl (sync_meta, context);
 }
 
+/**
+ * gst_gl_sync_meta_wait:
+ * @sync_meta: a #GstGLSyncMeta
+ * @context: a #GstGLContext
+ *
+ * Insert a wait into @context's command stream ensuring all previous OpenGL
+ * commands before @sync_meta have completed.
+ *
+ * Since: 1.6
+ */
 void
 gst_gl_sync_meta_wait (GstGLSyncMeta * sync_meta, GstGLContext * context)
 {
@@ -197,6 +244,17 @@ _wait_cpu (GstGLContext * context, GstGLSyncMeta * sync_meta)
   sync_meta->wait_cpu_gl (sync_meta, context);
 }
 
+/**
+ * gst_gl_sync_meta_wait_cpu:
+ * @sync_meta: a #GstGLSyncMeta
+ * @context: a #GstGLContext
+ *
+ * Perform a wait so that the sync point has passed from the CPU's perspective
+ * What that means, is that all GL operations changing CPU-visible data before
+ * the sync point are now visible.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_sync_meta_wait_cpu (GstGLSyncMeta * sync_meta, GstGLContext * context)
 {

gst-libs/gst/gl/gstglsyncmeta.h

@@ -29,9 +29,31 @@ G_BEGIN_DECLS
 #define GST_GL_SYNC_META_INFO     (gst_gl_sync_meta_get_info())
 typedef struct _GstGLSyncMeta GstGLSyncMeta;
 
+/**
+ * GST_BUFFER_POOL_OPTION_GL_SYNC_META:
+ *
+ * An option that can be activated on bufferpools to request OpenGL
+ * synchronization metadata on buffers from the pool.
+ */
 #define GST_BUFFER_POOL_OPTION_GL_SYNC_META "GstBufferPoolOptionGLSyncMeta"
 
-struct _GstGLSyncMeta {
+/**
+ * GstGLSyncMeta:
+ * @parent: the parent #GstMeta
+ * @context: the #GstGLContext used to allocate the meta
+ * @data: a custom data pointer for the implementation
+ * @set_sync: set a sync point in the OpenGL command stream
+ * @set_sync_gl: the same as @set_sync but called from @context's thread
+ * @wait: execute a wait on the previously set sync point into the OpenGL command stream
+ * @wait_gl: the same as @wait but called from @context's thread
+ * @wait_cpu: wait for the previously set sync point to pass from the CPU
+ * @wait_cpu_gl: the same as @wait_cpu but called from @context's thread
+ * @copy: copy @data into a new #GstGLSyncMeta
+ * @free: free @data
+ * @free_gl: free @data in @context's thread
+ */
+struct _GstGLSyncMeta
+{
   GstMeta parent;
 
   GstGLContext *context;
@@ -62,11 +84,11 @@ GST_EXPORT
 GstGLSyncMeta *     gst_buffer_add_gl_sync_meta_full    (GstGLContext * context, GstBuffer * buffer,
                                                          gpointer data);
 GST_EXPORT
-void                gst_gl_sync_meta_set_sync_point     (GstGLSyncMeta * sync, GstGLContext * context);
+void                gst_gl_sync_meta_set_sync_point     (GstGLSyncMeta * sync_meta, GstGLContext * context);
 GST_EXPORT
-void                gst_gl_sync_meta_wait               (GstGLSyncMeta * sync, GstGLContext * context);
+void                gst_gl_sync_meta_wait               (GstGLSyncMeta * sync_meta, GstGLContext * context);
 GST_EXPORT
-void                gst_gl_sync_meta_wait_cpu           (GstGLSyncMeta * sync, GstGLContext * context);
+void                gst_gl_sync_meta_wait_cpu           (GstGLSyncMeta * sync_meta, GstGLContext * context);
 
 G_END_DECLS
 

gst-libs/gst/gl/gstglutils.c

@@ -17,6 +17,13 @@
  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  * Boston, MA 02110-1301, USA.
  */
+
+/**
+ * SECTION:gstglutils
+ * @short_description: some miscellaneous utilities for OpenGL
+ * @see_also: #GstGLContext
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

gst-libs/gst/gl/gstglviewconvert.c

@@ -22,6 +22,8 @@
 
 /**
  * SECTION:gstglviewconvert
+ * @short_description: convert between steroscopic/multiview video formats
+ * @see_also: #GstGLColorConvert, #GstGLContext
  *
  * Convert stereoscopic/multiview video using fragment shaders.
  */
@@ -129,6 +131,7 @@ gst_gl_stereo_downmix_mode_get_type (void)
   return g_define_type_id__volatile;
 }
 
+/* *INDENT-OFF* */
 /* These match the order and number of DOWNMIX_ANAGLYPH_* modes */
 static GLfloat downmix_matrices[][2][9] = {
   {                             /* Green-Magenta Dubois */
@@ -152,6 +155,7 @@ static gfloat identity_matrix[] = {
   0.0f, 0.0f, 1.0f, 0.0f,
   0.0f, 0.0f, 0.0f, 1.0f,
 };
+/* *INDENT-ON* */
 
 #define glsl_OES_extension_string "#extension GL_OES_EGL_image_external : require \n"
 
@@ -327,12 +331,28 @@ gst_gl_view_convert_finalize (GObject * object)
   G_OBJECT_CLASS (gst_gl_view_convert_parent_class)->finalize (object);
 }
 
+/**
+ * gst_gl_view_convert_new:
+ *
+ * Returns: a new #GstGLViewConvert
+ *
+ * Since: 1.6
+ */
 GstGLViewConvert *
 gst_gl_view_convert_new (void)
 {
   return g_object_new (GST_TYPE_GL_VIEW_CONVERT, NULL);
 }
 
+/**
+ * gst_gl_view_convert_set_context:
+ * @viewconvert: a #GstGLViewConvert
+ * @context: the #GstGLContext to set
+ *
+ * Set @context on @viewconvert
+ *
+ * Since: 1.6
+ */
 void
 gst_gl_view_convert_set_context (GstGLViewConvert * viewconvert,
     GstGLContext * context)
@@ -398,6 +418,8 @@ _view_convert_set_format (GstGLViewConvert * viewconvert,
  * @out_caps: output #GstCaps
  *
  * Initializes @viewconvert with the information required for conversion.
+ *
+ * Since: 1.6
  */
 gboolean
 gst_gl_view_convert_set_caps (GstGLViewConvert * viewconvert,
@@ -1038,6 +1060,19 @@ _intersect_with_mview_modes (GstCaps * caps, const GValue * modes)
   return result;
 }
 
+/**
+ * gst_gl_view_convert_transform_caps:
+ * @viewconvert: a #GstGLViewConvert
+ * @direction: a #GstPadDirection
+ * @caps: (transfer none): the #GstCaps to transform
+ * @filter: (transfer none): a set of filter #GstCaps
+ *
+ * Provides an implementation of #GstBaseTransformClass::transform_caps()
+ *
+ * Returns: (transfer full): the converted #GstCaps
+ *
+ * Since: 1.6
+ */
 GstCaps *
 gst_gl_view_convert_transform_caps (GstGLViewConvert * viewconvert,
     GstPadDirection direction, GstCaps * caps, GstCaps * filter)
@@ -1215,6 +1250,19 @@ _fixate_texture_target (GstGLViewConvert * viewconvert,
   return gst_caps_fixate (other);
 }
 
+/**
+ * gst_gl_view_convert_fixate_caps:
+ * @viewconvert: a #GstGLViewConvert
+ * @direction: a #GstPadDirection
+ * @caps: (transfer none): the #GstCaps of @direction
+ * @othercaps: (transfer full): the #GstCaps to fixate
+ *
+ * Provides an implementation of #GstBaseTransformClass::fixate_caps()
+ *
+ * Returns: (transfer full): the fixated #GstCaps
+ *
+ * Since: 1.6
+ */
 GstCaps *
 gst_gl_view_convert_fixate_caps (GstGLViewConvert * viewconvert,
     GstPadDirection direction, GstCaps * caps, GstCaps * othercaps)
@@ -1295,6 +1343,15 @@ done:
   return othercaps;
 }
 
+/**
+ * gst_gl_view_convert_reset:
+ * @viewconvert: a #GstGLViewConvert
+ *
+ * Reset @viewconvert to the default state.  Further operation will require
+ * setting the caps with gst_gl_view_convert_set_caps().
+ *
+ * Since: 1.6
+ */
 void
 gst_gl_view_convert_reset (GstGLViewConvert * viewconvert)
 {
@@ -1368,6 +1425,18 @@ gst_gl_view_convert_get_property (GObject * object, guint prop_id,
   }
 }
 
+/**
+ * gst_gl_view_convert_perform:
+ * @viewconvert: a #GstGLViewConvert
+ * @inbuf: (transfer none): the #GstGLMemory filled #GstBuffer to convert
+ *
+ * Converts the data contained by @inbuf using the formats specified by the
+ * #GstCaps passed to gst_gl_view_convert_set_caps() 
+ *
+ * Returns: (transfer full): a converted #GstBuffer or %NULL
+ *
+ * Since: 1.6
+ */
 GstBuffer *
 gst_gl_view_convert_perform (GstGLViewConvert * viewconvert, GstBuffer * inbuf)
 {
@@ -2122,6 +2191,18 @@ out:
   return;
 }
 
+/**
+ * gst_gl_view_convert_submit_input_buffer:
+ * @viewconvert: a #GstGLViewConvert
+ * @is_discont: true if we have a discontinuity
+ * @input: (transfer full): a #GstBuffer
+ *
+ * Submit @input to be processed by @viewconvert
+ *
+ * Returns: a #GstFlowReturn
+ *
+ * Since: 1.6
+ */
 GstFlowReturn
 gst_gl_view_convert_submit_input_buffer (GstGLViewConvert * viewconvert,
     gboolean is_discont, GstBuffer * input)
@@ -2155,6 +2236,17 @@ gst_gl_view_convert_submit_input_buffer (GstGLViewConvert * viewconvert,
   return ret;
 }
 
+/**
+ * gst_gl_view_convert_get_output:
+ * @viewconvert: a #GstGLViewConvert
+ * @outbuf_ptr: (out): a #GstBuffer
+ *
+ * Retrieve the processed output buffer placing the output in @outbuf_ptr.
+ *
+ * Returns: a #GstFlowReturn
+ *
+ * Since: 1.6
+ */
 GstFlowReturn
 gst_gl_view_convert_get_output (GstGLViewConvert * viewconvert,
     GstBuffer ** outbuf_ptr)

gst-libs/gst/gl/gstglviewconvert.h

@@ -36,14 +36,27 @@ G_BEGIN_DECLS
 GST_EXPORT
 GType gst_gl_stereo_downmix_mode_get_type (void);
 
+/**
+ * GstGLStereoDownmix:
+ * @GST_GL_STEREO_DOWNMIX_ANAGLYPH_GREEN_MAGENTA_DUBOIS: Dubois optimised Green-Magenta anaglyph
+ * @GST_GL_STEREO_DOWNMIX_ANAGLYPH_RED_CYAN_DUBOIS: Dubois optimised Red-Cyan anaglyph
+ * @GST_GL_STEREO_DOWNMIX_ANAGLYPH_AMBER_BLUE_DUBOIS: Dubois optimised Amber-Blue anaglyph
+ *
+ * Output anaglyph type to generate when downmixing to mono
+ */
 enum _GstGLStereoDownmix {
   GST_GL_STEREO_DOWNMIX_ANAGLYPH_GREEN_MAGENTA_DUBOIS,
   GST_GL_STEREO_DOWNMIX_ANAGLYPH_RED_CYAN_DUBOIS,
   GST_GL_STEREO_DOWNMIX_ANAGLYPH_AMBER_BLUE_DUBOIS,
 };
-
 typedef enum _GstGLStereoDownmix GstGLStereoDownmix;
 
+/**
+ * GstGLViewConvert:
+ *
+ * #GstGLViewConvert is an opaque struct and should only be accessed through the
+ * provided api.
+ */
 struct _GstGLViewConvert
 {
   GstObject object;
@@ -77,11 +90,16 @@ struct _GstGLViewConvert
   gpointer _padding[GST_PADDING];
 };
 
+/**
+ * GstGLViewConvertClass:
+ *
+ * Opaque #GstGLViewConvertClass struct
+ */
 struct _GstGLViewConvertClass
 {
+  /* <private> */
   GstObjectClass object_class;
 
-  /* <private> */
   gpointer                  _padding[GST_PADDING];
 };
 

gst-libs/gst/gl/gstglwindow.h

@@ -43,6 +43,12 @@ G_BEGIN_DECLS
 
 #define GST_GL_WINDOW_ERROR (gst_gl_window_error_quark ())
 
+/**
+ * GstGLWindowError:
+ * @GST_GL_WINDOW_ERROR_FAILED: failed for a unspecified reason
+ * @GST_GL_WINDOW_ERROR_OLD_LIBS: the implementation is too old
+ * @GST_GL_WINDOW_ERROR_RESOURCE_UNAVAILABLE: no such resource was found
+ */
 typedef enum
 {
   GST_GL_WINDOW_ERROR_FAILED,
@@ -108,13 +114,14 @@ struct _GstGLWindow {
  *                      not have been called.  Required to be reentrant.
  * @open: open the connection to the display
  * @close: close the connection to the display
- * @get_surface_dimensions: get the width and height of the surface we are
- *                          rendering into.
  * @handle_events: whether to handle 'extra' events from the windowing system.
  *                 Basic events like surface moves and resizes are still valid
  *                 things to listen for.
  * @set_preferred_size: request that the window change surface size.  The
  *                      implementation is free to ignore this information.
+ * @show: request that the window be shown to the user
+ * @set_render_rectangle: request a rectangle to render into.  See #GstVideoOverlay
+ * @queue_resize: request a resize to occur when possible
  */
 struct _GstGLWindowClass {
   GstObjectClass parent_class;