Commit 93ea284f authored by Ronald S. Bultje's avatar Ronald S. Bultje
Browse files

docs/pwg/: Add as a placeholder for future filling-in.

Original commit message from CVS:
2004-01-27  Ronald Bultje  <rbultje@ronald.bitfreak.net>

* docs/pwg/advanced_interfaces.xml:
* docs/pwg/pwg.xml:
Add as a placeholder for future filling-in.
* docs/pwg/basics_autoplugging.xml:
* docs/pwg/basics_buffers.xml:
* docs/pwg/basics_elements.xml:
* docs/pwg/basics_events.xml:
* docs/pwg/basics_plugins.xml:
* docs/pwg/basics_types.xml:
Remove, because unused (this is all in intro_basics.xml).
* docs/pwg/building_signals.xml:
Short intro to signals + reference to GObject docs - we really
shouldn't go into these sort of things to deply because we don't
use them that extensively anyway.
* docs/pwg/building_state.xml:
Explanation of states. Benjamin, please check.
* docs/pwg/building_testapp.xml:
Put everything in one page - putting only a few lines of content
per page doesn't really make sense.

Time to get into the advanced topics. ;).
parent 8e29a588
2004-01-27 Ronald Bultje <rbultje@ronald.bitfreak.net>
* docs/pwg/advanced_interfaces.xml:
* docs/pwg/pwg.xml:
Add as a placeholder for future filling-in.
* docs/pwg/basics_autoplugging.xml:
* docs/pwg/basics_buffers.xml:
* docs/pwg/basics_elements.xml:
* docs/pwg/basics_events.xml:
* docs/pwg/basics_plugins.xml:
* docs/pwg/basics_types.xml:
Remove, because unused (this is all in intro_basics.xml).
* docs/pwg/building_signals.xml:
Short intro to signals + reference to GObject docs - we really
shouldn't go into these sort of things to deply because we don't
use them that extensively anyway.
* docs/pwg/building_state.xml:
Explanation of states. Benjamin, please check.
* docs/pwg/building_testapp.xml:
Put everything in one page - putting only a few lines of content
per page doesn't really make sense.
Time to get into the advanced topics. ;).
2004-01-27 Ronald Bultje <rbultje@ronald.bitfreak.net> 2004-01-27 Ronald Bultje <rbultje@ronald.bitfreak.net>
* docs/pwg/advanced_types.xml: * docs/pwg/advanced_types.xml:
......
<chapter id="cha-advanced-interfaces">
<title>Interfaces</title>
<para>
WRITEME
</para>
</chapter>
<!-- ############ chapter ############# -->
<chapter id="cha-autopluggers">
<title>Autopluggers</title>
<para>
&GStreamer; has an autoplugging mechanism, which enables application writers
to simply specify start and end elements for a path, and the system will
then create a path which links these elements, in accordance with the type
information provided by the elements.
</para>
<para>
It is possible to devise many different schemes for generating such
pathways, perhaps to optimise based on special criteria, or with some
specific constraints. It is thus possible to define new autoplugging
systems, using the plugin system.
</para>
</chapter>
<!-- ############ chapter ############# -->
<chapter id="cha-buffers">
<title>Buffers</title>
<para>
Buffers are structures used to pass data between elements. All streams of
data are chopped up into chunks which are stored in buffers. Buffers can be
of any size, and also contain metadata indicating the type of data contained
in them. Buffers can be allocated by various different schemes, and may
either be passed on by elements or unreferenced (and the memory used by the
buffer freed).
</para>
<sect1 id="sect1-buffers-anatomy">
<title>Anatomy of a buffer</title>
<para>
</para>
</sect1>
<sect1 id="sect1-buffers-refcounts">
<title>Refcounts and mutability</title>
<para>
</para>
</sect1>
<sect1 id="sect1-buffers-metadata">
<title>Metadata</title>
<para>
</para>
</sect1>
</chapter>
<!-- ############ chapter ############# -->
<chapter id="cha-basics-elements">
<title>Elements, Plugins, and Filters</title>
<para>
In the &GStreamer; framework, a <emphasis>plugin</emphasis> is a specific
sort of code module that gets loaded when a program requests the
functionality that the plugin provides. A plugin is essentially a shared
code library.
<emphasis>Filters</emphasis> are an
important subset of plugins that process data, as opposed to producing or
consuming data. (Producers and consumers of data are called
<emphasis>source</emphasis> and <emphasis>sink</emphasis> plugins,
respectively.)
</para>
<para>
Elements are at the core of &GStreamer;. Without elements, &GStreamer; is
just a bunch of pipe fittings with nothing to link. A large number of
elements (filters, sources, and sinks) ship with &GStreamer;, but extra
elements can also be written. The purpose of this guide is to help you
learn to create new elements.
</para>
<para>
An element may be constructed in several different ways, but all must
conform to the same basic rules. This guide presents one basic way to build
a filter elementA simple filter may be built with the
FilterFactory, where the only code that need be written is the actual filter
code. A more complex filter, or a source or sink, will need to be written
out fully for complete access to the features and performance possible with
&GStreamer;.
</para>
<para>
The implementation of a new element will be contained in a plugin: a single
plugin may contain the implementation of several elements, or just a single
one.
</para>
</chapter>
<!-- ############ chapter ############# -->
<chapter id="cha-events">
<title>Events</title>
<para>
</para>
</chapter>
<!-- ############ chapter ############# -->
<chapter id="cha-plugins">
<title>Plugins</title>
<para>
Extensions to &GStreamer; can be made using a plugin mechanism. This is used
extensively in &GStreamer; even if only the standard package is being used:
a few very basic functions reside in the core library, and all others are
implemented in plugins.
</para>
<para>
Plugins are only loaded when needed: a plugin registry is used to store the
details of the plugins so that it is not neccessary to load all plugins to
determine which are needed. This registry needs to be updated whenever a new
plugin is added to the system: see the <emphasis>gst-register</emphasis>
utility and the documentation in the &GstAppDevMan; for more details.
</para>
<para>
User extensions to &GStreamer; can be installed in the main plugin
directory, and will immediately be available for use in applications.
<emphasis>gst-register</emphasis> should be run to update the repository:
but the system should work correctly even if it hasn't been - it will just
take longer to load the correct plugin.
</para>
<para>
User specific plugin directories and registries will be available in future
versions of &GStreamer;.
</para>
</chapter>
<!-- ############ chapter ############# -->
<chapter id="cha-typing">
<title>Typing and Properties</title>
<para>
A type system is used to ensure that the data passed between elements is in
a recognised format, and that the various parameters required to fully
specify that format match up correctly. Each link that is made between
elements has a specified type. This is related, but different, to the
metadata in buffers which describes the type of data in that particular
buffer. See the next chapter of this document for details of the available
types.
</para>
</chapter>
...@@ -4,6 +4,11 @@ ...@@ -4,6 +4,11 @@
<chapter id="cha-building-signals"> <chapter id="cha-building-signals">
<title>Signals</title> <title>Signals</title>
<para> <para>
Define signals in enum. Signals can be used to notify applications of events specific to this
object. Note, however, that the application needs to be aware of signals
and their meaning, so if you're looking for a generic way for application-
element interaction, signals are probably not what you're looking for. In
many cases, however, signals can be very useful. See the GObject
documentation for all internals about signals.
</para> </para>
</chapter> </chapter>
...@@ -3,6 +3,55 @@ ...@@ -3,6 +3,55 @@
What are states? What are states?
</title> </title>
<para> <para>
A state describes whether the element instance is initialized, whether it
is ready to transfer data and whether it is currently handling data. There
are four states defined in &GStreamer;: <classname>GST_STATE_NULL</classname>,
<classname>GST_STATE_READY</classname>, <classname>GST_STATE_PAUSED</classname>
and <classname>GST_STATE_PLAYING</classname>.
</para>
<para>
<classname>GST_STATE_NULL</classname> (from now on referred to as
<quote>NULL</quote>) is the default state of an element. In this state, it
has not allocated any runtime resources, it has not loaded any runtime
libraries and it can obviously not handle data.
</para>
<para>
<classname>GST_STATE_READY</classname> (from now on referred to as
<quote>READY</quote>) is the next state that an element can be in. In the
READY state, an element has all default resources (runtime-libraries,
runtime-memory) allocated. However, it has not yet allocated or defined
anything that is stream-specific. When going from NULL to READY state
(<classname>GST_STATE_NULL_TO_READY</classname>), an element should
allocate any non-stream-specific resources and should load runtime-loadable
libraries (if any). When going the other way around (from READY to NULL,
<classname>GST_STATE_READY_TO_NULL</classname>), an element should unload
these libraries and free all allocated resources. Examples of such
resources are hardware devices. Note that files are generally streams,
and these should thus be considered as stream-specific resources; therefore,
they should <emphasis>not</emphasis> be allocated in this state.
</para>
<para>
<classname>GST_STATE_PAUSED</classname> (from now on referred to as
<quote>PAUSED</quote>) is a state in which an element is by all means able
to handle data; the only 'but' here is that it doesn't actually handle
any data. When going from the READY state into the PAUSED state
(<classname>GST_STATE_READY_TO_PAUSED</classname>), the element will
usually not do anything at all: all stream-specific info is generally
handled in the <function>_link ()</function>, which is called during caps
negotiation. Exceptions to this rule are, for example, files: these are
considered stream-specific data (since one file is one stream), and should
thus be opened in this state change. When going from the PAUSED back to
READY (<classname>GST_STATE_PAUSED_TO_READY</classname>), all
stream-specific data should be discarded.
</para>
<para>
<classname>GST_STATE_PLAYING</classname> (from now on referred to as
<quote>PLAYING</quote>) is the highest state that an element can be in. It
is similar to PAUSED, except that now, data is actually passing over the
pipeline. The transition from PAUSED to PLAYING
(<classname>GST_STATE_PAUSED_TO_PLAYING</classname>) should be as small
as possible and would ideally cause no delay at all. The same goes for the
reverse transition (<classname>GST_STATE_PLAYING_TO_PAUSED</classname>).
</para> </para>
</chapter> </chapter>
<chapter id="cha-statemanage-filters"> <chapter id="cha-statemanage-filters">
...@@ -10,5 +59,44 @@ ...@@ -10,5 +59,44 @@
Mangaging filter state Mangaging filter state
</title> </title>
<para> <para>
An element can be notified of state changes through a virtual function
pointer. Inside this function, the element can initialize any sort of
specific data needed by the element, and it can optionally fail to
go from one state to another.
</para> </para>
<programlisting>
static GstElementStateReturn
gst_my_filter_change_state (GstElement *element);
static void
gst_my_filter_class_init (GstMyFilterClass *klass)
{
GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
element_class->change_state = gst_my_filter_change_state;
}
static GstElementStateReturn
gst_my_filter_change_state (GstElement *element)
{
GstMyFilter *filter = GST_MY_FILTER (element);
switch (GST_STATE_TRANSITION (element)) {
case GST_STATE_NULL_TO_READY:
if (!gst_my_filter_allocate_memory (filter))
return GST_STATE_FAILURE;
break;
case GST_STATE_READY_TO_NULL:
gst_my_filter_free_memory (filter);
break;
default:
break;
}
if (GST_ELEMENT_CLASS (parent_class)->change_state)
return GST_ELEMENT_CLASS (parent_class)->change_state (element);
return GST_STATE_SUCCESS;
}
</programlisting>
</chapter> </chapter>
...@@ -14,8 +14,6 @@ ...@@ -14,8 +14,6 @@
Manual</ulink>. Manual</ulink>.
</para> </para>
<sect1 id="cha-testapp-init" xreflabel="Initialization">
<title>Initialization</title>
<para> <para>
At the start, you need to initialize the &GStreamer; core library by At the start, you need to initialize the &GStreamer; core library by
calling <function>gst_init ()</function>. You can alternatively call calling <function>gst_init ()</function>. You can alternatively call
...@@ -23,10 +21,7 @@ ...@@ -23,10 +21,7 @@
a pointer to popt tables. You can then use libpopt to handle the a pointer to popt tables. You can then use libpopt to handle the
given argument table, and this will finish the &GStreamer; intialization. given argument table, and this will finish the &GStreamer; intialization.
</para> </para>
</sect1>
<sect1 id="cha-testapp-inst" xreflabel="Instantiating the plugins">
<title>Instantiating the plugins</title>
<para> <para>
You can create elements using <function>gst_element_factory_make ()</function>, You can create elements using <function>gst_element_factory_make ()</function>,
where the first argument is the element type that you want to create, where the first argument is the element type that you want to create,
...@@ -43,20 +38,14 @@ ...@@ -43,20 +38,14 @@
(indeed, an eletric fence memory debugger wrapper element) to check (indeed, an eletric fence memory debugger wrapper element) to check
for memory errors. for memory errors.
</para> </para>
</sect1>
<sect1 id="cha-testapp-link" xreflabel="Linking the plugins">
<title>Linking the plugins</title>
<para> <para>
During linking, your test application can use fixation or filtered caps During linking, your test application can use fixation or filtered caps
as a way to drive a specific type of data to or from your element. This as a way to drive a specific type of data to or from your element. This
is a very simple and effective way of checking multiple types of input is a very simple and effective way of checking multiple types of input
and output in your element. and output in your element.
</para> </para>
</sect1>
<sect1 id="cha-testapp-running" xreflabel="Running the pipeline">
<title>Running the pipeline</title>
<para> <para>
Running the pipeline happens through the <function>gst_bin_iterate ()</function> Running the pipeline happens through the <function>gst_bin_iterate ()</function>
function. Note that during running, you should connect to at least the function. Note that during running, you should connect to at least the
...@@ -65,10 +54,7 @@ ...@@ -65,10 +54,7 @@
you should add events into the pipeline and make sure your plugin handles you should add events into the pipeline and make sure your plugin handles
these correctly (with respect to clocking, internal caching, etc.). these correctly (with respect to clocking, internal caching, etc.).
</para> </para>
</sect1>
<sect1 id="cha-testapp-cleanup" xreflabel="Cleaning up the memory">
<title>Cleaning up the memory</title>
<para> <para>
Never forget to clean up memory in your plugin or your test application. Never forget to clean up memory in your plugin or your test application.
When going to the NULL state, your element should clean up allocated When going to the NULL state, your element should clean up allocated
...@@ -76,10 +62,7 @@ ...@@ -76,10 +62,7 @@
possible support libraries. Your application should <function>unref ()</function> possible support libraries. Your application should <function>unref ()</function>
the pipeline and make sure it doesn't crash. the pipeline and make sure it doesn't crash.
</para> </para>
</sect1>
<sect1 id="cha-testapp-all" xreflabel="Summary">
<title>Summary</title>
<programlisting> <programlisting>
#include &lt;gst/gst.h&gt; #include &lt;gst/gst.h&gt;
...@@ -117,5 +100,4 @@ main (gint arcg, ...@@ -117,5 +100,4 @@ main (gint arcg,
return 0; return 0;
} }
</programlisting> </programlisting>
</sect1>
</chapter> </chapter>
...@@ -24,6 +24,7 @@ ...@@ -24,6 +24,7 @@
<!ENTITY ADVANCED_CLOCK SYSTEM "advanced_clock.xml"> <!ENTITY ADVANCED_CLOCK SYSTEM "advanced_clock.xml">
<!ENTITY ADVANCED_DPARAMS SYSTEM "advanced_dparams.xml"> <!ENTITY ADVANCED_DPARAMS SYSTEM "advanced_dparams.xml">
<!ENTITY ADVANCED_MIDI SYSTEM "advanced_midi.xml"> <!ENTITY ADVANCED_MIDI SYSTEM "advanced_midi.xml">
<!ENTITY ADVANCED_INTERFACES SYSTEM "advanced_interfaces.xml">
<!ENTITY OTHER_SOURCE SYSTEM "other_source.xml"> <!ENTITY OTHER_SOURCE SYSTEM "other_source.xml">
<!ENTITY OTHER_SINK SYSTEM "other_sink.xml"> <!ENTITY OTHER_SINK SYSTEM "other_sink.xml">
...@@ -124,6 +125,7 @@ ...@@ -124,6 +125,7 @@
&ADVANCED_CLOCK; &ADVANCED_CLOCK;
&ADVANCED_DPARAMS; &ADVANCED_DPARAMS;
&ADVANCED_MIDI; &ADVANCED_MIDI;
&ADVANCED_INTERFACES;
</part> </part>
<!-- ############ part ############# --> <!-- ############ part ############# -->
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment