mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-08 13:18:52 +00:00
Original commit message from CVS: put back old manual structure before integrating ronald's changes
198 lines
9 KiB
XML
198 lines
9 KiB
XML
<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 <gst/gst.h>
|
|
#include <gst/control/control.h>
|
|
...
|
|
</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(&argc,&argv);
|
|
gst_control_init(&argc,&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_DOUBLE);
|
|
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_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(&mem, 0, sizeof(mem))
|
|
...
|
|
|
|
gdouble set_to_value;
|
|
GstDParam *volume;
|
|
GValue set_val;
|
|
ZERO(set_val);
|
|
g_value_init(&set_val, G_TYPE_DOUBLE);
|
|
...
|
|
g_value_set_double(&set_val, set_to_value);
|
|
g_object_set_property(G_OBJECT(volume), "value_double", &set_val);
|
|
</programlisting>
|
|
<para>Or if you create an actual GValue instance:</para>
|
|
<programlisting>
|
|
gdouble set_to_value;
|
|
GstDParam *volume;
|
|
GValue *set_val;
|
|
set_val = g_new0(GValue,1);
|
|
g_value_init(set_val, G_TYPE_DOUBLE);
|
|
...
|
|
g_value_set_double(set_val, set_to_value);
|
|
g_object_set_property(G_OBJECT(volume), "value_double", 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_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>
|
|
<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 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>
|
|
<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_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>
|
|
</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>
|