docs/manual/dparams-app.xml

   1 <chapter id="cha-dparams">
   2   <title>Dynamic Parameters</title>
   3
   4   <sect1>
   5     <title>Getting Started</title>
   6     <para>
   7       The Dynamic Parameters subsystem is contained within the
   8       <filename>gstcontrol</filename> library.
   9
  10       You need to include the header in your application's source file:
  11     </para>
  12     <programlisting>
  13 ...
  14 #include &lt;gst/gst.h&gt;
  15 #include &lt;gst/control/control.h&gt;
  16 ...
  17     </programlisting>
  18     <para>
  19       Your application should link to the shared library <filename>gstcontrol</filename>.
  20     </para>
  21     <para>
  22       The <filename>gstcontrol</filename> library needs to be initialized
  23       when your application is run.  This can be done after the the GStreamer
  24       library has been initialized.
  25     </para>
  26     <programlisting>
  27   ...
  28   gst_init(&amp;argc,&amp;argv);
  29   gst_control_init(&amp;argc,&amp;argv);
  30   ...
  31     </programlisting>
  32   </sect1>
  33
  34   <sect1>
  35     <title>Creating and Attaching Dynamic Parameters</title>
  36     <para>
  37       Once you have created your elements you can create and attach dparams to them.
  38       First you need to get the element's dparams manager. If you know exactly what kind of element
  39       you have, you may be able to get the dparams manager directly. However if this is not possible,
  40       you can get the dparams manager by calling <filename>gst_dpman_get_manager</filename>.
  41     </para>
  42     <para>
  43       Once you have the dparams manager, you must set the mode that the manager will run in.
  44       There is currently only one mode implemented called <filename>"synchronous"</filename> - this is used for real-time
  45       applications where the dparam value cannot be known ahead of time (such as a slider in a GUI).
  46       The mode is called <filename>"synchronous"</filename> because the dparams are polled by the element for changes before
  47       each buffer is processed.  Another yet-to-be-implemented mode is <filename>"asynchronous"</filename>.  This is used when
  48       parameter changes are known ahead of time - such as with a timelined editor.  The mode is called
  49       <filename>"asynchronous"</filename> because parameter changes may happen in the middle of a buffer being processed.
  50     </para>
  51     <programlisting>
  52   GstElement *sinesrc;
  53   GstDParamManager *dpman;
  54   ...
  55   sinesrc = gst_element_factory_make("sinesrc","sine-source");
  56   ...
  57   dpman = gst_dpman_get_manager (sinesrc);
  58   gst_dpman_set_mode(dpman, "synchronous");
  59     </programlisting>
  60     <para>
  61       If you don't know the names of the required dparams for your element you can call
  62       <filename>gst_dpman_list_dparam_specs(dpman)</filename> to get a NULL terminated array of param specs.
  63       This array should be freed after use.  You can find the name of the required dparam by calling
  64       <filename>g_param_spec_get_name</filename> on each param spec in the array. In our example,
  65       <filename>"volume"</filename> will be the name of our required dparam.
  66     </para>
  67     <para>
  68       Each type of dparam currently has its own <filename>new</filename> function. This may eventually
  69       be replaced by a factory method for creating new instances.  A default dparam instance can be created
  70       with the <filename>gst_dparam_new</filename> function. Once it is created it can be attached to a
  71       required dparam in the element.
  72     </para>
  73     <programlisting>
  74   GstDParam *volume;
  75   ...
  76   volume = gst_dparam_new(G_TYPE_FLOAT);
  77   if (gst_dpman_attach_dparam (dpman, "volume", volume)){
  78     /* the dparam was successfully attached */
  79     ...
  80   }
  81     </programlisting>
  82   </sect1>
  83
  84   <sect1>
  85     <title>Changing Dynamic Parameter Values</title>
  86     <para>
  87       All interaction with dparams to actually set the dparam value is done through simple GObject properties.
  88       There is a property value for each type that dparams supports - these currently being
  89       <filename>"value_float"</filename>, <filename>"value_int"</filename> and <filename>"value_int64"</filename>.
  90       To set the value of a dparam, simply set the property which matches the type of your dparam instance.
  91     </para>
  92     <programlisting>
  93 #define ZERO(mem) memset(&amp;mem, 0, sizeof(mem))
  94 ...
  95
  96   gfloat set_to_value;
  97   GstDParam *volume;
  98   GValue set_val;
  99   ZERO(set_val);
 100   g_value_init(&amp;set_val, G_TYPE_FLOAT);
 101   ...
 102   g_value_set_float(&amp;set_val, set_to_value);
 103   g_object_set_property(G_OBJECT(volume), "value_float", &amp;set_val);
 104     </programlisting>
 105     <para>Or if you create an actual GValue instance:</para>
 106     <programlisting>
 107   gfloat set_to_value;
 108   GstDParam *volume;
 109   GValue *set_val;
 110   set_val = g_new0(GValue,1);
 111   g_value_init(set_val, G_TYPE_FLOAT);
 112   ...
 113   g_value_set_float(set_val, set_to_value);
 114   g_object_set_property(G_OBJECT(volume), "value_float", set_val);
 115     </programlisting>
 116
 117   </sect1>
 118
 119   <sect1>
 120     <title>Different Types of Dynamic Parameter</title>
 121     <para>
 122       There are currently only two implementations of dparams so far.  They are both for real-time use so
 123       should be run in the <filename>"synchronous"</filename> mode.
 124     </para>
 125     <sect2>
 126       <title>GstDParam - the base dparam type</title>
 127       <para>
 128         All dparam implementations will subclass from this type.  It provides a basic implementation which simply
 129         propagates any value changes as soon as it can.
 130         A new instance can be created with the function <filename>GstDParam* gst_dparam_new (GType type)</filename>.
 131         It has the following object properties:
 132       </para>
 133       <itemizedlist>
 134         <listitem><para><filename>"value_float"</filename>
 135           - the property to set and get if it is a float dparam
 136         </para></listitem>
 137         <listitem><para><filename>"value_int"</filename>
 138           - the property to set and get if it is an integer dparam
 139         </para></listitem>
 140         <listitem><para><filename>"value_int64"</filename>
 141           - the property to set and get if it is a 64 bit integer dparam
 142         </para></listitem>
 143         <listitem><para><filename>"is_log"</filename>
 144           - readonly boolean which is TRUE if the param should be displayed on a log scale
 145         </para></listitem>
 146         <listitem><para><filename>"is_rate"</filename>
 147           - readonly boolean which is TRUE if the value is a proportion of the sample rate.
 148           For example with a sample rate of 44100, 0.5 would be 22050 Hz and 0.25 would be 11025 Hz.
 149         </para></listitem>
 150       </itemizedlist>
 151     </sect2>
 152     <sect2>
 153       <title>GstDParamSmooth - smoothing real-time dparam</title>
 154       <para>
 155         Some parameter changes can create audible artifacts if they change too rapidly.  The GstDParamSmooth
 156         implementation can greatly reduce these artifacts by limiting the rate at which the value can change.
 157         This is currently only supported for float dparams - the other types fall back to the default implementation.
 158         A new instance can be created with the function <filename>GstDParam* gst_dpsmooth_new (GType type)</filename>.
 159         It has the following object properties:
 160       </para>
 161       <itemizedlist>
 162         <listitem><para><filename>"update_period"</filename>
 163           - an int64 value specifying the number nanoseconds between updates. This will be ignored in
 164           <filename>"synchronous"</filename> mode since the buffer size dictates the update period.
 165         </para></listitem>
 166         <listitem><para><filename>"slope_time"</filename>
 167           - an int64 value specifying the time period to use in the maximum slope calculation
 168         </para></listitem>
 169         <listitem><para><filename>"slope_delta_float"</filename>
 170           - a float specifying the amount a float value can change in the given slope_time.
 171         </para></listitem>
 172       </itemizedlist>
 173       <para>
 174         Audible artifacts may not be completely eliminated by using this dparam. The only way to eliminate
 175         artifacts such as "zipper noise" would be for the element to implement its required dparams using the
 176         array method. This would allow dparams to change parameters at the sample rate which should eliminate
 177         any artifacts.
 178       </para>
 179
 180     </sect2>
 181     <sect2>
 182       <title>Timelined dparams</title>
 183       <para>
 184         A yet-to-be-implemented subclass of GstDParam will add an API which allows the creation and manipulation
 185         of points on a timeline.  This subclass will also provide a dparam implementation which uses linear
 186         interpolation between these points to find the dparam value at any given time.  Further subclasses can
 187         extend this functionality to implement more exotic interpolation algorithms such as splines.
 188       </para>
 189     </sect2>
 190   </sect1>
 191
 192 </chapter>