gstreamer/docs/pwg/advanced-dparams.xml
Stefan Kost 523041b533 docs/: describe dparams (controller) for plugins unify docs a little more
Original commit message from CVS:
* docs/README:
* docs/manual/intro-basics.xml:
* docs/manual/intro-preface.xml:
* docs/manual/manual.xml:
* docs/pwg/advanced-dparams.xml:
* docs/pwg/intro-basics.xml:
* docs/pwg/intro-preface.xml:
* docs/pwg/pwg.xml:
describe dparams (controller) for plugins
unify docs a little more
2006-02-02 11:24:19 +00:00

105 lines
3.7 KiB
XML

<!-- ############ chapter ############# -->
<chapter id="chapter-dparams">
<title>Supporting Dynamic Parameters</title>
<para>
Sometimes object properties are not powerful enough to control the
parameters that affect the behaviour of your element.
When this is the case you can mark these parameters as beeing Controllable.
Aware appliations can use the controller subsystem to dynamically adjust
the property values over time.
</para>
<sect1 id="section-dparam-start">
<title>Getting Started</title>
<para>
The controller subsystem is contained within the
<filename>gstcontroller</filename> library. You need to include the header in
your element's source file:
</para>
<programlisting>
...
#include &lt;gst/gst.h&gt;
#include &lt;gst/controller/gstcontroller.h&gt;
...
</programlisting>
<para>
Even though the <filename>gstcontroller</filename> library may be linked into
the host application, you should make sure it is initialized in your
<filename>plugin_init</filename> function:
</para>
<programlisting>
static gboolean
plugin_init (GstPlugin *plugin)
{
...
/* initialize library */
gst_controller_init (NULL, NULL);
...
}
</programlisting>
<para>
It makes not sense for all GObject parameter to be real-time controlled.
Therefore the next step is to mark controllable parameters.
This is done by using the special flag <constant>GST_PARAM_CONTROLLABLE</constant>.
when setting up GObject params in the <function>_class_init</function> method.
</para>
<programlisting>
g_object_class_install_property (gobject_class, PROP_FREQ,
g_param_spec_double ("freq", "Frequency", "Frequency of test signal",
0.0, 20000.0, 440.0,
G_PARAM_READWRITE | GST_PARAM_CONTROLLABLE));
</programlisting>
</sect1>
<sect1 id="chapter-dparam-loop">
<title>The Data Processing Loop</title>
<para>
In the last section we learned how to mark GObject params as controllable.
Application developers can then queue parameter changes for these parameters.
The approach the controller subsystem takes is to make plugins responsible
for pulling the changes in. This requires just one action:
</para>
<programlisting>
gst_object_sync_values(element,timestamp);
</programlisting>
<para>
This call makes all parameter-changes for the given timestamp active by
adjusting the GObject properties of the element. Its up to the element to
determine the synchronisation rate.
</para>
<sect2 id="chapter-dparam-loop-video">
<title>The Data Processing Loop for Video Elements</title>
<para>
For video processing elements it is the best to synchonise for every frame.
That means one would add the <function>gst_object_sync_values()</function>
call described in the previous section to the data processing function of
the element.
</para>
</sect2>
<sect2 id="chapter-dparam-loop-audio">
<title>The Data Processing Loop for Audio Elements</title>
<para>
For audio processing elements the case is not as easy as for video
processing elements. The problem here is that audio has a much higher rate.
For PAL video one will e.g. process 25 full frames per second, but for
standard audio it will be 44100 samples.
It is rarely useful to synchronise controllable parameters that often.
The easiest solution is also to have just one synchronisation call per
buffer processing. This makes the control-rate dependend on the buffer
size.
</para>
<para>
Elements that need a specific control-rate need to break their data
processing loop to synchronise every n-samples.
</para>
</sect2>
</sect1>
</chapter>