mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-01-11 09:55:36 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs/manual/advanced-dparams.xml: describe controller

Browse source 
Original commit message from CVS:
* docs/manual/advanced-dparams.xml:
describe controller
* docs/manual/advanced-position.xml:
* docs/manual/basics-init.xml:
* docs/manual/manual.xml:
* docs/manual/titlepage.xml:
* docs/pwg/pwg.xml:
* docs/pwg/titlepage.xml:
cleanup xml (more to come)
* libs/gst/controller/gstcontroller.c:
fix typo
This commit is contained in:
Stefan Kost 2006-01-30 21:11:38 +00:00
parent c0a0e6303e
commit a768c44689
9 changed files with 278 additions and 341 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
ChangeLog
View file

@ -1,3 +1,17 @@
2006-01-30 Stefan Kost <ensonic@users.sf.net>
* docs/manual/advanced-dparams.xml:
describe controller
* docs/manual/advanced-position.xml:
* docs/manual/basics-init.xml:
* docs/manual/manual.xml:
* docs/manual/titlepage.xml:
* docs/pwg/pwg.xml:
* docs/pwg/titlepage.xml:
cleanup xml (more to come)
* libs/gst/controller/gstcontroller.c:
fix typo
2006-01-30 Sebastien Moutte <sebastien@moutte.net> 2006-01-30 Sebastien Moutte <sebastien@moutte.net>
* win32/vs6/grammar.dsp: * win32/vs6/grammar.dsp:

193
docs/manual/advanced-dparams.xml
View file

