gl/docs: add to new docs system

sailfishos-mirror · May 21, 2019 · 51f2d05 · 51f2d05
1 parent ed33011
commit 51f2d05
Show file tree

Hide file tree

Showing 49 changed files with 208 additions and 123 deletions.
diff --git a/docs/libs/gl/index.md b/docs/libs/gl/index.md
@@ -0,0 +1,4 @@
+# GStreamer OpenGL Library
+
+This library should be linked to by getting cflags and libs from
+`gstreamer-gl-{{ gst_api_version.md }}.pc`.
diff --git a/docs/libs/gl/sitemap.txt b/docs/libs/gl/sitemap.txt
@@ -0,0 +1 @@
+gi-index
diff --git a/docs/meson.build b/docs/meson.build
@@ -71,10 +71,11 @@ foreach h: ['pbutils-private.h', 'gsttageditingprivate.h', 'id3v2.h',
   '_kiss_fft_guts_f32.h', '_kiss_fft_guts_f64.h', '_kiss_fft_guts_s16.h',
   '_kiss_fft_guts_s16.h', '_kiss_fft_guts_s32.h', '_kiss_fft_guts_s32.h',
   'pbutils-marshal.h', 'audio-resampler-private.h', '*orc-dist.*',
-  '*-neon.h', 'audio-resampler-macros.[ch]', '*-prelude.h'
+  '*-neon.h', 'audio-resampler-macros.[ch]', '*-prelude.h', '*_private.h',
+  'gstglfuncs.[ch]', 'gstgl_fwd.h'
   ]
 
