docs/manual/elements.xml

<chapter id="cha-elements">
  <title>GstElement</title>
  <para> 
    The most important object in <application>GStreamer</application> for the 
    application programmer is the <classname>GstElement</classname> object. 
  </para>

  <sect1 id="sec-elements-design">
    <title>What is a GstElement</title>
    <para> 
      The GstElement is the basic building block for the media pipeline. All the
      different components you are going to use are derived from this GstElement.
      This means that a lot of functions you are going to use operate on this object.
    </para>
    <para> Elements, from the perspective of GStreamer, are viewed as "black boxes" with a number of
      different aspects. One of these aspects is the presence of "pads", or connection points. This
      terminology arises from soldering; pads are where wires can be attached.
    </para>

    <sect2 id="sec-elements-src">
      <title>Source elements</title>
      <para>
        Source elements generate data for use by a pipeline, for example reading from disk or from a
	sound card.
      </para>
      <para>
        Below you see how we will visualize the element.
	We always draw a src pad to the right of the element.
      </para>
      <figure float="1" id="sec-element-srcimg">
        <title>Visualisation of a source element</title>
          <mediaobject>  
            <imageobject>
              <imagedata fileref="images/src-element.&magic;" format="&magic;" />
            </imageobject>
          </mediaobject>
      </figure>
      <para>
        Source elements do not accept data, they only generate data. You can see
	this in the figure because it only has a src pad. A src pad can only 
	generate buffers.
      </para>
    </sect2>

    <sect2 id="sec-elements-filter">
      <title>Filters and codecs</title>
      <para>
        Filter elements both have input and output pads. They operate on data they receive in their
	sink pads and produce data on their src pads. For example, MPEG decoders and volume filters
	would fall into this category.
      </para>
      <para>
        Elements are not constrained as to the number of pads they migh have; for example, a video
	mixer might have two input pads (the images of the two different video streams) and one
	output pad.
      </para>
      <figure float="1" id="sec-element-filterimg">
        <title>Visualisation of a filter element</title>
          <mediaobject>  
            <imageobject>
              <imagedata fileref="images/filter-element.&magic;" format="&magic;" />
            </imageobject>
          </mediaobject>
      </figure>
      <para>
        The above figure shows the visualisation of a filter element. This element has 
	one sink (input) pad and one src (output) pad. Sink pads are drawn on the left
	of the element.
      </para> 
      <figure float="1" id="sec-element-multifilterimg">
        <title>Visualisation of a filter element with
	  more than one output pad</title>
        <mediaobject>  
          <imageobject>
            <imagedata fileref="images/filter-element-multi.&magic;" format="&magic;" />
          </imageobject>
        </mediaobject>
      </figure>
      <para>
        The above figure shows the visualisation of a filter element with more than one output pad.
	An example of such a filter is the AVI splitter (demuxer). This element will parse the input
	data and extracts the audio and video data. Most of these filters dynamically send out a
	signal when a new pad is created so that the application programmer can connect an arbitrary
	element to the newly created pad.
      </para>
    </sect2>
  
    <sect2 id="sec-elements-sink">
      <title>Sink elements</title>
      <para>
        Sink elements are terminal points in a media pipeline. They accept data but do not produce
	anything. Disk writing, soundcard playback, and video output woul all be implemented by sink
	elements.
      </para>
      <figure float="1" id="sec-element-sinkimg">
        <title>Visualisation of a sink element</title>
        <mediaobject>  
          <imageobject>
            <imagedata fileref="images/sink-element.&magic;" format="&magic;" />
          </imageobject>
        </mediaobject>
      </figure>
    </sect2>
  </sect1>
  <sect1 id="sec-elements-create">
    <title>Creating a GstElement</title>
    <para> 
      GstElements are created from factories. To create an element, one has to get
      access the a <classname>GstElementFactory</classname> using a unique factoryname.
    </para> 
    <para> 
      The following code example is used to get a factory that can be used to create the 
      'mad' element, an mp3 decoder.
    </para> 
    <programlisting>
 GstElementFactory *factory;

 factory = gst_elementfactory_find ("mad");
    </programlisting>
    <para> 
      Once you have the handle to the elementfactory, you can create a real element with
      the following code fragment:
    </para> 
    <programlisting>
 GstElement *element;

 element = gst_elementfactory_create (factory, "decoder");
    </programlisting>
    <para>
      gst_elementfactory_create () will use the elementfactory to create an element with the given
      name. The name of the element is something you can use later on to lookup the element in a
      bin, for example. You can pass NULL as the name argument to get a unique, default name.
    </para>
    <para>
      A simple shortcut exists for creating an element from a factory. The following example creates
      an element, named "decoder" from the elementfactory named "mad". This convenient function is
      most widely used to create an element.
    </para>
    <programlisting>
 GstElement *element;

 element = gst_elementfactory_make ("mad", "decoder");
    </programlisting>
    <para> 
      An element can be destroyed with:  FIXME talk about refcounting
    </para> 
    <programlisting>
 GstElement *element;

  ...
 gst_element_destroy (element);
    </programlisting>
  </sect1>
</chapter>