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-intro-what"><!-- synchronize with AppDevMan -->
  10     <title>What is &GStreamer;?</title>
  11     <para>
  12       &GStreamer; is a framework for creating streaming media applications.
  13       The fundamental design comes from the video pipeline at Oregon Graduate
  14       Institute, as well as some ideas from DirectShow.
  15     </para>
  16
  17     <para>
  18       &GStreamer;'s development framework makes it possible to write any
  19       type of streaming multimedia application. The &GStreamer; framework
  20       is designed to make it easy to write applications that handle audio
  21       or video or both. It isn't restricted to audio and video, and can
  22       process any kind of data flow.
  23       The pipeline design is made to have little overhead above what the
  24       applied filters induce. This makes &GStreamer; a good framework for
  25       designing even high-end audio applications which put high demands on
  26       latency.
  27     </para>
  28
  29     <para>
  30       One of the the most obvious uses of &GStreamer; is using it to build
  31       a media player. &GStreamer; already includes components for building a
  32       media player that can support a very wide variety of formats, including
  33       MP3, Ogg/Vorbis, MPEG-1/2, AVI, Quicktime, mod, and more. &GStreamer;,
  34       however, is much more than just another media player. Its main advantages
  35       are that the pluggable components can be mixed and matched into arbitrary
  36       pipelines so that it's possible to write a full-fledged video or audio
  37       editing application.
  38     </para>
  39
  40     <para>
  41       The framework is based on plugins that will provide the various codec
  42       and other functionality. The plugins can be linked and arranged in
  43       a pipeline. This pipeline defines the flow of the data. Pipelines can
  44       also be edited with a GUI editor and saved as XML so that pipeline
  45       libraries can be made with a minimum of effort.
  46     </para>
  47
  48     <para>
  49       The &GStreamer; core function is to provide a framework for plugins,
  50       data flow and media type handling/negotiation. It also provides an
  51       API to write applications using the various plugins.
  52     </para>
  53   </sect1>
  54
  55   <!-- ############ sect1 ############# -->
  56
  57   <sect1 id="section-preface-who" xreflabel="Who Should Read This Guide?">
  58     <title>Who Should Read This Guide?</title>
  59     <para>
  60       This guide explains how to write new modules for &GStreamer;. The guide is
  61       relevant to several groups of people:
  62     </para>
  63     <itemizedlist>
  64       <listitem>
  65         <para>
  66           Anyone who wants to add support for new ways of processing data in
  67           &GStreamer;. For example, a person in this group might want to create
  68           a new data format converter, a new visualization tool, or a new
  69           decoder or encoder.
  70         </para>
  71       </listitem>
  72       <listitem>
  73         <para>
  74           Anyone who wants to add support for new input and output devices. For
  75           example, people in this group might want to add the ability to write
  76           to a new video output system or read data from a digital camera or
  77           special microphone.
  78         </para>
  79       </listitem>
  80       <listitem>
  81         <para>
  82           Anyone who wants to extend &GStreamer; in any way. You need to have an
  83           understanding of how the plugin system works before you can understand
  84           the constraints that the plugin system places on the rest of the code.
  85           Also, you might be surprised after reading this at how much can be
  86           done with plugins.
  87         </para>
  88       </listitem>
  89     </itemizedlist>
  90     <para>
  91       This guide is not relevant to you if you only want to use the existing
  92       functionality of &GStreamer;, or if you just want to use an application
  93       that uses &GStreamer;. If you are only interested in using existing
  94       plugins to write a new application - and there are quite a lot of
  95       plugins already - you might want to check the &GstAppDevMan;. If you
  96       are just trying to get help with a &GStreamer; application, then you
  97       should check with the user manual for that particular application.
  98     </para>
  99   </sect1>
 100
 101   <!-- ############ sect1 ############# -->
 102
 103   <sect1 id="section-preface-reading" xreflabel="Preliminary Reading">
 104     <title>Preliminary Reading</title>
 105     <para>
 106       This guide assumes that you are somewhat familiar with the basic workings
 107       of &GStreamer;. For a gentle introduction to programming concepts in
 108       &GStreamer;, you may wish to read the &GstAppDevMan; first.
 109       Also check out the other documentation available on the <ulink type="http"
 110       url="http://gstreamer.freedesktop.org/documentation/">&GStreamer; web site</ulink>.
 111     </para>
 112     <para><!-- synchronize with AppDevMan -->
 113       In order to understand this manual, you will need to have a basic
 114       understanding of the C language.
 115       Since &GStreamer; adheres to the GObject programming model, this guide
 116       also assumes that you understand the basics of <ulink type="http"
 117       url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject</ulink>
 118       programming.
 119       You may also want to have a look
 120       at Eric Harlow's book <emphasis>Developing Linux Applications with
 121       GTK+ and GDK</emphasis>.
 122     </para>
 123   </sect1>
 124
 125   <!-- ############ sect1 ############# -->
 126
 127   <sect1 id="section-preface-structure" xreflabel="Structure of This Guide">
 128     <title>Structure of This Guide</title>
 129     <para>
 130       To help you navigate through this guide, it is divided into several large
 131       parts. Each part addresses a particular broad topic concerning &GStreamer;
 132       plugin development. The parts of this guide are laid out in the following
 133       order:
 134     </para>
 135     <itemizedlist>
 136       <listitem>
 137         <para>
 138           <xref linkend="part-building"/> -
 139           Introduction to the structure of a plugin, using an example audio
 140           filter for illustration.
 141         </para>
 142         <para>
 143           This part covers all the basic steps you generally need to perform
 144           to build a plugin, such as registering the element with &GStreamer;
 145           and setting up the basics so it can receive data from and send data
 146           to neighbour elements. The discussion begins by giving examples of
 147           generating the basic structures and registering an element in
 148           <xref linkend="chapter-building-boiler"/>. Then, you will learn how
 149           to write the code to get a basic filter plugin working in <xref
 150           linkend="chapter-building-pads"/>, <xref
 151           linkend="chapter-building-chainfn"/> and <xref
 152           linkend="chapter-statemanage-states"/>.
 153         </para>
 154         <para>
 155           After that, we will show some of the GObject concepts on how to
 156           make an element configurable for applications and how to do
 157           application-element interaction in
 158           <xref linkend="chapter-building-args"/> and <xref
 159           linkend="chapter-building-signals"/>. Next, you will learn to build
 160           a quick test application to test all that you've just learned in
 161           <xref linkend="chapter-building-testapp"/>. We will just touch upon
 162           basics here. For full-blown application development, you should
 163           look at <ulink type="http"
 164           url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/index.html">the
 165           Application Development Manual</ulink>.
 166         </para>
 167       </listitem>
 168       <listitem>
 169         <para>
 170           <xref linkend="part-advanced"/> -
 171           Information on advanced features of &GStreamer; plugin development.
 172         </para>
 173         <para>
 174           After learning about the basic steps, you should be able to create a
 175           functional audio or video filter plugin with some nice features.
 176           However, &GStreamer; offers more for plugin writers. This part of the
 177           guide includes chapters on more advanced topics, such as scheduling,
 178           media type definitions in &GStreamer;, clocks, interfaces and
 179           tagging. Since these features are purpose-specific, you can read them
 180           in any order, most of them don't require knowledge from other
 181           sections.
 182         </para>
 183         <para>
 184           The first chapter, named <xref linkend="chapter-scheduling"/>,
 185           will explain some of the basics of element scheduling. It is not
 186           very in-depth, but is mostly some sort of an introduction on why
 187           other things work as they do. Read this chapter if you're interested
 188           in &GStreamer; internals. Next, we will apply this knowledge and
 189           discuss another type of data transmission than what you learned in
 190           <xref linkend="chapter-building-chainfn"/>: <xref
 191           linkend="chapter-scheduling"/>. Loop-based elements will give
 192           you more control over input rate. This is useful when writing, for
 193           example, muxers or demuxers.
 194         </para>
 195         <para>
 196           Next, we will discuss media identification in &GStreamer; in <xref
 197           linkend="chapter-building-types"/>. You will learn how to define
 198           new media types and get to know a list of standard media types
 199           defined in &GStreamer;.
 200         </para>
 201         <para>
 202           In the next chapter, you will learn the concept of request- and
 203           sometimes-pads, which are pads that are created dynamically, either
 204           because the application asked for it (request) or because the media
 205           stream requires it (sometimes). This will be in <xref
 206           linkend="chapter-advanced-request"/>.
 207         </para>
 208         <para>
 209           The next chapter, <xref linkend="chapter-advanced-clock"/>, will
 210           explain the concept of clocks in &GStreamer;. You need this
 211           information when you want to know how elements should achieve
 212           audio/video synchronization.
 213         </para>
 214         <para>
 215           The next few chapters will discuss advanced ways of doing
 216           application-element interaction. Previously, we learned on the
 217           GObject-ways of doing this in <xref linkend="chapter-building-args"/>
 218           and <xref linkend="chapter-building-signals"/>. We will discuss
 219           dynamic parameters, which are a way of defining element behaviour
 220           over time in advance, in <xref linkend="chapter-dparams"/>. Next,
 221           you will learn about interfaces in <xref
 222           linkend="chapter-advanced-interfaces"/>. Interfaces are very target-
 223           specific ways of application-element interaction, based on GObject's
 224           GInterface. Lastly, you will learn about how metadata is handled in
 225           &GStreamer; in <xref linkend="chapter-advanced-tagging"/>.
 226         </para>
 227         <para>
 228           The last chapter, <xref linkend="chapter-advanced-events"/>, will
 229           discuss the concept of events in &GStreamer;. Events are, on the
 230           one hand, another way of doing application-element interaction. It
 231           takes care of seeking, for example. On the other hand, it is also
 232           a way in which elements interact with each other, such as letting
 233           each other know about media stream discontinuities, forwarding tags
 234           inside a pipeline and so on.
 235         </para>
 236       </listitem>
 237       <listitem>
 238         <para>
 239           <xref linkend="part-other"/> - Explanation
 240           of writing other plugin types.
 241         </para>
 242         <para>
 243           Because the first two parts of the guide use an audio filter as an
 244           example, the concepts introduced apply to filter plugins. But many of
 245           the concepts apply equally to other plugin types, including sources,
 246           sinks, and autopluggers. This part of the guide presents the issues
 247           that arise when working on these more specialized plugin types. The
 248           chapter starts with a special focus on elements that can be written
 249           using a base-class (<xref linkend="chapter-other-base"/>), and
 250           later also goes into writing special types of elements in
 251           <xref linkend="chapter-other-oneton"/>, <xref
 252           linkend="chapter-other-ntoone"/> and <xref
 253           linkend="chapter-other-manager"/>.
 254         </para>
 255       </listitem>
 256       <listitem>
 257         <para>
 258           <xref linkend="part-appendix"/> - Further
 259           information for plugin developers.
 260         </para>
 261         <para>
 262           The appendices contain some information that stubbornly refuses
 263           to fit cleanly in other sections of the guide. Most of this section
 264           is not yet finished.
 265         </para>
 266       </listitem>
 267     </itemizedlist>
 268
 269     <para>
 270       The remainder of this introductory part of the guide presents a short
 271       overview of the basic concepts involved in &GStreamer; plugin development.
 272       Topics covered include <xref linkend="section-basics-elements"/>, <xref
 273       linkend="section-basics-pads"/>, <xref linkend="section-basics-data"/> and
 274       <xref linkend="section-basics-types"/>. If you are already familiar with
 275       this information, you can use this short overview to refresh your memory,
 276       or you can skip to <xref linkend="part-building"/>.
 277     </para>
 278     <para>
 279       As you can see, there a lot to learn, so let's get started!
 280     </para>
 281
 282     <itemizedlist>
 283       <listitem>
 284         <para>
 285           Creating compound and complex elements by extending from a GstBin.
 286           This will allow you to create plugins that have other plugins embedded
 287           in them.
 288         </para>
 289       </listitem>
 290       <listitem>
 291         <para>
 292           Adding new mime-types to the registry along with typedetect functions.
 293           This will allow your plugin to operate on a completely new media type.
 294         </para>
 295       </listitem>
 296     </itemizedlist>
 297   </sect1>
 298 </chapter>