@ -1,198 +1,81 @@
<chapter id="chapter-dparams"> <chapter id="chapter-dparams">
<title>Dynamic Parameters</title> <title>Dynamic Controllable Parameters</title>
<sect1 id="section-dparams-getting-started"> <sect1 id="section-dparams-getting-started">
<title>Getting Started</title> <title>Getting Started</title>
<para> <para>
The Dynamic Parameters subsystem is contained within the The controller subsystem offers a lightweight way to adjust gobject
properties over stream-time.
It works by using time-stamped value pairs that are queued for
element-properties.
At run-time the elements continously pull values changes for the
current stream-time.
</para>
<para>
This subsystem is contained within the
<filename>gstcontrol</filename> library. <filename>gstcontrol</filename> library.
You need to include the header in your application's source file: You need to include the header in your application's source file:
</para> </para>
<programlisting> <programlisting>
... ...
#include &lt;gst/gst.h&gt; #include &lt;gst/gst.h&gt;
#include &lt;gst/control/control.h&gt; #include &lt;gst/controller/gstcontroller.h&gt;
... ...
</programlisting> </programlisting>
<para> <para>
Your application should link to the shared library <filename>gstcontrol</filename>. Your application should link to the shared library <filename>gstreamer-controller</filename>.
</para> </para>
<para> <para>
The <filename>gstcontrol</filename> library needs to be initialized The <filename>gstreamer-controller</filename> library needs to be initialized
when your application is run. This can be done after the the GStreamer when your application is run. This can be done after the the GStreamer
library has been initialized. library has been initialized.
</para> </para>
<programlisting> <programlisting>
... ...
gst_init(&amp;argc,&amp;argv); gst_init(&amp;argc,&amp;argv);
gst_control_init(&amp;argc,&amp;argv); gst_controller_init(&amp;argc,&amp;argv);
... ...
</programlisting> </programlisting>
</sect1> </sect1>
<sect1 id="section-dparams-creating"> <sect1 id="section-dparams-parameters">
<title>Creating and Attaching Dynamic Parameters</title> <title>Setting up parameters</title>
<para> <para>
Once you have created your elements you can create and attach dparams to them. It makes not sense for all GObject parameter to be real-time controlled.
First you need to get the element's dparams manager. If you know exactly what kind of element Therefore the first step is to mark controllable parameters.
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> </para>
<programlisting> <programlisting>
GstElement *audiotestsrc; controller = g_object_control_properties(object, "prop1", "prop2",...);
GstDParamManager *dpman;
...
audiotestsrc = gst_element_factory_make("audiotestsrc", NULL);
...
dpman = gst_dpman_get_manager (audiotestsrc);
gst_dpman_set_mode(dpman, "synchronous");
</programlisting> </programlisting>
<para> <para>
If you don't know the names of the required dparams for your element you can call Next we can select an interpolation mode. This mode controls how inbetween
<filename>gst_dpman_list_dparam_specs(dpman)</filename> to get a NULL terminated array of param specs. values are determined.
This array should be freed after use. You can find the name of the required dparam by calling The controller subsystem can e.g. fill gaps by smoothing parameter changes.
<filename>g_param_spec_get_name</filename> on each param spec in the array. In our example, Each controllable GObject property can be
<filename>"volume"</filename> will be the name of our required dparam. interpolated differently.
</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> </para>
<programlisting> <programlisting>
GstDParam *volume; gst_controller_set_interpolation_mode(controller,"prop1",mode);
...
volume = gst_dparam_new(G_TYPE_DOUBLE);
if (gst_dpman_attach_dparam (dpman, "volume", volume)){
/* the dparam was successfully attached */
...
}
</programlisting> </programlisting>
</sect1>
<sect1 id="section-dparams-changing">
<title>Changing Dynamic Parameter Values</title>
<para> <para>
All interaction with dparams to actually set the dparam value is done through simple GObject properties. Finally one needs to set control points. These are time-stamped GValues.
There is a property value for each type that dparams supports - these currently being The values become active when the timestamp is reached. They still stay
<filename>"value_double"</filename>, <filename>"value_float"</filename>, <filename>"value_int"</filename> and <filename>"value_int64"</filename>. in the list. If e.g. the pipeline runs a loop (using a segmented seek),
To set the value of a dparam, simply set the property which matches the type of your dparam instance. the control-curve gets repeated as well.
</para> </para>
<programlisting> <programlisting>
#define ZERO(mem) memset(&amp;mem, 0, sizeof(mem)) gst_controller_set (controller, "prop1" ,0 * GST_SECOND, value1);
... gst_controller_set (controller, "prop1" ,1 * GST_SECOND, value2);
gdouble set_to_value;
GstDParam *volume;
GValue set_val;
ZERO(set_val);
g_value_init(&amp;set_val, G_TYPE_DOUBLE);
...
g_value_set_double(&amp;set_val, set_to_value);
g_object_set_property(G_OBJECT(volume), "value_double", &amp;set_val);
</programlisting> </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> <para>
There are currently only two implementations of dparams so far. They are both for real-time use so The controller subsystem has a builtin live-mode. Even though a parameter
should be run in the <filename>"synchronous"</filename> mode. has timestamped control-values assigned one can change the GObject
property through <function>g_object_set()</function>.
This is highly useful when binding the GObject properties to GUI widgets.
When the user adjusts the value with the widget, one can set the GOBject
property and this remains active until the next timestamped value overrides.
This also works with smoothed parameters.
</para> </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> </sect1>
</chapter> </chapter>

6
docs/manual/advanced-position.xml
View file

@ -39,7 +39,8 @@
source itself. source itself.
</para> </para>
<programlisting><!-- example-begin query.c a --> <programlisting>
<!-- example-begin query.c a -->
#include &lt;gst/gst.h&gt; #include &lt;gst/gst.h&gt;
<!-- example-end query.c a --> <!-- example-end query.c a -->
<!-- example-begin query.c b --><!-- <!-- example-begin query.c b --><!--
@ -71,7 +72,8 @@ my_bus_message_cb (GstBus *bus,
break; break;
} }
} }
--><!-- example-end query.c b --> -->
<!-- example-end query.c b -->
<!-- example-begin query.c c --> <!-- example-begin query.c c -->
static gboolean static gboolean
cb_print_position (GstElement *pipeline) cb_print_position (GstElement *pipeline)

6
docs/manual/basics-init.xml
View file

@ -20,6 +20,8 @@
A typical program &EXAFOOT; would have code to initialize A typical program &EXAFOOT; would have code to initialize
&GStreamer; that looks like this: &GStreamer; that looks like this:
</para> </para>
<example id="ex-init-c">
<title>Initializing GStreamer</title>
<programlisting> <programlisting>
<!-- example-begin init.c --> <!-- example-begin init.c -->
#include &lt;gst/gst.h&gt; #include &lt;gst/gst.h&gt;
@ -40,6 +42,7 @@ main (int argc,
} }
<!-- example-end init.c --> <!-- example-end init.c -->
</programlisting> </programlisting>
</example>
<para> <para>
Use the <symbol>GST_VERSION_MAJOR</symbol>, Use the <symbol>GST_VERSION_MAJOR</symbol>,
<symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol> <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
@ -62,6 +65,8 @@ main (int argc,
You can also use a GOption table to initialize your own parameters as You can also use a GOption table to initialize your own parameters as
shown in the next example: shown in the next example:
</para> </para>
<example id="ex-goption-c">
<title>Initialisation using the GOption interface</title>
<programlisting> <programlisting>
<!-- example-begin goption.c --> <!-- example-begin goption.c -->
#include &lt;gst/gst.h&gt; #include &lt;gst/gst.h&gt;
@ -97,6 +102,7 @@ main (int argc,
} }
<!-- example-end goption.c --> <!-- example-end goption.c -->
</programlisting> </programlisting>
</example>
<para> <para>
As shown in this fragment, you can use a <ulink As shown in this fragment, you can use a <ulink
url="http://developer.gnome.org/doc/API/2.0/glib/glib-Commandline-option-parser.html" url="http://developer.gnome.org/doc/API/2.0/glib/glib-Commandline-option-parser.html"

58
docs/manual/manual.xml
View file

