From 6d292c86e9501f142ac0c430255a8879b7c91b32 Mon Sep 17 00:00:00 2001 From: Jan Schmidt Date: Tue, 5 Nov 2019 01:40:10 +1100 Subject: [PATCH] switchbin: Add docs Add documentation clauses and enrol switchbin to generate plugin docs --- docs/plugins/gst_plugins_cache.json | 76 +++++++++++++++++++++++++++++++++++++ gst/switchbin/gstswitchbin.c | 49 ++++++++++++++++++++++-- 2 files changed, 122 insertions(+), 3 deletions(-) diff --git a/docs/plugins/gst_plugins_cache.json b/docs/plugins/gst_plugins_cache.json index 7d08a10..f1bd410 100644 --- a/docs/plugins/gst_plugins_cache.json +++ b/docs/plugins/gst_plugins_cache.json @@ -46771,6 +46771,82 @@ "tracers": {}, "url": "Unknown package origin" }, + "switchbin": { + "description": "switchbin", + "elements": { + "switchbin": { + "author": "Carlos Rafael Giani ", + "description": "Switch between sub-pipelines (paths) based on input caps", + "hierarchy": [ + "GstSwitchBin", + "GstBin", + "GstElement", + "GstObject", + "GInitiallyUnowned", + "GObject" + ], + "klass": "Generic/Bin", + "long-name": "switchbin", + "pad-templates": { + "sink": { + "caps": "ANY", + "direction": "sink", + "presence": "always" + }, + "src": { + "caps": "ANY", + "direction": "src", + "presence": "always" + } + }, + "properties": { + "async-handling": { + "blurb": "The bin will handle Asynchronous state changes", + "construct": false, + "construct-only": false, + "default": "false", + "type-name": "gboolean", + "writable": true + }, + "current-path": { + "blurb": "Currently selected path", + "construct": false, + "construct-only": false, + "default": "-1", + "max": "-1", + "min": "0", + "type-name": "guint", + "writable": false + }, + "message-forward": { + "blurb": "Forwards all children messages", + "construct": false, + "construct-only": false, + "default": "false", + "type-name": "gboolean", + "writable": true + }, + "num-paths": { + "blurb": "Number of paths", + "construct": false, + "construct-only": false, + "default": "0", + "max": "-2", + "min": "0", + "type-name": "guint", + "writable": true + } + }, + "rank": "none" + } + }, + "filename": "gstswitchbin", + "license": "LGPL", + "package": "GStreamer Bad Plug-ins git", + "source": "gst-plugins-bad", + "tracers": {}, + "url": "Unknown package origin" + }, "teletext": { "description": "Teletext plugin", "elements": { diff --git a/gst/switchbin/gstswitchbin.c b/gst/switchbin/gstswitchbin.c index ef160f2..18f5fc6 100644 --- a/gst/switchbin/gstswitchbin.c +++ b/gst/switchbin/gstswitchbin.c @@ -19,6 +19,44 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:element-switchbin + * @title: switchbin + * + * switchbin is a helper element which chooses between a set of + * processing chains (paths) based on input caps, and changes if new caps + * arrive. Paths are child objects, which are accessed by the + * #GstChildProxy interface. + * + * Whenever new input caps are encountered at the switchbin's sinkpad, + * the * first path with matching caps is picked. The paths are looked at + * in order: path \#0's caps are looked at first, checked against the new + * input caps with gst_caps_can_intersect(), and if its return value + * is TRUE, path \#0 is picked. Otherwise, path \#1's caps are looked at etc. + * If no path matches, an error is reported. + * + * + * Example launch line + * + * In this example, if the data is raw PCM audio with 44.1 kHz, a volume + * element is used for reducing the audio volume to 10%. Otherwise, it is + * just passed through. So, a 44.1 kHz MP3 will sound quiet, a 48 kHz MP3 + * will be at full volume. + * + * |[ + * gst-launch-1.0 uridecodebin uri= ! switchbin num-paths=2 \ + * path0::element="audioconvert ! volume volume=0.1" path0::caps="audio/x-raw, rate=44100" \ + * path1::element="identity" path1::caps="ANY" ! \ + * autoaudiosink + * ]| + * + * This example's path \#1 is a fallback "catch-all" path. Its caps are "ANY" caps, + * so any input caps will match against this. A catch-all path with an identity element + * is useful for cases where certain kinds of processing should only be done for specific + * formats, like the example above (it applies volume only to 44.1 kHz PCM audio). + * + * + */ #include #include @@ -39,17 +77,14 @@ enum PROP_NUM_PATHS }; - #define DEFAULT_NUM_PATHS 0 - static GstStaticPadTemplate static_sink_template = GST_STATIC_PAD_TEMPLATE ("sink", GST_PAD_SINK, GST_PAD_ALWAYS, GST_STATIC_CAPS_ANY); - static GstStaticPadTemplate static_src_template = GST_STATIC_PAD_TEMPLATE ("src", GST_PAD_SRC, @@ -178,6 +213,14 @@ gst_switch_bin_class_init (GstSwitchBinClass * klass) object_class->set_property = GST_DEBUG_FUNCPTR (gst_switch_bin_set_property); object_class->get_property = GST_DEBUG_FUNCPTR (gst_switch_bin_get_property); + /** + * GstSwitchBin:num-paths + * + * Configure how many paths the switchbin will be choosing between. Attempting + * to configure a path outside the range 0..(n-1) will fail. Reducing the + * number of paths will release any paths outside the new range, which might + * trigger activation of a new path by re-assessing the current caps. + */ g_object_class_install_property (object_class, PROP_NUM_PATHS, g_param_spec_uint ("num-paths", -- 2.7.4