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.
   9     It works by using time-stamped value pairs that are queued for
  10     element-properties.
  11     At run-time the elements continously pull values changes for the
  12     current stream-time.
  13     </para>
  14     <para>
  15       This subsystem is contained within the
  16       <filename>gstcontroller</filename> library.
  17       You need to include the header in your application's source file:
  18     </para>
  19     <programlisting>
  20 ...
  21 #include &lt;gst/gst.h&gt;
  22 #include &lt;gst/controller/gstcontroller.h&gt;
  23 ...
  24     </programlisting>
  25     <para>
  26       Your application should link to the shared library <filename>gstreamer-controller</filename>.
  27     </para>
  28     <para>
  29       The <filename>gstreamer-controller</filename> library needs to be initialized
  30       when your application is run.  This can be done after the the GStreamer
  31       library has been initialized.
  32     </para>
  33     <programlisting>
  34   ...
  35   gst_init (&amp;argc, &amp;argv);
  36   gst_controller_init (&amp;argc, &amp;argv);
  37   ...
  38     </programlisting>
  39   </sect1>
  40
  41   <sect1 id="section-dparams-parameters">
  42     <title>Setting up parameter control</title>
  43     <para>
  44       The first step is to select the parameters that should be controlled.
  45       This returns a controller object that is needed to further adjust the
  46       behaviour.
  47     </para>
  48     <programlisting>
  49   controller = g_object_control_properties(object, "prop1", "prop2",...);
  50     </programlisting>
  51     <para>
  52       Next we can select an interpolation mode. This mode controls how inbetween
  53       values are determined.
  54       The controller subsystem can e.g. fill gaps by smoothing parameter changes.
  55       Each controllable GObject property can be
  56       interpolated differently.
  57     </para>
  58     <programlisting>
  59   gst_controller_set_interpolation_mode(controller,"prop1",mode);
  60     </programlisting>
  61     <para>
  62       Finally one needs to set control points. These are time-stamped GValues.
  63       The values become active when the timestamp is reached. They still stay
  64       in the list. If e.g. the pipeline runs a loop (using a segmented seek),
  65       the control-curve gets repeated as well.
  66     </para>
  67     <programlisting>
  68   gst_controller_set (controller, "prop1" ,0 * GST_SECOND, value1);
  69   gst_controller_set (controller, "prop1" ,1 * GST_SECOND, value2);
  70     </programlisting>
  71     <para>
  72       The controller subsystem has a builtin live-mode. Even though a parameter
  73       has timestamped control-values assigned one can change the GObject
  74       property through <function>g_object_set()</function>.
  75       This is highly useful when binding the GObject properties to GUI widgets.
  76       When the user adjusts the value with the widget, one can set the GOBject
  77       property and this remains active until the next timestamped value overrides.
  78       This also works with smoothed parameters.
  79     </para>
  80   </sect1>
  81
  82 </chapter>