@ -18,6 +18,8 @@
</footnote> </footnote>
"> ">
<!ENTITY TITLEPAGE SYSTEM "titlepage.xml">
<!-- Part 1: Overview --> <!-- Part 1: Overview -->
<!ENTITY INTRO SYSTEM "intro-preface.xml"> <!ENTITY INTRO SYSTEM "intro-preface.xml">
<!ENTITY MOTIVATION SYSTEM "intro-motivation.xml"> <!ENTITY MOTIVATION SYSTEM "intro-motivation.xml">
@ -58,61 +60,7 @@
]> ]>
<book id="index"> <book id="index">
<bookinfo> &TITLEPAGE;
<authorgroup>
<author>
<firstname>Wim</firstname>
<surname>Taymans</surname>
<authorblurb>
<para>
<email>wim.taymans@chello.be</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Steve</firstname>
<surname>Baker</surname>
<authorblurb>
<para>
<email>stevebaker_org@yahoo.co.uk</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Andy</firstname>
<surname>Wingo</surname>
<authorblurb>
<para>
<email>wingo@pobox.com</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Ronald</firstname>
<othername>S.</othername>
<surname>Bultje</surname>
<authorblurb>
<para>
<email>rbultje@ronald.bitfreak.net</email>
</para>
</authorblurb>
</author>
</authorgroup>
<legalnotice id="misc-legalnotice">
<para>
This material may be distributed only subject to the terms and
conditions set forth in the Open Publication License, v1.0 or later (the
latest version is presently available at <ulink url="
http://www.opencontent.org/opl.shtml"
type="http">http://www.opencontent.org/opl.shtml</ulink>).
</para>
</legalnotice>
<title>&GStreamer; Application Development Manual (&GST_VERSION;)</title>
</bookinfo>
<!-- ############# Introduction & Overview - part ############### --> <!-- ############# Introduction & Overview - part ############### -->

69
docs/manual/titlepage.xml Normal file
View file

@ -0,0 +1,69 @@
<bookinfo>
<authorgroup>
<author>
<firstname>Wim</firstname>
<surname>Taymans</surname>
<authorblurb>
<para>
<email>wim.taymans@chello.be</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Steve</firstname>
<surname>Baker</surname>
<authorblurb>
<para>
<email>stevebaker_org@yahoo.co.uk</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Andy</firstname>
<surname>Wingo</surname>
<authorblurb>
<para>
<email>wingo@pobox.com</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Ronald</firstname>
<othername>S.</othername>
<surname>Bultje</surname>
<authorblurb>
<para>
<email>rbultje@ronald.bitfreak.net</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Stefan</firstname>
<surname>Kost</surname>
<authorblurb>
<para>
<email>ensonic@users.sf.net</email>
</para>
</authorblurb>
</author>
</authorgroup>
<legalnotice id="misc-legalnotice">
<para>
This material may be distributed only subject to the terms and
conditions set forth in the Open Publication License, v1.0 or later (the
latest version is presently available at <ulink url="
http://www.opencontent.org/opl.shtml"
type="http">http://www.opencontent.org/opl.shtml</ulink>).
</para>
</legalnotice>
<title>&GStreamer; Application Development Manual (&GST_VERSION;)</title>
</bookinfo>

15
docs/pwg/pwg.xml
View file

@ -8,9 +8,11 @@
<!ENTITY TITLEPAGE SYSTEM "titlepage.xml"> <!ENTITY TITLEPAGE SYSTEM "titlepage.xml">
<!-- Part 1: Introduction -->
<!ENTITY INTRO_PREFACE SYSTEM "intro-preface.xml"> <!ENTITY INTRO_PREFACE SYSTEM "intro-preface.xml">
<!ENTITY INTRO_BASICS SYSTEM "intro-basics.xml"> <!ENTITY INTRO_BASICS SYSTEM "intro-basics.xml">
<!-- Part 2: Building a Plugin -->
<!ENTITY BUILDING_BOILER SYSTEM "building-boiler.xml"> <!ENTITY BUILDING_BOILER SYSTEM "building-boiler.xml">
<!ENTITY BUILDING_DEBUG SYSTEM "building-debug.xml"> <!ENTITY BUILDING_DEBUG SYSTEM "building-debug.xml">
<!ENTITY BUILDING_PADS SYSTEM "building-pads.xml"> <!ENTITY BUILDING_PADS SYSTEM "building-pads.xml">
@ -20,6 +22,7 @@
<!ENTITY BUILDING_SIGNALS SYSTEM "building-signals.xml"> <!ENTITY BUILDING_SIGNALS SYSTEM "building-signals.xml">
<!ENTITY BUILDING_TESTAPP SYSTEM "building-testapp.xml"> <!ENTITY BUILDING_TESTAPP SYSTEM "building-testapp.xml">
<!-- Part 3: Advanced Filter Concepts -->
<!ENTITY ADVANCED_NEGOTIATION SYSTEM "advanced-negotiation.xml"> <!ENTITY ADVANCED_NEGOTIATION SYSTEM "advanced-negotiation.xml">
<!ENTITY ADVANCED_SCHEDULING SYSTEM "advanced-scheduling.xml"> <!ENTITY ADVANCED_SCHEDULING SYSTEM "advanced-scheduling.xml">
<!ENTITY ADVANCED_TYPES SYSTEM "advanced-types.xml"> <!ENTITY ADVANCED_TYPES SYSTEM "advanced-types.xml">
@ -31,11 +34,13 @@
<!ENTITY ADVANCED_TAGGING SYSTEM "advanced-tagging.xml"> <!ENTITY ADVANCED_TAGGING SYSTEM "advanced-tagging.xml">
<!ENTITY ADVANCED_EVENTS SYSTEM "advanced-events.xml"> <!ENTITY ADVANCED_EVENTS SYSTEM "advanced-events.xml">
<!-- Part 4: Creating special element types -->
<!ENTITY OTHER_BASE SYSTEM "other-base.xml"> <!ENTITY OTHER_BASE SYSTEM "other-base.xml">
<!ENTITY OTHER_ONETON SYSTEM "other-oneton.xml"> <!ENTITY OTHER_ONETON SYSTEM "other-oneton.xml">
<!ENTITY OTHER_NTOONE SYSTEM "other-ntoone.xml"> <!ENTITY OTHER_NTOONE SYSTEM "other-ntoone.xml">
<!ENTITY OTHER_MANAGER SYSTEM "other-manager.xml"> <!ENTITY OTHER_MANAGER SYSTEM "other-manager.xml">
<!-- Appendices -->
<!ENTITY APPENDIX_CHECKLIST SYSTEM "appendix-checklist.xml"> <!ENTITY APPENDIX_CHECKLIST SYSTEM "appendix-checklist.xml">
<!ENTITY APPENDIX_PORTING SYSTEM "appendix-porting.xml"> <!ENTITY APPENDIX_PORTING SYSTEM "appendix-porting.xml">
<!ENTITY APPENDIX_LICENSING SYSTEM "appendix-licensing.xml"> <!ENTITY APPENDIX_LICENSING SYSTEM "appendix-licensing.xml">
@ -49,7 +54,7 @@
<book id="index"> <book id="index">
&TITLEPAGE; &TITLEPAGE;
<!-- ############# part ############### --> <!-- ############# Introduction - part ############### -->
<part id="part-introduction" xreflabel="Introduction"> <part id="part-introduction" xreflabel="Introduction">
<title>Introduction</title> <title>Introduction</title>
@ -78,7 +83,7 @@
&INTRO_BASICS; &INTRO_BASICS;
</part> </part>
<!-- ############ part ############# --> <!-- ############ Building a Plugin - part ############# -->
<part id="part-building" xreflabel="Building a Plugin"> <part id="part-building" xreflabel="Building a Plugin">
<title>Building a Plugin</title> <title>Building a Plugin</title>
@ -118,7 +123,7 @@
&BUILDING_TESTAPP; &BUILDING_TESTAPP;
</part> </part>
<!-- ############ part ############# --> <!-- ############ Advanced Filter Concepts - part ############# -->
<part id="part-advanced" xreflabel="Advanced Filter Concepts"> <part id="part-advanced" xreflabel="Advanced Filter Concepts">
<title>Advanced Filter Concepts</title> <title>Advanced Filter Concepts</title>
@ -148,7 +153,7 @@
</part> </part>
<!-- ############ part ############# --> <!-- ############ Creating special element types - part ############# -->
<part id="part-other" xreflabel="Creating special element types"> <part id="part-other" xreflabel="Creating special element types">
<title>Creating special element types</title> <title>Creating special element types</title>
@ -173,7 +178,7 @@
&OTHER_MANAGER; &OTHER_MANAGER;
</part> </part>
<!-- ############ part ############# --> <!-- ############ Appendices - part ############# -->
<part id="part-appendix" xreflabel="Appendices"> <part id="part-appendix" xreflabel="Appendices">
<title>Appendices</title> <title>Appendices</title>

10
docs/pwg/titlepage.xml
View file

@ -52,6 +52,16 @@
</para> </para>
</authorblurb> </authorblurb>
</author> </author>
<author>
<firstname>Stefan</firstname>
<surname>Kost</surname>
<authorblurb>
<para>
<email>ensonic@users.sf.net</email>
</para>
</authorblurb>
</author>
</authorgroup> </authorgroup>
<legalnotice id="misc-legalnotice"> <legalnotice id="misc-legalnotice">

4
libs/gst/controller/gstcontroller.c
View file

@ -25,8 +25,8 @@
* @short_description: dynamic parameter control subsystem * @short_description: dynamic parameter control subsystem
* *
* The controller subsystem offers a lightweight way to adjust gobject * The controller subsystem offers a lightweight way to adjust gobject
* properties over stream-time. It works by using time-stampled value pairs that * properties over stream-time. It works by using time-stamped value pairs that
* are queued for element-properties. At run-time the elements continously pulls * are queued for element-properties. At run-time the elements continously pull
* values changes for the current stream-time. * values changes for the current stream-time.
* *
* What needs to be changed in a #GstElement? * What needs to be changed in a #GstElement?