usually need to do so in only a couple of places:
<itemizedlist>
<listitem>
+ <para>
In the element <filename>init</filename> function, just after the call
to <filename>gst_dpman_new</filename>
+ </para>
</listitem>
<listitem>
+ <para>
Whenever a new pad is created so that parameters can affect data going
into or out of a specific pad. An example of this would be a mixer
element where a seperate volume parameter is needed on every pad.
+ </para>
</listitem>
</itemizedlist>
</para>
used within your element. Each of these methods has its own function to
define a required dparam:
<itemizedlist>
- <listitem><filename>gst_dpman_add_required_dparam_direct</filename></listitem>
- <listitem><filename>gst_dpman_add_required_dparam_callback</filename></listitem>
- <listitem><filename>gst_dpman_add_required_dparam_array</filename></listitem>
+<!-- FIXME: are we sure we need to use filename for function calls ??? -->
+ <listitem><para><filename>gst_dpman_add_required_dparam_direct</filename></para></listitem>
+ <listitem><para><filename>gst_dpman_add_required_dparam_callback</filename></para></listitem>
+ <listitem><para><filename>gst_dpman_add_required_dparam_array</filename></para></listitem>
</itemizedlist>
These functions will return TRUE if the required dparam was added
successfully.
The common parameters to these functions are:
<itemizedlist>
<listitem>
+ <para>
<filename>GstDParamManager *dpman</filename> the element's dparam
manager
+ </para>
</listitem>
<listitem>
+ <para>
<filename>GParamSpec *param_spec</filename> the param spec which defines
the required dparam
+ </para>
</listitem>
<listitem>
+ <para>
<filename>gboolean is_log</filename> whether this dparam value should be
interpreted on a log scale (such as a frequency or a decibel value)
+ </para>
</listitem>
<listitem>
+ <para>
<filename>gboolean is_rate</filename> whether this dparam 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>
</para>
- <sect2 id="sect-dparam-direct">
+ <sect1 id="sect-dparam-direct">
<title>Direct Method</title>
<para>
This method is the simplest and has the lowest overhead for parameters
You can now use <filename>example->volume</filename> anywhere in your
element knowing that it will always contain the correct value to use.
</para>
- </sect2>
- <sect2 id="sect-dparam-callback">
+ </sect1>
+ <sect1 id="sect-dparam-callback">
<title>Callback Method</title>
<para>
This should be used if the you have other values to calculate whenever a
Now <filename>example->volume_i</filename> can be used elsewhere and it
will always contain the correct value.
</para>
- </sect2>
- <sect2 id="sect-dparam-array">
+ </sect1>
+ <sect1 id="sect-dparam-array">
<title>Array Method</title>
<para>
This method is quite different from the other two. It could be thought of
<itemizedlist>
<listitem>
+ <para>
Certain optimisations may be possible since you can iterate over your
dparams array and your buffer data together.
+ </para>
</listitem>
<listitem>
+ <para>
Some dparams may be able to interpolate changing values at the sample
rate. This would allow the array to contain very smoothly changing
values which may be required for the stability and quality of some DSP
algorithms.
+ </para>
</listitem>
</itemizedlist>
<para>
not yet ready to be used in elements, but plugin writers should be aware
of its existance for the future.
</para>
- </sect2>
+ </sect1>
</chapter>
<chapter id="cha-dparam-loop">
The macro <filename>GST_DPMAN_PREPROCESS</filename> will do the following:
<itemizedlist>
<listitem>
+ <para>
Update any dparams which are due to be updated.
+ </para>
</listitem>
<listitem>
+ <para>
Calculate how many samples should be processed before the next required
update
+ </para>
</listitem>
<listitem>
+ <para>
Return the number of samples until next update, or the number of samples
in the buffer - whichever is less.
+ </para>
</listitem>
</itemizedlist>
In fact <filename>GST_DPMAN_PROCESS</filename> may do the same things as
<filename>GST_DPMAN_PREPROCESS</filename> depending on the mode that the
dparam manager is running in (see below).
</para>
- <sect2 id="sect-dparam-modes">
+ <sect1 id="sect-dparam-modes">
<title>DParam Manager Modes</title>
<para>
A brief explanation of dparam manager modes might be useful here even
element's parameters be updated in differently. These include:
<itemizedlist>
<listitem>
+ <para>
<emphasis>Timelined</emphasis> - all parameter changes are known in
advance before the pipeline is run.
+ </para>
</listitem>
<listitem>
+ <para>
<emphasis>Realtime low-latency</emphasis> - Nothing is known ahead of
time about when a parameter might change. Changes need to be
propagated to the element as soon as possible.
+ </para>
</listitem>
</itemizedlist>
When a dparam-aware application gets the dparam manager for an element,
mode this could be done without affecting the sample accuracy of the
parameter updates
</para>
- </sect2>
- <sect2 id="sect-dparam-audio-video">
+ </sect1>
+ <sect1 id="sect-dparam-audio-video">
<title>DParam Manager Modes</title>
<para>
All of the explanation so far has presumed that the buffer contains audio
required. For more than one frame per buffer, treat it the same as the
audio case.
</para>
- </sect2>
+ </sect1>
</chapter>
<!-- ############ sect1 ############# -->
- <sect1 name="sect1-boiler-examine" xreflabel="Examining the Basic Code">
+ <sect1 id="sect1-boiler-examine">
<title>Examining the Basic Code</title>
<para>
First we will examine the code you would be likely to place in a header
<filename>examples/pwg/examplefilter/boiler/gstexamplefilter.h</filename>.
</para>
- <example name="ex-boiler-examine-h" xreflabel="Example Plugin Header File">
+ <example id="ex-boiler-examine-h">
<title>Example Plugin Header File</title>
<programlisting>
/* Definition of structure storing data for this element. */
This guide is intended to help you understand the &GStreamer; framework
(version &GstVersion;) so you can develop new plugins to extend the
existing functionality. The guide addresses most issues by following the
- development of an example plugin — an audio filter plugin —
+ development of an example plugin - an audio filter plugin -
written in C. However, the later parts of the guide also present some
issues involved in writing other types of plugins, and the end of the
guide describes some of the Python bindings for &GStreamer;.
This guide is not relevant to you if you only want to use the existing
functionality of &GStreamer;, or if you just want to use an application
that uses &GStreamer;. If you are only interested in using existing
- plugins to write a new application — and there are quite a lot of
- plugins already — you might want to check the &GstAppDevMan;. If you
+ plugins to write a new application - and there are quite a lot of
+ plugins already - you might want to check the &GstAppDevMan;. If you
are just trying to get help with a &GStreamer; application, then you
should check with the user manual for that particular application.
</para>
<itemizedlist>
<listitem>
<para>
- <guilabel><xref linkend="part-building"/></guilabel> —
+ <xref linkend="part-building"/> -
Introduction to the structure of a plugin, using an example audio
filter for illustration.
</para>
you will learn how to write the code to get a basic filter plugin
working: These steps include chapters on <xref
linkend="cha-building-types"/>, <xref linkend="cha-building-pads"/>,
- <xref linkend="cha-building-chainfn"/>, and <xref
- linkend="cha-building-state"/>.
+ <xref linkend="cha-building-chainfn"/>, and <!-- <xref
+ linkend="cha-building-state"/>--> (WRITEME: building state).
</para>
<para>
After you have finished the first steps, you will be able to create a
working plugin, but your new plugin might not have all the
functionality you need. To provide some standard functionality, you
will learn how to add more features to a new plugin. These features
- are described in the chapters on <xref linkend="cha-building-props"/>
+ are described in the chapters on
+ <!--FIXME: WRITEME <xref linkend="cha-building-props"/> -->
+ (WRITEME)
and <xref linkend="cha-building-signals"/>. Finally, you will see in
- <xref linkend="cha-building-testapp"/> how to write a short test
+ <!--<xref linkend="cha-building-testapp"/>-->(WRITEME)
+ how to write a short test
application to try out your new plugin.
</para>
</listitem>
<listitem>
<para>
- <guilabel><xref linkend="part-advanced"/></guilabel> —
+ <xref linkend="part-advanced"/> -
Information on advanced features of &GStreamer; plugin development.
</para>
<para>
functional audio or video filter plugin with some nice features.
However, &GStreamer; offers more for plugin writers. This part of the
guide includes chapters on more advanced topics, such as <xref
- linkend="cha-advanced-scheduling"/>, <xref
- linkend="cha-advanced-request"/>, <xref
+ linkend="cha-advanced-request"/>, <!-- <xref
linkend="cha-advanced-clock"/>, <xref
+ linkend="cha-advanced-scheduling"/>, <xref
linkend="cha-advanced-dparams"/>, and <xref
- linkend="cha-advanced-midi"/>. Since these features are more advanced,
+ linkend="cha-advanced-midi"/>-->. Since these features are more advanced,
the chapters can basically be read in any order, as you find that your
plugins require these features.
</para>
</listitem>
<listitem>
<para>
- <guilabel><xref linkend="part-other"/></guilabel> — Explanation
+ <xref linkend="part-other"/> - Explanation
of writing other plugin types.
</para>
<para>
sinks, and autopluggers. This part of the guide presents the issues
that arise when working on these more specialized plugin types. The
part includes chapters on <xref linkend="cha-other-source"/>, <xref
- linkend="cha-other-sink"/>, <xref linkend="cha-other-scheduler"/>, and
+ linkend="cha-other-sink"/>, <!-- FIXME: WRITEME
+ <xref linkend="cha-other-scheduler"/>,--> and
<xref linkend="cha-other-autoplugger"/>.
</para>
</listitem>
<listitem>
<para>
- <guilabel><xref linkend="part-appendix"/></guilabel> — Further
+ <xref linkend="part-appendix"/> - Further
information for plugin developers.
</para>
<para>
The appendices contain some information that stubbornly refuses to fit
cleanly in other sections of the guide. This information includes
- <xref linkend="cha-appendix-checklist"/> and <xref
- linkend="cha-appendix-python"/>. FIXME: organize better.
+ <!-- FIXME: WRITEME
+ <xref linkend="cha-appendix-checklist"/>--> (WRITEME) and
+ <!-- <xref
+ linkend="cha-appendix-python"/>.--> FIXME: organize better.
</para>
</listitem>
</itemizedlist>
projects / platform / upstream / gstreamer.git / commitdiff