manual: improve the controller docs a little more

Reword some sections. Explain value mappings better.

docs/manual/advanced-dparams.xml

@@ -5,86 +5,97 @@
     <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
+      properties over stream-time. Normally 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
+      to properties using control-bindings. Control-sources provide values for a
-      for a given timestamp. At run-time the elements continously pull values
+      given time-stamp that are usually in the range of 0.0 to 1.0. 
-      changes for the current stream-time. GStreamer includes a few different
+      Control-bindings map the control-value to a gobject property they are bound to
-      control-sources, but applications can define their own by subclassing.
+      - 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.
     </para>
     <para>
-      This subsystem is contained within the
+      Most parts of the controller mechanism is implemented in GstObject. Also the
+      base classes for control-sources and control-bindings are included in the core
+      library. The existing implementations are contained within the
       <filename>gstcontroller</filename> library.
       You need to include the header in your application's source file:
     </para>
     <programlisting>
 ...
 #include &lt;gst/gst.h&gt;
-#include &lt;gst/controller/gstcontroller.h&gt;
+#include &lt;gst/controller/gstinterpolationcontrolsource.h&gt;
+#include &lt;gst/controller/gstdirectcontrolbinding.h&gt;
 ...
     </programlisting>
     <para>
-      Your application should link to the shared library <filename>gstreamer-controller</filename>.
+      Your application should link to the shared library 
+      <filename>gstreamer-controller</filename>. One can get the required flag for
+      compiler and linker by using pkg-config for gstreamer-controller-1.0.
     </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 (&amp;argc, &amp;argv);
-  gst_controller_init (&amp;argc, &amp;argv);
-  ...
-    </programlisting>
   </sect1>
   
   <sect1 id="section-dparams-parameters">
     <title>Setting up parameter control</title>
     <para>
-      Create a control-source. Lets use an interpolation control-source:
+      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 control-source:
     </para>
     <programlisting>
   csource = gst_interpolation_control_source_new ();
   g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
     </programlisting>
     <para>
-      Now we need to assign the control-source to the gobject property. One
+      Now we need to attach the control-source to the gobject property. This is done
-      control source can only be assigned to one property.
+      with a control-binding. One control source can be attached to several object
+      properties (even in different objects) using separate control-bindings.
     </para>
     <programlisting>
       gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
     </programlisting>
     <para>
-      This control-source takes new property values from a list of time-stamped
+      This type control-source takes new property values from a list of time-stamped
-      parameter changes. The source can e.g. fill gaps by smoothing parameter
+      parameter changes. The source can e.g. fill gaps by smoothing parameter changes
-      changes. This behaviour can be configured by setting the 
+      This behavior can be configured by setting the mode property of the
-      interpolation-mode.
+      control-source. Other control sources e.g. produce a stream of values by
+      calling <function>sin()</function> function. They have parameters to control
+      e.g. the frequency. As control-sources are GstObjects too, one can attach
+      control-sources to these properties too.
     </para>
     <para>
-      Now we can set some control points. These are time-stamped GValues.
+      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 later mapped to the
+      maximum value in the target properties value range.
       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
+      the control-curve gets repeated as well.
-      different functions to specify the control-changes over time.
     </para>
     <programlisting>
-  gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1);
+  GstTimedValueControlSource *tv_csource = (GstTimedValueControlSource *)csource;
-  gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);
+  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);
     </programlisting>
     <para>
-      Now everything is ready to play. One final note - the controller subsystem
+      Now everything is ready to play. If the control-source is e.g. bound to a
-      has a builtin live-mode. Even though a property has a control-source
+      volume property, we will head a fade-in over 1 second. One word of caution,
-      assigned one can change the GObject property through the 
+      the volume element that comes with gstreamer has a value range of 0.0 to 4.0
-      <function>g_object_set()</function>.
+      on its volume property. If the above control-source is attached to the property
+      the volume will ramp up to 400%!
+    </para>
+    <para>
+      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 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
+      value overrides it. This also works with smoothed parameters. It does not
-      work for control-sources that constantly update the property (e.g. the lfo
+      work for control-sources that constantly update the property (e.g. the
-      control-source).
+      lfo_control_source).
     </para>
   </sect1>