more docs for the state of dparams

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

diff --git a/ChangeLog b/ChangeLog
index fa3dd71..0b6c152 100644 (file)
--- a/ChangeLog
+++ b/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):

diff --git a/docs/libs/tmpl/gstcontrol.sgml b/docs/libs/tmpl/gstcontrol.sgml
index afc9feb..f41c436 100644 (file)
--- a/docs/libs/tmpl/gstcontrol.sgml
+++ b/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>
 

diff --git a/docs/libs/tmpl/gstdataprotocol.sgml b/docs/libs/tmpl/gstdataprotocol.sgml
index 0cd1515..1bb87c8 100644 (file)
--- a/docs/libs/tmpl/gstdataprotocol.sgml
+++ b/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>
 

diff --git a/docs/libs/tmpl/gstdparam.sgml b/docs/libs/tmpl/gstdparam.sgml
index 349dbe5..7726db6 100644 (file)
--- a/docs/libs/tmpl/gstdparam.sgml
+++ b/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>
 

diff --git a/docs/libs/tmpl/gstdplinint.sgml b/docs/libs/tmpl/gstdplinint.sgml
index ca453e1..c76ea7d 100644 (file)
--- a/docs/libs/tmpl/gstdplinint.sgml
+++ b/docs/libs/tmpl/gstdplinint.sgml
@@ -14,6 +14,9 @@ linear interpolation dynamic parameter
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GstDParamLinInterp ##### -->
 <para>
 

diff --git a/docs/libs/tmpl/gstdpman.sgml b/docs/libs/tmpl/gstdpman.sgml
index b6a4d43..52ce531 100644 (file)
--- a/docs/libs/tmpl/gstdpman.sgml
+++ b/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>
 

diff --git a/docs/libs/tmpl/gstdpsmooth.sgml b/docs/libs/tmpl/gstdpsmooth.sgml
index bfd5e83..17dd2a5 100644 (file)
--- a/docs/libs/tmpl/gstdpsmooth.sgml
+++ b/docs/libs/tmpl/gstdpsmooth.sgml
@@ -14,6 +14,9 @@ realtime smoothed dynamic parameter
 
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
 <!-- ##### STRUCT GstDParamSmooth ##### -->
 <para>