From 82cf1b9c71d20d35e8447fab2f0438cd46a37ae9 Mon Sep 17 00:00:00 2001
From: Matthew Waters <matthew@centricular.com>
Date: Fri, 28 Jul 2017 11:00:12 +0100
Subject: [PATCH] gl/docs: some documentation updates

Add some missing/incomplete docs
---
 gst-libs/gst/gl/egl/gsteglimage.h  |  8 ++++
 gst-libs/gst/gl/gstglapi.c         |  2 +-
 gst-libs/gst/gl/gstglbasememory.c  | 10 +++++
 gst-libs/gst/gl/gstglbasememory.h  | 31 ++++++++++++++
 gst-libs/gst/gl/gstglbuffer.h      | 10 +++++
 gst-libs/gst/gl/gstglcontext.c     |  6 ++-
 gst-libs/gst/gl/gstglcontext.h     |  7 +++
 gst-libs/gst/gl/gstgldisplay.h     |  6 +++
 gst-libs/gst/gl/gstglfilter.c      |  3 +-
 gst-libs/gst/gl/gstglframebuffer.c |  2 +
 gst-libs/gst/gl/gstglmemory.c      |  2 +-
 gst-libs/gst/gl/gstglmemory.h      | 17 +++++++-
 gst-libs/gst/gl/gstglmemorypbo.h   |  2 +-
 gst-libs/gst/gl/gstglsl.c          | 69 ++++++++++++++++++++++++++++++
 gst-libs/gst/gl/gstglsl.h          |  7 +++
 gst-libs/gst/gl/gstglupload.h      |  1 +
 gst-libs/gst/gl/gstglwindow.h      | 19 ++++++++
 17 files changed, 195 insertions(+), 7 deletions(-)

diff --git a/gst-libs/gst/gl/egl/gsteglimage.h b/gst-libs/gst/gl/egl/gsteglimage.h
index 56ec7e1c08..327709d476 100644
--- a/gst-libs/gst/gl/egl/gsteglimage.h
+++ b/gst-libs/gst/gl/egl/gsteglimage.h
@@ -39,6 +39,14 @@ GType gst_egl_image_get_type (void);
 
 typedef struct _GstEGLImage GstEGLImage;
 
+/**
+ * GstEGLImageDestroyNotify:
+ * @image: a #GstEGLImage
+ * @data: user data passed to gst_egl_image_new_wrapped()
+ *
+ * Function to be called when the GstEGLImage is destroyed. It should free
+ * the associated #EGLImage if necessary
+ */
 typedef void (*GstEGLImageDestroyNotify) (GstEGLImage * image,
     gpointer data);
 
diff --git a/gst-libs/gst/gl/gstglapi.c b/gst-libs/gst/gl/gstglapi.c
index bfa1c9ae25..6960a5545a 100644
--- a/gst-libs/gst/gl/gstglapi.c
+++ b/gst-libs/gst/gl/gstglapi.c
@@ -20,7 +20,7 @@
 
 /**
  * SECTION:gstglapi
- * @title: GstGLApi
+ * @title: GstGLAPI
  * @short_description: OpenGL API specific functionality
  * @see_also: #GstGLDisplay, #GstGLContext
  *
diff --git a/gst-libs/gst/gl/gstglbasememory.c b/gst-libs/gst/gl/gstglbasememory.c
index 9e89f45faa..d7bd88cb12 100644
--- a/gst-libs/gst/gl/gstglbasememory.c
+++ b/gst-libs/gst/gl/gstglbasememory.c
@@ -192,6 +192,16 @@ _align_data (gpointer data, gsize align)
 }
 
 /* subclass usage only */
