gl*memory: document new functionality and objects

10 files changed, 503 insertions, 41 deletions

diff --git a/gst-libs/gst/gl/gstgl_enums.h b/gst-libs/gst/gl/gstgl_enums.h
index c4578e4ee..25c7b39ac 100644
--- a/gst-libs/gst/gl/gstgl_enums.h
+++ b/gst-libs/gst/gl/gstgl_enums.h
@@ -21,6 +21,15 @@
 #ifndef _GST_GL_ENUMS_H_
 #define _GST_GL_ENUMS_H_
 
+/**
+ * GstGLTextureTarget:
+ * @GST_GL_TEXTURE_TARGET_NONE: no texture target
+ * @GST_GL_TEXTURE_TARGET_2D: 2D texture target
+ * @GST_GL_TEXTURE_TARGET_RECTANGLE: rectangle texture target
+ * @GST_GL_TEXTURE_TARGET_EXTERNAL_OES: external oes texture target
+ *
+ * Since: 1.8
+ */
 typedef enum
 {
   GST_GL_TEXTURE_TARGET_NONE,
diff --git a/gst-libs/gst/gl/gstglbasememory.c b/gst-libs/gst/gl/gstglbasememory.c
index 7300da5ba..062c19c59 100644
--- a/gst-libs/gst/gl/gstglbasememory.c
+++ b/gst-libs/gst/gl/gstglbasememory.c
@@ -107,6 +107,8 @@ _mem_create_gl (GstGLContext * context, struct create_data *transfer)
  * @notify: (allow-none): a #GDestroyNotify
  *
  * Initializes @mem with the required parameters
+ *
+ * Since: 1.8
  */
 void
 gst_gl_base_memory_init (GstGLBaseMemory * mem, GstAllocator * allocator,
@@ -176,7 +178,8 @@ _align_data (gpointer data, gsize align)
   guint8 *ret = data;
   gsize aoffset;
 
-  /* do alignment */
+  /* do alignment, data must have enough padding at the end to move at most
+   * align bytes */
   if ((aoffset = ((guintptr) ret & align))) {
     aoffset = (align + 1) - aoffset;
     ret += aoffset;
@@ -457,6 +460,8 @@ _mem_free (GstAllocator * allocator, GstMemory * memory)
  *
  * Initializes the GL Base Memory allocator. It is safe to call this function
  * multiple times.  This must be called before any other GstGLBaseMemory operation.
+ *
+ * Since: 1.8
  */
 void
 gst_gl_base_memory_init_once (void)
@@ -508,6 +513,8 @@ gst_gl_base_memory_allocator_init (GstGLBaseMemoryAllocator * allocator)
  * @mem:a #GstMemory
  * 
  * Returns: whether the memory at @mem is a #GstGLBaseMemory
+ *
+ * Since: 1.8
  */
 gboolean
 gst_is_gl_base_memory (GstMemory * mem)
@@ -525,6 +532,8 @@ gst_is_gl_base_memory (GstMemory * mem)
  * @size: the number of bytes to copy
  *
  * Returns: whether the copy suceeded.
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_base_memory_memcpy (GstGLBaseMemory * src, GstGLBaseMemory * dest,
@@ -564,7 +573,7 @@ gst_gl_base_memory_memcpy (GstGLBaseMemory * src, GstGLBaseMemory * dest,
  * gst_gl_allocation_params_init:
  * @params: the #GstGLAllocationParams to initialize
  * @struct_size: the struct size of the implementation
- * @alloc: some alloc flags
+ * @alloc_flags: some alloc flags
  * @copy: a copy function
  * @free: a free function
  * @context: (transfer none): a #GstGLContext
@@ -579,6 +588,8 @@ gst_gl_base_memory_memcpy (GstGLBaseMemory * src, GstGLBaseMemory * dest,
  * when freeing the memory.
  *
  * Returns: whether the paramaters could be initialized
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_allocation_params_init (GstGLAllocationParams * params,
@@ -617,6 +628,8 @@ gst_gl_allocation_params_init (GstGLAllocationParams * params,
  *
  * Returns: a copy of the #GstGLAllocationParams specified by @src or %NULL on
  *          failure
+ *
+ * Since: 1.8
  */
 GstGLAllocationParams *
 gst_gl_allocation_params_copy (GstGLAllocationParams * src)
@@ -638,6 +651,8 @@ gst_gl_allocation_params_copy (GstGLAllocationParams * src)
  * @params: the #GstGLAllocationParams to initialize
  *
  * Frees the #GstGLAllocationParams and all associated data.
+ *
+ * Since: 1.8
  */
 void
 gst_gl_allocation_params_free (GstGLAllocationParams * params)
@@ -648,6 +663,15 @@ gst_gl_allocation_params_free (GstGLAllocationParams * params)
   g_free (params);
 }
 
+/**
+ * gst_gl_allocation_params_free_data:
+ * @params: the source #GstGLAllocationParams
+ *
+ * Frees the dynamically allocated data in @params.  Direct subclasses
+ * should call this function in their own overriden free function.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_allocation_params_free_data (GstGLAllocationParams * params)
 {
@@ -657,6 +681,16 @@ gst_gl_allocation_params_free_data (GstGLAllocationParams * params)
     gst_allocation_params_free (params->alloc_params);
 }
 
+/**
+ * gst_gl_allocation_params_copy_data:
+ * @src: the source #GstGLAllocationParams
+ * @dest: the destination #GstGLAllocationParams
+ *
+ * Copies the dynamically allocated data from @src to @dest.  Direct subclasses
+ * should call this function in their own overriden copy function.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_allocation_params_copy_data (GstGLAllocationParams * src,
     GstGLAllocationParams * dest)
@@ -679,6 +713,8 @@ G_DEFINE_BOXED_TYPE (GstGLAllocationParams, gst_gl_allocation_params,
  * @params: the #GstGLAllocationParams to allocate the memory with
  *
  * Returns: a new #GstGLBaseMemory from @allocator with the requested @params.
+ *
+ * Since: 1.8
  */
 GstGLBaseMemory *
 gst_gl_base_memory_alloc (GstGLBaseMemoryAllocator * allocator,
diff --git a/gst-libs/gst/gl/gstglbasememory.h b/gst-libs/gst/gl/gstglbasememory.h
index adea5baef..f862c85c5 100644
--- a/gst-libs/gst/gl/gstglbasememory.h
+++ b/gst-libs/gst/gl/gstglbasememory.h
@@ -44,6 +44,13 @@ GType gst_gl_base_memory_allocator_get_type(void);
 GQuark gst_gl_base_memory_error_quark (void);
 #define GST_GL_BASE_MEMORY_ERROR (gst_gl_base_memory_error_quark ())
 
+/**
+ * GstGLBaseMemoryError:
+ * @GST_GL_BASE_MEMORY_ERROR_FAILED: generic faliure
+ * @GST_GL_BASE_MEMORY_ERROR_OLD_LIBS: the implementation is too old and doesn't
+ *                                     implement enough features
+ * @GST_GL_BASE_MEMORY_ERROR_RESOURCE_UNAVAILABLE: a resource could not be found
+ */
 typedef enum
 {
   GST_GL_BASE_MEMORY_ERROR_FAILED,
@@ -51,6 +58,13 @@ typedef enum
   GST_GL_BASE_MEMORY_ERROR_RESOURCE_UNAVAILABLE,
 } GstGLBaseMemoryError;
 
+/**
+ * GstGLBaseMemoryTransfer:
+ * @GST_GL_BASE_MEMORY_TRANSFER_NEED_DOWNLOAD: the texture needs downloading
+ *                                             to the data pointer
+ * @GST_GL_BASE_MEMORY_TRANSFER_NEED_UPLOAD:   the data pointer needs uploading
+ *                                             to the texture
+ */
 typedef enum
 {
   GST_GL_BASE_MEMORY_TRANSFER_NEED_DOWNLOAD   = (GST_MEMORY_FLAG_LAST << 0),
@@ -101,9 +115,22 @@ struct _GstGLBaseMemory
 };
 
 typedef struct _GstGLAllocationParams GstGLAllocationParams;
-/* subclass has to compose with the parent class */
+/**
+ * GstGLAllocationParamsCopyFunc:
+ * @src: the source #GstGLAllocationParams to copy from
+ * @dest: the source #GstGLAllocationParams to copy
+ *
+ * Copies the parameters from @src into @dest.  The subclass must compose copy
+ * functions from the superclass.
+ */
 typedef void    (*GstGLAllocationParamsCopyFunc)    (GstGLAllocationParams * src, GstGLAllocationParams * dest);
-/* subclass has to compose with the parent class */
+/**
+ * GstGLAllocationParamsFreeFunc:
+ * @params: a #GstGLAllocationParams
+ *
+ * Free any dynamically allocated data.  The subclass must call the superclass'
+ * free.
+ */
 typedef void    (*GstGLAllocationParamsFreeFunc)    (gpointer params);
 
 #define GST_TYPE_GL_ALLOCATION_PARAMS (gst_gl_allocation_params_get_type())
@@ -114,6 +141,20 @@ GType gst_gl_allocation_params_get_type (void);
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE (1 << 2)
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER (1 << 16)
 
+/**
+ * GstGLAllocationParams:
+ * @struct_size: the size of the struct (including and subclass data)
+ * @copy: a #GstGLAllocationParamsCopyFunc
+ * @free: a #GstGLAllocationParamsFreeFunc
+ * @alloc_flags: allocation flags
+ * @alloc_size: the allocation size
+ * @alloc_params: the #GstAllocationParams
+ * @context: a #GstGLContext
+ * @notify: a #GDestroyNotify
+ * @user_data: argument to call @notify with
+ * @wrapped_data: the wrapped data pointer
+ * @gl_handle: the wrapped OpenGL handle
+ */
 /* Because GstAllocationParams is not subclassable, start our own subclass
  * chain.  FIXME: 2.0 make GstAllocationParams subclassable */
 struct _GstGLAllocationParams
@@ -158,35 +199,113 @@ void                    gst_gl_allocation_params_free_data  (GstGLAllocationPara
 void                    gst_gl_allocation_params_copy_data  (GstGLAllocationParams * src,
                                                              GstGLAllocationParams * dest);
 
+/**
+ * GstGLBaseMemoryAllocatorAllocFunction:
+ * @allocator: a #GstGLBaseMemoryAllocator
+ * @params: the #GstGLAllocationParams to allocate the memory with
+ *
+ * Note: not called with a GL context current
+ *
+ * Returns: a newly allocated #GstGLBaseMemory from @allocator and @params
+ *
+ * Since: 1.8
+ */
 typedef GstGLBaseMemory *   (*GstGLBaseMemoryAllocatorAllocFunction)        (GstGLBaseMemoryAllocator * allocator,
                                                                              GstGLAllocationParams * params);
+
+/**
+ * GstGLBaseMemoryAllocatorCreateFunction:
+ * @mem: a #GstGLBaseMemory
+ * @error: a #GError to use on failure
+ *
+ * As this virtual method is called with an OpenGL context current, use this
+ * function to allocate and OpenGL resources needed for your application
+ *
+ * Returns: whether the creation succeeded
+ *
+ * Since: 1.8
+ */
 typedef gboolean            (*GstGLBaseMemoryAllocatorCreateFunction)       (GstGLBaseMemory * mem,
                                                                              GError ** error);
+
+/**
+ * GstGLBaseMemoryAllocatorMapFunction:
+ * @mem: a #GstGLBaseMemory
+ * @info: a #GstMapInfo to map with
+ * @maxsize: the size to map
+ *
+ * Also see gst_memory_map();
+ *
+ * Returns: the mapped pointer
+ *
+ * Since: 1.8
+ */
 typedef gpointer            (*GstGLBaseMemoryAllocatorMapFunction)          (GstGLBaseMemory * mem,
                                                                              GstMapInfo * info,
                                                                              gsize maxsize);
+/**
+ * GstGLBaseMemoryAllocatorUnmapFunction:
+ * @mem: a #GstGLBaseMemory
+ * @info: a #GstMapInfo to map with
+ *
+ * Also see gst_memory_unmap();
+ *
+ * Since: 1.8
+ */
 typedef void                (*GstGLBaseMemoryAllocatorUnmapFunction)        (GstGLBaseMemory * mem,
                                                                              GstMapInfo * info);
+
+/**
+ * GstGLBaseMemoryAllocatorCopyFunction:
+ * @mem: a #GstGLBaseMemory
+ * @offset: the offset to copy from
+ * @size: the number of bytes to copy
+ *
+ * Also see gst_memory_copy();
+ *
+ * Returns: the newly copied #GstGLMemory or %NULL
+ *
+ * Since: 1.8
+ */
 typedef GstGLBaseMemory *   (*GstGLBaseMemoryAllocatorCopyFunction)         (GstGLBaseMemory * mem,
                                                                              gssize offset,
                                                                              gssize size);
+
+/**
+ * GstGLBaseMemoryAllocatorDestroyFunction:
+ * @mem: a #GstGLBaseMemory
+ *
+ * Destroy any resources allocated throughout the lifetime of @mem
+ *
+ * Since: 1.8
+ */
 typedef void                (*GstGLBaseMemoryAllocatorDestroyFunction)      (GstGLBaseMemory * mem);
 
 /**
  * GstGLBaseMemoryAllocator
  *
- * Opaque #GstGLAllocator struct
+ * Opaque #GstGLBaseMemoryAllocator struct
+ *
+ * Since: 1.8
  */
 struct _GstGLBaseMemoryAllocator
 {
+  /*< private >*/
   GstAllocator parent;
   GstMemoryCopyFunction fallback_mem_copy;
 };
 
 /**
  * GstGLBaseMemoryAllocatorClass:
+ * @parent_class: the parent class
+ * @alloc: a #GstGLBaseMemoryAllocatorAllocFunctions
+ * @create: a #GstGLBaseMemoryAllocatorCreateFunction
+ * @map: a #GstGLBaseMemoryAllocatorMapFunction
+ * @unmap: a #GstGLBaseMemoryAllocatorUnmapFunction
+ * @copy: a #GstGLBaseMemoryAllocatorCopyFunction
+ * @destroy: a #GstGLBaseMemoryAllocatorDestroyFunction
  *
- * The #GstGLBaseMemoryAllocatorClass only contains private data
+ * Since: 1.8
  */
 struct _GstGLBaseMemoryAllocatorClass
 {
@@ -211,6 +330,8 @@ struct _GstGLBaseMemoryAllocatorClass
  * GST_GL_BASE_MEMORY_ALLOCATOR_NAME:
  *
  * The name of the GL buffer allocator
+ *
+ * Since: 1.8
  */
 #define GST_GL_BASE_MEMORY_ALLOCATOR_NAME   "GLBaseMemory"
 
@@ -222,7 +343,7 @@ void          gst_gl_base_memory_init      (GstGLBaseMemory * mem,
                                             GstMemory * parent,
                                             GstGLContext * context,
                                             GstAllocationParams * params,
-                                            gsize maxsize,
+                                            gsize size,
                                             gpointer user_data,
                                             GDestroyNotify notify);
 
diff --git a/gst-libs/gst/gl/gstglbuffer.c b/gst-libs/gst/gl/gstglbuffer.c
index 4b0100085..2abdd6d77 100644
--- a/gst-libs/gst/gl/gstglbuffer.c
+++ b/gst-libs/gst/gl/gstglbuffer.c
@@ -227,6 +227,19 @@ _gl_buffer_unmap (GstGLBuffer * mem, GstMapInfo * info)
   /* XXX: optimistically transfer data */
 }
 
+/**
+ * gst_gl_buffer_copy_buffer_sub_data:
+ * @src: the source #GstGLBuffer
+ * @dest: the destination #GstGLBuffer
+ * @offset: the offset to copy from @src
+ * @size: the size to copy from @src
+ *
+ * Copies @src into @dest using glCopyBufferSubData().
+ *
+ * Returns: whether the copy operation succeeded
+ *
+ * Since: 1.8
+ */
 static gboolean
 gst_gl_buffer_copy_buffer_sub_data (GstGLBuffer * src,
     GstGLBuffer * dest, gssize offset, gssize size)
@@ -332,6 +345,19 @@ _gst_gl_buffer_allocation_params_free_data (GstGLBufferAllocationParams *
   gst_gl_allocation_params_free_data (&params->parent);
 }
 
+/**
+ * gst_gl_buffer_allocation_params_new:
+ * @context: a #GstGLContext
+ * @alloc_size: the size in bytes to allocate
+ * @alloc_params: (allow-none): the #GstAllocationParams for @tex_id
+ * @gl_target: the OpenGL target to allocate
+ * @gl_usage: the OpenGL usage hint to allocate with
+ *
+ * Returns: a new #GstGLBufferAllocationParams for allocating OpenGL buffer
+ *          objects
+ *
+ * Since: 1.8
+ */
 GstGLBufferAllocationParams *
 gst_gl_buffer_allocation_params_new (GstGLContext * context, gsize alloc_size,
     GstAllocationParams * alloc_params, guint gl_target, guint gl_usage)
@@ -413,7 +439,9 @@ gst_gl_buffer_allocator_init (GstGLBufferAllocator * allocator)
  * gst_gl_buffer_init_once:
  *
  * Initializes the GL Buffer allocator. It is safe to call this function
- * multiple times.  This must be called before any other GstGLBuffer operation.
+ * multiple times.  This must be called before any other #GstGLBuffer operation.
+ *
+ * Since: 1.8
  */
 void
 gst_gl_buffer_init_once (void)
@@ -439,6 +467,8 @@ gst_gl_buffer_init_once (void)
  * @mem:a #GstMemory
  * 
  * Returns: whether the memory at @mem is a #GstGLBuffer
+ *
+ * Since: 1.8
  */
 gboolean
 gst_is_gl_buffer (GstMemory * mem)
diff --git a/gst-libs/gst/gl/gstglbuffer.h b/gst-libs/gst/gl/gstglbuffer.h
index 306ac3800..ef519d853 100644
--- a/gst-libs/gst/gl/gstglbuffer.h
+++ b/gst-libs/gst/gl/gstglbuffer.h
@@ -44,7 +44,8 @@ GType gst_gl_buffer_allocator_get_type(void);
  * @mem: the parent object
  * @context: the #GstGLContext to use for GL operations
  * @id: the buffer id for this memory
- * @target: the GL target of this texture for binding purposes
+ * @target: the OpenGL target of this texture for binding purposes
+ * @usage_hints: the OpenGL usage hints this buffer was created with
  *
  * Represents information about a GL buffer
  */
@@ -61,6 +62,12 @@ typedef struct _GstGLBufferAllocationParams GstGLBufferAllocationParams;
 
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_BUFFER (1 << 4)
 
+/**
+ * GstGLBufferAllocationParams:
+ * @parent: parent object
+ * @gl_target: the OpenGL target to bind the buffer to
+ * @gl_usage: the OpenGL usage hint to create the buffer with
+ */
 struct _GstGLBufferAllocationParams
 {
   GstGLAllocationParams     parent;
diff --git a/gst-libs/gst/gl/gstglformat.c b/gst-libs/gst/gl/gstglformat.c
index e8e5e46ce..237e25095 100644
--- a/gst-libs/gst/gl/gstglformat.c
+++ b/gst-libs/gst/gl/gstglformat.c
@@ -108,6 +108,14 @@ _gl_type_n_bytes (guint type)
   }
 }
 
+/**
+ * gst_gl_format_type_n_bytes:
+ * @format: the OpenGL format, %GL_RGBA, %GL_LUMINANCE, etc
+ * @type: the OpenGL type, %GL_UNSIGNED_BYTE, %GL_FLOAT, etc
+ *
+ * Returns: the number of bytes the specified @format, @type combination takes
+ * per pixel
+ */
 guint
 gst_gl_format_type_n_bytes (guint format, guint type)
 {
@@ -115,6 +123,12 @@ gst_gl_format_type_n_bytes (guint format, guint type)
       _gl_type_n_bytes (type);
 }
 
+/**
+ * gst_gl_texture_type_n_bytes:
+ * @tex_format: a #GstVideoGLTextureType
+ *
+ * Returns: the number of bytes @tex_format used per pixel
+ */
 guint
 gst_gl_texture_type_n_bytes (GstVideoGLTextureType tex_format)
 {
@@ -128,6 +142,12 @@ gst_gl_texture_type_n_bytes (GstVideoGLTextureType tex_format)
   return gst_gl_format_type_n_bytes (format, type);
 }
 
+/**
+ * gst_gl_format_from_gl_texture_type:
+ * @tex_format: a #GstVideoGLTextureType
+ *
+ * Returns: the OpenGL format specified by @tex_format
+ */
 guint
 gst_gl_format_from_gl_texture_type (GstVideoGLTextureType tex_format)
 {
@@ -150,6 +170,15 @@ gst_gl_format_from_gl_texture_type (GstVideoGLTextureType tex_format)
   }
 }
 
+/**
+ * gst_gl_texture_type_from_format:
+ * @context: a #GstGLContext
+ * @v_format: a #GstVideoFormat
+ * @plane: the plane number (starting from 0)
+ *
+ * Returns: the #GstVideoGLTextureType for the specified @format and @plane
+ *          that can be allocated using @context
+ */
 GstVideoGLTextureType
 gst_gl_texture_type_from_format (GstGLContext * context,
     GstVideoFormat v_format, guint plane)
@@ -227,6 +256,15 @@ gst_gl_texture_type_from_format (GstGLContext * context,
   return GST_VIDEO_GL_TEXTURE_TYPE_RGBA;
 }
 
+/**
+ * gst_gl_sized_gl_format_from_gl_format_type:
+ * @context: a #GstGLContext
+ * @format: an OpenGL format, %GL_RGBA, %GL_LUMINANCE, etc
+ * @type: an OpenGL type, %GL_UNSIGNED_BYTE, %GL_FLOAT, etc
+ *
+ * Returns: the sized internal format specified by @format and @type that can
+ *          be used in @context
+ */
 guint
 gst_gl_sized_gl_format_from_gl_format_type (GstGLContext * context,
     guint format, guint type)
@@ -288,6 +326,12 @@ gst_gl_sized_gl_format_from_gl_format_type (GstGLContext * context,
   return 0;
 }
 
+/**
+ * gst_gl_texture_target_to_string:
+ * @target: a #GstGLTextureTarget
+ *
+ * Returns: the stringified version of @target or %NULL
+ */
 const gchar *
 gst_gl_texture_target_to_string (GstGLTextureTarget target)
 {
@@ -303,6 +347,13 @@ gst_gl_texture_target_to_string (GstGLTextureTarget target)
   }
 }
 
+/**
+ * gst_gl_texture_target_to_string:
+ * @str: a string equivalant to one of the GST_GL_TEXTURE_TARGET_*_STR values
+ *
+ * Returns: the #GstGLTextureTarget represented by @str or
+ *          %GST_GL_TEXTURE_TARGET_NONE
+ */
 GstGLTextureTarget
 gst_gl_texture_target_from_string (const gchar * str)
 {
@@ -319,6 +370,13 @@ gst_gl_texture_target_from_string (const gchar * str)
   return GST_GL_TEXTURE_TARGET_NONE;
 }
 
+/**
+ * gst_gl_texture_target_to_gl:
+ * @target: a #GstGLTextureTarget
+ *
+ * Returns: the OpenGL value for binding the @target with glBindTexture() and
+ *          similar functions or 0
+ */
 guint
 gst_gl_texture_target_to_gl (GstGLTextureTarget target)
 {
@@ -334,6 +392,13 @@ gst_gl_texture_target_to_gl (GstGLTextureTarget target)
   }
 }
 
+/**
+ * gst_gl_texture_target_from_gl:
+ * @target: an OpenGL texture binding target
+ *
+ * Returns: the #GstGLTextureTarget that's equiavalant to @target or
+ *          %GST_GL_TEXTURE_TARGET_NONE
+ */
 GstGLTextureTarget
 gst_gl_texture_target_from_gl (guint target)
 {
@@ -349,6 +414,12 @@ gst_gl_texture_target_from_gl (guint target)
   }
 }
 
+/**
+ * gst_gl_texture_target_to_buffer_pool_option:
+ * @target: a #GstGLTextureTarget
+ *
+ * Returns: a string representing the @GstBufferPoolOption specified by @target
+ */
 const gchar *
 gst_gl_texture_target_to_buffer_pool_option (GstGLTextureTarget target)
 {
diff --git a/gst-libs/gst/gl/gstglformat.h b/gst-libs/gst/gl/gstglformat.h
index c8e67645f..fcd618a49 100644
--- a/gst-libs/gst/gl/gstglformat.h
+++ b/gst-libs/gst/gl/gstglformat.h
@@ -26,12 +26,46 @@
 #include <gst/gl/gstgl_fwd.h>
 #include <gst/video/video.h>
 
+/**
+ * GST_GL_TEXTURE_TARGET_2D_STR:
+ *
+ * String used for %GST_GL_TEXTURE_TARGET_2D in things like caps values
+ */
 #define GST_GL_TEXTURE_TARGET_2D_STR "2D"
+
+/**
+ * GST_GL_TEXTURE_TARGET_RECTANGLE_STR:
+ *
+ * String used for %GST_GL_TEXTURE_TARGET_RECTANGLE in things like caps values
+ */
 #define GST_GL_TEXTURE_TARGET_RECTANGLE_STR "rectangle"
+
+/**
+ * GST_GL_TEXTURE_TARGET_EXTERNAL_OES_STR:
+ *
+ * String used for %GST_GL_TEXTURE_TARGET_EXTERNAL_OES in things like caps values
+ */
 #define GST_GL_TEXTURE_TARGET_EXTERNAL_OES_STR "external-oes"
 
+/**
+ * GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_2D:
+ *
+ * String used for %GST_GL_TEXTURE_TARGET_2D as a #GstBufferPool pool option
+ */
 #define GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_2D "GstBufferPoolOptionGLTextureTarget2D"
+
+/**
+ * GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_RECTANGLE:
+ *
+ * String used for %GST_GL_TEXTURE_TARGET_RECTANGLE as a #GstBufferPool pool option
+ */
 #define GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_RECTANGLE "GstBufferPoolOptionGLTextureTargetRectangle"
+
+/**
+ * GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_EXTERNAL_OES:
+ *
+ * String used for %GST_GL_TEXTURE_TARGET_ESTERNAL_OES as a #GstBufferPool pool option
+ */
 #define GST_BUFFER_POOL_OPTION_GL_TEXTURE_TARGET_EXTERNAL_OES "GstBufferPoolOptionGLTextureTargetExternalOES"
 
 G_BEGIN_DECLS
diff --git a/gst-libs/gst/gl/gstglmemory.c b/gst-libs/gst/gl/gstglmemory.c
index 95974d874..020bc7ce1 100644
--- a/gst-libs/gst/gl/gstglmemory.c
+++ b/gst-libs/gst/gl/gstglmemory.c
@@ -34,22 +34,15 @@
  * @short_description: memory subclass for GL textures
  * @see_also: #GstMemory, #GstAllocator, #GstGLBufferPool
  *
- * GstGLMemory is a #GstGLBaseBuffer subclass providing support for the mapping of
- * GL textures.  
+ * GstGLMemory is a #GstGLBaseMemory subclass providing support for the mapping of
+ * OpenGL textures.  
  *
- * #GstGLMemory is created through gst_gl_memory_alloc() or system memory can
- * be wrapped through gst_gl_memory_wrapped().
+ * #GstGLMemory is created or wrapped through gst_gl_base_memory_alloc()
+ * with #GstGLVideoAllocationParams.
  *
  * Data is uploaded or downloaded from the GPU as is necessary.
  */
 
-/* Implementation notes
- *
- * PBO transfer's are implemented using GstGLBaseBuffer.  We just need to
- * ensure that the texture data is written/read to/from before/after calling
- * the parent class which performs the pbo buffer transfer.
- */
-
 #define USING_OPENGL(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL, 1, 0))
 #define USING_OPENGL3(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL3, 3, 1))
 #define USING_GLES(context) (gst_gl_context_check_gl_version (context, GST_GL_API_GLES, 1, 0))
@@ -266,12 +259,18 @@ _gl_tex_create (GstGLMemory * gl_mem, GError ** error)
  * @allocator: the #GstAllocator to initialize with
  * @parent: (allow-none): the parent #GstMemory to initialize with
  * @context: the #GstGLContext to initialize with
+ * @target: the #GstGLTextureTarget for this #GstGLMemory
  * @params: (allow-none): the @GstAllocationParams to initialize with
- * @size: the number of bytes to be allocated
+ * @info: the #GstVideoInfo for this #GstGLMemory
+ * @plane: the plane number (starting from 0) for this #GstGLMemory
+ * @valign: (allow-none): optional #GstVideoAlignment parameters
  * @notify: (allow-none): a #GDestroyNotify
  * @user_data: (allow-none): user data to call @notify with
  *
- * Initializes @mem with the required parameters
+ * Initializes @mem with the required parameters.  @info is assumed to have
+ * already have been modified with gst_video_info_align().
+ *
+ * Since: 1.8
  */
 void
 gst_gl_memory_init (GstGLMemory * mem, GstAllocator * allocator,
@@ -326,6 +325,21 @@ gst_gl_memory_init (GstGLMemory * mem, GstAllocator * allocator,
       mem->mem.mem.size);
 }
 
+/**
+ * gst_gl_memory_read_pixels:
+ * @gl_mem: a #GstGLMemory
+ * @read_pointer: the data pointer to pass to glReadPixels
+ *
+ * Reads the texture in #GstGLMemory into @read_pointer if no buffer is bound
+ * to %GL_PIXEL_PACK_BUFFER.  Otherwise @read_pointer is the byte offset into
+ * the currently bound %GL_PIXEL_PACK_BUFFER buffer to store the result of
+ * glReadPixels.  See the OpenGL specification for glReadPixels for more
+ * details.
+ *
+ * Returns: whether theread operation succeeded
+ *
+ * Since: 1.8
+ */
 gboolean
 gst_gl_memory_read_pixels (GstGLMemory * gl_mem, gpointer read_pointer)
 {
@@ -453,6 +467,15 @@ _upload_cpu_write (GstGLMemory * gl_mem, GstMapInfo * info, gsize maxsize)
   gst_gl_memory_texsubimage (gl_mem, gl_mem->mem.data);
 }
 
+/**
+ * gst_gl_memory_texsubimage:
+ * @gl_mem: a #GstGLMemory
+ * @read_pointer: the data pointer to pass to glTexSubImage
+ *
+ * See gst_gl_memory_read_pixels() for what @read_pointer signifies.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_memory_texsubimage (GstGLMemory * gl_mem, gpointer read_pointer)
 {
@@ -559,6 +582,22 @@ _gl_tex_unmap (GstGLMemory * gl_mem, GstMapInfo * info)
   alloc_class->unmap (GST_GL_BASE_MEMORY_CAST (gl_mem), info);
 }
 
+/**
+ * gst_gl_memory_copy_texiamge:
+ * @gl_mem: the source #GstGLMemory
+ * @tex_id: the destination texture id
+ * @out_target: the destination #GstGLTextureTarget
+ * @out_tex_type: the destination #GstVideoGLTextureType
+ * @out_width: the destination width
+ * @out_height: the destination height
+ *
+ * Copies the texture in #GstGLMemory into the texture specified by @tex_id,
+ * @out_target, @out_tex_type, @out_width and @out_height.
+ *
+ * Returns: whether the copy succeeded.
+ *
+ * Since: 1.8
+ */
 gboolean
 gst_gl_memory_copy_teximage (GstGLMemory * src, guint tex_id,
     GstGLTextureTarget out_target, GstVideoGLTextureType out_tex_type,
@@ -820,7 +859,7 @@ gst_gl_memory_allocator_init (GstGLMemoryAllocator * allocator)
  * gst_gl_memory_copy_into:
  * @gl_mem:a #GstGLMemory
  * @tex_id:OpenGL texture id
- * @taget: the #GstGLTextureTarget
+ * @target: the #GstGLTextureTarget
  * @tex_type: the #GstVideoGLTextureType
  * @width: width of @tex_id
  * @height: height of @tex_id
@@ -828,18 +867,9 @@ gst_gl_memory_allocator_init (GstGLMemoryAllocator * allocator)
  * Copies @gl_mem into the texture specfified by @tex_id.  The format of @tex_id
  * is specified by @tex_type, @width and @height.
  *
- * If @respecify is %TRUE, then the copy is performed in terms of the texture
- * data.  This is useful for splitting RGBA textures into RG or R textures or
- * vice versa. The requirement for this to succeed is that the backing texture
- * data must be the same size, i.e. say a RGBA8 texture is converted into a RG8
- * texture, then the RG texture must have twice as many pixels available for
- * output as the RGBA texture.
- *
- * Otherwise, if @respecify is %FALSE, then the copy is performed per texel
- * using glCopyTexImage.  See the OpenGL specification for details on the
- * mappings between texture formats.
- *
  * Returns: Whether the copy suceeded
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_memory_copy_into (GstGLMemory * gl_mem, guint tex_id,
@@ -861,6 +891,14 @@ gst_gl_memory_copy_into (GstGLMemory * gl_mem, guint tex_id,
   return copy_params.result;
 }
 
+/**
+ * gst_gl_memory_get_texture_width:
+ * @gl_mem: a #GstGLMemory
+ *
+ * Returns: the texture width of @gl_mem
+ *
+ * Since: 1.8
+ */
 gint
 gst_gl_memory_get_texture_width (GstGLMemory * gl_mem)
 {
@@ -869,6 +907,14 @@ gst_gl_memory_get_texture_width (GstGLMemory * gl_mem)
   return gl_mem->tex_width;
 }
 
+/**
+ * gst_gl_memory_get_texture_height:
+ * @gl_mem: a #GstGLMemory
+ *
+ * Returns: the texture height of @gl_mem
+ *
+ * Since: 1.8
+ */
 gint
 gst_gl_memory_get_texture_height (GstGLMemory * gl_mem)
 {
@@ -877,6 +923,14 @@ gst_gl_memory_get_texture_height (GstGLMemory * gl_mem)
   return _get_plane_height (&gl_mem->info, gl_mem->plane);
 }
 
+/**
+ * gst_gl_memory_get_texture_type:
+ * @gl_mem: a #GstGLMemory
+ *
+ * Returns: the #GstVideoGLTextureType of @gl_mem
+ *
+ * Since: 1.8
+ */
 GstVideoGLTextureType
 gst_gl_memory_get_texture_type (GstGLMemory * gl_mem)
 {
@@ -885,6 +939,14 @@ gst_gl_memory_get_texture_type (GstGLMemory * gl_mem)
   return gl_mem->tex_type;
 }
 
+/**
+ * gst_gl_memory_get_texture_target:
+ * @gl_mem: a #GstGLMemory
+ *
+ * Returns: the #GstGLTextureTarget of @gl_mem
+ *
+ * Since: 1.8
+ */
 GstGLTextureTarget
 gst_gl_memory_get_texture_target (GstGLMemory * gl_mem)
 {
@@ -893,6 +955,14 @@ gst_gl_memory_get_texture_target (GstGLMemory * gl_mem)
   return gl_mem->tex_target;
 }
 
+/**
+ * gst_gl_memory_get_texture_id:
+ * @gl_mem: a #GstGLMemory
+ *
+ * Returns: the OpenGL texture handle of @gl_mem
+ *
+ * Since: 1.8
+ */
 guint
 gst_gl_memory_get_texture_id (GstGLMemory * gl_mem)
 {
@@ -906,6 +976,8 @@ gst_gl_memory_get_texture_id (GstGLMemory * gl_mem)
  *
  * Initializes the GL Base Texture allocator. It is safe to call this function
  * multiple times.  This must be called before any other GstGLMemory operation.
+ *
+ * Since: 1.4
  */
 void
 gst_gl_memory_init_once (void)
@@ -931,6 +1003,8 @@ gst_gl_memory_init_once (void)
  * @mem:a #GstMemory
  * 
  * Returns: whether the memory at @mem is a #GstGLMemory
+ *
+ * Since: 1.4
  */
 gboolean
 gst_is_gl_memory (GstMemory * mem)
@@ -956,6 +1030,30 @@ _gst_gl_video_allocation_params_set_video_alignment (GstGLVideoAllocationParams
   }
 }
 
+/**
+ * gst_gl_video_allocation_params_init_full:
+ * @params: a #GstGLVideoAllocationParams to initialize
+ * @struct_size: the size of the struct in @params
+ * @alloc_flags: some allocation flags
+ * @copy: a copy function
+ * @free: a free function
+ * @context: a #GstGLContext
+ * @alloc_params: (allow-none): the #GstAllocationParams for @wrapped_data
+ * @v_info: the #GstVideoInfo for @wrapped_data
+ * @plane: the video plane @wrapped_data represents
+ * @valign: (allow-none): any #GstVideoAlignment applied to symem mappings of @wrapped_data
+ * @target: the #GstGLTextureTarget
+ * @wrapped_data: (allow-none): the optional data pointer to wrap
+ * @gl_handle: the optional OpenGL handle to wrap or 0
+ * @user_data: (allow-none): user data to call @notify with
+ * @notify: (allow-none): a #GDestroyNotify
+ *
+ * Intended for subclass usage
+ *
+ * Returns: initializes @params with the parameters specified
+ *
+ * Since: 1.8
+ */
 gboolean
 gst_gl_video_allocation_params_init_full (GstGLVideoAllocationParams * params,
     gsize struct_size, guint alloc_flags, GstGLAllocationParamsCopyFunc copy,
@@ -1003,6 +1101,8 @@ gst_gl_video_allocation_params_init_full (GstGLVideoAllocationParams * params,
  * @target: the #GstGLTextureTarget for @wrapped_data
  *
  * Returns: a new #GstGLVideoAllocationParams for allocating #GstGLMemory's
+ *
+ * Since: 1.8
  */
 GstGLVideoAllocationParams *
 gst_gl_video_allocation_params_new (GstGLContext * context,
@@ -1040,6 +1140,8 @@ gst_gl_video_allocation_params_new (GstGLContext * context,
  * @notify: (allow-none): a #GDestroyNotify
  *
  * Returns: a new #GstGLVideoAllocationParams for wrapping @wrapped_data
+ *
+ * Since: 1.8
  */
 GstGLVideoAllocationParams *
 gst_gl_video_allocation_params_new_wrapped_data (GstGLContext * context,
@@ -1078,6 +1180,8 @@ gst_gl_video_allocation_params_new_wrapped_data (GstGLContext * context,
  * @notify: (allow-none): a #GDestroyNotify
  *
  * Returns: a new #GstGLVideoAllocationParams for wrapping @tex_id
+ *
+ * Since: 1.8
  */
 GstGLVideoAllocationParams *
 gst_gl_video_allocation_params_new_wrapped_texture (GstGLContext * context,
@@ -1103,6 +1207,15 @@ gst_gl_video_allocation_params_new_wrapped_texture (GstGLContext * context,
   return params;
 }
 
+/**
+ * gst_gl_video_allocation_params_free_data:
+ * @params: a #GstGLVideoAllocationParams
+ *
+ * Unset and free any dynamically allocated resources.  Intended for subclass
+ * usage only to chain up at the end of a subclass free function.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_video_allocation_params_free_data (GstGLVideoAllocationParams * params)
 {
@@ -1112,6 +1225,16 @@ gst_gl_video_allocation_params_free_data (GstGLVideoAllocationParams * params)
   gst_gl_allocation_params_free_data (&params->parent);
 }
 
+/**
+ * gst_gl_video_allocation_params_copy_data:
+ * @src_vid: source #GstGLVideoAllocationParams to copy from
+ * @dest_vid: destination #GstGLVideoAllocationParams to copy into
+ *
+ * Copy and set any dynamically allocated resources in @dest_vid.  Intended
+ * for subclass usage only to chain up at the end of a subclass copy function.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_video_allocation_params_copy_data (GstGLVideoAllocationParams * src_vid,
     GstGLVideoAllocationParams * dest_vid)
@@ -1141,6 +1264,8 @@ gst_gl_video_allocation_params_copy_data (GstGLVideoAllocationParams * src_vid,
  * @params: the #GstGLVideoAllocationParams to allocate with
  *
  * Returns: whether the buffer was correctly setup
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_memory_setup_buffer (GstGLMemoryAllocator * allocator,
@@ -1191,6 +1316,14 @@ gst_gl_memory_setup_buffer (GstGLMemoryAllocator * allocator,
   return TRUE;
 }
 
+/**
+ * gst_gl_memory_allocator_get_default:
+ * @context: a #GstGLContext
+ *
+ * Returns: the default #GstGLMemoryAllocator supported by @context
+ *
+ * Since: 1.8
+ */
 GstGLMemoryAllocator *
 gst_gl_memory_allocator_get_default (GstGLContext * context)
 {
diff --git a/gst-libs/gst/gl/gstglmemory.h b/gst-libs/gst/gl/gstglmemory.h
index d595773de..b032a5ce7 100644
--- a/gst-libs/gst/gl/gstglmemory.h
+++ b/gst-libs/gst/gl/gstglmemory.h
@@ -138,8 +138,8 @@ GstGLVideoAllocationParams * gst_gl_video_allocation_params_new_wrapped_texture
 /* subclass usage */
 void            gst_gl_video_allocation_params_free_data    (GstGLVideoAllocationParams * params);
 /* subclass usage */
-void            gst_gl_video_allocation_params_copy_data    (GstGLVideoAllocationParams * src,
-                                                             GstGLVideoAllocationParams * dest);
+void            gst_gl_video_allocation_params_copy_data    (GstGLVideoAllocationParams * src_vid,
+                                                             GstGLVideoAllocationParams * dest_vid);
 
 /**
  * GstGLMemoryAllocator
diff --git a/gst-libs/gst/gl/gstglmemorypbo.c b/gst-libs/gst/gl/gstglmemorypbo.c
index 8e8bbb83a..f653e1c38 100644
--- a/gst-libs/gst/gl/gstglmemorypbo.c
+++ b/gst-libs/gst/gl/gstglmemorypbo.c
@@ -34,8 +34,8 @@
  * @short_description: memory subclass for GL textures
  * @see_also: #GstMemory, #GstAllocator, #GstGLBufferPool
  *
- * GstGLMemoryPBO is a #GstGLMemory subclass providing support for the mapping of
- * GL textures.  
+ * #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().
@@ -731,8 +731,9 @@ gst_gl_memory_pbo_allocator_init (GstGLMemoryPBOAllocator * allocator)
 /**
  * gst_gl_memory_pbo_copy_into_texture:
  * @gl_mem:a #GstGLMemoryPBO
- * @tex_id:OpenGL texture id
- * @tex_type: a #GstVideoGLTextureType
+ * @tex_id: the destination texture id
+ * @target: the destination #GstGLTextureTarget
+ * @tex_type: the destination #GstVideoGLTextureType
  * @width: width of @tex_id
  * @height: height of @tex_id
  * @stride: stride of the backing texture data
@@ -753,6 +754,8 @@ gst_gl_memory_pbo_allocator_init (GstGLMemoryPBOAllocator * allocator)
  * mappings between texture formats.
  *
  * Returns: Whether the copy suceeded
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_memory_pbo_copy_into_texture (GstGLMemoryPBO * gl_mem, guint tex_id,
@@ -789,6 +792,14 @@ _download_transfer (GstGLContext * context, GstGLMemoryPBO * gl_mem)
   g_mutex_unlock (&mem->lock);
 }
 
+/**
+ * gst_gl_memory_pbo_download_transfer:
+ * @gl_mem: a #GstGLMemoryPBO
+ *
+ * Transfer the texture data from the texture into the PBO if necessary.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_memory_pbo_download_transfer (GstGLMemoryPBO * gl_mem)
 {
@@ -815,6 +826,14 @@ _upload_transfer (GstGLContext * context, GstGLMemoryPBO * gl_mem)
   g_mutex_unlock (&mem->lock);
 }
 
+/**
+ * gst_gl_memory_pbo_download_transfer:
+ * @gl_mem: a #GstGLMemoryPBO
+ *
+ * Transfer the texture data from the PBO into the texture if necessary.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_memory_pbo_upload_transfer (GstGLMemoryPBO * gl_mem)
 {
@@ -850,10 +869,12 @@ gst_gl_memory_pbo_init_once (void)
 }
 
 /**
- * gst_is_gl_memory:
+ * gst_is_gl_memory_pbo:
  * @mem:a #GstMemory
  * 
  * Returns: whether the memory at @mem is a #GstGLMemoryPBO
+ *
+ * Since: 1.8
  */
 gboolean
 gst_is_gl_memory_pbo (GstMemory * mem)