docs/pwg/pwg.xml

   1 <?xml version='1.0' encoding='utf-8'?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % image-entities SYSTEM "image.entities">
   5 %image-entities;
   6 <!ENTITY % version-entities SYSTEM "version.entities">
   7 %version-entities;
   8
   9 <!ENTITY TITLEPAGE            SYSTEM "titlepage.xml">
  10
  11 <!-- Part 1: Introduction -->
  12 <!ENTITY INTRO_PREFACE        SYSTEM "intro-preface.xml">
  13 <!ENTITY INTRO_BASICS         SYSTEM "intro-basics.xml">
  14
  15 <!-- Part 2: Building a Plugin -->
  16 <!ENTITY BUILDING_BOILER      SYSTEM "building-boiler.xml">
  17 <!ENTITY BUILDING_DEBUG       SYSTEM "building-debug.xml">
  18 <!ENTITY BUILDING_PADS        SYSTEM "building-pads.xml">
  19 <!ENTITY BUILDING_CHAINFN     SYSTEM "building-chainfn.xml">
  20 <!ENTITY BUILDING_EVENTFN     SYSTEM "building-eventfn.xml">
  21 <!ENTITY BUILDING_QUERYFN     SYSTEM "building-queryfn.xml">
  22 <!ENTITY BUILDING_STATE       SYSTEM "building-state.xml">
  23 <!ENTITY BUILDING_PROPS       SYSTEM "building-props.xml">
  24 <!ENTITY BUILDING_SIGNALS     SYSTEM "building-signals.xml">
  25 <!ENTITY BUILDING_TESTAPP     SYSTEM "building-testapp.xml">
  26
  27 <!-- Part 3: Advanced Filter Concepts -->
  28 <!ENTITY ADVANCED_REQUEST     SYSTEM "advanced-request.xml">
  29 <!ENTITY ADVANCED_SCHEDULING  SYSTEM "advanced-scheduling.xml">
  30 <!ENTITY ADVANCED_NEGOTIATION SYSTEM "advanced-negotiation.xml">
  31 <!ENTITY ADVANCED_ALLOCATION  SYSTEM "advanced-allocation.xml">
  32 <!ENTITY ADVANCED_TYPES       SYSTEM "advanced-types.xml">
  33 <!ENTITY ADVANCED_EVENTS      SYSTEM "advanced-events.xml">
  34 <!ENTITY ADVANCED_CLOCK       SYSTEM "advanced-clock.xml">
  35 <!ENTITY ADVANCED_QOS         SYSTEM "advanced-qos.xml">
  36 <!ENTITY ADVANCED_DPARAMS     SYSTEM "advanced-dparams.xml">
  37 <!ENTITY ADVANCED_INTERFACES  SYSTEM "advanced-interfaces.xml">
  38 <!ENTITY ADVANCED_TAGGING     SYSTEM "advanced-tagging.xml">
  39
  40 <!-- Part 4: Creating special element types -->
  41 <!ENTITY OTHER_BASE           SYSTEM "other-base.xml">
  42 <!ENTITY OTHER_ONETON         SYSTEM "other-oneton.xml">
  43 <!ENTITY OTHER_NTOONE         SYSTEM "other-ntoone.xml">
  44 <!ENTITY OTHER_MANAGER        SYSTEM "other-manager.xml">
  45
  46 <!-- Appendices -->
  47 <!ENTITY APPENDIX_CHECKLIST   SYSTEM "appendix-checklist.xml">
  48 <!ENTITY APPENDIX_PORTING     SYSTEM "appendix-porting.xml">
  49 <!ENTITY APPENDIX_LICENSING   SYSTEM "appendix-licensing.xml">
  50 <!ENTITY APPENDIX_PYTHON      SYSTEM "appendix-python.xml">
  51
  52 <!ENTITY GStreamer    "<application>GStreamer</application>">
  53 <!ENTITY GstAppDevMan "<emphasis>GStreamer Application Development Manual</emphasis>">
  54 <!ENTITY GstLibRef    "<emphasis>GStreamer Library Reference</emphasis>">
  55 ]>
  56
  57 <book id="index">
  58   &TITLEPAGE;
  59
  60   <!-- ############# Introduction - part ############### -->
  61
  62   <part id="part-introduction" xreflabel="Introduction">
  63     <title>Introduction</title>
  64     <partintro>
  65       <para><!-- synchronize with AppDevMan -->
  66         &GStreamer; is an extremely powerful and versatile framework for creating
  67         streaming media applications. Many of the virtues of the &GStreamer;
  68         framework come from its modularity: &GStreamer; can seamlessly
  69         incorporate new plugin modules. But because modularity and power often
  70         come at a cost of greater complexity (consider, for example, <ulink
  71         type="http" url="http://www.omg.org/">CORBA</ulink>), writing new
  72         plugins is not always easy.
  73       </para>
  74       <para>
  75         This guide is intended to help you understand the &GStreamer; framework
  76         (version &GST_VERSION;) so you can develop new plugins to extend the
  77         existing functionality. The guide addresses most issues by following the
  78         development of an example plugin - an audio filter plugin -
  79         written in C. However, the later parts of the guide also present some
  80         issues involved in writing other types of plugins, and the end of the
  81         guide describes some of the Python bindings for &GStreamer;.
  82       </para>
  83     </partintro>
  84
  85     &INTRO_PREFACE;
  86     &INTRO_BASICS;
  87   </part>
  88
  89   <!-- ############ Building a Plugin - part ############# -->
  90
  91   <part id="part-building" xreflabel="Building a Plugin">
  92     <title>Building a Plugin</title>
  93     <partintro>
  94       <para>
  95         You are now ready to learn how to build a plugin. In this part of the
  96         guide, you will learn how to apply basic &GStreamer;
  97         programming concepts to write a simple plugin. The previous parts of the
  98         guide have contained no explicit example code, perhaps making things a
  99         bit abstract and difficult to understand. In contrast, this section will
 100         present both applications and code by following the development of an
 101         example audio filter plugin called <quote>MyFilter</quote>.
 102       </para>
 103       <para>
 104         The example filter element will begin with a single input pad and a
 105         single
 106         output pad. The filter will, at first, simply pass media and event data
 107         from its sink pad to its source pad without modification. But by the end
 108         of this part of the guide, you will learn to add some more interesting
 109         functionality, including properties and signal handlers. And after
 110         reading the next part of the guide, <xref linkend="part-advanced"/>, you
 111         will be able to add even more functionality to your plugins.
 112       </para>
 113       <para>
 114         The example code used in this part of the guide can be found in
 115         <filename class="directory">examples/pwg/examplefilter/</filename> in
 116         your &GStreamer; directory.
 117       </para>
 118     </partintro>
 119
 120     &BUILDING_BOILER;
 121     &BUILDING_PADS;
 122     &BUILDING_CHAINFN;
 123     &BUILDING_EVENTFN;
 124     &BUILDING_QUERYFN;
 125     &BUILDING_STATE;
 126     &BUILDING_PROPS;
 127     &BUILDING_SIGNALS;
 128     &BUILDING_TESTAPP;
 129   </part>
 130
 131   <!-- ############ Advanced Filter Concepts - part ############# -->
 132
 133   <part id="part-advanced" xreflabel="Advanced Filter Concepts">
 134     <title>Advanced Filter Concepts</title>
 135     <partintro>
 136       <para>
 137         By now, you should be able to create basic filter elements that can
 138         receive and send data. This is the simple model that &GStreamer; stands
 139         for. But &GStreamer; can do much more than only this! In this chapter,
 140         various advanced topics will be discussed, such as scheduling, special
 141         pad types, clocking, events, interfaces, tagging and more. These topics
 142         are the sugar that makes &GStreamer; so easy to use for applications.
 143       </para>
 144     </partintro>
 145
 146     &ADVANCED_REQUEST;
 147     &ADVANCED_SCHEDULING;
 148     &ADVANCED_NEGOTIATION;
 149     &ADVANCED_ALLOCATION;
 150     &ADVANCED_TYPES;
 151     &ADVANCED_EVENTS;
 152     &ADVANCED_CLOCK;
 153     &ADVANCED_QOS;
 154     &ADVANCED_DPARAMS;
 155     &ADVANCED_INTERFACES;
 156     &ADVANCED_TAGGING;
 157
 158     <!-- FIXME: add querying, event handling and conversion -->
 159
 160   </part>
 161
 162   <!-- ############ Creating special element types - part ############# -->
 163
 164   <part id="part-other" xreflabel="Creating special element types">
 165     <title>Creating special element types</title>
 166     <partintro>
 167       <para>
 168         By now, we have looked at pretty much any feature that can be embedded
 169         into a &GStreamer; element. Most of this has been fairly low-level and
 170         given deep insights in how &GStreamer; works internally. Fortunately,
 171         &GStreamer; contains some easier-to-use interfaces to create such
 172         elements. In order to do that, we will look closer at the element
 173         types for which &GStreamer; provides base classes (sources, sinks and
 174         transformation elements). We will also look closer at some types of
 175         elements that require no specific coding such as scheduling-interaction
 176         or data passing, but rather require specific pipeline control (e.g.
 177         N-to-1 elements and managers).
 178       </para>
 179     </partintro>
 180
 181     &OTHER_BASE;
 182     &OTHER_ONETON;
 183     &OTHER_NTOONE;
 184     &OTHER_MANAGER;
 185   </part>
 186
 187   <!-- ############ Appendices - part ############# -->
 188
 189   <part id="part-appendix" xreflabel="Appendices">
 190     <title>Appendices</title>
 191     <partintro>
 192       <para>
 193         This chapter contains things that don't belong anywhere else.
 194       </para>
 195     </partintro>
 196
 197       &APPENDIX_CHECKLIST;
 198       &APPENDIX_PORTING;
 199       &APPENDIX_LICENSING;
 200       &APPENDIX_PYTHON;
 201   </part>
 202
 203 </book>