docs/manual/manual.xml

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % image-entities SYSTEM "image.entities">
%image-entities;
<!ENTITY % version-entities SYSTEM "version.entities">
%version-entities;
<!ENTITY % url-entities SYSTEM "url.entities">
%url-entities;

<!ENTITY EXAFOOT "
<footnote>
  <para>
    The code for this example is automatically extracted from
    the documentation and built under <filename>tests/examples/manual</filename>
    in the GStreamer tarball.
  </para>
</footnote>
">

<!ENTITY TITLEPAGE            SYSTEM "titlepage.xml">

<!-- Part 1: Overview -->
<!ENTITY INTRO                SYSTEM "intro-preface.xml">

<!ENTITY GSTREAMER            SYSTEM "intro-gstreamer.xml">
<!ENTITY MOTIVATION           SYSTEM "intro-motivation.xml">
<!ENTITY CONCEPTS             SYSTEM "intro-basics.xml">

<!-- Part 2: Basic Concepts -->
<!ENTITY INIT                 SYSTEM "basics-init.xml">
<!ENTITY ELEMENTS             SYSTEM "basics-elements.xml">
<!ENTITY BINS                 SYSTEM "basics-bins.xml">
<!ENTITY BUS                  SYSTEM "basics-bus.xml">
<!ENTITY PADS                 SYSTEM "basics-pads.xml">
<!ENTITY DATA                 SYSTEM "basics-data.xml">
<!ENTITY HELLOWORLD           SYSTEM "basics-helloworld.xml">

<!-- Part 3: Advanced Concepts -->
<!ENTITY QUERYEVENTS          SYSTEM "advanced-position.xml">
<!ENTITY METADATA             SYSTEM "advanced-metadata.xml">
<!ENTITY INTERFACES           SYSTEM "advanced-interfaces.xml">
<!ENTITY CLOCKS               SYSTEM "advanced-clocks.xml">
<!ENTITY BUFFERING            SYSTEM "advanced-buffering.xml">
<!ENTITY DPARAMS              SYSTEM "advanced-dparams.xml">
<!ENTITY THREADS              SYSTEM "advanced-threads.xml">
<!ENTITY AUTOPLUGGING         SYSTEM "advanced-autoplugging.xml">
<!ENTITY DATAACCESS           SYSTEM "advanced-dataaccess.xml">

<!-- Part 4: Higher-level interfaces -->
<!ENTITY PLAYBACK             SYSTEM "highlevel-playback.xml">

<!-- Appendices -->
<!ENTITY PROGRAMS             SYSTEM "appendix-programs.xml">
<!ENTITY COMPILING            SYSTEM "appendix-compiling.xml">
<!ENTITY CHECKLIST            SYSTEM "appendix-checklist.xml">
<!ENTITY PORTING              SYSTEM "appendix-porting.xml">
<!ENTITY INTEGRATION          SYSTEM "appendix-integration.xml">
<!ENTITY LICENSING            SYSTEM "appendix-licensing.xml">
<!ENTITY QUOTES               SYSTEM "appendix-quotes.xml">

<!ENTITY GStreamer    "<application>GStreamer</application>">
<!ENTITY GstPWG       "<emphasis>GStreamer Plugin Writer's Guide</emphasis>">
]>

<book id="index">
  &TITLEPAGE;
  
<!-- ############# Introduction ############### -->

<preface><title>Foreword</title>
      <para><!-- synchronize with PWG -->
        &GStreamer; is an extremely powerful and versatile framework for
        creating streaming media applications. Many of the virtues of the
        &GStreamer; framework come from its modularity: &GStreamer; can
        seamlessly incorporate new plugin modules. But because modularity
        and power often come at a cost of greater complexity, writing new
        applications is not always easy.
      </para>
      <para>
        This guide is intended to help you understand the &GStreamer;
        framework (version &GST_VERSION;) so you can develop applications
        based on it. The first chapters will focus on development of a
        simple audio player, with much effort going into helping you
        understand &GStreamer; concepts. Later chapters will go into
        more advanced topics related to media playback, but also at
        other forms of media processing (capture, editing, etc.).
      </para>
</preface>


<preface><title>Introduction</title>

  &INTRO;

</preface>

<!-- ############# Overview - part ############### -->

  <part id="part-introduction">
    <title>About GStreamer</title>
    <partintro>
      <para>
    This part gives you an overview of the technologies described in
    this book.
      </para>
    </partintro>

    &GSTREAMER;
    &MOTIVATION;
    &CONCEPTS;

  </part>

