mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-11-22 17:51:16 +00:00
Code Issues 1 Projects Releases Wiki Activity

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

Browse source 
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. ;).
This commit is contained in:
Ronald S. Bultje 2004-01-27 14:58:21 +00:00
parent 8e29a5888a
commit 93ea284fe4
12 changed files with 126 additions and 161 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
ChangeLog
View file

@ -1,3 +1,27 @@
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>
* docs/pwg/advanced_types.xml:

6
docs/pwg/advanced-interfaces.xml Normal file
View file

@ -0,0 +1,6 @@
<chapter id="cha-advanced-interfaces">
<title>Interfaces</title>
<para>
WRITEME
</para>
</chapter>

18
docs/pwg/basics-autoplugging.xml
View file

@ -1,18 +0,0 @@
<!-- ############ 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>

32
docs/pwg/basics-buffers.xml
View file

@ -1,32 +0,0 @@
<!-- ############ 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>

39
docs/pwg/basics-elements.xml
View file

@ -1,39 +0,0 @@
<!-- ############ 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>

8
docs/pwg/basics-events.xml
View file

@ -1,8 +0,0 @@
<!-- ############ chapter ############# -->
<chapter id="cha-events">
<title>Events</title>
<para>
</para>
</chapter>

30
docs/pwg/basics-plugins.xml
View file

@ -1,30 +0,0 @@
<!-- ############ 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>

15
docs/pwg/basics-types.xml
View file

@ -1,15 +0,0 @@
<!-- ############ 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>

7
docs/pwg/building-signals.xml
View file

@ -4,6 +4,11 @@
<chapter id="cha-building-signals">
<title>Signals</title>
<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>
</chapter>

88
docs/pwg/building-state.xml
View file

@ -3,6 +3,55 @@
What are states?
</title>
<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>
</chapter>
<chapter id="cha-statemanage-filters">
@ -10,5 +59,44 @@
Mangaging filter state
</title>
<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>
<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>

18
docs/pwg/building-testapp.xml
View file

@ -14,8 +14,6 @@
Manual</ulink>.
</para>
<sect1 id="cha-testapp-init" xreflabel="Initialization">
<title>Initialization</title>
<para>
At the start, you need to initialize the &GStreamer; core library by
calling <function>gst_init ()</function>. You can alternatively call
@ -23,10 +21,7 @@
a pointer to popt tables. You can then use libpopt to handle the
given argument table, and this will finish the &GStreamer; intialization.
</para>
</sect1>
<sect1 id="cha-testapp-inst" xreflabel="Instantiating the plugins">
<title>Instantiating the plugins</title>
<para>
You can create elements using <function>gst_element_factory_make ()</function>,
where the first argument is the element type that you want to create,
@ -43,20 +38,14 @@
(indeed, an eletric fence memory debugger wrapper element) to check
for memory errors.
</para>
</sect1>
<sect1 id="cha-testapp-link" xreflabel="Linking the plugins">
<title>Linking the plugins</title>
<para>
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
is a very simple and effective way of checking multiple types of input
and output in your element.
</para>
</sect1>
<sect1 id="cha-testapp-running" xreflabel="Running the pipeline">
<title>Running the pipeline</title>
<para>
Running the pipeline happens through the <function>gst_bin_iterate ()</function>
function. Note that during running, you should connect to at least the
@ -65,10 +54,7 @@
you should add events into the pipeline and make sure your plugin handles
these correctly (with respect to clocking, internal caching, etc.).
</para>
</sect1>
<sect1 id="cha-testapp-cleanup" xreflabel="Cleaning up the memory">
<title>Cleaning up the memory</title>
<para>
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
@ -76,10 +62,7 @@
possible support libraries. Your application should <function>unref ()</function>
the pipeline and make sure it doesn't crash.
</para>
</sect1>
<sect1 id="cha-testapp-all" xreflabel="Summary">
<title>Summary</title>
<programlisting>
#include &lt;gst/gst.h&gt;
@ -117,5 +100,4 @@ main (gint arcg,
return 0;
}
</programlisting>
</sect1>
</chapter>

2
docs/pwg/pwg.xml
View file

@ -24,6 +24,7 @@
<!ENTITY ADVANCED_CLOCK SYSTEM "advanced_clock.xml">
<!ENTITY ADVANCED_DPARAMS SYSTEM "advanced_dparams.xml">
<!ENTITY ADVANCED_MIDI SYSTEM "advanced_midi.xml">
<!ENTITY ADVANCED_INTERFACES SYSTEM "advanced_interfaces.xml">
<!ENTITY OTHER_SOURCE SYSTEM "other_source.xml">
<!ENTITY OTHER_SINK SYSTEM "other_sink.xml">
@ -124,6 +125,7 @@
&ADVANCED_CLOCK;
&ADVANCED_DPARAMS;
&ADVANCED_MIDI;
&ADVANCED_INTERFACES;
</part>
<!-- ############ part ############# -->