+/**
+ * gst_gl_base_memory_alloc_data:
+ * @gl_mem: a #GstGLBaseMemory
+ *
+ * Note: only intended for subclass usage to allocate the sytem memory buffer
+ * on demand.  If there is already a non-NULL data pointer in @gl_mem->data,
+ * then this function imply returns TRUE.
+ *
+ * Returns: whether the system memory could be allocated
+ */
 gboolean
 gst_gl_base_memory_alloc_data (GstGLBaseMemory * gl_mem)
 {
diff --git a/gst-libs/gst/gl/gstglbasememory.h b/gst-libs/gst/gl/gstglbasememory.h
index 6bdadf78b1..7f9e2265b2 100644
--- a/gst-libs/gst/gl/gstglbasememory.h
+++ b/gst-libs/gst/gl/gstglbasememory.h
@@ -29,6 +29,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GST_GL_BASE_MEMORY_ERROR:
+ *
+ * Error domain for GStreamer's GL memory module. Errors in this domain will be
+ * from the #GstGLBaseMemoryError enumeration
+ */
 #define GST_TYPE_GL_BASE_MEMORY (gst_gl_base_memory_get_type())
 GST_EXPORT
 GType gst_gl_base_memory_get_type(void);
@@ -145,9 +151,34 @@ typedef void    (*GstGLAllocationParamsFreeFunc)    (gpointer params);
 GST_EXPORT
 GType gst_gl_allocation_params_get_type (void);
 
+/**
+ * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_ALLOC:
+ *
+ * GL Allocation flag indicating that the implementation should allocate the
+ * necessary resources.
+ */
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_ALLOC (1 << 0)
+
+/**
+ * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_SYSMEM:
+ *
+ * GL Allocation flag for using the provided system memory data as storage.
+ */
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_SYSMEM (1 << 1)
+
+/**
+ * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE:
+ *
+ * GL Allocation flag for using the provided GPU handle as storage.
+ */
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE (1 << 2)
+
+/**
+ * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER:
+ *
+ * Values >= than #GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER can be used for
+ * user-defined purposes.
+ */
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER (1 << 16)
 
 /**
diff --git a/gst-libs/gst/gl/gstglbuffer.h b/gst-libs/gst/gl/gstglbuffer.h
index 01deb8a8c7..90f8eb2607 100644
--- a/gst-libs/gst/gl/gstglbuffer.h
+++ b/gst-libs/gst/gl/gstglbuffer.h
@@ -64,6 +64,11 @@ typedef struct _GstGLBufferAllocationParams GstGLBufferAllocationParams;
 GST_EXPORT
 GType gst_gl_buffer_allocation_params_get_type (void);
 
+/**
+ * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_BUFFER:
+ *
+ * GL allocation flag indicating the allocation of a GL buffer.
+ */
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_BUFFER (1 << 4)
 
 /**
@@ -116,6 +121,11 @@ struct _GstGLBufferAllocatorClass
   gpointer _padding[GST_PADDING];
 };
 
+/**
+ * GST_CAPS_FEATURE_MEMORY_GL_BUFFER:
+ *
+ * Name of the caps feature indicating the use of GL buffers
+ */
 #define GST_CAPS_FEATURE_MEMORY_GL_BUFFER "memory:GLBuffer"
 
 /**
diff --git a/gst-libs/gst/gl/gstglcontext.c b/gst-libs/gst/gl/gstglcontext.c
index db35dc7bc2..aed46185ef 100644
--- a/gst-libs/gst/gl/gstglcontext.c
+++ b/gst-libs/gst/gl/gstglcontext.c
@@ -838,7 +838,11 @@ gst_gl_context_get_gl_api (GstGLContext * context)
  * 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)
+ * e.g.
+ *
+ * |[<!-- language="C" -->
+ * void (GSTGLAPI *PFN_glGetIntegerv) (GLenum name, GLint * ret)
+ * ]|
  *
  * Returns: a function pointer or %NULL
  *
diff --git a/gst-libs/gst/gl/gstglcontext.h b/gst-libs/gst/gl/gstglcontext.h
index 031b612870..53ed34e755 100644
--- a/gst-libs/gst/gl/gstglcontext.h
+++ b/gst-libs/gst/gl/gstglcontext.h
@@ -43,6 +43,13 @@ GType gst_gl_context_get_type       (void);
 
 GST_EXPORT
 GQuark gst_gl_context_error_quark (void);
+
+/**
+ * GST_GL_CONTEXT_ERROR:
+ *
+ * Error domain for GStreamer's GL context module. Errors in this domain will
+ * be from the #GstGLContextError enumeration
+ */
 #define GST_GL_CONTEXT_ERROR (gst_gl_context_error_quark ())
 
 /**
diff --git a/gst-libs/gst/gl/gstgldisplay.h b/gst-libs/gst/gl/gstgldisplay.h
index deac9dfe4b..66165a9ec5 100644
--- a/gst-libs/gst/gl/gstgldisplay.h
+++ b/gst-libs/gst/gl/gstgldisplay.h
@@ -50,6 +50,7 @@ GType gst_gl_display_get_type (void);
  * @GST_GL_DISPLAY_TYPE_WIN32: Win32 display
  * @GST_GL_DISPLAY_TYPE_DISPMANX: Dispmanx display
  * @GST_GL_DISPLAY_TYPE_EGL: EGL display
+ * @GST_GL_DISPLAY_TYPE_VIV_FB: Vivante Framebuffer display
  * @GST_GL_DISPLAY_TYPE_ANY: any display type
  */
 typedef enum
@@ -117,6 +118,11 @@ GstGLAPI         gst_gl_display_get_gl_api             (GstGLDisplay * display);
 GST_EXPORT
 GstGLAPI         gst_gl_display_get_gl_api_unlocked    (GstGLDisplay * display);
 
+/**
+ * GST_GL_DISPLAY_CONTEXT_TYPE:
+ *
+ * The name used in #GstContext queries for requesting a #GstGLDisplay
+ */
 #define GST_GL_DISPLAY_CONTEXT_TYPE "gst.gl.GLDisplay"
 GST_EXPORT
 void     gst_context_set_gl_display (GstContext * context, GstGLDisplay * display);
diff --git a/gst-libs/gst/gl/gstglfilter.c b/gst-libs/gst/gl/gstglfilter.c
index dd46aba4f4..77b3e999da 100644
--- a/gst-libs/gst/gl/gstglfilter.c
+++ b/gst-libs/gst/gl/gstglfilter.c
@@ -896,8 +896,7 @@ gst_gl_filter_decide_allocation (GstBaseTransform * trans, GstQuery * query)
  * @inbuf: an input buffer
  * @outbuf: an output buffer
  *
- * Perform automatic upload if needed, call filter_texture vfunc and then an
- * automatic download if needed.
+ * Calls filter_texture vfunc with correctly mapped #GstGLMemorys
  *
  * Returns: whether the transformation succeeded
  *
diff --git a/gst-libs/gst/gl/gstglframebuffer.c b/gst-libs/gst/gl/gstglframebuffer.c
index 40188dc219..2e1c3bc859 100644
--- a/gst-libs/gst/gl/gstglframebuffer.c
+++ b/gst-libs/gst/gl/gstglframebuffer.c
@@ -509,6 +509,8 @@ gst_gl_framebuffer_get_effective_dimensions (GstGLFramebuffer * fb,
 /**
  * gst_gl_context_check_framebuffer_status:
  * @context: a #GstGLContext
+ * @fbo_target: the GL value of the framebuffer target, GL_FRAMEBUFFER,
+ *              GL_READ_FRAMEBUFFER, GL_DRAW_FRAMEBUFFER
  *
  * Returns: whether whether the current framebuffer is complete
  *
diff --git a/gst-libs/gst/gl/gstglmemory.c b/gst-libs/gst/gl/gstglmemory.c
index 8123672934..aba40ef1ed 100644
--- a/gst-libs/gst/gl/gstglmemory.c
+++ b/gst-libs/gst/gl/gstglmemory.c
@@ -618,7 +618,7 @@ _gl_tex_unmap (GstGLMemory * gl_mem, GstMapInfo * info)
 }
 
 /**
- * gst_gl_memory_copy_texiamge:
+ * gst_gl_memory_copy_teximage:
  * @gl_mem: the source #GstGLMemory
  * @tex_id: the destination texture id
  * @out_target: the destination #GstGLTextureTarget
diff --git a/gst-libs/gst/gl/gstglmemory.h b/gst-libs/gst/gl/gstglmemory.h
index c7de5c78c9..3a4bf9f9c4 100644
--- a/gst-libs/gst/gl/gstglmemory.h
+++ b/gst-libs/gst/gl/gstglmemory.h
@@ -43,7 +43,17 @@ GType gst_gl_memory_allocator_get_type(void);
 
 #define GST_GL_MEMORY_CAST(obj) ((GstGLMemory *) obj)
 
+/**
+ * GST_CAPS_FEATURE_MEMORY_GL_MEMORY:
+ *
+ * Name of the caps feature for indicating the use of #GstGLMemory
+ */
 #define GST_CAPS_FEATURE_MEMORY_GL_MEMORY "memory:GLMemory"
+/**
+ * GST_GL_MEMORY_VIDEO_FORMATS_STR:
+ *
+ * List of video formats that are supported by #GstGLMemory
+ */
 #define GST_GL_MEMORY_VIDEO_FORMATS_STR \
     "{ RGBA, BGRA, RGBx, BGRx, ARGB, ABGR, xRGB, xBGR, RGB, BGR, RGB16, BGR16, " \
     "AYUV, I420, YV12, NV12, NV21, YUY2, UYVY, Y41B, Y42B, Y444, " \
@@ -90,6 +100,11 @@ GType gst_gl_video_allocation_params_get_type (void);
 
 typedef struct _GstGLVideoAllocationParams GstGLVideoAllocationParams;
 
+/**
+ * GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_VIDEO:
+ *
+ * GL allocation flag indicating the allocation of 2D video frames
+ */
 #define GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_VIDEO (1 << 3)
 
 /**
@@ -99,7 +114,7 @@ typedef struct _GstGLVideoAllocationParams GstGLVideoAllocationParams;
  * @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_fomrat: the #GstGLFormat to allocate
+ * @tex_format: the #GstGLFormat to allocate
  */
 struct _GstGLVideoAllocationParams
 {
diff --git a/gst-libs/gst/gl/gstglmemorypbo.h b/gst-libs/gst/gl/gstglmemorypbo.h
index f8d9ed0e7a..77eff7b954 100644
--- a/gst-libs/gst/gl/gstglmemorypbo.h
+++ b/gst-libs/gst/gl/gstglmemorypbo.h
@@ -58,7 +58,7 @@ struct _GstGLMemoryPBO
 };
 
 /**
- * GST_GL_MEMORY_PBO_ALLOCATOR:
+ * GST_GL_MEMORY_PBO_ALLOCATOR_NAME:
  *
  * The name of the GL Memory PBO allocator
  */
diff --git a/gst-libs/gst/gl/gstglsl.c b/gst-libs/gst/gl/gstglsl.c
index 78fc45d83b..81226260fe 100644
--- a/gst-libs/gst/gl/gstglsl.c
+++ b/gst-libs/gst/gl/gstglsl.c
@@ -94,6 +94,12 @@ static const struct glsl_profile_string glsl_profiles[] = {
   {GST_GLSL_PROFILE_COMPATIBILITY, "compatibility"},
 };
 
+/**
+ * gst_glsl_version_to_string:
+ * @version: a #GstGLSLVersion
+ *
+ * Returns: (nullable): the name of @version or %NULL on error
+ */
 const gchar *
 gst_glsl_version_to_string (GstGLSLVersion version)
 {
@@ -110,6 +116,12 @@ gst_glsl_version_to_string (GstGLSLVersion version)
   return NULL;
 }
 
+/**
+ * gst_glsl_version_from_string:
+ * @string: a GLSL version string
+ *
+ * Returns: the #GstGLSLVersion of @string or %GST_GLSL_VERSION_NONE on error
+ */
 GstGLSLVersion
 gst_glsl_version_from_string (const gchar * string)
 {
@@ -133,6 +145,12 @@ gst_glsl_version_from_string (const gchar * string)
   return 0;
 }
 
+/**
+ * gst_glsl_profile_to_string:
+ * @profile: a #GstGLSLProfile
+ *
+ * Returns: (nullable): the name for @profile or %NULL on error
+ */
 const gchar *
 gst_glsl_profile_to_string (GstGLSLProfile profile)
 {
@@ -153,6 +171,12 @@ gst_glsl_profile_to_string (GstGLSLProfile profile)
   return NULL;
 }
 
+/**
+ * gst_glsl_profile_from_string:
+ * @string: a GLSL version string
+ *
+ * Returns: the #GstGLSLProfile of @string or %GST_GLSL_PROFILE_NONE on error
+ */
 GstGLSLProfile
 gst_glsl_profile_from_string (const gchar * string)
 {
@@ -203,6 +227,13 @@ _is_valid_version_profile (GstGLSLVersion version, GstGLSLProfile profile)
   return FALSE;
 }
 
+/**
+ * gst_glsl_version_profile_to_string:
+ * @version: a #GstGLSLVersion
+ * @profile: a #GstGLSLVersion
+ *
+ * Returns: the combined GLSL #version string for @version and @profile
+ */
 gchar *
 gst_glsl_version_profile_to_string (GstGLSLVersion version,
     GstGLSLProfile profile)
@@ -262,6 +293,17 @@ _check_valid_version_preprocessor_string (const gchar * str)
   return NULL;
 }
 
+/**
+ * gst_glsl_version_profile_from_string:
+ * @string: a valid GLSL #version string
+ * @version_ret: (out): resulting #GstGLSLVersion
+ * @profile_ret: (out): resulting #GstGLSLVersion
+ *
+ * Note: this function expects either a #version GLSL preprocesser directive
+ * or a valid GLSL version and/or profile.
+ *
+ * Returns: TRUE if a valid #version string was found, FALSE otherwise
+ */
 gboolean
 gst_glsl_version_profile_from_string (const gchar * string,
     GstGLSLVersion * version_ret, GstGLSLProfile * profile_ret)
@@ -417,6 +459,17 @@ _gst_glsl_shader_string_find_version (const gchar * str)
   return NULL;
 }
 
