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