mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-26 19:51:11 +00:00
198 lines
8.6 KiB
XML
198 lines
8.6 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.net/docs/">&GStreamer; web site</ulink>,
|
|
particularly the documents available in the <ulink type="http"
|
|
url="http://gstreamer.net/wiki/">&GStreamer; wiki</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>.
|
|
</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>
|