mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-22 16:26:39 +00:00
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)
This commit is contained in:
David Schleef
parent
2ec9dab401
commit
365e52cce4
3 changed files with 24 additions and 205 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <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_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(&mem, 0, sizeof(mem))
|
||||
...
|
||||
|
||||
gfloat set_to_value;
|
||||
GstDParam *volume;
|
||||
GValue set_val;
|
||||
ZERO(set_val);
|
||||
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>
|
||||
<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>
|
||||
|
|
@ -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(&mem, 0, sizeof(mem))
|
||||
...
|
||||
|
||||
gfloat set_to_value;
|
||||
gdouble set_to_value;
|
||||
GstDParam *volume;
|
||||
GValue set_val;
|
||||
ZERO(set_val);
|
||||
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>
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue