Tim-Philipp Müller | 4583b4f | 2011-01-14 00:20:43 +0000 | [diff] [blame] | 1 | <?xml version='1.0' encoding='utf-8'?> |
Thomas Vander Stichele | 7d4cb79 | 2003-10-08 14:34:09 +0000 | [diff] [blame] | 2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
Thomas Vander Stichele | f55a809 | 2004-05-03 16:03:24 +0000 | [diff] [blame] | 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ |
Thomas Vander Stichele | 7d4cb79 | 2003-10-08 14:34:09 +0000 | [diff] [blame] | 4 | <!ENTITY % image-entities SYSTEM "image.entities"> |
| 5 | %image-entities; |
Thomas Vander Stichele | e8a2e56 | 2004-02-12 13:04:02 +0000 | [diff] [blame] | 6 | <!ENTITY % version-entities SYSTEM "version.entities"> |
| 7 | %version-entities; |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 8 | |
| 9 | <!ENTITY TITLEPAGE SYSTEM "titlepage.xml"> |
| 10 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 11 | <!-- Part 1: Introduction --> |
Thomas Vander Stichele | 97cd7e6 | 2004-01-28 15:45:46 +0000 | [diff] [blame] | 12 | <!ENTITY INTRO_PREFACE SYSTEM "intro-preface.xml"> |
| 13 | <!ENTITY INTRO_BASICS SYSTEM "intro-basics.xml"> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 14 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 15 | <!-- Part 2: Building a Plugin --> |
Thomas Vander Stichele | 97cd7e6 | 2004-01-28 15:45:46 +0000 | [diff] [blame] | 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_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 Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 24 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 25 | <!-- Part 3: Advanced Filter Concepts --> |
Ronald S. Bultje | a13be0a | 2005-07-06 12:18:00 +0000 | [diff] [blame] | 26 | <!ENTITY ADVANCED_NEGOTIATION SYSTEM "advanced-negotiation.xml"> |
Thomas Vander Stichele | 97cd7e6 | 2004-01-28 15:45:46 +0000 | [diff] [blame] | 27 | <!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 Stichele | 97cd7e6 | 2004-01-28 15:45:46 +0000 | [diff] [blame] | 32 | <!ENTITY ADVANCED_INTERFACES SYSTEM "advanced-interfaces.xml"> |
| 33 | <!ENTITY ADVANCED_TAGGING SYSTEM "advanced-tagging.xml"> |
| 34 | <!ENTITY ADVANCED_EVENTS SYSTEM "advanced-events.xml"> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 35 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 36 | <!-- Part 4: Creating special element types --> |
Ronald S. Bultje | 835e826 | 2005-07-20 08:29:06 +0000 | [diff] [blame] | 37 | <!ENTITY OTHER_BASE SYSTEM "other-base.xml"> |
Ronald S. Bultje | 47d8f12 | 2004-02-02 21:52:46 +0000 | [diff] [blame] | 38 | <!ENTITY OTHER_ONETON SYSTEM "other-oneton.xml"> |
| 39 | <!ENTITY OTHER_NTOONE SYSTEM "other-ntoone.xml"> |
Ronald S. Bultje | 47d8f12 | 2004-02-02 21:52:46 +0000 | [diff] [blame] | 40 | <!ENTITY OTHER_MANAGER SYSTEM "other-manager.xml"> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 41 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 42 | <!-- Appendices --> |
Thomas Vander Stichele | 97cd7e6 | 2004-01-28 15:45:46 +0000 | [diff] [blame] | 43 | <!ENTITY APPENDIX_CHECKLIST SYSTEM "appendix-checklist.xml"> |
Ronald S. Bultje | c9a37cf | 2005-07-01 12:43:03 +0000 | [diff] [blame] | 44 | <!ENTITY APPENDIX_PORTING SYSTEM "appendix-porting.xml"> |
Christian Schaller | 4439f81 | 2005-01-31 11:43:05 +0000 | [diff] [blame] | 45 | <!ENTITY APPENDIX_LICENSING SYSTEM "appendix-licensing.xml"> |
Thomas Vander Stichele | 97cd7e6 | 2004-01-28 15:45:46 +0000 | [diff] [blame] | 46 | <!ENTITY APPENDIX_PYTHON SYSTEM "appendix-python.xml"> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 47 | |
| 48 | <!ENTITY GStreamer "<application>GStreamer</application>"> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 49 | <!ENTITY GstAppDevMan "<emphasis>GStreamer Application Development Manual</emphasis>"> |
| 50 | <!ENTITY GstLibRef "<emphasis>GStreamer Library Reference</emphasis>"> |
| 51 | ]> |
| 52 | |
Thomas Vander Stichele | a0e8e56 | 2003-12-02 18:21:35 +0000 | [diff] [blame] | 53 | <book id="index"> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 54 | &TITLEPAGE; |
| 55 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 56 | <!-- ############# Introduction - part ############### --> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 57 | |
| 58 | <part id="part-introduction" xreflabel="Introduction"> |
| 59 | <title>Introduction</title> |
| 60 | <partintro> |
Stefan Kost | 523041b | 2006-02-02 11:24:19 +0000 | [diff] [blame] | 61 | <para><!-- synchronize with AppDevMan --> |
Tim-Philipp Müller | 0b60f83 | 2007-01-26 13:07:36 +0000 | [diff] [blame] | 62 | &GStreamer; is an extremely powerful and versatile framework for creating |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 63 | 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 Stichele | e8a2e56 | 2004-02-12 13:04:02 +0000 | [diff] [blame] | 72 | (version &GST_VERSION;) so you can develop new plugins to extend the |
Leif Johnson | af236bd | 2002-11-28 08:37:12 +0000 | [diff] [blame] | 73 | existing functionality. The guide addresses most issues by following the |
Thomas Vander Stichele | 5e3f920 | 2002-12-18 15:14:16 +0000 | [diff] [blame] | 74 | development of an example plugin - an audio filter plugin - |
Leif Johnson | af236bd | 2002-11-28 08:37:12 +0000 | [diff] [blame] | 75 | 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 Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 78 | </para> |
| 79 | </partintro> |
| 80 | |
| 81 | &INTRO_PREFACE; |
| 82 | &INTRO_BASICS; |
| 83 | </part> |
| 84 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 85 | <!-- ############ Building a Plugin - part ############# --> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 86 | |
Thomas Vander Stichele | fdfb2b8 | 2004-03-01 17:15:28 +0000 | [diff] [blame] | 87 | <part id="part-building" xreflabel="Building a Plugin"> |
| 88 | <title>Building a Plugin</title> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 89 | <partintro> |
| 90 | <para> |
Leif Johnson | af236bd | 2002-11-28 08:37:12 +0000 | [diff] [blame] | 91 | You are now ready to learn how to build a plugin. In this part of the |
Thomas Vander Stichele | fdfb2b8 | 2004-03-01 17:15:28 +0000 | [diff] [blame] | 92 | guide, you will learn how to apply basic &GStreamer; |
Leif Johnson | af236bd | 2002-11-28 08:37:12 +0000 | [diff] [blame] | 93 | 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öge | bd38b09 | 2010-04-16 20:09:40 +0200 | [diff] [blame] | 97 | example audio filter plugin called <quote>MyFilter</quote>. |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 98 | </para> |
| 99 | <para> |
Thomas Vander Stichele | fdfb2b8 | 2004-03-01 17:15:28 +0000 | [diff] [blame] | 100 | The example filter element will begin with a single input pad and a |
| 101 | single |
Leif Johnson | af236bd | 2002-11-28 08:37:12 +0000 | [diff] [blame] | 102 | 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 Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 108 | </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 Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 125 | <!-- ############ Advanced Filter Concepts - part ############# --> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 126 | |
| 127 | <part id="part-advanced" xreflabel="Advanced Filter Concepts"> |
| 128 | <title>Advanced Filter Concepts</title> |
| 129 | <partintro> |
| 130 | <para> |
Ronald S. Bultje | 47d8f12 | 2004-02-02 21:52:46 +0000 | [diff] [blame] | 131 | 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 Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 137 | </para> |
| 138 | </partintro> |
| 139 | |
Ronald S. Bultje | a13be0a | 2005-07-06 12:18:00 +0000 | [diff] [blame] | 140 | &ADVANCED_NEGOTIATION; |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 141 | &ADVANCED_SCHEDULING; |
| 142 | &ADVANCED_TYPES; |
| 143 | &ADVANCED_REQUEST; |
| 144 | &ADVANCED_CLOCK; |
| 145 | &ADVANCED_DPARAMS; |
Ronald S. Bultje | 93ea284 | 2004-01-27 14:58:21 +0000 | [diff] [blame] | 146 | &ADVANCED_INTERFACES; |
Ronald S. Bultje | 26c9fb0 | 2004-01-28 14:16:59 +0000 | [diff] [blame] | 147 | &ADVANCED_TAGGING; |
| 148 | &ADVANCED_EVENTS; |
Ronald S. Bultje | 1fef270 | 2004-12-23 14:26:14 +0000 | [diff] [blame] | 149 | |
| 150 | <!-- FIXME: add querying, event handling and conversion --> |
| 151 | |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 152 | </part> |
| 153 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 154 | <!-- ############ Creating special element types - part ############# --> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 155 | |
Ronald S. Bultje | 835e826 | 2005-07-20 08:29:06 +0000 | [diff] [blame] | 156 | <part id="part-other" xreflabel="Creating special element types"> |
| 157 | <title>Creating special element types</title> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 158 | <partintro> |
| 159 | <para> |
Ronald S. Bultje | 47d8f12 | 2004-02-02 21:52:46 +0000 | [diff] [blame] | 160 | By now, we have looked at pretty much any feature that can be embedded |
Ronald S. Bultje | 835e826 | 2005-07-20 08:29:06 +0000 | [diff] [blame] | 161 | 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 Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 170 | </para> |
| 171 | </partintro> |
| 172 | |
Ronald S. Bultje | 835e826 | 2005-07-20 08:29:06 +0000 | [diff] [blame] | 173 | &OTHER_BASE; |
Ronald S. Bultje | 47d8f12 | 2004-02-02 21:52:46 +0000 | [diff] [blame] | 174 | &OTHER_ONETON; |
| 175 | &OTHER_NTOONE; |
Ronald S. Bultje | 47d8f12 | 2004-02-02 21:52:46 +0000 | [diff] [blame] | 176 | &OTHER_MANAGER; |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 177 | </part> |
| 178 | |
Stefan Kost | a768c44 | 2006-01-30 21:11:38 +0000 | [diff] [blame] | 179 | <!-- ############ Appendices - part ############# --> |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 180 | |
| 181 | <part id="part-appendix" xreflabel="Appendices"> |
| 182 | <title>Appendices</title> |
| 183 | <partintro> |
| 184 | <para> |
Ronald S. Bultje | 47d8f12 | 2004-02-02 21:52:46 +0000 | [diff] [blame] | 185 | This chapter contains things that don't belong anywhere else. |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 186 | </para> |
| 187 | </partintro> |
| 188 | |
| 189 | &APPENDIX_CHECKLIST; |
Ronald S. Bultje | c9a37cf | 2005-07-01 12:43:03 +0000 | [diff] [blame] | 190 | &APPENDIX_PORTING; |
Christian Schaller | 4439f81 | 2005-01-31 11:43:05 +0000 | [diff] [blame] | 191 | &APPENDIX_LICENSING; |
Leif Johnson | 622a80d | 2002-09-27 18:34:33 +0000 | [diff] [blame] | 192 | &APPENDIX_PYTHON; |
| 193 | </part> |
| 194 | |
| 195 | </book> |