From 9bafa08a5dc8227ac44cf0feb658bb08427bbe4e Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Thu, 3 Nov 2016 12:03:24 +1100 Subject: [PATCH] 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 --- gst-libs/gst/gl/egl/gstglcontext_egl.h | 18 ++++- gst-libs/gst/gl/egl/gstgldisplay_egl.c | 8 +-- gst-libs/gst/gl/egl/gstglmemoryegl.c | 9 +++ gst-libs/gst/gl/gstglapi.c | 9 +++ gst-libs/gst/gl/gstglbasefilter.c | 2 +- gst-libs/gst/gl/gstglbasememory.h | 2 +- gst-libs/gst/gl/gstglbuffer.h | 1 - gst-libs/gst/gl/gstglbufferpool.c | 10 +-- gst-libs/gst/gl/gstglcolorconvert.c | 62 ++++++++++++++-- gst-libs/gst/gl/gstglcolorconvert.h | 6 +- gst-libs/gst/gl/gstglcontext.c | 67 ++++++++++++++--- gst-libs/gst/gl/gstglcontext.h | 14 ++++ gst-libs/gst/gl/gstgldebug.c | 1 - gst-libs/gst/gl/gstgldisplay.c | 8 +++ gst-libs/gst/gl/gstglfilter.c | 17 +++++ gst-libs/gst/gl/gstglfilter.h | 27 +++---- gst-libs/gst/gl/gstglformat.c | 11 ++- gst-libs/gst/gl/gstglframebuffer.h | 2 +- gst-libs/gst/gl/gstglmemory.c | 5 +- gst-libs/gst/gl/gstglmemory.h | 21 ++++-- gst-libs/gst/gl/gstglmemorypbo.c | 5 +- gst-libs/gst/gl/gstglmemorypbo.h | 3 +- gst-libs/gst/gl/gstgloverlaycompositor.c | 6 ++ gst-libs/gst/gl/gstglsl.h | 48 ++++++++++++- gst-libs/gst/gl/gstglslstage.c | 22 ++++++ gst-libs/gst/gl/gstglslstage.h | 4 +- gst-libs/gst/gl/gstglsyncmeta.c | 58 +++++++++++++++ gst-libs/gst/gl/gstglsyncmeta.h | 30 ++++++-- gst-libs/gst/gl/gstglutils.c | 7 ++ gst-libs/gst/gl/gstglviewconvert.c | 92 ++++++++++++++++++++++++ gst-libs/gst/gl/gstglviewconvert.h | 22 +++++- gst-libs/gst/gl/gstglwindow.h | 11 ++- 32 files changed, 535 insertions(+), 73 deletions(-) diff --git a/gst-libs/gst/gl/egl/gstglcontext_egl.h b/gst-libs/gst/gl/egl/gstglcontext_egl.h index c73cd0229e..69b750abe2 100644 --- a/gst-libs/gst/gl/egl/gstglcontext_egl.h +++ b/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 +{ + /* */ GstGLContext context; EGLContext egl_context; @@ -63,7 +70,14 @@ struct _GstGLContextEGL { EGLNativeWindowType window_handle; }; -struct _GstGLContextEGLClass { +/** + * GstGLContextEGLCLass: + * + * Opaque #GstGLContextEGLClass struct + */ +struct _GstGLContextEGLClass +{ + /* */ GstGLContextClass parent; }; diff --git a/gst-libs/gst/gl/egl/gstgldisplay_egl.c b/gst-libs/gst/gl/egl/gstgldisplay_egl.c index c0c8022d33..a208808295 100644 --- a/gst-libs/gst/gl/egl/gstgldisplay_egl.c +++ b/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() - * for details on what is a valid name. + * Create a new #GstGLDisplayEGL using the default EGL_DEFAULT_DISPLAY. * * 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 */ diff --git a/gst-libs/gst/gl/egl/gstglmemoryegl.c b/gst-libs/gst/gl/egl/gstglmemoryegl.c index 3079e53d99..3cd1941409 100644 --- a/gst-libs/gst/gl/egl/gstglmemoryegl.c +++ b/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 diff --git a/gst-libs/gst/gl/gstglapi.c b/gst-libs/gst/gl/gstglapi.c index f79a6e49b2..5ae9344e1a 100644 --- a/gst-libs/gst/gl/gstglapi.c +++ b/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 diff --git a/gst-libs/gst/gl/gstglbasefilter.c b/gst-libs/gst/gl/gstglbasefilter.c index 556cd43a12..e6d973acd0 100644 --- a/gst-libs/gst/gl/gstglbasefilter.c +++ b/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 * diff --git a/gst-libs/gst/gl/gstglbasememory.h b/gst-libs/gst/gl/gstglbasememory.h index 980eb403aa..622eef1107 100644 --- a/gst-libs/gst/gl/gstglbasememory.h +++ b/gst-libs/gst/gl/gstglbasememory.h @@ -332,12 +332,12 @@ struct _GstGLBaseMemoryAllocatorClass GstGLBaseMemoryAllocatorUnmapFunction unmap; GstGLBaseMemoryAllocatorCopyFunction copy; GstGLBaseMemoryAllocatorDestroyFunction destroy; + /* */ #if 0 GstGLBaseMemoryAllocatorFlushFunction flush; /* make CPU writes visible to the GPU */ GstGLBaseMemoryAllocatorInvalidateFunction invalidate; /* make GPU writes visible to the CPU */ #endif - /* */ gpointer _padding[GST_PADDING]; }; diff --git a/gst-libs/gst/gl/gstglbuffer.h b/gst-libs/gst/gl/gstglbuffer.h index c6ef6a5a80..b93931027f 100644 --- a/gst-libs/gst/gl/gstglbuffer.h +++ b/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 diff --git a/gst-libs/gst/gl/gstglbufferpool.c b/gst-libs/gst/gl/gstglbufferpool.c index 218169aa81..4b3cf28ccb 100644 --- a/gst-libs/gst/gl/gstglbufferpool.c +++ b/gst-libs/gst/gl/gstglbufferpool.c @@ -28,15 +28,17 @@ /** * SECTION:gstglbufferpool - * @short_description: buffer pool for #GstGLMemory objects - * @see_also: #GstBufferPool, #GstGLMemory + * @short_description: buffer pool for #GstGLBaseMemory objects + * @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 */ diff --git a/gst-libs/gst/gl/gstglcolorconvert.c b/gst-libs/gst/gl/gstglcolorconvert.c index 908a53eccf..0bf6b469e9 100644 --- a/gst-libs/gst/gl/gstglcolorconvert.c +++ b/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 - * #GstVideoInfos 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) diff --git a/gst-libs/gst/gl/gstglcolorconvert.h b/gst-libs/gst/gl/gstglcolorconvert.h index efae55e32e..76a5247cde 100644 --- a/gst-libs/gst/gl/gstglcolorconvert.h +++ b/gst-libs/gst/gl/gstglcolorconvert.h @@ -76,9 +76,9 @@ struct _GstGLColorConvert */ struct _GstGLColorConvertClass { + /* */ GstObjectClass object_class; - /* */ 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); diff --git a/gst-libs/gst/gl/gstglcontext.c b/gst-libs/gst/gl/gstglcontext.c index 2bc0a780ad..e68de9aa3e 100644 --- a/gst-libs/gst/gl/gstglcontext.c +++ b/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 - * @minor: (out): (allow-none): the minor version + * @major: (out) (allow-none): the major 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 - * @other_context as a context to share shareable OpenGL objects with. See the - * OpenGL specification for what is shared between contexts. + * Creates an OpenGL context with the specified @other_context as a context + * to share shareable OpenGL objects with. See the OpenGL specification for + * 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 - * determine their existence and so will fail if that is not the case. + * Check for an OpenGL @feature being supported. + * + * 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 * diff --git a/gst-libs/gst/gl/gstglcontext.h b/gst-libs/gst/gl/gstglcontext.h index 699a73f727..13db75e577 100644 --- a/gst-libs/gst/gl/gstglcontext.h +++ b/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 >*/ diff --git a/gst-libs/gst/gl/gstgldebug.c b/gst-libs/gst/gl/gstgldebug.c index 5b89bf64ca..b63244da0e 100644 --- a/gst-libs/gst/gl/gstgldebug.c +++ b/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() * diff --git a/gst-libs/gst/gl/gstgldisplay.c b/gst-libs/gst/gl/gstgldisplay.c index 3ffc90666a..d6849a737f 100644 --- a/gst-libs/gst/gl/gstgldisplay.c +++ b/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) { diff --git a/gst-libs/gst/gl/gstglfilter.c b/gst-libs/gst/gl/gstglfilter.c index b0693c15b8..2dbdecee0b 100644 --- a/gst-libs/gst/gl/gstglfilter.c +++ b/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) diff --git a/gst-libs/gst/gl/gstglfilter.h b/gst-libs/gst/gl/gstglfilter.h index 6538abdcb9..d1333d5855 100644 --- a/gst-libs/gst/gl/gstglfilter.h +++ b/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 - * @pool: the currently configured #GstBufferPool - * @display: the currently configured #GstGLDisplay + * @parent: parent #GstGLBaseFilter * @in_info: the video info for input buffers * @out_info: the video info for output buffers - * @fbo: GL Framebuffer object used for transformations - * @depthbuffer: GL renderbuffer attached to @fbo - * @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 - * #GstBuffers. + * @out_caps: the output #GstCaps + * @fbo: #GstGLFramebuffer object used for transformations */ 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); + /* */ gpointer _padding[GST_PADDING]; }; diff --git a/gst-libs/gst/gl/gstglformat.c b/gst-libs/gst/gl/gstglformat.c index 1a71327b47..d64c05d743 100644 --- a/gst-libs/gst/gl/gstglformat.c +++ b/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 diff --git a/gst-libs/gst/gl/gstglframebuffer.h b/gst-libs/gst/gl/gstglframebuffer.h index 240477f12a..0d0078ab06 100644 --- a/gst-libs/gst/gl/gstglframebuffer.h +++ b/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 diff --git a/gst-libs/gst/gl/gstglmemory.c b/gst-libs/gst/gl/gstglmemory.c index 73c3b591f4..84dd16db11 100644 --- a/gst-libs/gst/gl/gstglmemory.c +++ b/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 * diff --git a/gst-libs/gst/gl/gstglmemory.h b/gst-libs/gst/gl/gstglmemory.h index 6cdcdcea5f..a7f488c278 100644 --- a/gst-libs/gst/gl/gstglmemory.h +++ b/gst-libs/gst/gl/gstglmemory.h @@ -51,8 +51,7 @@ GType gst_gl_memory_allocator_get_type(void); /** * GstGLMemory: - * @mem: the parent object - * @context: the #GstGLContext to use for GL operations + * @mem: the parent #GstGLBaseMemory object * @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 { + /* */ GstGLBaseMemoryAllocator parent; - /* */ gpointer _padding[GST_PADDING]; }; /** * GstGLMemoryAllocatorClass: - * - * The #GstGLMemoryAllocatorClass only contains private data + * @map: provide a custom map implementation + * @copy: provide a custom copy implementation + * @unmap: provide a custom unmap implementation */ struct _GstGLMemoryAllocatorClass { + /* */ GstGLBaseMemoryAllocatorClass parent_class; + /* */ GstGLBaseMemoryAllocatorMapFunction map; GstGLBaseMemoryAllocatorCopyFunction copy; GstGLBaseMemoryAllocatorUnmapFunction unmap; diff --git a/gst-libs/gst/gl/gstglmemorypbo.c b/gst-libs/gst/gl/gstglmemorypbo.c index ebf8f2971c..632f483fd6 100644 --- a/gst-libs/gst/gl/gstglmemorypbo.c +++ b/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. diff --git a/gst-libs/gst/gl/gstglmemorypbo.h b/gst-libs/gst/gl/gstglmemorypbo.h index 66ee6b8db1..7a76119c55 100644 --- a/gst-libs/gst/gl/gstglmemorypbo.h +++ b/gst-libs/gst/gl/gstglmemorypbo.h @@ -49,12 +49,11 @@ GType gst_gl_memory_pbo_allocator_get_type(void); */ struct _GstGLMemoryPBO { + /* */ GstGLMemory mem; - /* */ GstGLBuffer *pbo; - /* */ gpointer _padding[GST_PADDING]; }; diff --git a/gst-libs/gst/gl/gstgloverlaycompositor.c b/gst-libs/gst/gl/gstgloverlaycompositor.c index f6548a06b0..46bc7ff235 100644 --- a/gst-libs/gst/gl/gstgloverlaycompositor.c +++ b/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 diff --git a/gst-libs/gst/gl/gstglsl.h b/gst-libs/gst/gl/gstglsl.h index 097fea254b..4d5a7545af 100644 --- a/gst-libs/gst/gl/gstglsl.h +++ b/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 */ diff --git a/gst-libs/gst/gl/gstglslstage.c b/gst-libs/gst/gl/gstglslstage.c index 770b1d0123..708dff1a24 100644 --- a/gst-libs/gst/gl/gstglslstage.c +++ b/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) diff --git a/gst-libs/gst/gl/gstglslstage.h b/gst-libs/gst/gl/gstglslstage.h index b01100639f..f37e8f653f 100644 --- a/gst-libs/gst/gl/gstglslstage.h +++ b/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 { + /* */ GstObjectClass parent; - /* */ gpointer _padding[GST_PADDING]; }; diff --git a/gst-libs/gst/gl/gstglsyncmeta.c b/gst-libs/gst/gl/gstglsyncmeta.c index 582784c94c..b8822704de 100644 --- a/gst-libs/gst/gl/gstglsyncmeta.c +++ b/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) { diff --git a/gst-libs/gst/gl/gstglsyncmeta.h b/gst-libs/gst/gl/gstglsyncmeta.h index f9800641ef..ea67b79108 100644 --- a/gst-libs/gst/gl/gstglsyncmeta.h +++ b/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 diff --git a/gst-libs/gst/gl/gstglutils.c b/gst-libs/gst/gl/gstglutils.c index 4a23914b59..b18b803de8 100644 --- a/gst-libs/gst/gl/gstglutils.c +++ b/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 diff --git a/gst-libs/gst/gl/gstglviewconvert.c b/gst-libs/gst/gl/gstglviewconvert.c index 5fa06eb738..d4a2c1b69d 100644 --- a/gst-libs/gst/gl/gstglviewconvert.c +++ b/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) diff --git a/gst-libs/gst/gl/gstglviewconvert.h b/gst-libs/gst/gl/gstglviewconvert.h index 8f3ee8a191..d418ca90e0 100644 --- a/gst-libs/gst/gl/gstglviewconvert.h +++ b/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 { + /* */ GstObjectClass object_class; - /* */ gpointer _padding[GST_PADDING]; }; diff --git a/gst-libs/gst/gl/gstglwindow.h b/gst-libs/gst/gl/gstglwindow.h index 730be00dc8..a5cc5b4b02 100644 --- a/gst-libs/gst/gl/gstglwindow.h +++ b/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;