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:
Finish documenting the current state of mimetypes.
* docs/pwg/building_boiler.xml:
--- /dev/null
+<chapter id="cha-advanced-interfaces">
+ <title>Interfaces</title>
+ <para>
+ WRITEME
+ </para>
+</chapter>
+++ /dev/null
-
-<!-- ############ 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>
+++ /dev/null
-
-<!-- ############ 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>
+++ /dev/null
-
-<!-- ############ 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>
-
+++ /dev/null
-
-<!-- ############ chapter ############# -->
-
-<chapter id="cha-events">
- <title>Events</title>
- <para>
- </para>
-</chapter>
+++ /dev/null
-
-<!-- ############ 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>
+++ /dev/null
-
-<!-- ############ 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>
<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>
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">
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>
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
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,
(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
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
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 <gst/gst.h>
return 0;
}
</programlisting>
- </sect1>
</chapter>
<!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">
&ADVANCED_CLOCK;
&ADVANCED_DPARAMS;
&ADVANCED_MIDI;
+ &ADVANCED_INTERFACES;
</part>
<!-- ############ part ############# -->
projects / platform / upstream / gstreamer.git / commitdiff