mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-25 03:01:03 +00:00
105 lines
3.7 KiB
XML
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 being Controllable.
|
|
Aware applications 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 <gst/gst.h>
|
|
#include <gst/controller/gstcontroller.h>
|
|
...
|
|
</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 | G_PARAM_STATIC_STRINGS));
|
|
</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 synchronise 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 depend 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>
|