<para>
In this chapter you will learn how to construct the bare minimum code for a
new plugin. Starting from ground zero, you will see how to get the
- &GStreamer; template source. Then you will learn how to use a few simple
- command line tools to copy and modify a template plugin and thus create your
- new plugin. By the end of all this, you will have a functional audio filter
- plugin that you can compile and test.
+ &GStreamer; template source. Then you will learn how to use a few basic
+ tools to copy and modify a template plugin to create a new plugin. If you
+ follow the examples here, then by the end of this chapter you will have a
+ functional audio filter plugin that you can compile and use in &GStreamer;
+ applications.
</para>
<!-- ############ sect1 ############# -->
can write the entire plugin by hand, or you can copy an existing plugin
template and write the plugin code you need. The second method is by far
the simpler of the two, so the first method will not even be described
- here.
+ here. (Errm, that is, <quote>it is left as an exercise to the
+ reader.</quote>)
</para>
<para>
The first step is to check out a copy of the
<filename>gst-template</filename> CVS module to get an important tool and
- the source code template for the basic &GStreamer; plugin. To check out
- the <filename>gst-template</filename> module, type the following two
- commands on a command line:
+ the source code template for a basic &GStreamer; plugin. To check out the
+ <filename>gst-template</filename> module, make sure you are connected to
+ the internet, and type the following commands at a command console:
</para>
<screen>
+<prompt>shell $ </prompt><userinput>cd .</userinput>
<prompt>shell $ </prompt><userinput>cvs -d:pserver:anonymous@cvs.gstreamer.sourceforge.net:/cvsroot/gstreamer login</userinput>
Logging in to :pserver:anonymous@cvs.gstreamer.sourceforge.net:2401/cvsroot/gstreamer
CVS password:
</screen>
<para>
After the first command, you will have to press <keycap>ENTER</keycap> to
- log in to the CVS server. You might have to log in twice. The second
+ log in to the CVS server. (You might have to log in twice.) The second
command will check out a series of files and directories into <filename
class="directory">./gst-template</filename>. The template you will be
using is in <filename
<!-- ############ sect1 ############# -->
- <sect1 id="sect1-boiler-filterstamp" xreflabel="Using Filterstamp">
- <title>Using Filterstamp</title>
+ <sect1 id="sect1-boiler-project-stamp" xreflabel="Using the Project Stamp">
+ <title>Using the Project Stamp</title>
<para>
The first thing to do when making a new element is to specify some basic
details about it: what its name is, who wrote it, what version number it
The standard way of defining the boilerplate is simply to write some code,
and fill in some structures. As mentioned in the previous section, the
easiest way to do this is to copy a template and add functionality
- according to your needs. To help you do so, there is a script called
- <command>pluginstamp.sh</command> in the <filename
- class="directory">tools/</filename> directory of the
- <filename>gst-template</filename> source tree that does exactly this.
+ according to your needs. To help you do so, there are some tools in the
+ <filename class="directory">./gst-template/tools/</filename> directory.
+ One tool, <filename>gst-quick-stamp</filename>, is a quick command line
+ tool. The other, <filename>gst-project-stamp</filename>, is a full GNOME
+ druid application that takes you through the steps of creating a new
+ project (either a plugin or an application).
</para>
<para>
To use <command>pluginstamp.sh</command>, first open up a terminal window.
<para>
Note that capitalization is important for the name of the plugin. Under
some operating systems, capitalization is also important when specifying
- directory names. For example, the
- following commands create the ExampleFilter plugin based on the plugin
- template and put the output files in a new directory called <filename
+ directory names. For example, the following commands create the
+ ExampleFilter plugin based on the plugin template and put the output files
+ in a new directory called <filename
class="directory">~/src/examplefilter/</filename>:
</para>
<screen>
<!ENTITY APPENDIX_PYTHON SYSTEM "appendix_python.xml">
<!ENTITY GStreamer "<application>GStreamer</application>">
-<!ENTITY GstVersion "0.4.1">
+<!ENTITY GstVersion "0.4.2.2">
<!ENTITY GstAppDevMan "<emphasis>GStreamer Application Development Manual</emphasis>">
<!ENTITY GstLibRef "<emphasis>GStreamer Library Reference</emphasis>">
]>
</para>
<para>
This guide is intended to help you understand the &GStreamer; framework
- so you can develop new plugins to extend &GStreamer;'s functionality.
- This guide introduces most of the basic plugin writing issues in version
- &GstVersion; of &GStreamer;. This guide presents most issues in the
- context of an example audio filter plugin written in C. However, the
- guide also addresses some issues involved in writing other types of
- plugins, and the end of the guide also describes some of the Python
- bindings for &GStreamer;.
+ (version &GstVersion;) so you can develop new plugins to extend the
+ existing functionality. The guide addresses most issues by following the
+ development of an example plugin — an audio filter plugin —
+ written in C. However, the later parts of the guide also present some
+ issues involved in writing other types of plugins, and the end of the
+ guide describes some of the Python bindings for &GStreamer;.
</para>
</partintro>
<title>Building a Filter</title>
<partintro>
<para>
- You now have the neccessary concepts to build your first plugin. In this
- part of the guide, you will learn how to apply these concepts to write a
- simple audio filter plugin. The previous parts of the guide have
- contained no explicit example code, perhaps making things a bit abstract
- and difficult to understand. In contrast, this section will present both
- applications and code by following the development of an example audio
- filter plugin called <quote>ExampleFilter</quote>.
+ You are now ready to learn how to build a plugin. In this part of the
+ guide, you will learn how to apply basic &GStreamer; and GNOME
+ programming concepts to write a simple plugin. The previous parts of the
+ guide have contained no explicit example code, perhaps making things a
+ bit abstract and difficult to understand. In contrast, this section will
+ present both applications and code by following the development of an
+ example audio filter plugin called <quote>ExampleFilter</quote>.
</para>
<para>
The example filter will begin with a single input pad and a single
- output pad. The filter will, at first, simply pass data through without
- modification. But by the end of this part of the guide, you will learn
- to add some more interesting functionality, including properties and
- signal handlers. And after reading the next part of the guide, <xref
- linkend="part-advanced"/>, you will be able to add even more
- functionality to your plugins.
+ output pad. The filter will, at first, simply pass media and event data
+ from its sink pad to its source pad without modification. But by the end
+ of this part of the guide, you will learn to add some more interesting
+ functionality, including properties and signal handlers. And after
+ reading the next part of the guide, <xref linkend="part-advanced"/>, you
+ will be able to add even more functionality to your plugins.
</para>
<para>
The example code used in this part of the guide can be found in
<title>Basic Concepts</title>
<para>
This chapter of the guide introduces the basic concepts of &GStreamer;.
- Understanding these concepts will help you see the issues involved in
+ Understanding these concepts will help you grok the issues involved in
extending &GStreamer;. Many of these concepts are explained in greater
- detail in the &GstAppDevMan;. The basic concepts presented here serve mainly
+ detail in the &GstAppDevMan;; the basic concepts presented here serve mainly
to refresh your memory.
</para>
<para>
Elements are at the core of &GStreamer;. In the context of plugin
development, an <emphasis>element</emphasis> is an object derived from the
- <classname>GstElement</classname> class. An element provides some sort of
- functionality when connected with other elements. Without elements,
- &GStreamer; is just a bunch of conceptual pipe fittings with nothing to
- connect. A large number of elements ship with &GStreamer;, but extra
- elements can also be written. The purpose of this guide is to help you
- learn to create new elements, which are encapsulated in plugins as
- described below.
+ <classname>GstElement</classname> class. Elements provide some sort of
+ functionality when connected with other elements: For example, a source
+ element provides data to a stream, and a filter element acts on the data
+ in a stream. Without elements, &GStreamer; is just a bunch of conceptual
+ pipe fittings with nothing to connect. A large number of elements ship
+ with &GStreamer;, but extra elements can also be written.
</para>
<para>
- A <emphasis>filter</emphasis> is an important type of element that
- processes a stream of data, as opposed to producing or consuming streams
- of data. Producers and consumers of data are called
- <emphasis>source</emphasis> and <emphasis>sink</emphasis> elements,
- respectively.
+ Just writing a new element is not entirely enough, however: You will need
+ to encapsulate your element in a <emphasis>plugin</emphasis> to enable
+ &GStreamer; to use it. A plugin is essentially a loadable block of code,
+ usually called a shared object file or a dynamically linked library. A
+ single plugin may contain the implementation of several elements, or just
+ a single one. For simplicity, this guide concentrates primarily on plugins
+ containing one element.
</para>
<para>
- Just writing a new element is not entirely enough, however: You will need
- to encapsulate your element in a plugin to enable &GStreamer; to use it. A
- <emphasis>plugin</emphasis> is essentially a loadable block of code,
- usually a shared object file or dynamically linked library. A single
- plugin may contain the implementation of several elements, or just a
- single one. For simplicity, this guide concentrates primarily on plugins
- containing one filter type element.
+ A <emphasis>filter</emphasis> is an important type of element that
+ processes a stream of data. Producers and consumers of data are called
+ <emphasis>source</emphasis> and <emphasis>sink</emphasis> elements,
+ respectively. Elements that connect other elements together are called
+ <emphasis>autoplugger</emphasis> elements, and a <emphasis>bin</emphasis>
+ element contains other elements. Bins are often responsible for scheduling
+ the elements that they contain so that data flows smoothly.
</para>
<para>
The plugin mechanism is used everywhere in &GStreamer;, even if only the
<para>
<emphasis>Pads</emphasis> are used to negotiate connections and data flow
between elements in &GStreamer;. A pad can be viewed as a
- <quote>place</quote> on an element where connections may be made with
- other elements. Pads have specific data handling capabilities: That is, a
- pad only knows how to give or receive certain types of data. Connections
- are only allowed when the capabilities of two pads are compatible.
+ <quote>place</quote> or <quote>port</quote> on an element where
+ connections may be made with other elements. Pads have specific data
+ handling capabilities: A pad only knows how to give or receive certain
+ types of data. Connections are only allowed when the capabilities of two
+ pads are compatible.
</para>
<para>
An analogy may be helpful here. A pad is similar to a plug or jack on a
physical device. Consider, for example, a home theater system consisting
- of an amplifier, a DVD player, and a television. Connecting the DVD player
- to the amplifier is allowed only because both devices have audio jacks,
- and connecting the television to the DVD player is allowed because both
- devices have compatible video jacks. Pads in &GStreamer; serve the same
- purpose as the jacks in the home theater system.
+ of an amplifier, a DVD player, and a (silent) video projector. Connecting
+ the DVD player to the amplifier is allowed because both devices have audio
+ jacks, and connecting the projector to the DVD player is allowed because
+ both devices have compatible video jacks. Connections between the
+ projector and the amplifier may not be made because the projector and
+ amplifier have different types of jacks. Pads in &GStreamer; serve the
+ same purpose as the jacks in the home theater system.
+ </para>
+ <para>
+ For the moment, all data in &GStreamer; flows one way through a connection
+ between elements. Data flows out of one element through one or more
+ <emphasis>source pads</emphasis>, and elements accept incoming data through
+ one or more <emphasis>sink pads</emphasis>. Source and sink elements have
+ only source and sink pads, respectively.
</para>
<para>
See the &GstLibRef; for the current implementation details of a <ulink
All streams of data in &GStreamer; are chopped up into chunks that are
passed from a source pad on one element to a sink pad on another element.
<emphasis>Buffers</emphasis> are structures used to hold these chunks of
- data. Buffers can be of any size, theoretically. Buffers may contain any
- sort of data that the two pads involved know how to handle: Normally, a
+ data. Buffers can be of any size, theoretically, and they may contain any
+ sort of data that the two connected pads know how to handle. Normally, a
buffer contains a chunk of some sort of audio or video data that flows
from one element to another.
</para>
A reference count indicating the number of elements currently
holding a reference to the buffer. When the buffer reference count
falls to zero, the buffer will be unlinked, and its memory will be
- freed in some sense (see the next part about <xref
- linkend="sect2-buffers-bufferpools"/> for more details).
+ freed in some sense (see below for more details).
</para>
</listitem>
</itemizedlist>
<para>
Buffers can be allocated using various schemes, and they may either be
passed on by an element or unreferenced, thus freeing the memory used by
- the buffer.
+ the buffer. Buffer allocation and unlinking are important concepts when
+ dealing with real time media processing, since memory allocation is
+ relatively slow on most systems.
+ </para>
+ <para>
+ To improve the latency in a media pipeline, many &GStreamer; elements
+ use a <emphasis>buffer pool</emphasis> to handle buffer allocation and
+ unlinking. A buffer pool is a relatively large chunk of memory that is
+ the &GStreamer; process requests early on from the operating system.
+ Later, when elements request memory for a new buffer, the buffer pool
+ can serve the request quickly by giving out a piece of the allocated
+ memory. This saves a call to the operating system and lowers latency.
+ [If it seems at this point like &GStreamer; is acting like an operating
+ system (doing memory management, etc.), don't worry: &GStreamer;OS isn't
+ due out for quite a few years!]
</para>
<para>
- Normally, filter elements in &GStreamer; deal with a buffer in place,
- meaning that they do not create or destroy buffers. Sometimes, however,
- elements might need to alter the reference count of a buffer to copy or
- destroy the buffer, or to create a new buffer. For the most part, this
- guide does not deal with elements that alter a buffer's reference count,
- but buffer referencing is an important concept to know.
+ Normally in a media pipeline, most filter elements in &GStreamer; deal
+ with a buffer in place, meaning that they do not create or destroy
+ buffers. Sometimes, however, elements might need to alter the reference
+ count of a buffer, either by copying or destroying the buffer, or by
+ creating a new buffer. These topics are generally reserved for
+ non-filter elements, so they will be addressed at that point.
</para>
</sect2>
</sect1>
<sect1 id="sect1-basics-events" xreflabel="Events">
<title>Events</title>
<para>
- Events are a special type of data in &GStreamer;.
- <emphasis>Events</emphasis> indicate some sort of notable event that has
- happened somewhere in an element's pipeline. Just like any other data
- type, an event comes to an element through its pads. Events are contained
- in a <classname>GstBuffer</classname>, so an event buffer will contain
- only an event, not any other type of data.
+ Sometimes elements in a media processing pipeline need to know that
+ something has happened. An <emphasis>event</emphasis> is a special type of
+ data in &GStreamer; designed to serve this purpose. Events describe some
+ sort of activity that has happened somewhere in an element's pipeline, for
+ example, the end of the media stream or a clock discontinuity. Just like
+ any other data type, an event comes to an element on a sink pad and is
+ contained in a normal buffer. Unlike normal stream buffers, though, an
+ event buffer contains only an event, not any media stream data.
</para>
<para>
See the &GstLibRef; for the current implementation details of a <ulink
<listitem>
<para>
<guilabel><xref linkend="part-building"/></guilabel> —
- Introduction to the structure of a plugin. This part covers all the
- different steps you have to perform to build a basic audio filter
- plugin. The discussion begins by giving examples of generating the
- basic structures with <xref linkend="cha-building-boiler"/>. Then you
- will learn how to write the code to get a basic filter plugin working.
- Several chapters cover these concepts, including <xref
+ Introduction to the structure of a plugin, using an example audio
+ filter for illustration.
+ </para>
+ <para>
+ This part covers all the basic steps you generally need to perform to
+ build a plugin. The discussion begins by giving examples of generating
+ the basic structures with <xref linkend="cha-building-boiler"/>. Then
+ you will learn how to write the code to get a basic filter plugin
+ working: These steps include chapters on <xref
linkend="cha-building-types"/>, <xref linkend="cha-building-pads"/>,
<xref linkend="cha-building-chainfn"/>, and <xref
linkend="cha-building-state"/>.
</para>
<para>
- After you have finished these chapters, you will have a working
- plugin, but your new plugin might not have all the functionality you
- need. To provide some standard functionality, you will learn how to
- add features to a filter in the chapters on <xref
- linkend="cha-building-props"/> and <xref
- linkend="cha-building-signals"/>. Finally, you will learn to test your
- new plugin in <xref linkend="cha-building-testapp"/>.
+ After you have finished the first steps, you will be able to create a
+ working plugin, but your new plugin might not have all the
+ functionality you need. To provide some standard functionality, you
+ will learn how to add more features to a new plugin. These features
+ are described in the chapters on <xref linkend="cha-building-props"/>
+ and <xref linkend="cha-building-signals"/>. Finally, you will see in
+ <xref linkend="cha-building-testapp"/> how to write a short test
+ application to try out your new plugin.
</para>
</listitem>
<listitem>
<para>
<guilabel><xref linkend="part-advanced"/></guilabel> —
Information on advanced features of &GStreamer; plugin development.
+ </para>
+ <para>
After learning about the basic steps, you should be able to create a
functional audio or video filter plugin with some nice features.
However, &GStreamer; offers more for plugin writers. This part of the
- guide includes chapters on <xref linkend="cha-advanced-scheduling"/>,
- <xref linkend="cha-advanced-request"/>, <xref
+ guide includes chapters on more advanced topics, such as <xref
+ linkend="cha-advanced-scheduling"/>, <xref
+ linkend="cha-advanced-request"/>, <xref
linkend="cha-advanced-clock"/>, <xref
linkend="cha-advanced-dparams"/>, and <xref
linkend="cha-advanced-midi"/>. Since these features are more advanced,
- the chapters can basically be read in any order, as you need the
- features for your custom plugins.
+ the chapters can basically be read in any order, as you find that your
+ plugins require these features.
</para>
</listitem>
<listitem>
<para>
<guilabel><xref linkend="part-other"/></guilabel> — Explanation
- of writing source and sink plugins. Although the concepts introduced
- in the two previous parts of this guide apply to filter plugins, many
- of the concepts apply equally to source and sink plugins. This part
- will take a look at creating source and sink type plugins for
- &GStreamer; in the chapters on <xref linkend="cha-other-source"/> and
- <xref linkend="cha-other-sink"/>. The chapter on <xref
- linkend="cha-other-autoplugger"/> describes writing autoplugger
- plugins.
+ of writing other plugin types.
+ </para>
+ <para>
+ Because the first two parts of the guide use an audio filter as an
+ example, the concepts introduced apply to filter plugins. But many of
+ the concepts apply equally to other plugin types, including sources,
+ sinks, and autopluggers. This part of the guide presents the issues
+ that arise when working on these more specialized plugin types. The
+ part includes chapters on <xref linkend="cha-other-source"/>, <xref
+ linkend="cha-other-sink"/>, <xref linkend="cha-other-scheduler"/>, and
+ <xref linkend="cha-other-autoplugger"/>.
</para>
</listitem>
<listitem>
<para>
- <guilabel><xref linkend="part-appendix"/></guilabel> — The
- appendices contain some information that stubbornly refused to fit
- cleanly in other sections of this guide, like the <xref
- linkend="cha-appendix-checklist"/> and <xref
+ <guilabel><xref linkend="part-appendix"/></guilabel> — Further
+ information for plugin developers.
+ </para>
+ <para>
+ The appendices contain some information that stubbornly refuses to fit
+ cleanly in other sections of the guide. This information includes
+ <xref linkend="cha-appendix-checklist"/> and <xref
linkend="cha-appendix-python"/>. FIXME: organize better.
</para>
</listitem>
</itemizedlist>
<para>
- The remainder of this introductory part presents a short overview of the
- basic concepts involved in &GStreamer; plugin development. People familiar
- with the &GstAppDevMan; can use this short overview to refresh their
- memory. Topics covered include <xref linkend="sect1-basics-elements"/>,
- <xref linkend="sect1-basics-pads"/>, <xref
- linkend="sect1-basics-buffers"/>, <xref linkend="sect1-basics-types"/>,
- and <xref linkend="sect1-basics-events"/>.
+ The remainder of this introductory part of the guide presents a short
+ overview of the basic concepts involved in &GStreamer; plugin development.
+ Topics covered include <xref linkend="sect1-basics-elements"/>, <xref
+ linkend="sect1-basics-pads"/>, <xref linkend="sect1-basics-buffers"/>,
+ <xref linkend="sect1-basics-types"/>, and <xref
+ linkend="sect1-basics-events"/>. If you are already familiar with this
+ information, you can use this short overview to refresh your memory, or
+ you can skip to <xref linkend="part-building"/>.
</para>
-
<para>
As you can see, there a lot to learn, so let's get started!
</para>
This will allow your plugin to operate on a completely new media type.
</para>
</listitem>
- <listitem>
- <para>
- Creating custom schedulers when the default schedulers are
- insufficient.
- </para>
- </listitem>
- <listitem>
- <para>
- Creating custom autopluggers when the default ones are insufficient
- for your needs.
- </para>
- </listitem>
</itemizedlist>
</sect1>
</chapter>
projects / platform / upstream / gstreamer.git / commitdiff