| <chapter id="chapter-dparams"> |
| <title>Dynamic Controllable Parameters</title> |
| |
| <sect1 id="section-dparams-getting-started"> |
| <title>Getting Started</title> |
| <para> |
| The controller subsystem offers a lightweight way to adjust gobject |
| properties over stream-time. Normaly these properties are changed using |
| <function>g_object_set()</function>. Timing those calls reliably so that |
| the changes affect certain stream times is close to impossible. The |
| controller takes time into account. It works by attaching control-sources |
| to properties. Control-sources can provide new values for the properties |
| for a given timestamp. At run-time the elements continously pull values |
| changes for the current stream-time. GStreamer includes a few different |
| control-sources, but applications can define their own by subclassing. |
| </para> |
| <para> |
| This subsystem is contained within the |
| <filename>gstcontroller</filename> library. |
| You need to include the header in your application's source file: |
| </para> |
| <programlisting> |
| ... |
| #include <gst/gst.h> |
| #include <gst/controller/gstcontroller.h> |
| ... |
| </programlisting> |
| <para> |
| Your application should link to the shared library <filename>gstreamer-controller</filename>. |
| </para> |
| <para> |
| The <filename>gstreamer-controller</filename> library needs to be initialized |
| when your application is run. This can be done after the GStreamer |
| library has been initialized. |
| </para> |
| <programlisting> |
| ... |
| gst_init (&argc, &argv); |
| gst_controller_init (&argc, &argv); |
| ... |
| </programlisting> |
| </sect1> |
| |
| <sect1 id="section-dparams-parameters"> |
| <title>Setting up parameter control</title> |
| <para> |
| The first step is to select the parameters that should be controlled. |
| This returns a controller object that is needed to further adjust the |
| behaviour. |
| </para> |
| <programlisting> |
| controller = gst_object_control_properties(object, "prop1", "prop2",...); |
| </programlisting> |
| <para> |
| Next we attach a control-source to each parameter. Lets use an |
| interpolation control-source: |
| </para> |
| <programlisting> |
| csource = gst_interpolation_control_source_new (); |
| gst_interpolation_control_source_set_interpolation_mode(csource, GST_INTERPOLATE_LINEAR); |
| </programlisting> |
| <para> |
| Now we need to assign the control-source to the gobject property. One |
| control source can only be assigned to one property. |
| </para> |
| <programlisting> |
| gst_controller_set_control_source (controller, "prop1", csource); |
| </programlisting> |
| <para> |
| This control-source takes new property values from a list of time-stamped |
| parameter changes. The source can e.g. fill gaps by smoothing parameter |
| changes. This behaviour can be configured by setting the |
| interpolation-mode. |
| </para> |
| <para> |
| Now we can set some control points. These are time-stamped GValues. |
| 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), |
| the control-curve gets repeated as well. Other control-sources have |
| different functions to specify the control-changes over time. |
| </para> |
| <programlisting> |
| gst_interpolation_control_source_set (csource, 0 * GST_SECOND, value1); |
| gst_interpolation_control_source_set (csource, 1 * GST_SECOND, value2); |
| </programlisting> |
| <para> |
| Now everything is ready to play. One final note - the controller subsystem |
| has a builtin live-mode. Even though a property has a control-source |
| assigned one can change the GObject property through the |
| <function>g_object_set()</function>. |
| This is highly useful when binding the GObject properties to GUI widgets. |
| When the user adjusts the value with the widget, one can set the GObject |
| property and this remains active until the next programmed control-source |
| value overrides it. This also works with smoothed parameters. It might not |
| work for control-sources that constantly update the property (e.g. the lfo |
| control-source). |
| </para> |
| </sect1> |
| |
| </chapter> |