more docs for the state of dparams

Original commit message from CVS:
more docs for the state of dparams

ChangeLog

@@ -1,3 +1,13 @@
+2005-02-22  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/libs/tmpl/gstcontrol.sgml:
+	* docs/libs/tmpl/gstdparam.sgml:
+	* docs/libs/tmpl/gstdplinint.sgml:
+	* docs/libs/tmpl/gstdpman.sgml:
+	* docs/libs/tmpl/gstdpsmooth.sgml:
+	* docs/libs/tmpl/gstunitconvert.sgml:
+    more docs for the state of dparams
+
 2005-02-19  Benjamin Otte  <in7y118@public.uni-hamburg.de>
 
 	* gst/gstelementfactory.c: (gst_element_factory_create):

docs/libs/tmpl/gstcontrol.sgml

@@ -6,15 +6,25 @@ dynamic parameter functionality.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-This library provides a Manager that maintains a list of dynamically
-controlable parameters for a GstElement.
+This library provides a manager component (#GstDParamManager) that maintains a
+list of dynamically controlable parameters for a #GstElement.
 Just think of a volume slider in a mixer.
 </para>
 
 <para>
-To use this library one needs to add some code to initialize it.
+#GstElement instances wanting to provide dynamic parameters, need to provide
+a #GParamSpec and an update method. The application that will later use the
+control parameter, will create a #DParam instance and attach that to use
+provided #GParamSpec and update method.
+The control library provides several #DParam implementations that can be used
+interchangably. The base on just updated the parameter, while others can smooth
+the control changes.
+</para>
+
+<para>
+To use this library in a application one needs to add some code to initialize it.
 <example>
-<title>Adding the control library to a project</title>
+<title>Adding the control library to an application (step 1)</title>
 <programlisting>
 ...
 &hash;include &lt;gst/gst.h&gt;
@@ -25,7 +35,37 @@ gst_control_init(&amp;argc,&amp;argv);
 ...
 </programlisting>
 </example>
-The next step is to get hold of the GstDParamManager instance of a GstElement.
+</para>
+<para>
+The next step is to get hold of the #GstDParamManager instance of a #GstElement
+and set the working mode of the manager.
+<example>
+<title>Adding the control library to an application (step 2)</title>
+<programlisting>
+dparam_manager=gst_dpman_get_manager(element);
+gst_dpman_set_mode(dparam_manager, "synchronous");
+</programlisting>
+</example>
+</para>
+
+<para>
+Finally one need to attach a new #DParam to the paramter spec.
+<example>
+<title>Adding the control library to an application (step 3)</title>
+<programlisting>
+pspec=gst_dpman_get_param_spec(dparam_manager,"volume");
+dparam=gst_dparam_new(G_PARAM_SPEC_VALUE_TYPE(pspec));
+gst_dpman_attach_dparam(dparam_manager,g_param_spec_get_name(pspecs),dparam);
+</programlisting>
+</example>
+For a full example look at the <file>gst-plugins/gst/sine/demo-dparams.c</file>
+</para>
+<para>
+To add dparam support to a plugin look at <file>gst-plugins/gst/sine/gstsinesrc.c</file>
+or <file>gst-plugins/gst/volume/gstvolume.c</file>.
+The key concept is to call GST_DPMAN_PREPROCESS() before processing data and to
+wrap the data processing (chain or loop function) by GST_DPMAN_PROCESS().
+This allows the manager to interupt processing to apply new control values.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -33,6 +73,9 @@ The next step is to get hold of the GstDParamManager instance of a GstElement.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### FUNCTION gst_control_init ##### -->
 <para>
 

docs/libs/tmpl/gstdataprotocol.sgml

@@ -27,6 +27,9 @@ network connections also need a protocol to do this.
 #GstBuffer, #GstCaps, #GstEvent
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### ENUM GstDPHeaderFlag ##### -->
 <para>
 

docs/libs/tmpl/gstdparam.sgml

@@ -6,7 +6,8 @@ dynamic parameter instance
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This base class for dynamic parameters will update parameters as they are.
+Subclasses of this do more advanced updates like smoothing parameter changes.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -14,6 +15,9 @@ dynamic parameter instance
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GstDParam ##### -->
 <para>
 

docs/libs/tmpl/gstdplinint.sgml

@@ -14,6 +14,9 @@ linear interpolation dynamic parameter
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GstDParamLinInterp ##### -->
 <para>
 

docs/libs/tmpl/gstdpman.sgml

@@ -6,7 +6,7 @@ dynamic parameter manager
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The manager bings all functions to work with #GstElements and their #GstDParams.
+The manager provides a set of functions to work with #GstElements and their #GstDParams.
 One can find out which dparams an element has, get the parameter specs and
 pick a control change rate.
 </para>
@@ -20,6 +20,9 @@ are for applications that use elements with dparams.
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GstDParamManager ##### -->
 <para>
 

docs/libs/tmpl/gstdpsmooth.sgml

@@ -14,6 +14,9 @@ realtime smoothed dynamic parameter
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GstDParamSmooth ##### -->
 <para>