From af236bd270202ddc9482d0cdd6fb4f393fa47340 Mon Sep 17 00:00:00 2001 From: Leif Johnson Date: Thu, 28 Nov 2002 08:37:12 +0000 Subject: [PATCH] + small updates to plugin writer's guide Original commit message from CVS: + small updates to plugin writer's guide --- docs/pwg/building-boiler.xml | 41 +++++---- docs/pwg/gst-plugin-writers-guide.xml | 41 +++++---- docs/pwg/intro-basics.xml | 122 ++++++++++++++++---------- docs/pwg/intro-preface.xml | 99 ++++++++++----------- 4 files changed, 167 insertions(+), 136 deletions(-) diff --git a/docs/pwg/building-boiler.xml b/docs/pwg/building-boiler.xml index 5e864fd6af..c8c12a6c98 100644 --- a/docs/pwg/building-boiler.xml +++ b/docs/pwg/building-boiler.xml @@ -5,10 +5,11 @@ 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. @@ -20,16 +21,18 @@ 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, it is left as an exercise to the + reader.) The first step is to check out a copy of the gst-template CVS module to get an important tool and - the source code template for the basic &GStreamer; plugin. To check out - the gst-template module, type the following two - commands on a command line: + the source code template for a basic &GStreamer; plugin. To check out the + gst-template module, make sure you are connected to + the internet, and type the following commands at a command console: +shell $ cd . shell $ cvs -d:pserver:anonymous@cvs.gstreamer.sourceforge.net:/cvsroot/gstreamer login Logging in to :pserver:anonymous@cvs.gstreamer.sourceforge.net:2401/cvsroot/gstreamer CVS password: @@ -47,7 +50,7 @@ U gst-template/gst-app/src/Makefile.am After the first command, you will have to press ENTER 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 ./gst-template. The template you will be using is in - - Using Filterstamp + + Using the Project Stamp 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 @@ -72,10 +75,12 @@ U gst-template/gst-app/src/Makefile.am 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 - pluginstamp.sh in the tools/ directory of the - gst-template source tree that does exactly this. + according to your needs. To help you do so, there are some tools in the + ./gst-template/tools/ directory. + One tool, gst-quick-stamp, is a quick command line + tool. The other, gst-project-stamp, is a full GNOME + druid application that takes you through the steps of creating a new + project (either a plugin or an application). To use pluginstamp.sh, first open up a terminal window. @@ -97,9 +102,9 @@ U gst-template/gst-app/src/Makefile.am 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 ~/src/examplefilter/: diff --git a/docs/pwg/gst-plugin-writers-guide.xml b/docs/pwg/gst-plugin-writers-guide.xml index dfee7db9fb..71c0a98e9b 100644 --- a/docs/pwg/gst-plugin-writers-guide.xml +++ b/docs/pwg/gst-plugin-writers-guide.xml @@ -32,7 +32,7 @@ GStreamer"> - + GStreamer Application Development Manual"> GStreamer Library Reference"> ]> @@ -56,13 +56,12 @@ 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;. @@ -76,22 +75,22 @@ Building a Filter - 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 ExampleFilter. + 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 ExampleFilter. 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, , 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, , you + will be able to add even more functionality to your plugins. The example code used in this part of the guide can be found in diff --git a/docs/pwg/intro-basics.xml b/docs/pwg/intro-basics.xml index 31770d4ab4..53a26afe64 100644 --- a/docs/pwg/intro-basics.xml +++ b/docs/pwg/intro-basics.xml @@ -4,9 +4,9 @@ Basic Concepts 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. @@ -17,29 +17,30 @@ Elements are at the core of &GStreamer;. In the context of plugin development, an element is an object derived from the - GstElement 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. - - - A filter 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 - source and sink elements, - respectively. + GstElement 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. 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 - plugin 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. + to encapsulate your element in a plugin 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. + + + A filter is an important type of element that + processes a stream of data. Producers and consumers of data are called + source and sink elements, + respectively. Elements that connect other elements together are called + autoplugger elements, and a bin + element contains other elements. Bins are often responsible for scheduling + the elements that they contain so that data flows smoothly. The plugin mechanism is used everywhere in &GStreamer;, even if only the @@ -66,19 +67,29 @@ Pads are used to negotiate connections and data flow between elements in &GStreamer;. A pad can be viewed as a - place 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. + place or port 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. 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. + + + 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 + source pads, and elements accept incoming data through + one or more sink pads. Source and sink elements have + only source and sink pads, respectively. See the &GstLibRef; for the current implementation details of a Buffers 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. @@ -125,8 +136,7 @@ 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 for more details). + freed in some sense (see below for more details). @@ -143,15 +153,29 @@ 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. - 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. + To improve the latency in a media pipeline, many &GStreamer; elements + use a buffer pool 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!] + + + 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. @@ -456,12 +480,14 @@ Events - Events are a special type of data in &GStreamer;. - Events 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 GstBuffer, 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 event 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. See the &GstLibRef; for the current implementation details of a — - 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 . Then you - will learn how to write the code to get a basic filter plugin working. - Several chapters cover these concepts, including + + 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 . Then + you will learn how to write the code to get a basic filter plugin + working: These steps include chapters on , , , and . - 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 and . Finally, you will learn to test your - new plugin in . + 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 + and . Finally, you will see in + how to write a short test + application to try out your new plugin. — Information on advanced features of &GStreamer; plugin development. + + 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 , - , , , , , and . 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. — 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 and - . The chapter on describes writing autoplugger - plugins. + of writing other plugin types. + + + 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 , , , and + . - — The - appendices contain some information that stubbornly refused to fit - cleanly in other sections of this guide, like the and — Further + information for plugin developers. + + + The appendices contain some information that stubbornly refuses to fit + cleanly in other sections of the guide. This information includes + and . FIXME: organize better. - 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 , - , , , - and . + 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 , , , + , and . If you are already familiar with this + information, you can use this short overview to refresh your memory, or + you can skip to . - As you can see, there a lot to learn, so let's get started! @@ -175,18 +188,6 @@ This will allow your plugin to operate on a completely new media type. - - - Creating custom schedulers when the default schedulers are - insufficient. - - - - - Creating custom autopluggers when the default ones are insufficient - for your needs. - -