mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-24 17:20:36 +00:00
498cda94b5
Original commit message from CVS: patch by: Luc Pionchon <luc.pionchon@nokia.com> * docs/manual/manual.xml: - Reorganised the previous "introduction" bundle into Foreword, Introduction, and About GStreamer. The two first are <preface> docbook elements. The later is the first part of the book. - added intro-gstreamer.xml (content partially from intro-preface.xml) - moved appendix-win32.xml into appendix-integration.xml * docs/manual/intro-preface.xml: gstreamer section moved... * docs/manual/intro-gstreamer.xml: ...here. new file. * docs/manual/appendix-win32.xml: removed file. Content moved... * docs/manual/appendix-integration.xml: ...here. * docs/manual/highlevel-components.xml: section about GstEditor moved... * docs/manual/appendix-checklist.xml: ...here.
265 lines
9 KiB
XML
265 lines
9 KiB
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>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 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 XML SYSTEM "highlevel-xml.xml">
|
|
<!ENTITY COMPONENTS SYSTEM "highlevel-components.xml">
|
|
|
|
<!-- Appendices -->
|
|
<!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 chapter 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;
|
|
&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, XML-based pipelines 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>
|
|
|
|
&COMPONENTS;
|
|
&XML;
|
|
|
|
</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.8 applications to &GStreamer;-0.10.
|
|
</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...
|
|
-->
|
|
|
|
&CHECKLIST;
|
|
&PORTING;
|
|
&INTEGRATION;
|
|
&LICENSING;
|
|
"ES;
|
|
|
|
</part>
|
|
</book>
|