mobile/docs/manual/advanced-dparams.xml

   1 <chapter id="chapter-dparams">
   2   <title>Dynamic Controllable Parameters</title>
   3
   4   <sect1 id="section-dparams-getting-started">
   5     <title>Getting Started</title>
   6     <para>
   7       The controller subsystem offers a lightweight way to adjust gobject
   8       properties over stream-time. Normaly these properties are changed using
   9       <function>g_object_set()</function>. Timing those calls reliably so that
  10       the changes affect certain stream times is close to impossible. The
  11       controller takes time into account. It works by attaching control-sources
  12       to properties. Control-sources can provide new values for the properties
  13       for a given timestamp. At run-time the elements continously pull values
  14       changes for the current stream-time. GStreamer includes a few different
  15       control-sources, but applications can define their own by subclassing.
  16     </para>
  17     <para>
  18       This subsystem is contained within the
  19       <filename>gstcontroller</filename> library.
  20       You need to include the header in your application's source file:
  21     </para>
  22     <programlisting>
  23 ...
  24 #include &lt;gst/gst.h&gt;
  25 #include &lt;gst/controller/gstcontroller.h&gt;
  26 ...
  27     </programlisting>
  28     <para>
  29       Your application should link to the shared library <filename>gstreamer-controller</filename>.
  30     </para>
  31     <para>
  32       The <filename>gstreamer-controller</filename> library needs to be initialized
  33       when your application is run.  This can be done after the GStreamer
  34       library has been initialized.
  35     </para>
  36     <programlisting>
  37   ...
  38   gst_init (&amp;argc, &amp;argv);
  39   gst_controller_init (&amp;argc, &amp;argv);
  40   ...
  41     </programlisting>
  42   </sect1>
  43
  44   <sect1 id="section-dparams-parameters">
  45     <title>Setting up parameter control</title>
  46     <para>
  47       The first step is to select the parameters that should be controlled.
  48       This returns a controller object that is needed to further adjust the
  49       behaviour.
  50     </para>
  51     <programlisting>
  52   controller = gst_object_control_properties(object, "prop1", "prop2",...);
  53     </programlisting>
  54     <para>
  55       Next we attach a control-source to each parameter. Lets use an
  56       interpolation control-source:
  57     </para>
  58     <programlisting>
  59   csource = gst_interpolation_control_source_new ();
  60   gst_interpolation_control_source_set_interpolation_mode(csource, GST_INTERPOLATE_LINEAR);
  61     </programlisting>
  62     <para>
  63       Now we need to assign the control-source to the gobject property. One
  64       control source can only be assigned to one property.
  65     </para>
  66     <programlisting>
  67       gst_controller_set_control_source (controller, "prop1", csource);
  68     </programlisting>
  69     <para>
  70       This control-source takes new property values from a list of time-stamped
  71       parameter changes. The source can e.g. fill gaps by smoothing parameter
  72       changes. This behaviour can be configured by setting the
  73       interpolation-mode.
  74     </para>
  75     <para>
  76       Now we can set some control points. These are time-stamped GValues.
  77       The values become active when the timestamp is reached. They still stay
  78       in the list. If e.g. the pipeline runs a loop (using a segmented seek),
  79       the control-curve gets repeated as well. Other control-sources have
  80       different functions to specify the control-changes over time.
  81     </para>
  82     <programlisting>
  83   gst_interpolation_control_source_set (csource, 0 * GST_SECOND, value1);
  84   gst_interpolation_control_source_set (csource, 1 * GST_SECOND, value2);
  85     </programlisting>
  86     <para>
  87       Now everything is ready to play. One final note - the controller subsystem
  88       has a builtin live-mode. Even though a property has a control-source
  89       assigned one can change the GObject property through the
  90       <function>g_object_set()</function>.
  91       This is highly useful when binding the GObject properties to GUI widgets.
  92       When the user adjusts the value with the widget, one can set the GObject
  93       property and this remains active until the next programmed control-source
  94       value overrides it. This also works with smoothed parameters. It might not
  95       work for control-sources that constantly update the property (e.g. the lfo
  96       control-source).
  97     </para>
  98   </sect1>
  99
 100 </chapter>