From 8003acf5bb6deb7a9ee2604ed6e17bb387a9c819 Mon Sep 17 00:00:00 2001 From: Matthew Waters Date: Thu, 18 May 2023 16:55:27 +1000 Subject: [PATCH] gl: update docs for mixer move Part-of: --- girs/GstGL-1.0.gir | 446 ++++++++++++++++++ .../gst-docs/symbols/symbol_index.json | 4 +- .../docs/plugins/gst_plugins_cache.json | 65 --- .../gst-libs/gst/gl/gstglbasemixer.c | 11 +- .../gst-libs/gst/gl/gstglbasemixer.h | 98 +++- .../gst-libs/gst/gl/gstglmixer.c | 16 +- .../gst-libs/gst/gl/gstglmixer.h | 97 +++- 7 files changed, 654 insertions(+), 83 deletions(-) diff --git a/girs/GstGL-1.0.gir b/girs/GstGL-1.0.gir index 8c9f84166f..b719d23a86 100644 --- a/girs/GstGL-1.0.gir +++ b/girs/GstGL-1.0.gir @@ -1049,6 +1049,137 @@ function to allocate and OpenGL resources needed for your application to the texture + + #GstGLBaseMixer handles the nitty gritty details of retrieving an OpenGL +context. It provides some virtual methods to know when the OpenGL context +is available and is not available within this element. + + + called in the GL thread to setup the element GL state. + + + whether the start was successful + + + + + + + + + + called in the GL thread to setup the element GL state. + + + + + + + + + + + + + + the #GstGLContext found by @mix + + + + + a #GstGLBaseMixer + + + + + + The #GstGLContext in use by this #GstGLBaseMixer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + whether the start was successful + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GstGLBaseSrc handles the nitty gritty details of retrieving an OpenGL context. It also provided some wrappers around #GstBaseSrc's `start()` and @@ -4563,6 +4694,181 @@ mappings between texture formats. + + #GstGLMixer helps implement an element that operates on RGBA textures. + + + Perform operations on the input buffers to produce an +output buffer. + + + + + + + + + + + + + + + Perform processing required and call #GstGLMixerClass::process_textures(). +Intended for use within implementations of +#GstGLMixerClass::process_buffers(). + + + whether processing of textures succeeded + + + + + the #GstGLMixer + + + + + + + + + + + (nullable): The #GstGLFramebuffer in use by this @mix + + + + + the #GstGLMixer + + + + + + Perform processing required and call #GstGLMixerClass::process_textures(). +Intended for use within implementations of +#GstGLMixerClass::process_buffers(). + + + whether processing of textures succeeded + + + + + the #GstGLMixer + + + + output @GstBuffer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + whether processing of textures succeeded + + + + + the #GstGLMixer + + + + + + + + + + + + + + + Adds the default RGBA pad templates to this class. If you have any special +template requirements like a different pad subclass or different supported +caps, you should not call this function and add the pad templates yourself +manually. + + + + + + + the #GstGLMixerClass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Opaque #GstGLOverlayCompositor object @@ -9162,6 +9468,48 @@ user-defined purposes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -9507,6 +9855,48 @@ e.g. for `CONFIG_ID`: `GST_GL_CONFIG_ATTRIB_NAME (CONFIG_ID)` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -9748,6 +10138,34 @@ e.g. for `CONFIG_ID`: `GST_GL_CONFIG_ATTRIB_NAME (CONFIG_ID)` + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -9881,6 +10299,34 @@ e.g. for `CONFIG_ID`: `GST_GL_CONFIG_ATTRIB_NAME (CONFIG_ID)` + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/subprojects/gst-docs/symbols/symbol_index.json b/subprojects/gst-docs/symbols/symbol_index.json index a9cb708763..0453276977 100644 --- a/subprojects/gst-docs/symbols/symbol_index.json +++ b/subprojects/gst-docs/symbols/symbol_index.json @@ -10041,7 +10041,7 @@ "GstGLBaseMemoryError", "GstGLBaseMemoryTransfer", "GstGLBaseMixer", - "GstGLBaseMixer:context", + "GstGLBaseMixerClass", "GstGLBaseMixerPad", "GstGLBaseSrc", "GstGLBaseSrc.context", @@ -10311,7 +10311,9 @@ "GstGLMixerBinStartTimeSelection::first", "GstGLMixerBinStartTimeSelection::set", "GstGLMixerBinStartTimeSelection::zero", + "GstGLMixerClass", "GstGLMixerPad", + "GstGLMixerPadClass", "GstGLMosaic", "GstGLMosaic!sink_%u", "GstGLMosaic!src", diff --git a/subprojects/gst-plugins-base/docs/plugins/gst_plugins_cache.json b/subprojects/gst-plugins-base/docs/plugins/gst_plugins_cache.json index 8b3a73da61..7566255686 100644 --- a/subprojects/gst-plugins-base/docs/plugins/gst_plugins_cache.json +++ b/subprojects/gst-plugins-base/docs/plugins/gst_plugins_cache.json @@ -6882,43 +6882,6 @@ } ] }, - "GstGLBaseMixer": { - "hierarchy": [ - "GstGLBaseMixer", - "GstVideoAggregator", - "GstAggregator", - "GstElement", - "GstObject", - "GInitiallyUnowned", - "GObject" - ], - "kind": "object", - "properties": { - "context": { - "blurb": "Get OpenGL context", - "conditionally-available": false, - "construct": false, - "construct-only": false, - "controllable": false, - "mutable": "null", - "readable": true, - "type": "GstGLContext", - "writable": false - } - } - }, - "GstGLBaseMixerPad": { - "hierarchy": [ - "GstGLBaseMixerPad", - "GstVideoAggregatorPad", - "GstAggregatorPad", - "GstPad", - "GstObject", - "GInitiallyUnowned", - "GObject" - ], - "kind": "object" - }, "GstGLDeinterlaceMethod": { "kind": "enum", "values": [ @@ -7047,19 +7010,6 @@ } ] }, - "GstGLMixer": { - "hierarchy": [ - "GstGLMixer", - "GstGLBaseMixer", - "GstVideoAggregator", - "GstAggregator", - "GstElement", - "GstObject", - "GInitiallyUnowned", - "GObject" - ], - "kind": "object" - }, "GstGLMixerBinStartTimeSelection": { "kind": "enum", "values": [ @@ -7080,21 +7030,6 @@ } ] }, - "GstGLMixerPad": { - "hierarchy": [ - "GstGLMixerPad", - "GstGLBaseMixerPad", - "GstVideoAggregatorPad", - "GstAggregatorPad", - "GstPad", - "GstObject", - "GInitiallyUnowned", - "GObject" - ], - "kind": "object", - "properties": {}, - "signals": {} - }, "GstGLRotateMethod": { "kind": "enum", "values": [ diff --git a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.c b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.c index 443d634902..a529e98182 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.c +++ b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.c @@ -88,8 +88,6 @@ gst_gl_base_mixer_pad_class_init (GstGLBaseMixerPadClass * klass) vaggpad_class->prepare_frame = NULL; vaggpad_class->clean_frame = NULL; - - gst_type_mark_as_plugin_api (GST_TYPE_GL_BASE_MIXER_PAD, 0); } static void @@ -385,6 +383,13 @@ gst_gl_base_mixer_class_init (GstGLBaseMixerClass * klass) klass->gl_start = gst_gl_base_mixer_default_gl_start; klass->gl_stop = gst_gl_base_mixer_default_gl_stop; + /** + * GstGLBaseMixer:context: + * + * The #GstGLContext in use by this #GstGLBaseMixer + * + * Since: 1.24 + */ g_object_class_install_property (gobject_class, PROP_CONTEXT, g_param_spec_object ("context", "OpenGL context", @@ -395,8 +400,6 @@ gst_gl_base_mixer_class_init (GstGLBaseMixerClass * klass) g_type_class_ref (GST_TYPE_GL_BASE_MIXER_PAD); klass->supported_gl_api = GST_GL_API_ANY; - - gst_type_mark_as_plugin_api (GST_TYPE_GL_BASE_MIXER, 0); } static void diff --git a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.h b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.h index 5977c6d6ec..422343256f 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.h +++ b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglbasemixer.h @@ -43,15 +43,44 @@ G_BEGIN_DECLS typedef struct _GstGLBaseMixerPad GstGLBaseMixerPad; typedef struct _GstGLBaseMixerPadClass GstGLBaseMixerPadClass; -/* all information needed for one video stream */ +/** + * GstGLBaseMixerPad: + * + * Since: 1.24 + */ struct _GstGLBaseMixerPad { - GstVideoAggregatorPad parent; /* subclass the pad */ + /** + * GstGLBaseMixerPad.parent: + * + * parent #GstVideoAggregatorPad + * + * Since: 1.24 + */ + GstVideoAggregatorPad parent; + + /*< private >*/ + gpointer _padding[GST_PADDING]; }; +/** + * GstGLBaseMixerPadClass: + * + * Since: 1.24 + */ struct _GstGLBaseMixerPadClass { + /** + * GstGLBaseMixerPadClass.parent_class: + * + * parent #GstVideoAggregatorPadClass + * + * Since: 1.24 + */ GstVideoAggregatorPadClass parent_class; + + /*< private >*/ + gpointer _padding[GST_PADDING]; }; G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstGLBaseMixerPad, gst_object_unref); @@ -75,26 +104,89 @@ typedef struct _GstGLBaseMixer GstGLBaseMixer; typedef struct _GstGLBaseMixerClass GstGLBaseMixerClass; typedef struct _GstGLBaseMixerPrivate GstGLBaseMixerPrivate; +/** + * GstGLBaseMixer: + * + * Since: 1.24 + */ struct _GstGLBaseMixer { - GstVideoAggregator vaggregator; + /** + * GstGLBaseMixer.parent: + * + * parent #GstVideoAggregator + * + * Since: 1.24 + */ + GstVideoAggregator parent; + /** + * GstGLBaseMixer.display: + * + * the currently configured #GstGLDisplay + * + * Since: 1.24 + */ GstGLDisplay *display; + /** + * GstGLBaseMixer.context: + * + * the currently configured #GstGLContext + * + * Since: 1.24 + */ GstGLContext *context; + /*< private >*/ gpointer _padding[GST_PADDING]; GstGLBaseMixerPrivate *priv; }; +/** + * GstGLBaseMixerClass: + * + * Since: 1.24 + */ struct _GstGLBaseMixerClass { + /** + * GstGLBaseMixerClass.parent_class: + * + * the parent #GstVideoAggregatorClass + * + * Since: 1.24 + */ GstVideoAggregatorClass parent_class; + /** + * GstGLBaseMixerClass.supported_gl_api: + * + * the logical-OR of #GstGLAPI's supported by this element + * + * Since: 1.24 + */ GstGLAPI supported_gl_api; + /** + * GstGLBaseMixerClass::gl_start: + * + * called in the GL thread to setup the element GL state. + * + * Returns: whether the start was successful + * + * Since: 1.24 + */ gboolean (*gl_start) (GstGLBaseMixer * mix); + /** + * GstGLBaseMixerClass::gl_stop: + * + * called in the GL thread to setup the element GL state. + * + * Since: 1.24 + */ void (*gl_stop) (GstGLBaseMixer * mix); + /*< private >*/ gpointer _padding[GST_PADDING]; }; diff --git a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.c b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.c index 39b592af0e..cdc130b394 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.c +++ b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.c @@ -466,9 +466,6 @@ gst_gl_mixer_class_init (GstGLMixerClass * klass) /* Register the pad class */ g_type_class_ref (GST_TYPE_GL_MIXER_PAD); - - gst_type_mark_as_plugin_api (GST_TYPE_GL_MIXER_PAD, 0); - gst_type_mark_as_plugin_api (GST_TYPE_GL_MIXER, 0); } static void @@ -673,6 +670,19 @@ context_error: } } +/** + * gst_gl_mixer_process_textures: + * @mix: the #GstGLMixer + * @outbuf: output @GstBuffer + * + * Perform processing required and call #GstGLMixerClass::process_textures(). + * Intended for use within implementations of + * #GstGLMixerClass::process_buffers(). + * + * Returns: whether processing of textures succeeded + * + * Since: 1.24 + */ gboolean gst_gl_mixer_process_textures (GstGLMixer * mix, GstBuffer * outbuf) { diff --git a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.h b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.h index 2c461e015c..42778413f3 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.h +++ b/subprojects/gst-plugins-base/gst-libs/gst/gl/gstglmixer.h @@ -46,17 +46,53 @@ typedef struct _GstGLMixerPrivate GstGLMixerPrivate; typedef struct _GstGLMixerPad GstGLMixerPad; typedef struct _GstGLMixerPadClass GstGLMixerPadClass; -/* all information needed for one video stream */ +/** + * GstGLMixerPad: + * + * Since: 1.24 + */ struct _GstGLMixerPad { + /** + * GstGLMixerPad.parent: + * + * parent #GstGLBaseMixerPad + * + * Since: 1.24 + */ GstGLBaseMixerPad parent; + /** + * GstGLMixerPad.current_texture: + * + * the current input texture for this pad + * + * Since: 1.24 + */ guint current_texture; + + /*< private >*/ + gpointer _padding[GST_PADDING]; }; +/** + * GstGLMixerPadClass: + * + * Since: 1.24 + */ struct _GstGLMixerPadClass { + /** + * GstGLMixerPadClass.parent_class: + * + * parent #GstGLBaseMixerPadClass + * + * Since: 1.24 + */ GstGLBaseMixerPadClass parent_class; + + /*< private >*/ + gpointer _padding[GST_PADDING]; }; G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstGLMixerPad, gst_object_unref); @@ -76,24 +112,71 @@ GType gst_gl_mixer_pad_get_type (void); #define GST_GL_MIXER_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_GL_MIXER,GstGLMixerClass)) -typedef gboolean (*GstGLMixerProcessFunc) (GstGLMixer *mix, GstBuffer *outbuf); -typedef gboolean (*GstGLMixerProcessTextures) (GstGLMixer *mix, GstGLMemory *out_tex); - +/** + * GstGLMixer: + * + * Since: 1.24 + */ struct _GstGLMixer { - GstGLBaseMixer vaggregator; + /** + * GstGLMixer.parent: + * + * Since: 1.24 + */ + GstGLBaseMixer parent; + /** + * GstGLMixer.out_caps: + * + * the configured output #GstCaps + * + * Since: 1.24 + */ GstCaps *out_caps; + /*< private >*/ GstGLMixerPrivate *priv; + + /*< private >*/ + gpointer _padding[GST_PADDING]; }; +/** + * GstGLMixerClass: + * + * Since: 1.24 + */ struct _GstGLMixerClass { + /** + * GstGLMixerClass.parent_class: + * + * Since: 1.24 + */ GstGLBaseMixerClass parent_class; - GstGLMixerProcessFunc process_buffers; - GstGLMixerProcessTextures process_textures; + /** + * GstGLMixerClass::process_buffers: + * + * Perform operations on the input buffers to produce an + * output buffer. + * + * Since: 1.24 + */ + gboolean (*process_buffers) (GstGLMixer * mix, GstBuffer *outbuf); + /** + * GstGLMixerClass::process_textures: + * + * perform operations with the input and output buffers mapped + * as textures. Will not be called if @process_buffers is overriden. + * + * Since: 1.24 + */ + gboolean (*process_textures) (GstGLMixer * mix, GstGLMemory *out_tex); + + /*< private >*/ + gpointer _padding[GST_PADDING]; }; G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstGLMixer, gst_object_unref);