docs/manual/elements.xml

   1 <chapter id="cha-elements">
   2   <title>GstElement</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="sec-elements-design">
   9     <title>What is a GstElement</title>
  10     <para>
  11       <classname>GstElement</classname> is the basic building block for the
  12       media pipeline. All the different 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", or link points. This terminology arises from soldering;
  20       pads are where wires can be attached.
  21     </para>
  22
  23     <sect2 id="sec-elements-src">
  24       <title>Source elements</title>
  25       <para>
  26         Source elements generate data for use by a pipeline, for example
  27         reading from disk or from a sound card.
  28       </para>
  29       <para>
  30         Below you see how we will visualize the element.
  31         We always draw a source pad to the right of the element.
  32       </para>
  33       <figure float="1" id="sec-element-srcimg">
  34         <title>Visualisation of a source element</title>
  35           <mediaobject>
  36             <imageobject>
  37               <imagedata fileref="images/src-element.&magic;" format="&MAGIC;" />
  38             </imageobject>
  39           </mediaobject>
  40       </figure>
  41       <para>
  42         Source elements do not accept data, they only generate data. You can
  43         see this in the figure because it only has a source pad. A source
  44         pad can only generate data.
  45       </para>
  46     </sect2>
  47
  48     <sect2 id="sec-elements-filter">
  49       <title>Filters and codecs</title>
  50       <para>
  51         Filter elements both have input and output pads. They operate on
  52         data they receive in their sink pads and produce data on their source
  53         pads. For example, MPEG decoders and volume filters would fall into
  54         this category.
  55       </para>
  56       <para>
  57         Elements are not constrained as to the number of pads they might have;
  58         for example, a video mixer might have two input pads (the images of
  59         the two different video streams) and one output pad.
  60       </para>
  61       <figure float="1" id="sec-element-filterimg">
  62         <title>Visualisation of a filter element</title>
  63           <mediaobject>
  64             <imageobject>
  65               <imagedata fileref="images/filter-element.&magic;" format="&MAGIC;" />
  66             </imageobject>
  67           </mediaobject>
  68       </figure>
  69       <para>
  70         The above figure shows the visualisation of a filter element.
  71         This element has one sink (input) pad and one source (output) pad.
  72         Sink pads are drawn on the left of the element.
  73       </para>
  74       <figure float="1" id="sec-element-multifilterimg">
  75         <title>Visualisation of a filter element with
  76           more than one output pad</title>
  77         <mediaobject>
  78           <imageobject>
  79             <imagedata fileref="images/filter-element-multi.&magic;"
  80                        format="&MAGIC;" />
  81           </imageobject>
  82         </mediaobject>
  83       </figure>
  84       <para>
  85         The above figure shows the visualisation of a filter element with
  86         more than one output pad. An example of such a filter is the AVI
  87         splitter (demultiplexer). This element will parse the input data and
  88         extract the audio and video data. Most of these filters dynamically
  89         send out a signal when a new pad is created so that the application
  90         programmer can link an arbitrary element to the newly created pad.
  91       </para>
  92     </sect2>
  93
  94     <sect2 id="sec-elements-sink">
  95       <title>Sink elements</title>
  96       <para>
  97         Sink elements are terminal points in a media pipeline. They accept
  98         data but do not produce anything. Disk writing, soundcard playback,
  99         and video output would all be implemented by sink elements.
 100       </para>
 101       <figure float="1" id="sec-element-sinkimg">
 102         <title>Visualisation of a sink element</title>
 103         <mediaobject>
 104           <imageobject>
 105             <imagedata fileref="images/sink-element.&magic;" format="&MAGIC;" />
 106           </imageobject>
 107         </mediaobject>
 108       </figure>
 109     </sect2>
 110   </sect1>
 111   <sect1 id="sec-elements-create">
 112     <title>Creating a GstElement</title>
 113     <para>
 114       A <classname>GstElement</classname> object is created from
 115       a factory.  To create an element, you have to get access to a
 116       <classname>GstElementFactory</classname> object using a unique
 117       factory name.
 118     </para>
 119     <para>
 120       The following code example is used to get a factory that can be used
 121       to create the 'mad' element, an mp3 decoder.
 122     </para>
 123     <programlisting>
 124  GstElementFactory *factory;
 125
 126  factory = gst_element_factory_find ("mad");
 127     </programlisting>
 128     <para>
 129       Once you have the handle to the element factory, you can create a
 130       real element with the following code fragment:
 131     </para>
 132     <programlisting>
 133  GstElement *element;
 134
 135  element = gst_element_factory_create (factory, "decoder");
 136     </programlisting>
 137     <para>
 138       <function>gst_element_factory_create</function> will use the element
 139       factory to create an element with the given name. The name of the
 140       element is something you can use later on to look up the element in
 141       a bin, for example. You can pass <symbol>NULL</symbol> as the name
 142       argument to get a unique, default name.
 143     </para>
 144     <para>
 145       A simple shortcut exists for creating an element from a factory. The
 146       following example creates an element named "decoder" from the element
 147       factory named "mad". This convenience function is most widely used to
 148       create an element.
 149     </para>
 150     <programlisting>
 151  GstElement *element;
 152
 153  element = gst_element_factory_make ("mad", "decoder");
 154     </programlisting>
 155     <para>
 156       When you don't need the element anymore, you need to unref it, as shown in the following
 157       example.
 158     </para>
 159     <programlisting>
 160  GstElement *element;
 161
 162   ...
 163  gst_element_unref (element);
 164     </programlisting>
 165   </sect1>
 166   <sect1 id="sec-elements-properties">
 167     <title>GstElement properties</title>
 168     <para>
 169       A <classname>GstElement</classname> can have several properties
 170       which are implemented using standard <classname>GObject</classname>
 171       properties. The usual <classname>GObject</classname> methods to query,
 172       set and get property values and <classname>GParamSpecs</classname>
 173       are therefore supported.
 174     </para>
 175     <para>
 176       Every <classname>GstElement</classname> inherits at least
 177       one property of its parent <classname>GstObject</classname>:
 178       the "name" property. This is the name you provide to the
 179       functions <function>gst_element_factory_make</function> or
 180       <function>gst_element_factory_create</function>. You can get and set
 181       this property using the functions
 182       <function>gst_object_set_name</function>
 183       and <function>gst_object_get_name</function> or use the
 184       <classname>GObject</classname> property mechanism as shown below.
 185     </para>
 186     <programlisting>
 187  GstElement *element;
 188  GValue value = { 0, }; /* initialize the GValue for g_object_get() */
 189
 190  element = gst_element_factory_make ("mad", "decoder");
 191  g_object_set (G_OBJECT (element), "name", "mydecoder", NULL);
 192  ...
 193
 194  g_value_init (&amp;value, G_TYPE_STRING);
 195  g_object_get_property (G_OBJECT (element), "name", &amp;value);
 196  ...
 197     </programlisting>
 198     <para>
 199       Most plugins provide additional properties to provide more information
 200       about their configuration or to configure the element.
 201       <command>gst-inspect</command> is a useful tool to query the properties
 202       of a particular element, it will also use property introspection to give
 203       a short explanation about the function of the property and about the
 204       parameter types and ranges it supports.
 205     </para>
 206     <para>
 207       For more information about <classname>GObject</classname>
 208       properties we recommend you read the <ulink
 209       url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
 210       type="http">GObject manual</ulink>.
 211     </para>
 212   </sect1>
 213
 214   <sect1 id="sec-elements-signals">
 215     <title>GstElement signals</title>
 216     <para>
 217       A <classname>GstElement</classname> also provides various
 218       <classname>GObject</classname> signals that can be used as a flexible
 219       callback mechanism.
 220     </para>
 221   </sect1>
 222
 223   <sect1 id="sec-elements-factories">
 224     <title>More about GstElementFactory</title>
 225     <para>
 226       We talk some more about the GstElementFactory object.
 227     </para>
 228
 229     <sect2 id="sec-elements-factories-details">
 230       <title>Getting information about an element using the factory details</title>
 231       <para>
 232       </para>
 233     </sect2>
 234
 235     <sect2 id="sec-elements-factories-padtemplates">
 236       <title>Finding out what pads an element can contain</title>
 237       <para>
 238       </para>
 239     </sect2>
 240
 241     <sect2 id="sec-elements-factories-query">
 242       <title>Different ways of querying the factories</title>
 243       <para>
 244       </para>
 245     </sect2>
 246   </sect1>
 247 </chapter>