-    libs_excludes += [join_paths(meson.current_source_dir(), '..', 'gst-libs/gst/*/', h)]
+  libs_excludes += [join_paths(meson.current_source_dir(), '..', 'gst-libs/gst/*/', h)]
 endforeach
 
 libs = [
@@ -91,17 +92,28 @@ libs = [
 ]
 
 if build_gstgl
-  libs + [['gl', gl_gir, gstgl_dep]]
+  libs += [['gl', gl_gir, gstgl_dep, [
+      join_paths('../gst-libs/gst', 'gl', 'egl', 'gstegl.[ch]'),
+      join_paths('../gst-libs/gst', 'gl', 'egl', 'gsteglimage.[ch]'),
+      join_paths('../gst-libs/gst', 'gl', 'egl', 'gstgldisplay_egl.[ch]'),
+      join_paths('../gst-libs/gst', 'gl', 'egl', 'gstglmemoryegl.[ch]'),
+      join_paths('../gst-libs/gst', 'gl', 'x11', 'gstgldisplay_x11.[ch]'),
+      join_paths('../gst-libs/gst', 'gl', 'wayland', 'gstgldisplay_wayland.[ch]'),
+  ]]]
 endif
 
 libs_doc = []
 foreach lib: libs
   name = lib[0]
   gir = lib[1]
   deps = [lib[2], gir]
+  extra_sources = []
+  if lib.length() >= 4
+    extra_sources = lib[3]
+  endif
   libs_doc += [hotdoc.generate_doc('gst-plugins-base-' + name,
       project_version: api_version,
-      gi_c_sources: [join_paths('../gst-libs/gst', name, '*.[hc]')],
+      gi_c_sources: [join_paths('../gst-libs/gst', name, '*.[hc]')] + extra_sources,
       gi_sources: gir[0].full_path(),
       gi_c_source_filters: libs_excludes,
       gi_c_source_roots: [join_paths(meson.current_source_dir(), '../gst-libs/gst/' + name), ],

diff --git a/ext/gl/gstglalpha.h b/ext/gl/gstglalpha.h
@@ -65,7 +65,6 @@ GstGLAlphaMethod;
 struct _GstGLAlpha {
   GstGLFilter videofilter;
 
-  /* < private > */
   GstGLShader *alpha_shader;
   GstGLShader *chroma_key_shader;
 

diff --git a/ext/gl/gstglcolorbalance.h b/ext/gl/gstglcolorbalance.h
@@ -49,7 +49,6 @@ typedef struct _GstGLColorBalanceClass GstGLColorBalanceClass;
 struct _GstGLColorBalance {
   GstGLFilter videofilter;
 
-  /* < private > */
   GstGLShader *shader;
 
   /* channels for interface */

diff --git a/ext/gl/gstgldownloadelement.h b/ext/gl/gstgldownloadelement.h
@@ -41,7 +41,6 @@ typedef struct _GstGLDownloadElementClass GstGLDownloadElementClass;
 
 struct _GstGLDownloadElement
 {
-  /* <private> */
   GstGLBaseFilter  parent;
 
   gboolean do_pbo_transfers;
@@ -51,7 +50,6 @@ struct _GstGLDownloadElement
 
 struct _GstGLDownloadElementClass
 {
-  /* <private> */
   GstGLBaseFilterClass object_class;
 };
 

diff --git a/ext/gl/gstgloverlay.h b/ext/gl/gstgloverlay.h
@@ -53,7 +53,6 @@ struct _GstGLOverlay
 
   gdouble       alpha;
 
-  /* <private> */
   GstGLShader  *shader;
   GstGLMemory  *image_memory;
 

diff --git a/ext/gl/gstgluploadelement.h b/ext/gl/gstgluploadelement.h
@@ -46,7 +46,6 @@ typedef struct _GstGLUploadElementPrivate GstGLUploadElementPrivate;
  */
 struct _GstGLUploadElement
 {
-  /* <private> */
   GstGLBaseFilter     parent;
 
   GstGLUpload *upload;

diff --git a/ext/gl/gstglvideomixer.c b/ext/gl/gstglvideomixer.c
@@ -545,7 +545,6 @@ struct _GstGLVideoMixerPad
 {
   GstGLMixerPad parent;
 
-  /* < private > */
   /* properties */
   gint xpos, ypos;
   gint width, height;

diff --git a/gst-libs/gst/gl/egl/gstegl.c b/gst-libs/gst/gl/egl/gstegl.c
@@ -17,6 +17,14 @@
  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  * Boston, MA 02110-1301, USA.
  */
+
+/**
+ * SECTION:gstegl
+ * @short_description: EGL helpers
+ * @title: GstEGL
+ * @see_also: #GstGLDisplayEGL, #GstEGLImage
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

diff --git a/gst-libs/gst/gl/egl/gsteglimage.c b/gst-libs/gst/gl/egl/gsteglimage.c
@@ -27,11 +27,11 @@
  * @title: GstEGLImage
  * @see_also: #GstGLMemoryEGL, #GstGLContext
  *
- * #GstEGLImage represents and holds an #EGLImage handle.
+ * #GstEGLImage represents and holds an `EGLImage` handle.
  *
  * A #GstEGLImage can be created from a dmabuf with gst_egl_image_from_dmabuf(),
  * or gst_egl_image_from_dmabuf_direct(), or #GstGLMemoryEGL provides a
- * #GstAllocator to allocate #EGLImage's bound to and OpenGL texture.
+ * #GstAllocator to allocate `EGLImage`'s bound to and OpenGL texture.
  */
 
 #ifdef HAVE_CONFIG_H
@@ -200,7 +200,7 @@ gst_egl_image_ensure_debug_category (void)
  * gst_egl_image_get_image:
  * @image: a #GstEGLImage
  *
- * Returns: the #EGLImageKHR of @image
+ * Returns: the `EGLImage` of @image
  */
 gpointer
 gst_egl_image_get_image (GstEGLImage * image)
@@ -400,7 +400,7 @@ _destroy_egl_image (GstEGLImage * image, gpointer user_data)
  * gst_egl_image_from_texture:
  * @context: a #GstGLContext (must be an EGL context)
  * @gl_mem: a #GstGLMemory
- * @attribs: additional attributes to add to the eglCreateImage() call.
+ * @attribs: additional attributes to add to the `eglCreateImage`() call.
  *
  * Returns: (transfer full): a #GstEGLImage wrapping @gl_mem or %NULL on failure
  */

diff --git a/gst-libs/gst/gl/egl/gsteglimage.h b/gst-libs/gst/gl/egl/gsteglimage.h
@@ -43,7 +43,7 @@ typedef struct _GstEGLImage 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
+ * the associated `EGLImage` if necessary
  */
 typedef void (*GstEGLImageDestroyNotify) (GstEGLImage * image,
     gpointer data);

diff --git a/gst-libs/gst/gl/egl/gstglcontext_egl.h b/gst-libs/gst/gl/egl/gstglcontext_egl.h
@@ -50,7 +50,7 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstGLContextEGL, gst_object_unref)
  */
 struct _GstGLContextEGL
 {
-  /* <private> */
+  /*< private >*/
   GstGLContext context;
 
   GstGLDisplayEGL *display_egl;
@@ -78,7 +78,7 @@ struct _GstGLContextEGL
  */
 struct _GstGLContextEGLClass
 {
-  /* <private> */
+  /*< private >*/
   GstGLContextClass parent;
 };
 

diff --git a/gst-libs/gst/gl/egl/gstgldisplay_egl.c b/gst-libs/gst/gl/egl/gstgldisplay_egl.c
@@ -18,6 +18,17 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION:gstgldisplay_egl
+ * @short_description: EGL Display connection
+ * @title: GstGLDisplayEGL
+ * @see_also: #GstGLDisplay
+ *
+ * #GstGLDisplayEGL represents a connection to an EGL `EGLDisplay` handle created
+ * internally (gst_gl_display_egl_new()) or wrapped by the application
+ * (gst_gl_display_egl_new_with_egl_display())
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -92,11 +103,11 @@ gst_gl_display_egl_finalize (GObject * object)
  * @type: a #GstGLDisplayType
  * @display: pointer to a display (or 0)
  *
- * Attempts to create a new #EGLDisplay from @display.  If @type is
+ * Attempts to create a new `EGLDisplay` from @display.  If @type is
  * %GST_GL_DISPLAY_TYPE_ANY, then @display must be 0. @type must not be
  * %GST_GL_DISPLAY_TYPE_NONE.
  *
- * Returns: A #EGLDisplay or %EGL_NO_DISPLAY
+ * Returns: A `EGLDisplay` or `EGL_NO_DISPLAY`
  *
  * Since: 1.12
  */

diff --git a/gst-libs/gst/gl/egl/gstgldisplay_egl.h b/gst-libs/gst/gl/egl/gstgldisplay_egl.h
@@ -48,7 +48,7 @@ struct _GstGLDisplayEGL
 {
   GstGLDisplay          parent;
 
-  /* <private> */
+  /*< private >*/
   gpointer display;
 
   gboolean foreign_display;

diff --git a/gst-libs/gst/gl/egl/gstglmemoryegl.c b/gst-libs/gst/gl/egl/gstglmemoryegl.c
@@ -25,6 +25,7 @@
 /**
  * SECTION:gstglmemoryegl
  * @short_description: memory subclass for EGLImage's
+ * @title: GstGLMemoryEGL
  * @see_also: #GstGLMemory, #GstGLBaseMemoryAllocator, #GstGLBufferPool
  *
  * #GstGLMemoryEGL is created or wrapped through gst_gl_base_memory_alloc()

diff --git a/gst-libs/gst/gl/egl/gstglmemoryegl.h b/gst-libs/gst/gl/egl/gstglmemoryegl.h
@@ -46,7 +46,7 @@ GST_GL_API GType gst_gl_memory_egl_allocator_get_type(void);
  */
 struct _GstGLMemoryEGL
 {
-  /* <private> */
+  /*< private >*/
   GstGLMemory mem;
 
   GstEGLImage *image;
@@ -74,13 +74,13 @@ GST_GL_API
 gpointer      gst_gl_memory_egl_get_display             (GstGLMemoryEGL * mem);
 
 /**
- * GstGLMemoryEGLAllocator
+ * GstGLMemoryEGLAllocator:
  *
  * Opaque #GstGLMemoryEGLAllocator struct
  */
 struct _GstGLMemoryEGLAllocator
 {
-  /* <private> */
+  /*< private >*/
 
   GstGLMemoryAllocator parent;
 
@@ -94,7 +94,7 @@ struct _GstGLMemoryEGLAllocator
  */
 struct _GstGLMemoryEGLAllocatorClass
 {
-  /* <private> */
+  /*< private >*/
   GstGLMemoryAllocatorClass parent_class;
 
   gpointer _padding[GST_PADDING];

diff --git a/gst-libs/gst/gl/gbm/gstgldisplay_gbm.h b/gst-libs/gst/gl/gbm/gstgldisplay_gbm.h
@@ -48,7 +48,7 @@ struct _GstGLDisplayGBM
 {
   GstGLDisplay parent;
 
-  /* <private> */
+  /*< private >*/
 
   int drm_fd;
   drmModeRes *drm_mode_resources;

diff --git a/gst-libs/gst/gl/gstglapi.c b/gst-libs/gst/gl/gstglapi.c
@@ -33,6 +33,15 @@
 
 #include "gstglapi.h"
 
+/**
+ * GstGLFuncs:
+ *
+ * Structure containing function pointers to OpenGL functions.
+ *
+ * Each field is named exactly the same as the OpenGL function without the
+ * `gl` prefix.
+ */
+
 /**
  * gst_gl_api_to_string:
  * @api: a #GstGLAPI to stringify

diff --git a/gst-libs/gst/gl/gstglbasefilter.c b/gst-libs/gst/gl/gstglbasefilter.c
@@ -35,8 +35,8 @@
  *
  * #GstGLBaseFilter handles the nitty gritty details of retrieving an OpenGL
  * context.  It also provided some wrappers around #GstBaseTransform's
- * start(), stop() and set_caps() virtual methods that ensure an OpenGL context
- * is available and current in the calling thread.
+ * `start()`, `stop()` and `set_caps()` virtual methods that ensure an OpenGL
+ * context is available and current in the calling thread.
  */
 
 #define GST_CAT_DEFAULT gst_gl_base_filter_debug

diff --git a/gst-libs/gst/gl/gstglbasememory.c b/gst-libs/gst/gl/gstglbasememory.c
@@ -53,6 +53,11 @@ GST_DEBUG_CATEGORY_STATIC (GST_CAT_GL_BASE_MEMORY);
 
 GST_DEFINE_MINI_OBJECT_TYPE (GstGLBaseMemory, gst_gl_base_memory);
 
+/**
+ * gst_gl_base_memory_error_quark:
+ *
+ * Returns: the quark used for #GstGLBaseMemory in #GError's
+ */
 GQuark
 gst_gl_base_memory_error_quark (void)
 {

diff --git a/gst-libs/gst/gl/gstglbasememory.h b/gst-libs/gst/gl/gstglbasememory.h
@@ -107,7 +107,7 @@ struct _GstGLBaseMemory
 
   GstGLContext         *context;
 
-  /* <protected> */
+  /*< protected >*/
   GMutex                lock;
 
   GstMapFlags           map_flags;       /* cumulative map flags */
@@ -118,7 +118,7 @@ struct _GstGLBaseMemory
 
   GstGLQuery           *query;
 
-  /* <private> */
+  /*< private >*/
   gsize                 alloc_size;     /* because maxsize is used for mapping */
   gpointer              alloc_data;
 
@@ -215,7 +215,7 @@ struct _GstGLAllocationParams
   /* GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_WRAP_GPU_HANDLE only */
   gpointer                          gl_handle;
 
-  /* <private> */
+  /*< private >*/
   gpointer                          _padding[GST_PADDING];
 };
 
@@ -370,8 +370,8 @@ struct _GstGLBaseMemoryAllocatorClass
   GstGLBaseMemoryAllocatorUnmapFunction         unmap;
   GstGLBaseMemoryAllocatorCopyFunction          copy;
   GstGLBaseMemoryAllocatorDestroyFunction       destroy;
-  /* <private> */
 
+  /*< private >*/
   gpointer                                      _padding[GST_PADDING];
 };
 

diff --git a/gst-libs/gst/gl/gstglbuffer.h b/gst-libs/gst/gl/gstglbuffer.h
@@ -80,7 +80,7 @@ struct _GstGLBufferAllocationParams
   guint                     gl_target;
   guint                     gl_usage;
 
-  /* <private> */
+  /*< private >*/
   gpointer                  _padding[GST_PADDING];
 };
 
@@ -100,7 +100,7 @@ struct _GstGLBufferAllocator
 {
   GstGLBaseMemoryAllocator parent;
 
-  /* <private> */
+  /*< private >*/
   gpointer _padding[GST_PADDING];
 };
 
@@ -113,7 +113,7 @@ struct _GstGLBufferAllocatorClass
 {
   GstGLBaseMemoryAllocatorClass parent_class;
 
-  /* <private> */
+  /*< private >*/
   gpointer _padding[GST_PADDING];
 };
 

diff --git a/gst-libs/gst/gl/gstglbufferpool.h b/gst-libs/gst/gl/gstglbufferpool.h
@@ -47,7 +47,7 @@ struct _GstGLBufferPool
 
   GstGLContext *context;
 
-  /* <private> */
+  /*< private >*/
   GstGLBufferPoolPrivate *priv;
 
   gpointer _padding[GST_PADDING];
@@ -62,7 +62,7 @@ struct _GstGLBufferPoolClass
 {
   GstBufferPoolClass parent_class;
 
-  /* <private> */
+  /*< private >*/
   gpointer _padding[GST_PADDING];
 };