mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-06-05 06:58:56 +00:00
Code Issues 1 Projects Releases Wiki Activity

Wrote introduction, and changed name to plugin writers guide (though files still need rename). I'll leave the filena...

Browse source 
Original commit message from CVS:
Wrote introduction, and changed name to plugin writers guide (though
files still need rename).  I'll leave the filenames as is for now, since
the name might still change again...
This commit is contained in:
Richard Boulton 2001-01-07 00:12:46 +00:00
parent 7c51d6e0ca
commit 3408d28133
3 changed files with 216 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

163
docs/fwg/gst-filter-writers-guide.sgml
View file

@ -1,53 +1,37 @@
<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "" [
<!ENTITY TITLEPAGE SYSTEM "titlepage.sgml">
<!ENTITY INTRO SYSTEM "intro.sgml">
<!ENTITY ELEMENTPADS SYSTEM "elementpads.sgml">
<!ENTITY BUFFERS SYSTEM "buffers.sgml">
<!ENTITY CHAINVSLOOP SYSTEM "chainvsloop.sgml">
<!ENTITY SCHEDULING SYSTEM "scheduling.sgml">
<!ENTITY TYPING SYSTEM "typing.sgml">
]>
<book id="index">
<bookinfo>
<authorgroup>
<author>
<firstname>Richard</firstname>
<surname>Boulton</surname>
<authorblurb>
<para>
<email>richard-gst@tartarus.org</email>
</para>
</authorblurb>
</author>
</authorgroup>
<legalnotice>
<para>
This material may be distributed only subject to the terms and
conditions set forth in the Open Publication License, v1.0 or later (the
latest version is presently available at <ulink url="
http://www.opencontent.org/openpub/"
type="http">http://www.opencontent.org/openpub/</ulink> )
</para>
</legalnotice>
<title><application>GStreamer</application> Filter Writer's Guide</title>
</bookinfo>
&TITLEPAGE;
<!-- ############# Overview - part ############### -->
<part id="overview"><title>Overview</title>
<partintro>
<para>
This book describes how to extend the capabilities of
<application>GStreamer</application> by creating a new filter. The
reader should be familiar with the basic workings of
<application>GStreamer</application>. For a gentle introduction to
GStreamer, you may wish to read the <emphasis>FIXME</emphasis> Since
<application>GStreamer</application> adheres to the GTK+ programming
model, the reader is also assumed to understand the basics of GTK+.
<para>
This document describes how to extend the capabilities of
<application>GStreamer</application> by creating new plugins.
</para>
<para>
It first describes the concepts required and the ways in which
<application>GStreamer</application> can be extended. It then goes
through a worked example of how to write a simple filter (for data
processing), and how to test and debug it. More advanced concepts are
then introduced, with worked examples of each. Next, writing source
and sink elements (for performing input and output) is discussed.
Finally, checklists of things to be sure to do when extending
<application>GStreamer</application> are presented.
</para>
</partintro>
<!-- ############ Introduction - chapter ############# -->
&INTRO;
</part>
@ -55,15 +39,114 @@
<part id="basic-concepts"><title>Basic concepts</title>
<partintro>
<para>
We will first describe the concepts it is neccessary to understand
before building a filter.
<para>
Filters are at the core of what GStreamer is. Without filters,
GStreamer is just a bunch of pipe fittings with nothing to
connect. A large number of filters (known as elements) ship with
GStreamer, but they are only capable of so much. If you wish to
extend it beyond these standard capabilities, you must write
filters.
</para>
<para>
A filter may be constructed in several different ways, but all must
conform to the same basic rules. A simple filter may be built
with the FilterFactory, where the only code that need be written
is the actual filter code. A more complex filter may need to be
written out fully for complete access to the features and
performance possible with GStreamer. This guide will explain all
the steps necessary for both methods.
</para>
</partintro>
<!-- ############ Basic concepts - chapter ############# -->
&ELEMENTPADS;
&BUFFERS;
&CHAINVSLOOP;
&SCHEDULING;
&TYPING;
</part>
<!-- ############ Building A Filter - part ############# -->
</book>
GStreamer Filter Writer's Guide
===============================
Outline:
Basic concepts
Chain vs loop elements
Scheduling
Buffers
Typing and Properties
Metadata
Building our first filter
Constructing the boilerplate
Doing it the easy way with FilterFactory
(NOTE: FilterFactory doesn't exist yet)
Doing it the hard way with G[tk]Object
An identity filter
Building an object with pads
Attaching functions
The chain function
The plugin_init function
Registering the types
Registering the filter
Building a simple test application
Initialization
Instantiating the plugins
(NOTE: we really should have a debugging Sink)
Connecting them
Running the pipeline
Loop-based Elements
How scheduling works, aka pushing and pulling
How a loopfunc works, aka pulling and pushing
Adding a second output
Identity is now a tee
Modifying the test application
Types and Properties
Building a simple format for testing
A simple MIME type
Type properties
Typefind functions and autopluggin
Buffers and Metadata
Anatomy of a Buffer
Refcounts and mutability
Metadata
How Properties work efficiently
Metadata mutability
(FIXME: this is an unsolved problem)
Sources and Sinks
Writing a source
Pull vs loop based
Region pulling
(NOTE: somewhere explain how filters use this)
Writing a sink
Gee, that was easy
State management
What are states?
Mangaging filter state
Checklist
Things to check when writing a filter
Things to check when writing a source or sink
=====
Omega: a chain-based element has chain functions on each sink pad, the
connected source pad may directly call (i.e. on the stack) the chain
function
Omega: each chain function is responsible for doing something useful,
generally processing the buffer and pushing out the other end
Omega: a loop-based element has a single function attatched to the element
(not tha pads) that spins in a loop calling gst_pad_pull(sinkpad),
do stuff, gst_pad_push(srcpad)

56
docs/fwg/intro.sgml Normal file
View file

@ -0,0 +1,56 @@
<chapter id="cha-intro">
<title>Introduction</title>
<para>
<application>GStreamer</application> is a framework for creating
streaming media applications. It is extremely powerful and versatile,
and this versatility stems in part from its modularity, and its ability
to incorporate new modules seamlessly into its framework.
</para>
<sect1 id="sec-intro-doicare">
<title>Do I care?</title>
<para>
This guide explains how to write new modules for GStreamer. It is
relevant to:
<itemizedlist>
<listitem>
Anyone who wants to add support for new input and output
devices, often called sources and sinks. For example,
adding the ability to write to a new video output system
could be done by writing an appropriate sink plugin.
</listitem>
<listitem>
Anyone who wants to add support for new ways of processing
data in GStreamer, often called
filters. For example, a new data format converter could be
created.
</listitem>
<listitem>
Anyone who wants to extend GStreamer in
any way: you need to have an understanding of how the plugin system
works before you can understand the constraints it places on the
rest of the code. And you might be surprised at how much can be
done with plugins.
</listitem>
</itemizedlist>
</para>
<para>
This guide is not relevant to you if you only want to use the existing
functionality of GStreamer, or use an application which uses GStreamer.
You lot can go away. Shoo... (You might find the <emphasis>GStreamer
Application Development Manual</emphasis> helpful though.)
</para>
</sect1>
<sect1 id="sec-intro-reading">
<title>Preliminary reading</title>
<para>
The reader should be familiar with the basic workings of
<application>GStreamer</application>. For a gentle introduction to
GStreamer, you may wish to read the <emphasis>GStreamer Application
Development Manual</emphasis>. Since
<application>GStreamer</application> adheres to the GTK+ programming
model, the reader is also assumed to understand the basics of GTK+.
</para>
</sect1>
</chapter>

37
docs/fwg/titlepage.sgml Normal file
View file

@ -0,0 +1,37 @@
<bookinfo>
<authorgroup>
<author>
<firstname>Richard</firstname>
<surname>Boulton</surname>
<authorblurb>
<para>
<email>richard-gst@tartarus.org</email>
</para>
</authorblurb>
</author>
<author>
<firstname>Erik</firstname>
<surname>Walthinsen</surname>
<authorblurb>
<para>
<email>omega@temple-baptist.com</email>
</para>
</authorblurb>
</author>
</authorgroup>
<legalnotice>
<para>
This material may be distributed only subject to the terms and
conditions set forth in the Open Publication License, v1.0 or
later (the latest version is presently available at <ulink
url="http://www.opencontent.org/openpub/"
type="http">http://www.opencontent.org/openpub/"</ulink> )
</para>
</legalnotice>
<title><application>GStreamer</application> Plugin Writer's Guide</title>
</bookinfo>