docs/manual/basics-elements.xml

   1 <chapter id="chapter-elements">
   2   <title>Elements</title>
   3   <para>
   4     The most important object in <application>GStreamer</application> for the
   5     application programmer is the <classname>GstElement</classname> object.
   6   </para>
   7
   8   <sect1 id="section-elements-design">
   9     <title>What is an element ?</title>
  10     <para>
  11       An element is the basic building block for the media pipeline.
  12       All the different high-level components you are going to use are
  13       derived from <classname>GstElement</classname>.  This means that a
  14       lot of functions you are going to use operate on objects of this class.
  15     </para>
  16     <para>
  17       Elements, from the perspective of GStreamer, are viewed as "black boxes"
  18       with a number of different aspects. One of these aspects is the presence
  19       of "pads" (see <xref linkend="chapter-pads"/>), or link points. This terminology arises from soldering;
  20       pads are where wires can be attached.
  21     </para>
  22   </sect1>
  23
  24   <sect1 id="section-elements-types">
  25     <title>Types of elements</title>
  26
  27     <sect2 id="section-elements-src">
  28       <title>Source elements</title>
  29       <para>
  30         Source elements generate data for use by a pipeline, for example
  31         reading from disk or from a sound card.
  32       </para>
  33       <para>
  34         <xref linkend="section-element-srcimg"/> shows how we will visualise
  35         a source element.
  36         We always draw a source pad to the right of the element.
  37       </para>
  38       <figure float="1" id="section-element-srcimg">
  39         <title>Visualisation of a source element</title>
  40           <mediaobject>
  41             <imageobject>
  42               <imagedata fileref="images/src-element.&image;" format="&IMAGE;" />
  43             </imageobject>
  44           </mediaobject>
  45       </figure>
  46       <para>
  47         Source elements do not accept data, they only generate data. You can
  48         see this in the figure because it only has a source pad. A source
  49         pad can only generate data.
  50       </para>
  51     </sect2>
  52
  53     <sect2 id="section-elements-filter">
  54       <title>Filters and codecs</title>
  55       <para>
  56         Filter elements have both input and output pads. They operate on
  57         data they receive in their sink pads and produce data on their source
  58         pads. For example, MPEG decoders and volume filters would fall into
  59         this category.
  60       </para>
  61       <para>
  62         Elements are not constrained as to the number of pads they might have;
  63         for example, a video mixer might have two input pads (the images of
  64         the two different video streams) and one output pad.
  65       </para>
  66       <figure float="1" id="section-element-filterimg">
  67         <title>Visualisation of a filter element</title>
  68           <mediaobject>
  69             <imageobject>
  70               <imagedata fileref="images/filter-element.&image;" format="&IMAGE;" />
  71             </imageobject>
  72           </mediaobject>
  73       </figure>
  74       <para>
  75         <xref linkend="section-element-filterimg"/> shows how we will visualise
  76         a filter element.
  77         This element has one sink (input) pad and one source (output) pad.
  78         Sink pads are drawn on the left of the element.
  79       </para>
  80       <figure float="1" id="section-element-multifilterimg">
  81         <title>Visualisation of a filter element with
  82           more than one output pad</title>
  83         <mediaobject>
  84           <imageobject>
  85             <imagedata fileref="images/filter-element-multi.&image;"
  86                        format="&IMAGE;" />
  87           </imageobject>
  88         </mediaobject>
  89       </figure>
  90       <para>
  91         <xref linkend="section-element-multifilterimg"/> shows the visualisation of a filter element with
  92         more than one output pad. An example of such a filter is the AVI
  93         demultiplexer. This element will parse the input data and
  94         extract the audio and video data. Most of these filters dynamically
  95         send out a signal when a new pad is created so that the application
  96         programmer can link an arbitrary element to the newly created pad.
  97       </para>
  98     </sect2>
  99
 100     <sect2 id="section-elements-sink">
 101       <title>Sink elements</title>
 102       <para>
 103         Sink elements are end points in a media pipeline. They accept
 104         data but do not produce anything. Disk writing, soundcard playback,
 105         and video output would all be implemented by sink elements.
 106         <xref linkend="section-element-sinkimg"/> shows a sink element.
 107       </para>
 108       <figure float="1" id="section-element-sinkimg">
 109         <title>Visualisation of a sink element</title>
 110         <mediaobject>
 111           <imageobject>
 112             <imagedata fileref="images/sink-element.&image;" format="&IMAGE;" />
 113           </imageobject>
 114         </mediaobject>
 115       </figure>
 116     </sect2>
 117   </sect1>
 118 </chapter>