mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-12 11:26:39 +00:00
626cbdc8b2
Original commit message from CVS: cleanup of unused and forgoten sections fixed links from the manual and the pwg to the API docs added more notes to README
200 lines
8.7 KiB
XML
200 lines
8.7 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. The discussion begins by giving examples of generating
|
|
the basic structures with <xref linkend="chapter-building-boiler"/>. Then
|
|
you will learn how to write the code to get a basic filter plugin
|
|
working: These steps include chapters on <xref
|
|
linkend="chapter-building-types"/>, <xref linkend="chapter-building-pads"/>,
|
|
<xref linkend="chapter-building-chainfn"/>, and <!-- <xref
|
|
linkend="chapter-building-state"/>--> (WRITEME: building state).
|
|
</para>
|
|
<para>
|
|
After you have finished the first steps, you will be able to create a
|
|
working plugin, but your new plugin might not have all the
|
|
functionality you need. To provide some standard functionality, you
|
|
will learn how to add more features to a new plugin. These features
|
|
are described in the chapters on
|
|
<!--FIXME: WRITEME <xref linkend="chapter-building-props"/> -->
|
|
(WRITEME)
|
|
and <xref linkend="chapter-building-signals"/>.
|
|
Finally, you will see in
|
|
<!--<xref linkend="chapter-building-testapp"/>-->(WRITEME)
|
|
how to write a short test
|
|
application to try out your new plugin.
|
|
</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 <xref
|
|
linkend="chapter-advanced-request"/>, <!-- <xref
|
|
linkend="chapter-advanced-clock"/>, <xref
|
|
linkend="chapter-advanced-scheduling"/>, <xref
|
|
linkend="chapter-advanced-dparams"/>, and <xref
|
|
linkend="chapter-advanced-midi"/>-->. Since these features are more advanced,
|
|
the chapters can basically be read in any order, as you find that your
|
|
plugins require these features.
|
|
</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"/>, <!-- FIXME: WRITEME
|
|
<xref linkend="chapter-other-scheduler"/>,--> and
|
|
<xref linkend="chapter-other-autoplugger"/>.
|
|
</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. This information includes
|
|
<!-- FIXME: WRITEME
|
|
<xref linkend="chapter-appendix-checklist"/>--> (WRITEME) and
|
|
<!-- <xref
|
|
linkend="chapter-appendix-python"/>.--> FIXME: organize better.
|
|
</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>
|