gstreamer/docs/manual/elements.sgml

<chapter id="cha-elements">
  <title>GstElement</title>
  <para> 
    The most important object in GStreamer for the application programmer is
    the GstElement 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> 
      We will first describe the three most important types of elements that you are 
      going to use. They are the Source, Filter and Sink elements.
    </para>
    <para> 
      You will also see that those elements have pads. These are the elements 
      connections with the 'outside' world.
    </para>
    <sect2 id="sec-elements-src">
      <title>GStreamer source elements (<classname>GstSrc</classname>)</title>
      <para>
        This element will generate data that will be used by the pipeline. It is
	typically a file or an audio source.
      </para>
      <para>
        Below you see how we will visualize the <classname>GstSrc</classname> 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 <classname>GstSrc</classname> element</title>
        <graphic fileref="images/src-element" format="png"></graphic>
      </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>GStreamer filter elements (<classname>GstFilter</classname>)</title>
      <para>
        Filter elements both have an input and an output pad. They operate on data
	they receive in the sink pad and send the result to the src pad.
      </para> 
      <para>
        Examples of a filter element might include: an MPEG decoder, volume filter,...
      </para> 
      <para>
        Filters may also contain any number of input pads and output pads. For example,
	a video mixer might have to 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 <classname>GstFilter</classname> element</title>
        <graphic fileref="images/filter-element" format="png"></graphic>
      </figure>
      <para>
        The above figure shows the visualisation of a filter element. This element has 
	one sink pad (input) 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 <classname>GstFilter</classname> element with
	  more than one output pad</title>
        <graphic fileref="images/filter-element-multi" format="png"></graphic>
      </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. 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>GStreamer sink elements (<classname>GstSink</classname>)</title>
      <para> 
        This element accepts data but will not generate any new data. A sink element 
	is typically a file on disk, a soundcard, a display,... It is presented as
	below:
      </para> 
      <figure float="1" id="sec-element-sinkimg">
        <title>Visualisation of a <classname>GstSink</classname> element</title>
        <graphic fileref="images/sink-element" format="png"></graphic>
      </figure>
    </sect2>

  </sect1>
</chapter>