mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-26 02:00:33 +00:00
aaf787f488
Original commit message from CVS: * docs/pwg/advanced-events.xml: * docs/pwg/advanced-request.xml: * docs/pwg/advanced-scheduling.xml: * docs/pwg/appendix-porting.xml: * docs/pwg/building-boiler.xml: * docs/pwg/intro-preface.xml: * docs/pwg/other-ntoone.xml: Rewrite scheduling-chapter for scheduling model in 0.9. Add lots of example code and explanation for pad activation, loop() and getrange() functions and a bit more. Remove old comments pointing to loop-functions. * examples/pwg/Makefile.am: Add loop/getrange examples.
249 lines
12 KiB
XML
249 lines
12 KiB
XML
|
|
<!-- ############ chapter ############# -->
|
|
|
|
<chapter id="chapter-intro-preface" xreflabel="Preface">
|
|
<title>Preface</title>
|
|
|
|
<!-- ############ sect1 ############# -->
|
|
|
|
<sect1 id="section-preface-who" xreflabel="Who Should Read This Guide?">
|
|
<title>Who Should Read This Guide?</title>
|
|
<para>
|
|
This guide explains how to write new modules for &GStreamer;. The guide is
|
|
relevant to several groups of people:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Anyone who wants to add support for new ways of processing data in
|
|
&GStreamer;. For example, a person in this group might want to create
|
|
a new data format converter, a new visualization tool, or a new
|
|
decoder or encoder.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Anyone who wants to add support for new input and output devices. For
|
|
example, people in this group might want to add the ability to write
|
|
to a new video output system or read data from a digital camera or
|
|
special microphone.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Anyone who wants to extend &GStreamer; in any way. You need to have an
|
|
understanding of how the plugin system works before you can understand
|
|
the constraints that the plugin system places on the rest of the code.
|
|
Also, you might be surprised after reading this at how much can be
|
|
done with plugins.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
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
|
|
are just trying to get help with a &GStreamer; application, then you
|
|
should check with the user manual for that particular application.
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ############ sect1 ############# -->
|
|
|
|
<sect1 id="section-preface-reading" xreflabel="Preliminary Reading">
|
|
<title>Preliminary Reading</title>
|
|
<para>
|
|
This guide assumes that you are somewhat familiar with the basic workings
|
|
of &GStreamer;. For a gentle introduction to programming concepts in
|
|
&GStreamer;, you may wish to read the &GstAppDevMan; first. Also check out
|
|
the documentation available on the <ulink type="http"
|
|
url="http://gstreamer.freedesktop.org/documentation/">&GStreamer; web site</ulink>.
|
|
</para>
|
|
<para>
|
|
Since &GStreamer; adheres to the GObject programming model, this guide
|
|
also assumes that you understand the basics of <ulink type="http"
|
|
url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject</ulink>
|
|
programming. There are several good introductions to the GObject library,
|
|
including the <emphasis><ulink type="http"
|
|
url="http://www.gtk.org/tutorial/">GTK+ Tutorial</ulink></emphasis> and
|
|
the <emphasis><ulink type="http"
|
|
url="http://www.le-hacker.org/papers/gobject/index.html">Glib Object
|
|
system</ulink></emphasis>.
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ############ sect1 ############# -->
|
|
|
|
<sect1 id="section-preface-structure" xreflabel="Structure of This Guide">
|
|
<title>Structure of This Guide</title>
|
|
<para>
|
|
To help you navigate through this guide, it is divided into several large
|
|
parts. Each part addresses a particular broad topic concerning &GStreamer;
|
|
plugin development. The parts of this guide are laid out in the following
|
|
order:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<xref linkend="part-building"/> -
|
|
Introduction to the structure of a plugin, using an example audio
|
|
filter for illustration.
|
|
</para>
|
|
<para>
|
|
This part covers all the basic steps you generally need to perform
|
|
to build a plugin, such as registering the element with &GStreamer;
|
|
and setting up the basics so it can receive data from and send data
|
|
to neighbour elements. The discussion begins by giving examples of
|
|
generating the basic structures and registering an element in
|
|
<xref linkend="chapter-building-boiler"/>. Then, you will learn how
|
|
to write the code to get a basic filter plugin working in <xref
|
|
linkend="chapter-building-pads"/>, <xref
|
|
linkend="chapter-building-chainfn"/> and <xref
|
|
linkend="chapter-statemanage-states"/>.
|
|
</para>
|
|
<para>
|
|
After that, we will show some of the GObject concepts on how to
|
|
make an element configurable for applications and how to do
|
|
application-element interaction in
|
|
<xref linkend="chapter-building-args"/> and <xref
|
|
linkend="chapter-building-signals"/>. Next, you will learn to build
|
|
a quick test application to test all that you've just learned in
|
|
<xref linkend="chapter-building-testapp"/>. We will just touch upon
|
|
basics here. For full-blown application development, you should
|
|
look at <ulink type="http"
|
|
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/index.html">the
|
|
Application Development Manual</ulink>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<xref linkend="part-advanced"/> -
|
|
Information on advanced features of &GStreamer; plugin development.
|
|
</para>
|
|
<para>
|
|
After learning about the basic steps, you should be able to create a
|
|
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 scheduling,
|
|
media type definitions in &GStreamer;, clocks, interfaces and
|
|
tagging. Since these features are purpose-specific, you can read them
|
|
in any order, most of them don't require knowledge from other
|
|
sections.
|
|
</para>
|
|
<para>
|
|
The first chapter, named <xref linkend="chapter-scheduling"/>,
|
|
will explain some of the basics of element scheduling. It is not
|
|
very in-depth, but is mostly some sort of an introduction on why
|
|
other things work as they do. Read this chapter if you're interested
|
|
in &GStreamer; internals. Next, we will apply this knowledge and
|
|
discuss another type of data transmission than what you learned in
|
|
<xref linkend="chapter-building-chainfn"/>: <xref
|
|
linkend="chapter-scheduling"/>. Loop-based elements will give
|
|
you more control over input rate. This is useful when writing, for
|
|
example, muxers or demuxers.
|
|
</para>
|
|
<para>
|
|
Next, we will discuss media identification in &GStreamer; in <xref
|
|
linkend="chapter-building-types"/>. You will learn how to define
|
|
new media types and get to know a list of standard media types
|
|
defined in &GStreamer;.
|
|
</para>
|
|
<para>
|
|
In the next chapter, you will learn the concept of request- and
|
|
sometimes-pads, which are pads that are created dynamically, either
|
|
because the application asked for it (request) or because the media
|
|
stream requires it (sometimes). This will be in <xref
|
|
linkend="chapter-advanced-request"/>.
|
|
</para>
|
|
<para>
|
|
The next chapter, <xref linkend="chapter-advanced-clock"/>, will
|
|
explain the concept of clocks in &GStreamer;. You need this
|
|
information when you want to know how elements should achieve
|
|
audio/video synchronization.
|
|
</para>
|
|
<para>
|
|
The next few chapters will discuss advanced ways of doing
|
|
application-element interaction. Previously, we learned on the
|
|
GObject-ways of doing this in <xref linkend="chapter-building-args"/>
|
|
and <xref linkend="chapter-building-signals"/>. We will discuss
|
|
dynamic parameters, which are a way of defining element behaviour
|
|
over time in advance, in <xref linkend="chapter-dparams"/>. Next,
|
|
you will learn about interfaces in <xref
|
|
linkend="chapter-advanced-interfaces"/>. Interfaces are very target-
|
|
specific ways of application-element interaction, based on GObject's
|
|
GInterface. Lastly, you will learn about how metadata is handled in
|
|
&GStreamer; in <xref linkend="chapter-advanced-tagging"/>.
|
|
</para>
|
|
<para>
|
|
The last chapter, <xref linkend="chapter-advanced-events"/>, will
|
|
discuss the concept of events in &GStreamer;. Events are, on the
|
|
one hand, another way of doing application-element interaction. It
|
|
takes care of seeking, for example. On the other hand, it is also
|
|
a way in which elements interact with each other, such as letting
|
|
each other know about media stream discontinuities, forwarding tags
|
|
inside a pipeline and so on.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<xref linkend="part-other"/> - Explanation
|
|
of writing other plugin types.
|
|
</para>
|
|
<para>
|
|
Because the first two parts of the guide use an audio filter as an
|
|
example, the concepts introduced apply to filter plugins. But many of
|
|
the concepts apply equally to other plugin types, including sources,
|
|
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="chapter-other-source"/>,
|
|
<xref linkend="chapter-other-sink"/>, <xref
|
|
linkend="chapter-other-oneton"/>, <xref
|
|
linkend="chapter-other-ntoone"/> and <xref
|
|
linkend="chapter-other-manager"/>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<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. Most of this section
|
|
is not yet finished.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The remainder of this introductory part of the guide presents a short
|
|
overview of the basic concepts involved in &GStreamer; plugin development.
|
|
Topics covered include <xref linkend="section-basics-elements"/>, <xref
|
|
linkend="section-basics-pads"/>, <xref linkend="section-basics-data"/> and
|
|
<xref linkend="section-basics-types"/>. If you are already familiar with
|
|
this information, you can use this short overview to refresh your memory,
|
|
or you can skip to <xref linkend="part-building"/>.
|
|
</para>
|
|
<para>
|
|
As you can see, there a lot to learn, so let's get started!
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Creating compound and complex elements by extending from a GstBin.
|
|
This will allow you to create plugins that have other plugins embedded
|
|
in them.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Adding new mime-types to the registry along with typedetect functions.
|
|
This will allow your plugin to operate on a completely new media type.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
</chapter>
|