+/**
+ * gst_glsl_string_get_version_profile:
+ * @s: string to search for a valid #version string
+ * @version: (out): resulting #GstGLSLVersion
+ * @profile: (out): resulting #GstGLSLProfile
+ *
+ * Note: this function first searches the first 1 kilobytes for a #version
+ * preprocessor directive and then executes gst_glsl_version_profile_from_string().
+ *
+ * Returns: TRUE if a valid #version string was found, FALSE otherwise
+ */
 gboolean
 gst_glsl_string_get_version_profile (const gchar * s, GstGLSLVersion * version,
     GstGLSLProfile * profile)
@@ -443,6 +496,14 @@ error:
   }
 }
 
+/**
+ * gst_gl_version_to_glsl_version:
+ * @gl_api: the #GstGLAPI
+ * @maj: the major GL version
+ * @min: the minor GL version
+ *
+ * Returns: The minimum supported #GstGLSLVersion available for @gl_api, @maj and @min
+ */
 GstGLSLVersion
 gst_gl_version_to_glsl_version (GstGLAPI gl_api, gint maj, gint min)
 {
@@ -485,6 +546,14 @@ gst_gl_version_to_glsl_version (GstGLAPI gl_api, gint maj, gint min)
   return 0;
 }
 
+/**
+ * gst_gl_context_supports_glsl_profile_version:
+ * @context: a #GstGLContext
+ * @version: a #GstGLSLVersion
+ * @profile: a #GstGLSLProfile
+ *
+ * Returns: Whether @context supports the combination of @version with @profile
+ */
 gboolean
 gst_gl_context_supports_glsl_profile_version (GstGLContext * context,
     GstGLSLVersion version, GstGLSLProfile profile)
