mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-20 15:27:07 +00:00
Code Issues 1 Projects Releases Wiki Activity

application-development: dparams: improve content and formatting

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2017-09-11 11:48:27 -07:00
parent fd512524a7
commit 9903ac71e9
1 changed files with 54 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
markdown/application-development/advanced/dparams.md
View file

@ -6,96 +6,94 @@ title: Dynamic Controllable Parameters
## Getting Started ## Getting Started
The controller subsystem offers a lightweight way to adjust gobject GStreamer properties are normally set using `g_object_set()`, but timing these
properties over stream-time. Normally these properties are changed using calls reliably so that the changes affect certain stream times is close to
`g_object_set()`. Timing those calls reliably so that the changes affect impossible. The controller subsystem offers a lightweight way to adjust
certain stream times is close to impossible. The controller takes time `GObject` properties over stream-time.
into account. It works by attaching control-sources to properties using
control-bindings. Control-sources provide values for a given time-stamp
that are usually in the range of 0.0 to 1.0. Control-bindings map the
control-value to a gobject property they are bound to - converting the
type and scaling to the target property value range. At run-time the
elements continuously pull values changes for the current stream-time to
update the gobject properties. GStreamer includes a few different
control-sources and control-bindings already, but applications can
define their own by sub-classing from the respective base classes.
Most parts of the controller mechanism is implemented in GstObject. Also The controller takes time into account; it works by attaching
the base classes for control-sources and control-bindings are included `GstControlSource`s to properties using control-bindings. Control-sources
in the core library. The existing implementations are contained within provide values for a given time-stamp that are usually in the range of 0.0 to 1.0.
the `gstcontroller` library. You need to include the header in your Control-bindings map the control-value to the `GObject` property they are bound
application's source file: to, converting the type and scaling to the target property's value range. At
run-time the elements continuously pull value changes for the current
stream-time to update the `GObject` properties. GStreamer already includes a
few different `GstControlSource`s and control-bindings, but applications can
define their own by sub-classing the respective base classes.
Most parts of the controller mechanism are implemented in `GstObject`.
The base classes for `GstControlSource`s and control-bindings are also included
in the core library but the existing implementations are contained within
the `gstcontroller` library, so you need to include these headers in your
application's source file as needed:
``` c ``` c
...
#include <gst/gst.h> #include <gst/gst.h>
#include <gst/controller/gstinterpolationcontrolsource.h> #include <gst/controller/gstinterpolationcontrolsource.h>
#include <gst/controller/gstdirectcontrolbinding.h> #include <gst/controller/gstdirectcontrolbinding.h>
... ...
``` ```
Your application should link to the shared library Beyond including the proper headers, your application should link to the
`gstreamer-controller`. One can get the required flag for compiler and `gstreamer-controller` shared library. To get the required compiler and
linker by using pkg-config for gstreamer-controller-1.0. liker flags, you can use:
```
pkg-config --libs --cflags gstreamer-controller-1.0
```
## Setting up parameter control ## Setting up parameter control
If we have our pipeline set up and want to control some parameters, we If we have our pipeline set up and want to control some parameters, we
first need to create a control-source. Lets use an interpolation first need to create a `GstControlSource`. Lets use an interpolation
control-source: `GstControlSource`:
``` c ``` c
csource = gst_interpolation_control_source_new (); csource = gst_interpolation_control_source_new ();
g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
``` ```
Now we need to attach the control-source to the gobject property. This Now, we need to attach the `GstControlSource` to the gobject property. This
is done with a control-binding. One control source can be attached to is done with a control-binding. One control source can be attached to
several object properties (even in different objects) using separate several object properties (even in different objects) using separate
control-bindings. control-bindings.
``` c ``` c
gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
``` ```
This type control-source takes new property values from a list of This type `GstControlSource` takes new property values from a list of
time-stamped parameter changes. The source can e.g. fill gaps by time-stamped parameter changes. The source can e.g. fill gaps by
smoothing parameter changes This behavior can be configured by setting smoothing parameter changes. This behavior can be configured by setting
the mode property of the control-source. Other control sources e.g. the mode property of the `GstControlSource`. Other control sources e.g.
produce a stream of values by calling `sin()` function. They have produce a stream of values by calling `sin()` function. They have
parameters to control e.g. the frequency. As control-sources are parameters to control e.g. the frequency. As `GstControlSource`s are also
GstObjects too, one can attach control-sources to these properties too. `GstObject`s, one can attach `GstControlSource`s to these properties too.
Now we can set some control points. These are time-stamped gdouble Now we can set some control points. These are time-stamped gdouble
values and are usually in the range of 0.0 to 1.0. A value of 1.0 is values and are usually in the range of 0.0 to 1.0. A value of 1.0 is
later mapped to the maximum value in the target properties value range. later mapped to the maximum value in the target properties value range.
The values become active when the timestamp is reached. They still stay The values become active when the timestamp is reached. They still stay
in the list. If e.g. the pipeline runs a loop (using a segmented seek), in the list. If e.g. the pipeline runs a loop (using a segmented seek),
the control-curve gets repeated as the control-curve gets repeated as well.
well.
``` c ``` c
GstTimedValueControlSource *tv_csource = (GstTimedValueControlSource *)csource; GstTimedValueControlSource *tv_csource = (GstTimedValueControlSource *)csource;
gst_timed_value_control_source_set (tv_csource, 0 * GST_SECOND, 0.0); gst_timed_value_control_source_set (tv_csource, 0 * GST_SECOND, 0.0);
gst_timed_value_control_source_set (tv_csource, 1 * GST_SECOND, 1.0); gst_timed_value_control_source_set (tv_csource, 1 * GST_SECOND, 1.0);
``` ```
Now everything is ready to play. If the control-source is e.g. bound to Now everything is ready to play. If we bound the `GstControlSource` to a volume
a volume property, we will head a fade-in over 1 second. One word of property, we will hear a 1 second fade-in. One word of caution: GStreamer's
caution, the volume element that comes with gstreamer has a value range stock volume element has a `volume` property with a range from 0.0 to 4.0. If
of 0.0 to 4.0 on its volume property. If the above control-source is the above `GstControlSource` is attached to this property the volume will ramp
attached to the property the volume will ramp up to 400%\! up to 400%\!
One final note - the controller subsystem has a built-in live-mode. Even One final note: the controller subsystem has a built-in live-mode. Even
though a property has a control-source assigned one can change the though a property has a `GstControlSource` assigned one can set the
GObject property through the `g_object_set()`. This is highly useful `GObject` property with `g_object_set()`. This is highly useful when binding
when binding the GObject properties to GUI widgets. When the user the `GObject` properties to GUI widgets. When the user adjusts the value with
adjusts the value with the widget, one can set the GObject property and the widget, one can set the `GObject` property and this remains active until
this remains active until the next programmed control-source value the next programmed `GstControlSource` value overrides it. This also works with
overrides it. This also works with smoothed parameters. It does not work smoothed parameters but it does not work for `GstControlSource`s that constantly
for control-sources that constantly update the property (e.g. the update the property, like `GstLFOControlSource`.
lfo\_control\_source).