gl: document some GL caps specifics

Fixes: https://gitlab.freedesktop.org/gstreamer/gst-plugins-base/-/issues/854
Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-base/-/merge_requests/996>

diff --git a/gst-libs/gst/gl/gstgl_enums.h b/gst-libs/gst/gl/gstgl_enums.h
index 25c7b39..93d9fed 100644 (file)
--- a/gst-libs/gst/gl/gstgl_enums.h
+++ b/gst-libs/gst/gl/gstgl_enums.h
@@ -24,9 +24,17 @@
 /**
  * GstGLTextureTarget:
  * @GST_GL_TEXTURE_TARGET_NONE: no texture target
- * @GST_GL_TEXTURE_TARGET_2D: 2D texture target
+ * @GST_GL_TEXTURE_TARGET_2D: 2D texture target (`GL_TEXTURE_2D`)
  * @GST_GL_TEXTURE_TARGET_RECTANGLE: rectangle texture target
+ *     (`GL_TEXTURE_RECTANGLE`)
  * @GST_GL_TEXTURE_TARGET_EXTERNAL_OES: external oes texture target
+ *     (`GL_TEXTURE_EXTERNAL_OES`)
+ *
+ * The OpenGL texture target that an OpenGL texture can be bound to.  The
+ * gst_gl_value_set_texture_target_from_mask(),
+ * gst_gl_value_get_texture_target_mask(), and
+ * gst_gl_value_set_texture_target() functions can be used for handling texture
+ * targets with #GValue's when e.g. dealing with #GstCaps.
  *
  * Since: 1.8
  */

diff --git a/gst-libs/gst/gl/gstglmemory.c b/gst-libs/gst/gl/gstglmemory.c
index 566fc4a..76c04eb 100644 (file)
--- a/gst-libs/gst/gl/gstglmemory.c
+++ b/gst-libs/gst/gl/gstglmemory.c
@@ -43,6 +43,12 @@
  * with #GstGLVideoAllocationParams.
  *
  * Data is uploaded or downloaded from the GPU as is necessary.
+ *
+ * The #GstCaps that is used for #GstGLMemory based buffers should contain
+ * the %GST_CAPS_FEATURE_MEMORY_GL_MEMORY as a #GstCapsFeatures and should
+ * contain a 'texture-target' field with one of the #GstGLTextureTarget values
+ * as a string, i.e. some combination of 'texture-target=(string){2D,
+ * rectangle, external-oes}'.
  */
 
 #define USING_OPENGL(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL, 1, 0))

diff --git a/gst-libs/gst/gl/gstglutils.c b/gst-libs/gst/gl/gstglutils.c
index a4c35bd..a60aa45 100644 (file)
--- a/gst-libs/gst/gl/gstglutils.c
+++ b/gst-libs/gst/gl/gstglutils.c
@@ -661,7 +661,8 @@ gst_gl_get_plane_start (GstVideoInfo * info, GstVideoAlignment * valign,
  *
  * See gst_gl_value_set_texture_target_from_mask() for what entails a mask
  *
- * Returns: the mask of #GstGLTextureTarget's in @value
+ * Returns: the mask of #GstGLTextureTarget's in @value or
+ *     %GST_GL_TEXTURE_TARGET_NONE on failure
  */
 GstGLTextureTarget
 gst_gl_value_get_texture_target_mask (const GValue * targets)