docs/manual/dparams-app.xml: Fix to handle double dparams. (bug #134863)

Original commit message from CVS:
* docs/manual/dparams-app.xml:  Fix to handle double dparams.
(bug #134863)

diff --git a/ChangeLog b/ChangeLog
index e529406..a99fd0c 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2004-03-09  David Schleef  <ds@schleef.org>
+
+       * docs/manual/dparams-app.xml:  Fix to handle double dparams.
+       (bug #134863)
+
 2004-03-09  Thomas Vander Stichele  <thomas at apestaart dot org>
 
        * configure.ac: first bug fix due to major/minor bump

diff --git a/docs/manual/advanced-dparams.xml b/docs/manual/advanced-dparams.xml
deleted file mode 100644 (file)
index d7b1b3e..0000000
--- a/docs/manual/advanced-dparams.xml
+++ /dev/null
@@ -1,192 +0,0 @@
-<chapter id="chapter-dparams">
-  <title>Dynamic Parameters</title>
-  
-  <sect1 id="section-dparams-getting-started">
-    <title>Getting Started</title>
-    <para>
-      The Dynamic Parameters subsystem is contained within the
-      <filename>gstcontrol</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/control/control.h&gt;
-...
-    </programlisting>
-    <para>
-      Your application should link to the shared library <filename>gstcontrol</filename>.
-    </para>
-    <para>
-      The <filename>gstcontrol</filename> library needs to be initialized
-      when your application is run.  This can be done after the the GStreamer
-      library has been initialized.
-    </para>
-    <programlisting>
-  ...
-  gst_init(&amp;argc,&amp;argv);
-  gst_control_init(&amp;argc,&amp;argv);
-  ...
-    </programlisting>
-  </sect1>
-
-  <sect1 id="section-dparams-creating">
-    <title>Creating and Attaching Dynamic Parameters</title>
-    <para>
-      Once you have created your elements you can create and attach dparams to them.
-      First you need to get the element's dparams manager. If you know exactly what kind of element
-      you have, you may be able to get the dparams manager directly. However if this is not possible, 
-      you can get the dparams manager by calling <filename>gst_dpman_get_manager</filename>.
-    </para>
-    <para>
-      Once you have the dparams manager, you must set the mode that the manager will run in.
-      There is currently only one mode implemented called <filename>"synchronous"</filename> - this is used for real-time
-      applications where the dparam value cannot be known ahead of time (such as a slider in a GUI).
-      The mode is called <filename>"synchronous"</filename> because the dparams are polled by the element for changes before
-      each buffer is processed.  Another yet-to-be-implemented mode is <filename>"asynchronous"</filename>.  This is used when
-      parameter changes are known ahead of time - such as with a timelined editor.  The mode is called 
-      <filename>"asynchronous"</filename> because parameter changes may happen in the middle of a buffer being processed.
-    </para>
-    <programlisting>
-  GstElement *sinesrc;
-  GstDParamManager *dpman;
-  ...
-  sinesrc = gst_element_factory_make("sinesrc","sine-source");
-  ...
-  dpman = gst_dpman_get_manager (sinesrc);
-  gst_dpman_set_mode(dpman, "synchronous");
-    </programlisting>
-    <para>
-      If you don't know the names of the required dparams for your element you can call 
-      <filename>gst_dpman_list_dparam_specs(dpman)</filename> to get a NULL terminated array of param specs.
-      This array should be freed after use.  You can find the name of the required dparam by calling
-      <filename>g_param_spec_get_name</filename> on each param spec in the array. In our example, 
-      <filename>"volume"</filename> will be the name of our required dparam.
-    </para>
-    <para>
-      Each type of dparam currently has its own <filename>new</filename> function. This may eventually
-      be replaced by a factory method for creating new instances.  A default dparam instance can be created
-      with the <filename>gst_dparam_new</filename> function. Once it is created it can be attached to a 
-      required dparam in the element.
-    </para>
-    <programlisting>
-  GstDParam *volume;
-  ...
-  volume = gst_dparam_new(G_TYPE_FLOAT);
-  if (gst_dpman_attach_dparam (dpman, "volume", volume)){
-    /* the dparam was successfully attached */
-    ...
-  }
-    </programlisting>
-  </sect1>
-
-  <sect1 id="section-dparams-changing">
-    <title>Changing Dynamic Parameter Values</title>
-    <para>
-      All interaction with dparams to actually set the dparam value is done through simple GObject properties.
-      There is a property value for each type that dparams supports - these currently being 
-      <filename>"value_float"</filename>, <filename>"value_int"</filename> and <filename>"value_int64"</filename>.
-      To set the value of a dparam, simply set the property which matches the type of your dparam instance.
-    </para>
-    <programlisting>
-#define ZERO(mem) memset(&amp;mem, 0, sizeof(mem))
-...
-
-  gfloat set_to_value;
-  GstDParam *volume;
-  GValue set_val;
-  ZERO(set_val);
-  g_value_init(&amp;set_val, G_TYPE_FLOAT);
-  ...
-  g_value_set_float(&amp;set_val, set_to_value);
-  g_object_set_property(G_OBJECT(volume), "value_float", &amp;set_val);
-    </programlisting>
-    <para>Or if you create an actual GValue instance:</para>
-    <programlisting>
-  gfloat set_to_value;
-  GstDParam *volume;
-  GValue *set_val;
-  set_val = g_new0(GValue,1);
-  g_value_init(set_val, G_TYPE_FLOAT);
-  ...
-  g_value_set_float(set_val, set_to_value);
-  g_object_set_property(G_OBJECT(volume), "value_float", set_val);
-    </programlisting>
-
-  </sect1>
-
-  <sect1 id="section-dparams-types">
-    <title>Different Types of Dynamic Parameter</title>
-    <para>
-      There are currently only two implementations of dparams so far.  They are both for real-time use so 
-      should be run in the <filename>"synchronous"</filename> mode.
-    </para>
-    <sect2>
-      <title>GstDParam - the base dparam type</title>
-      <para>
-        All dparam implementations will subclass from this type.  It provides a basic implementation which simply 
-        propagates any value changes as soon as it can.  
-        A new instance can be created with the function <filename>GstDParam* gst_dparam_new (GType type)</filename>.
-        It has the following object properties:
-      </para>
-      <itemizedlist>
-        <listitem><para><filename>"value_float"</filename>
-          - the property to set and get if it is a float dparam
-        </para></listitem>
-        <listitem><para><filename>"value_int"</filename>
-          - the property to set and get if it is an integer dparam
-        </para></listitem>
-        <listitem><para><filename>"value_int64"</filename>
-          - the property to set and get if it is a 64 bit integer dparam
-        </para></listitem>
-        <listitem><para><filename>"is_log"</filename>
-          - readonly boolean which is TRUE if the param should be displayed on a log scale
-        </para></listitem>
-        <listitem><para><filename>"is_rate"</filename>
-          - readonly boolean which is TRUE if the value is a proportion of the sample rate.  
-          For example with a sample rate of 44100, 0.5 would be 22050 Hz and 0.25 would be 11025 Hz.
-        </para></listitem>
-      </itemizedlist>
-    </sect2>
-    <sect2>
-      <title>GstDParamSmooth - smoothing real-time dparam</title>
-      <para>
-        Some parameter changes can create audible artifacts if they change too rapidly.  The GstDParamSmooth
-        implementation can greatly reduce these artifacts by limiting the rate at which the value can change.
-        This is currently only supported for float dparams - the other types fall back to the default implementation.
-        A new instance can be created with the function <filename>GstDParam* gst_dpsmooth_new (GType type)</filename>.
-        It has the following object properties:
-      </para>
-      <itemizedlist>
-        <listitem><para><filename>"update_period"</filename>
-          - an int64 value specifying the number nanoseconds between updates. This will be ignored in 
-          <filename>"synchronous"</filename> mode since the buffer size dictates the update period.
-        </para></listitem>
-        <listitem><para><filename>"slope_time"</filename>
-          - an int64 value specifying the time period to use in the maximum slope calculation
-        </para></listitem>
-        <listitem><para><filename>"slope_delta_float"</filename>
-          - a float specifying the amount a float value can change in the given slope_time.
-        </para></listitem>
-      </itemizedlist>
-      <para>
-        Audible artifacts may not be completely eliminated by using this dparam. The only way to eliminate
-        artifacts such as "zipper noise" would be for the element to implement its required dparams using the 
-        array method. This would allow dparams to change parameters at the sample rate which should eliminate
-        any artifacts.
-      </para>
-      
-    </sect2>
-    <sect2>
-      <title>Timelined dparams</title>
-      <para>
-        A yet-to-be-implemented subclass of GstDParam will add an API which allows the creation and manipulation
-        of points on a timeline.  This subclass will also provide a dparam implementation which uses linear
-        interpolation between these points to find the dparam value at any given time.  Further subclasses can 
-        extend this functionality to implement more exotic interpolation algorithms such as splines.
-      </para>
-    </sect2>
-  </sect1>
-  
-</chapter>

diff --git a/docs/manual/dparams-app.xml b/docs/manual/dparams-app.xml
index d7b1b3e..b0f9d71 100644 (file)
--- a/docs/manual/dparams-app.xml
+++ b/docs/manual/dparams-app.xml
@@ -73,7 +73,7 @@
     <programlisting>
   GstDParam *volume;
   ...
-  volume = gst_dparam_new(G_TYPE_FLOAT);
+  volume = gst_dparam_new(G_TYPE_DOUBLE);
   if (gst_dpman_attach_dparam (dpman, "volume", volume)){
     /* the dparam was successfully attached */
     ...
@@ -86,32 +86,32 @@
     <para>
       All interaction with dparams to actually set the dparam value is done through simple GObject properties.
       There is a property value for each type that dparams supports - these currently being 
-      <filename>"value_float"</filename>, <filename>"value_int"</filename> and <filename>"value_int64"</filename>.
+      <filename>"value_double"</filename>, <filename>"value_float"</filename>, <filename>"value_int"</filename> and <filename>"value_int64"</filename>.
       To set the value of a dparam, simply set the property which matches the type of your dparam instance.
     </para>
     <programlisting>
 #define ZERO(mem) memset(&amp;mem, 0, sizeof(mem))
 ...
 
-  gfloat set_to_value;
+  gdouble set_to_value;
   GstDParam *volume;
   GValue set_val;
   ZERO(set_val);
-  g_value_init(&amp;set_val, G_TYPE_FLOAT);
+  g_value_init(&amp;set_val, G_TYPE_DOUBLE);
   ...
-  g_value_set_float(&amp;set_val, set_to_value);
-  g_object_set_property(G_OBJECT(volume), "value_float", &amp;set_val);
+  g_value_set_double(&amp;set_val, set_to_value);
+  g_object_set_property(G_OBJECT(volume), "value_double", &amp;set_val);
     </programlisting>
     <para>Or if you create an actual GValue instance:</para>
     <programlisting>
-  gfloat set_to_value;
+  gdouble set_to_value;
   GstDParam *volume;
   GValue *set_val;
   set_val = g_new0(GValue,1);
-  g_value_init(set_val, G_TYPE_FLOAT);
+  g_value_init(set_val, G_TYPE_DOUBLE);
   ...
-  g_value_set_float(set_val, set_to_value);
-  g_object_set_property(G_OBJECT(volume), "value_float", set_val);
+  g_value_set_double(set_val, set_to_value);
+  g_object_set_property(G_OBJECT(volume), "value_double", set_val);
     </programlisting>
 
   </sect1>
@@ -131,6 +131,9 @@
         It has the following object properties:
       </para>
       <itemizedlist>
+        <listitem><para><filename>"value_double"</filename>
+          - the property to set and get if it is a double dparam
+        </para></listitem>
         <listitem><para><filename>"value_float"</filename>
           - the property to set and get if it is a float dparam
         </para></listitem>
@@ -154,7 +157,7 @@
       <para>
         Some parameter changes can create audible artifacts if they change too rapidly.  The GstDParamSmooth
         implementation can greatly reduce these artifacts by limiting the rate at which the value can change.
-        This is currently only supported for float dparams - the other types fall back to the default implementation.
+        This is currently only supported for double and float dparams - the other types fall back to the default implementation.
         A new instance can be created with the function <filename>GstDParam* gst_dpsmooth_new (GType type)</filename>.
         It has the following object properties:
       </para>
@@ -166,6 +169,9 @@
         <listitem><para><filename>"slope_time"</filename>
           - an int64 value specifying the time period to use in the maximum slope calculation
         </para></listitem>
+        <listitem><para><filename>"slope_delta_double"</filename>
+          - a double specifying the amount a double value can change in the given slope_time.
+        </para></listitem>
         <listitem><para><filename>"slope_delta_float"</filename>
           - a float specifying the amount a float value can change in the given slope_time.
         </para></listitem>
@@ -182,8 +188,8 @@
       <title>Timelined dparams</title>
       <para>
         A yet-to-be-implemented subclass of GstDParam will add an API which allows the creation and manipulation
-        of points on a timeline.  This subclass will also provide a dparam implementation which uses linear
-        interpolation between these points to find the dparam value at any given time.  Further subclasses can 
+        of points on a timeline. This subclass will also provide a dparam implementation which uses linear
+        interpolation between these points to find the dparam value at any given time. Further subclasses can 
         extend this functionality to implement more exotic interpolation algorithms such as splines.
       </para>
     </sect2>