blob: 9a97b69b02ae848adacb985c2085707ca7ef4969 [file] [log] [blame]
Tim-Philipp Müller4583b4f2011-01-14 00:20:43 +00001<?xml version='1.0' encoding='utf-8'?>
Thomas Vander Stichele7d4cb792003-10-08 14:34:09 +00002<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
Thomas Vander Stichelef55a8092004-05-03 16:03:24 +00003 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
Thomas Vander Stichele7d4cb792003-10-08 14:34:09 +00004<!ENTITY % image-entities SYSTEM "image.entities">
5%image-entities;
Thomas Vander Stichelee8a2e562004-02-12 13:04:02 +00006<!ENTITY % version-entities SYSTEM "version.entities">
7%version-entities;
Leif Johnson622a80d2002-09-27 18:34:33 +00008
9<!ENTITY TITLEPAGE SYSTEM "titlepage.xml">
10
Stefan Kosta768c442006-01-30 21:11:38 +000011<!-- Part 1: Introduction -->
Thomas Vander Stichele97cd7e62004-01-28 15:45:46 +000012<!ENTITY INTRO_PREFACE SYSTEM "intro-preface.xml">
13<!ENTITY INTRO_BASICS SYSTEM "intro-basics.xml">
Leif Johnson622a80d2002-09-27 18:34:33 +000014
Stefan Kosta768c442006-01-30 21:11:38 +000015<!-- Part 2: Building a Plugin -->
Thomas Vander Stichele97cd7e62004-01-28 15:45:46 +000016<!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_STATE SYSTEM "building-state.xml">
21<!ENTITY BUILDING_PROPS SYSTEM "building-props.xml">
22<!ENTITY BUILDING_SIGNALS SYSTEM "building-signals.xml">
23<!ENTITY BUILDING_TESTAPP SYSTEM "building-testapp.xml">
Leif Johnson622a80d2002-09-27 18:34:33 +000024
Stefan Kosta768c442006-01-30 21:11:38 +000025<!-- Part 3: Advanced Filter Concepts -->
Ronald S. Bultjea13be0a2005-07-06 12:18:00 +000026<!ENTITY ADVANCED_NEGOTIATION SYSTEM "advanced-negotiation.xml">
Thomas Vander Stichele97cd7e62004-01-28 15:45:46 +000027<!ENTITY ADVANCED_SCHEDULING SYSTEM "advanced-scheduling.xml">
28<!ENTITY ADVANCED_TYPES SYSTEM "advanced-types.xml">
29<!ENTITY ADVANCED_REQUEST SYSTEM "advanced-request.xml">
30<!ENTITY ADVANCED_CLOCK SYSTEM "advanced-clock.xml">
31<!ENTITY ADVANCED_DPARAMS SYSTEM "advanced-dparams.xml">
Thomas Vander Stichele97cd7e62004-01-28 15:45:46 +000032<!ENTITY ADVANCED_INTERFACES SYSTEM "advanced-interfaces.xml">
33<!ENTITY ADVANCED_TAGGING SYSTEM "advanced-tagging.xml">
34<!ENTITY ADVANCED_EVENTS SYSTEM "advanced-events.xml">
Leif Johnson622a80d2002-09-27 18:34:33 +000035
Stefan Kosta768c442006-01-30 21:11:38 +000036<!-- Part 4: Creating special element types -->
Ronald S. Bultje835e8262005-07-20 08:29:06 +000037<!ENTITY OTHER_BASE SYSTEM "other-base.xml">
Ronald S. Bultje47d8f122004-02-02 21:52:46 +000038<!ENTITY OTHER_ONETON SYSTEM "other-oneton.xml">
39<!ENTITY OTHER_NTOONE SYSTEM "other-ntoone.xml">
Ronald S. Bultje47d8f122004-02-02 21:52:46 +000040<!ENTITY OTHER_MANAGER SYSTEM "other-manager.xml">
Leif Johnson622a80d2002-09-27 18:34:33 +000041
Stefan Kosta768c442006-01-30 21:11:38 +000042<!-- Appendices -->
Thomas Vander Stichele97cd7e62004-01-28 15:45:46 +000043<!ENTITY APPENDIX_CHECKLIST SYSTEM "appendix-checklist.xml">
Ronald S. Bultjec9a37cf2005-07-01 12:43:03 +000044<!ENTITY APPENDIX_PORTING SYSTEM "appendix-porting.xml">
Christian Schaller4439f812005-01-31 11:43:05 +000045<!ENTITY APPENDIX_LICENSING SYSTEM "appendix-licensing.xml">
Thomas Vander Stichele97cd7e62004-01-28 15:45:46 +000046<!ENTITY APPENDIX_PYTHON SYSTEM "appendix-python.xml">
Leif Johnson622a80d2002-09-27 18:34:33 +000047
48<!ENTITY GStreamer "<application>GStreamer</application>">
Leif Johnson622a80d2002-09-27 18:34:33 +000049<!ENTITY GstAppDevMan "<emphasis>GStreamer Application Development Manual</emphasis>">
50<!ENTITY GstLibRef "<emphasis>GStreamer Library Reference</emphasis>">
51]>
52
Thomas Vander Stichelea0e8e562003-12-02 18:21:35 +000053<book id="index">
Leif Johnson622a80d2002-09-27 18:34:33 +000054 &TITLEPAGE;
55
Stefan Kosta768c442006-01-30 21:11:38 +000056 <!-- ############# Introduction - part ############### -->
Leif Johnson622a80d2002-09-27 18:34:33 +000057
58 <part id="part-introduction" xreflabel="Introduction">
59 <title>Introduction</title>
60 <partintro>
Stefan Kost523041b2006-02-02 11:24:19 +000061 <para><!-- synchronize with AppDevMan -->
Tim-Philipp Müller0b60f832007-01-26 13:07:36 +000062 &GStreamer; is an extremely powerful and versatile framework for creating
Leif Johnson622a80d2002-09-27 18:34:33 +000063 streaming media applications. Many of the virtues of the &GStreamer;
64 framework come from its modularity: &GStreamer; can seamlessly
65 incorporate new plugin modules. But because modularity and power often
66 come at a cost of greater complexity (consider, for example, <ulink
67 type="http" url="http://www.omg.org/">CORBA</ulink>), writing new
68 plugins is not always easy.
69 </para>
70 <para>
71 This guide is intended to help you understand the &GStreamer; framework
Thomas Vander Stichelee8a2e562004-02-12 13:04:02 +000072 (version &GST_VERSION;) so you can develop new plugins to extend the
Leif Johnsonaf236bd2002-11-28 08:37:12 +000073 existing functionality. The guide addresses most issues by following the
Thomas Vander Stichele5e3f9202002-12-18 15:14:16 +000074 development of an example plugin - an audio filter plugin -
Leif Johnsonaf236bd2002-11-28 08:37:12 +000075 written in C. However, the later parts of the guide also present some
76 issues involved in writing other types of plugins, and the end of the
77 guide describes some of the Python bindings for &GStreamer;.
Leif Johnson622a80d2002-09-27 18:34:33 +000078 </para>
79 </partintro>
80
81 &INTRO_PREFACE;
82 &INTRO_BASICS;
83 </part>
84
Stefan Kosta768c442006-01-30 21:11:38 +000085 <!-- ############ Building a Plugin - part ############# -->
Leif Johnson622a80d2002-09-27 18:34:33 +000086
Thomas Vander Stichelefdfb2b82004-03-01 17:15:28 +000087 <part id="part-building" xreflabel="Building a Plugin">
88 <title>Building a Plugin</title>
Leif Johnson622a80d2002-09-27 18:34:33 +000089 <partintro>
90 <para>
Leif Johnsonaf236bd2002-11-28 08:37:12 +000091 You are now ready to learn how to build a plugin. In this part of the
Thomas Vander Stichelefdfb2b82004-03-01 17:15:28 +000092 guide, you will learn how to apply basic &GStreamer;
Leif Johnsonaf236bd2002-11-28 08:37:12 +000093 programming concepts to write a simple plugin. The previous parts of the
94 guide have contained no explicit example code, perhaps making things a
95 bit abstract and difficult to understand. In contrast, this section will
96 present both applications and code by following the development of an
Sebastian Drögebd38b092010-04-16 20:09:40 +020097 example audio filter plugin called <quote>MyFilter</quote>.
Leif Johnson622a80d2002-09-27 18:34:33 +000098 </para>
99 <para>
Thomas Vander Stichelefdfb2b82004-03-01 17:15:28 +0000100 The example filter element will begin with a single input pad and a
101 single
Leif Johnsonaf236bd2002-11-28 08:37:12 +0000102 output pad. The filter will, at first, simply pass media and event data
103 from its sink pad to its source pad without modification. But by the end
104 of this part of the guide, you will learn to add some more interesting
105 functionality, including properties and signal handlers. And after
106 reading the next part of the guide, <xref linkend="part-advanced"/>, you
107 will be able to add even more functionality to your plugins.
Leif Johnson622a80d2002-09-27 18:34:33 +0000108 </para>
109 <para>
110 The example code used in this part of the guide can be found in
111 <filename class="directory">examples/pwg/examplefilter/</filename> in
112 your &GStreamer; directory.
113 </para>
114 </partintro>
115
116 &BUILDING_BOILER;
117 &BUILDING_PADS;
118 &BUILDING_CHAINFN;
119 &BUILDING_STATE;
120 &BUILDING_PROPS;
121 &BUILDING_SIGNALS;
122 &BUILDING_TESTAPP;
123 </part>
124
Stefan Kosta768c442006-01-30 21:11:38 +0000125 <!-- ############ Advanced Filter Concepts - part ############# -->
Leif Johnson622a80d2002-09-27 18:34:33 +0000126
127 <part id="part-advanced" xreflabel="Advanced Filter Concepts">
128 <title>Advanced Filter Concepts</title>
129 <partintro>
130 <para>
Ronald S. Bultje47d8f122004-02-02 21:52:46 +0000131 By now, you should be able to create basic filter elements that can
132 receive and send data. This is the simple model that &GStreamer; stands
133 for. But &GStreamer; can do much more than only this! In this chapter,
134 various advanced topics will be discussed, such as scheduling, special
135 pad types, clocking, events, interfaces, tagging and more. These topics
136 are the sugar that makes &GStreamer; so easy to use for applications.
Leif Johnson622a80d2002-09-27 18:34:33 +0000137 </para>
138 </partintro>
139
Ronald S. Bultjea13be0a2005-07-06 12:18:00 +0000140 &ADVANCED_NEGOTIATION;
Leif Johnson622a80d2002-09-27 18:34:33 +0000141 &ADVANCED_SCHEDULING;
142 &ADVANCED_TYPES;
143 &ADVANCED_REQUEST;
144 &ADVANCED_CLOCK;
145 &ADVANCED_DPARAMS;
Ronald S. Bultje93ea2842004-01-27 14:58:21 +0000146 &ADVANCED_INTERFACES;
Ronald S. Bultje26c9fb02004-01-28 14:16:59 +0000147 &ADVANCED_TAGGING;
148 &ADVANCED_EVENTS;
Ronald S. Bultje1fef2702004-12-23 14:26:14 +0000149
150 <!-- FIXME: add querying, event handling and conversion -->
151
Leif Johnson622a80d2002-09-27 18:34:33 +0000152 </part>
153
Stefan Kosta768c442006-01-30 21:11:38 +0000154 <!-- ############ Creating special element types - part ############# -->
Leif Johnson622a80d2002-09-27 18:34:33 +0000155
Ronald S. Bultje835e8262005-07-20 08:29:06 +0000156 <part id="part-other" xreflabel="Creating special element types">
157 <title>Creating special element types</title>
Leif Johnson622a80d2002-09-27 18:34:33 +0000158 <partintro>
159 <para>
Ronald S. Bultje47d8f122004-02-02 21:52:46 +0000160 By now, we have looked at pretty much any feature that can be embedded
Ronald S. Bultje835e8262005-07-20 08:29:06 +0000161 into a &GStreamer; element. Most of this has been fairly low-level and
162 given deep insights in how &GStreamer; works internally. Fortunately,
163 &GStreamer; contains some easier-to-use interfaces to create such
164 elements. In order to do that, we will look closer at the element
165 types for which &GStreamer; provides base classes (sources, sinks and
166 transformation elements). We will also look closer at some types of
167 elements that require no specific coding such as scheduling-interaction
168 or data passing, but rather require specific pipeline control (e.g.
169 N-to-1 elements and managers).
Leif Johnson622a80d2002-09-27 18:34:33 +0000170 </para>
171 </partintro>
172
Ronald S. Bultje835e8262005-07-20 08:29:06 +0000173 &OTHER_BASE;
Ronald S. Bultje47d8f122004-02-02 21:52:46 +0000174 &OTHER_ONETON;
175 &OTHER_NTOONE;
Ronald S. Bultje47d8f122004-02-02 21:52:46 +0000176 &OTHER_MANAGER;
Leif Johnson622a80d2002-09-27 18:34:33 +0000177 </part>
178
Stefan Kosta768c442006-01-30 21:11:38 +0000179 <!-- ############ Appendices - part ############# -->
Leif Johnson622a80d2002-09-27 18:34:33 +0000180
181 <part id="part-appendix" xreflabel="Appendices">
182 <title>Appendices</title>
183 <partintro>
184 <para>
Ronald S. Bultje47d8f122004-02-02 21:52:46 +0000185 This chapter contains things that don't belong anywhere else.
Leif Johnson622a80d2002-09-27 18:34:33 +0000186 </para>
187 </partintro>
188
189 &APPENDIX_CHECKLIST;
Ronald S. Bultjec9a37cf2005-07-01 12:43:03 +0000190 &APPENDIX_PORTING;
Christian Schaller4439f812005-01-31 11:43:05 +0000191 &APPENDIX_LICENSING;
Leif Johnson622a80d2002-09-27 18:34:33 +0000192 &APPENDIX_PYTHON;
193 </part>
194
195</book>