diff --git a/gst-libs/gst/gl/gstglsl.h b/gst-libs/gst/gl/gstglsl.h
index 42de2b9b42..af837fd943 100644
--- a/gst-libs/gst/gl/gstglsl.h
+++ b/gst-libs/gst/gl/gstglsl.h
@@ -27,6 +27,13 @@ G_BEGIN_DECLS
 
 GST_EXPORT
 GQuark gst_glsl_error_quark (void);
+
+/**
+ * GST_GLSL_ERROR:
+ *
+ * Error domain for GStreamer's GLSL module. Errors in this domain will be
+ * from the #GstGLSLError enumeration
+ */
 #define GST_GLSL_ERROR (gst_glsl_error_quark ())
 
 /**
diff --git a/gst-libs/gst/gl/gstglupload.h b/gst-libs/gst/gl/gstglupload.h
index 7b94929a18..c672fe5e0f 100644
--- a/gst-libs/gst/gl/gstglupload.h
+++ b/gst-libs/gst/gl/gstglupload.h
@@ -41,6 +41,7 @@ GType gst_gl_upload_get_type (void);
  * @GST_GL_UPLOAD_DONE: No further processing required
  * @GST_GL_UPLOAD_ERROR: An unspecified error occured
  * @GST_GL_UPLOAD_UNSUPPORTED: The configuration is unsupported.
+ * @GST_GL_UPLOAD_RECONFIGURE: This element requires a reconfiguration.
  */
 typedef enum
 {
diff --git a/gst-libs/gst/gl/gstglwindow.h b/gst-libs/gst/gl/gstglwindow.h
index 5d7ced4170..fccb0cff97 100644
--- a/gst-libs/gst/gl/gstglwindow.h
+++ b/gst-libs/gst/gl/gstglwindow.h
@@ -50,6 +50,12 @@ GType gst_gl_window_get_type       (void);
 
 GST_EXPORT
 GQuark gst_gl_window_error_quark (void);
+/**
+ * GST_GL_WINDOW_ERROR:
+ *
+ * Error domain for GStreamer's GL window module. Errors in this domain will be
+ * from the #GstGLWindowError enumeration
+ */
 #define GST_GL_WINDOW_ERROR (gst_gl_window_error_quark ())
 
 /**
@@ -68,7 +74,20 @@ typedef enum
 typedef void (*GstGLWindowCB) (gpointer data);
 typedef void (*GstGLWindowResizeCB) (gpointer data, guint width, guint height);
 
+/**
+ * GST_GL_WINDOW_CB:
+ * @f: the function to cast
+ *
+ * Cast to the currect function type for generic window callbacks
+ */
 #define	GST_GL_WINDOW_CB(f)			 ((GstGLWindowCB) (f))
+
+/**
+ * GST_GL_WINDOW_RESIZE_CB:
+ * @f: the function to cast
+ *
+ * Cast to the currect function type for window resize callbacks
+ */
 #define	GST_GL_WINDOW_RESIZE_CB(f)		 ((GstGLWindowResizeCB) (f))
 
 /**