docs/pwg/intro-preface.xml

   1
   2 <!-- ############ chapter ############# -->
   3
   4 <chapter id="chapter-intro-preface" xreflabel="Preface">
   5   <title>Preface</title>
   6
   7   <!-- ############ sect1 ############# -->
   8
   9   <sect1 id="section-preface-who" xreflabel="Who Should Read This Guide?">
  10     <title>Who Should Read This Guide?</title>
  11     <para>
  12       This guide explains how to write new modules for &GStreamer;. The guide is
  13       relevant to several groups of people:
  14     </para>
  15     <itemizedlist>
  16       <listitem>
  17         <para>
  18           Anyone who wants to add support for new ways of processing data in
  19           &GStreamer;. For example, a person in this group might want to create
  20           a new data format converter, a new visualization tool, or a new
  21           decoder or encoder.
  22         </para>
  23       </listitem>
  24       <listitem>
  25         <para>
  26           Anyone who wants to add support for new input and output devices. For
  27           example, people in this group might want to add the ability to write
  28           to a new video output system or read data from a digital camera or
  29           special microphone.
  30         </para>
  31       </listitem>
  32       <listitem>
  33         <para>
  34           Anyone who wants to extend &GStreamer; in any way. You need to have an
  35           understanding of how the plugin system works before you can understand
  36           the constraints that the plugin system places on the rest of the code.
  37           Also, you might be surprised after reading this at how much can be
  38           done with plugins.
  39         </para>
  40       </listitem>
  41     </itemizedlist>
  42     <para>
  43       This guide is not relevant to you if you only want to use the existing
  44       functionality of &GStreamer;, or if you just want to use an application
  45       that uses &GStreamer;. If you are only interested in using existing
  46       plugins to write a new application - and there are quite a lot of
  47       plugins already - you might want to check the &GstAppDevMan;. If you
  48       are just trying to get help with a &GStreamer; application, then you
  49       should check with the user manual for that particular application.
  50     </para>
  51   </sect1>
  52
  53   <!-- ############ sect1 ############# -->
  54
  55   <sect1 id="section-preface-reading" xreflabel="Preliminary Reading">
  56     <title>Preliminary Reading</title>
  57     <para>
  58       This guide assumes that you are somewhat familiar with the basic workings
  59       of &GStreamer;. For a gentle introduction to programming concepts in
  60       &GStreamer;, you may wish to read the &GstAppDevMan; first. Also check out
  61       the documentation available on the <ulink type="http"
  62       url="http://gstreamer.net/docs/">&GStreamer; web site</ulink>,
  63       particularly the documents available in the <ulink type="http"
  64       url="http://gstreamer.net/wiki/">&GStreamer; wiki</ulink>.
  65     </para>
  66     <para>
  67       Since &GStreamer; adheres to the GObject programming model, this guide
  68       also assumes that you understand the basics of <ulink type="http"
  69       url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject</ulink>
  70       programming. There are several good introductions to the GObject library,
  71       including the <emphasis><ulink type="http"
  72       url="http://www.gtk.org/tutorial/">GTK+ Tutorial</ulink></emphasis>.
  73     </para>
  74   </sect1>
  75
  76   <!-- ############ sect1 ############# -->
  77
  78   <sect1 id="section-preface-structure" xreflabel="Structure of This Guide">
  79     <title>Structure of This Guide</title>
  80     <para>
  81       To help you navigate through this guide, it is divided into several large
  82       parts. Each part addresses a particular broad topic concerning &GStreamer;
  83       plugin development. The parts of this guide are laid out in the following
  84       order:
  85     </para>
  86     <itemizedlist>
  87       <listitem>
  88         <para>
  89           <xref linkend="part-building"/> -
  90           Introduction to the structure of a plugin, using an example audio
  91           filter for illustration.
  92         </para>
  93         <para>
  94           This part covers all the basic steps you generally need to perform to
  95           build a plugin. The discussion begins by giving examples of generating
  96           the basic structures with <xref linkend="chapter-building-boiler"/>. Then
  97           you will learn how to write the code to get a basic filter plugin
  98           working: These steps include chapters on <xref
  99           linkend="chapter-building-types"/>, <xref linkend="chapter-building-pads"/>,
 100           <xref linkend="chapter-building-chainfn"/>, and <!-- <xref
 101           linkend="chapter-building-state"/>--> (WRITEME: building state).
 102         </para>
 103         <para>
 104           After you have finished the first steps, you will be able to create a
 105           working plugin, but your new plugin might not have all the
 106           functionality you need. To provide some standard functionality, you
 107           will learn how to add more features to a new plugin. These features
 108           are described in the chapters on
 109           <!--FIXME: WRITEME <xref linkend="chapter-building-props"/> -->
 110           (WRITEME)
 111           and <xref linkend="chapter-building-signals"/>. Finally, you will see in
 112           <!--<xref linkend="chapter-building-testapp"/>-->(WRITEME)
 113           how to write a short test
 114           application to try out your new plugin.
 115         </para>
 116       </listitem>
 117       <listitem>
 118         <para>
 119           <xref linkend="part-advanced"/> -
 120           Information on advanced features of &GStreamer; plugin development.
 121         </para>
 122         <para>
 123           After learning about the basic steps, you should be able to create a
 124           functional audio or video filter plugin with some nice features.
 125           However, &GStreamer; offers more for plugin writers. This part of the
 126           guide includes chapters on more advanced topics, such as <xref
 127           linkend="chapter-advanced-request"/>, <!-- <xref
 128           linkend="chapter-advanced-clock"/>, <xref
 129           linkend="chapter-advanced-scheduling"/>, <xref
 130           linkend="chapter-advanced-dparams"/>, and <xref
 131           linkend="chapter-advanced-midi"/>-->. Since these features are more advanced,
 132           the chapters can basically be read in any order, as you find that your
 133           plugins require these features.
 134         </para>
 135       </listitem>
 136       <listitem>
 137         <para>
 138           <xref linkend="part-other"/> - Explanation
 139           of writing other plugin types.
 140         </para>
 141         <para>
 142           Because the first two parts of the guide use an audio filter as an
 143           example, the concepts introduced apply to filter plugins. But many of
 144           the concepts apply equally to other plugin types, including sources,
 145           sinks, and autopluggers. This part of the guide presents the issues
 146           that arise when working on these more specialized plugin types. The
 147           part includes chapters on <xref linkend="chapter-other-source"/>, <xref
 148           linkend="chapter-other-sink"/>, <!-- FIXME: WRITEME
 149           <xref linkend="chapter-other-scheduler"/>,--> and
 150           <xref linkend="chapter-other-autoplugger"/>.
 151         </para>
 152       </listitem>
 153       <listitem>
 154         <para>
 155           <xref linkend="part-appendix"/> - Further
 156           information for plugin developers.
 157         </para>
 158         <para>
 159           The appendices contain some information that stubbornly refuses to fit
 160           cleanly in other sections of the guide. This information includes
 161           <!-- FIXME: WRITEME
 162           <xref linkend="chapter-appendix-checklist"/>--> (WRITEME) and
 163           <!-- <xref
 164           linkend="chapter-appendix-python"/>.--> FIXME: organize better.
 165         </para>
 166       </listitem>
 167     </itemizedlist>
 168
 169     <para>
 170       The remainder of this introductory part of the guide presents a short
 171       overview of the basic concepts involved in &GStreamer; plugin development.
 172       Topics covered include <xref linkend="section-basics-elements"/>, <xref
 173       linkend="section-basics-pads"/>, <xref linkend="section-basics-data"/> and
 174       <xref linkend="section-basics-types"/>. If you are already familiar with
 175       this information, you can use this short overview to refresh your memory,
 176       or you can skip to <xref linkend="part-building"/>.
 177     </para>
 178     <para>
 179       As you can see, there a lot to learn, so let's get started!
 180     </para>
 181
 182     <itemizedlist>
 183       <listitem>
 184         <para>
 185           Creating compound and complex elements by extending from a GstBin.
 186           This will allow you to create plugins that have other plugins embedded
 187           in them.
 188         </para>
 189       </listitem>
 190       <listitem>
 191         <para>
 192           Adding new mime-types to the registry along with typedetect functions.
 193           This will allow your plugin to operate on a completely new media type.
 194         </para>
 195       </listitem>
 196     </itemizedlist>
 197   </sect1>
 198 </chapter>