<!-- ############ Basic concepts - part ############# -->

  <part id="part-building">
    <title>Building an Application</title>
    <partintro>
      <para>
        In these chapters, we will discuss the basic concepts of &GStreamer;
        and the most-used objects, such as elements, pads and buffers. We
        will use a visual representation of these objects so that we can
        visualize the more complex pipelines you will learn to build later
        on. You will get a first glance at the &GStreamer; API, which should
        be enough for building elementary applications. Later on in this
        part, you will also learn to build a basic command-line application.
      </para>
      <para>
        Note that this part will give a look into the low-level API and
        concepts of &GStreamer;. Once you're going to build applications,
        you might want to use higher-level APIs. Those will be discussed
        later on in this manual.
      </para>
    </partintro>

    &INIT;
    &ELEMENTS;
    &BINS;
    &BUS;
    &PADS;
    &DATA;
    &HELLOWORLD;

  </part>

<!-- ############ Advanced GStreamer - part ############# -->

  <part id="part-advanced">
    <title>Advanced &GStreamer; concepts</title>
    <partintro>
      <para>
        In this part we will cover the more advanced features of &GStreamer;.
	With the basics you learned in the previous part you should be 
	able to create a <emphasis>simple</emphasis> application. However,
        &GStreamer; provides much more candy than just the basics of playing
        back audio files. In this chapter, you will learn more of the
	low-level features and internals of &GStreamer;.
      </para>
      <para>
        Some parts of this part will serve mostly as an explanation of
        how &GStreamer; works internally; they are not actually needed for
        actual application development. This includes chapters such as the
        ones covering scheduling, autoplugging and synchronization. Other
        chapters, however, discuss more advanced ways of
        pipeline-application interaction, and can turn out to be very useful
        for certain applications. This includes the chapters on metadata,
        querying and events, interfaces, dynamic parameters and pipeline
        data manipulation.
      </para>
    </partintro>

    &QUERYEVENTS;
    &METADATA;
    &INTERFACES;
    &CLOCKS;
    &BUFFERING;
    &DPARAMS;
    &THREADS;
    &AUTOPLUGGING;
    &DATAACCESS;

  </part>

<!-- ############ Higher-level APIs in GStreamer - part ############# -->

  <part id="part-highlevel">
    <title>Higher-level interfaces for &GStreamer; applications</title>
    <partintro>
      <para>
        In the previous two parts, you have learned many of the internals
        and their corresponding low-level interfaces into &GStreamer;
        application programming. Many people will, however, not need so
        much control (and as much code), but will prefer to use a standard
        playback interface that does most of the difficult internals for
        them. In this chapter, we will introduce you into the concept of
        autopluggers, playback managing elements and other such things.
        Those higher-level interfaces are intended to
        simplify &GStreamer;-based application programming. They do, however,
        also reduce the flexibility. It is up to the application developer
        to choose which interface he will want to use.
      </para>
    </partintro>

    &PLAYBACK;

  </part>

<!-- ############ Appendices - part ############# -->

  <part id="part-appendices">
    <title>Appendices</title>
    <partintro>
      <para>
        By now, you've learned all about the internals of &GStreamer; and
        application programming using the &GStreamer; framework. This part
        will go into some random bits that are useful to know if you're
        going to use &GStreamer; for serious application programming. It
        will touch upon things related to integration with popular desktop
        environments that we run on (GNOME, KDE, OS X, Windows), it will
        shortly explain how applications included with &GStreamer; can help
        making your life easier, and some information on debugging.
      </para>
      <para>
        In addition, we also provide a porting guide which will explain
        easily how to port &GStreamer;-0.10 applications to &GStreamer;-1.0.
      </para>
    </partintro>

    <!--
    Idea:
    * Debugging and error handling
     - 'error' signal in pipelines
     - checking return values and how to handle them
     - using signals for pipeline states
     - gst-debug
     - programs
    * Desktop integration
     - Linux/UNIX
	. {x,xv}imagesink
	. {oss,alsa}sink
	. {v4l,v4l2,oss,alsa}src
     - GNOME
	. GConf ({video,audio}{src,sink})
	. gnomevfssrc, gnomevfssink
	. popt
	. app examples (RB, Totem, gnome-media, ...)
     - KDE
	. kiosrc
	. app examples (JuK, AmaroK)
	. ask Scott/Mark
     - Mac OS X
	. native video/audio sink
     - Windows
	. build etc.
    * Quotes from devs
     - table please...
    -->

    &PROGRAMS;
    &COMPILING;
    &CHECKLIST;
    &PORTING;
    &INTEGRATION;
    &LICENSING;
    &QUOTES;

  </part>
</book>