gstreamer/docs/fwg/gst-plugin-writers-guide.sgml

<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "" [ 
<!ENTITY TITLEPAGE SYSTEM "titlepage.sgml">

<!ENTITY INTRO SYSTEM "intro.sgml">

<!ENTITY CONCEPTS SYSTEM "concepts.sgml">

<!ENTITY FIRSTPLUGIN SYSTEM ".sgml">

<!ENTITY TESTAPP SYSTEM ".sgml">

<!ENTITY LOOPBASED SYSTEM ".sgml">

<!ENTITY TYPESNPROPS SYSTEM ".sgml">

<!ENTITY BUFFERS SYSTEM ".sgml">

<!ENTITY SRCNSINK SYSTEM ".sgml">

<!ENTITY STATEMANAGE SYSTEM ".sgml">

<!ENTITY CHECKLIST SYSTEM ".sgml">
]>

<book id="index">
  &TITLEPAGE;
      
<!-- ############# part ############### -->

  <part id="introduction"><title>Introduction</title>
    <partintro>
      <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.
	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>

      &INTRO;
  </part>

<!-- ############ part ############# -->

  <part id="basic-concepts"><title>Basic concepts</title>
    <partintro>
      <para>

	This section introduces the basic concepts required to understand the
	issues involved in extending <application>GStreamer</application>

      </para>
    </partintro>

      &CONCEPTS;

  </part>

<!-- ############ part ############# -->

  <part id="first-plugin"><title>Building our first plugin</title>
    <partintro>
      <para>
	We are now have the neccessary concepts to build our first plugin.
	We are going to build an element which has a single input pad and
	a single output pad, and simply passes anything it reads on
	the input pad through and out on the output pad.  In a later
	section we will convert this plugin into something less useless.
      </para>
    </partintro>

      &FIRSTPLUGIN;

	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
  </part>

<!-- ############ part ############# -->

  <part id="test-app"><title>Building a simple test application</title>
    <partintro>
      <para>
      </para>
    </partintro>

      &TESTAPP;
	Initialization
	Instantiating the plugins
	  (NOTE: we really should have a debugging Sink)
	Connecting them
	Running the pipeline
  </part>

<!-- ############ part ############# -->

  <part id="loopbased"><title>Loop-based Elements</title>
    <partintro>
      <para>
      </para>
    </partintro>

      &LOOPBASED;
	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
  </part>

<!-- ############ part ############# -->

  <part id="typesnprops"><title>Types and Properties</title>
    <partintro>
      <para>
      </para>
    </partintro>

      &TYPESNPROPS;
	Building a simple format for testing
	A simple MIME type
	Type properties
	Typefind functions and autoplugging
  </part>

<!-- ############ part ############# -->

  <part id="buffersnmeta"><title>Buffers and Metadata</title>
    <partintro>
      <para>
      </para>
    </partintro>

      &BUFFERS;
	Anatomy of a Buffer
	Refcounts and mutability
	Metadata
		How Properties work efficiently
		Metadata mutability
		  (FIXME: this is an unsolved problem)
  </part>

<!-- ############ part ############# -->

  <part id="srcnsink"><title>Sources and Sinks</title>
    <partintro>
      <para>
      </para>
    </partintro>

      &SRCNSINK;
	Writing a source
		Pull vs loop based
		Region pulling
		  (NOTE: somewhere explain how filters use this)
	Writing a sink
		Gee, that was easy
  </part>

<!-- ############ part ############# -->

  <part id="statemanage"><title>State management</title>
    <partintro>
      <para>
      </para>
    </partintro>

      &STATEMANAGE;
	What are states?
	Mangaging filter state
  </part>

<!-- ############ part ############# -->

  <part id="checklist"><title>Checklist</title>
    <partintro>
      <para>
      </para>
    </partintro>

      &CHECKLIST;
	Things to check when writing a filter
	Things to check when writing a source or sink
  </part>

</book>





=====

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)