docs/manual/basics-elements.xml

   1 <chapter id="chapter-elements" xreflabel="Elements">
   2   <title>Elements</title>
   3   <para>
   4     The most important object in &GStreamer; for the application programmer
   5     is the <ulink type="http"
   6     url="../../gstreamer/html/GstElement.html"><classname>GstElement</classname></ulink>
   7     object. An element is the basic building block for a media pipeline. All
   8     the different high-level components you will use are derived from
   9     <classname>GstElement</classname>. Every decoder, encoder, demuxer, video
  10     or audio output is in fact a <classname>GstElement</classname>
  11   </para>
  12
  13   <sect1 id="section-elements-design" xreflabel="What are elements?">
  14     <title>What are elements?</title>
  15     <para>
  16       For the application programmer, elements are best visualized as black
  17       boxes. On the one end, you might put something in, the element does
  18       something with it and something else comes out at the other side. For
  19       a decoder element, ifor example, you'd put in encoded data, and the
  20       element would output decoded data. In the next chapter (see <xref
  21       linkend="chapter-pads"/>), you will learn more about data input and
  22       output in elements, and how you can set that up in your application.
  23     </para>
  24
  25     <sect2 id="section-elements-src">
  26       <title>Source elements</title>
  27       <para>
  28         Source elements generate data for use by a pipeline, for example
  29         reading from disk or from a sound card. <xref
  30         linkend="section-element-srcimg"/> shows how we will visualise
  31         a source element. We always draw a source pad to the right of
  32         the element.
  33       </para>
  34       <figure float="1" id="section-element-srcimg">
  35         <title>Visualisation of a source element</title>
  36           <mediaobject>
  37             <imageobject>
  38               <imagedata fileref="images/src-element.&image;"
  39               format="&IMAGE;"/>
  40             </imageobject>
  41           </mediaobject>
  42       </figure>
  43       <para>
  44         Source elements do not accept data, they only generate data. You can
  45         see this in the figure because it only has a source pad (on the
  46         right). A source pad can only generate data.
  47       </para>
  48     </sect2>
  49
  50     <sect2 id="section-elements-filter">
  51       <title>Filters, convertors, demuxers, muxers and codecs</title>
  52       <para>
  53         Filters and filter-like elements have both input and outputs pads.
  54         They operate on data that they receive on their input (sink) pads,
  55         and will provide data on their output (source) pads. Examples of
  56         such elements are a volume element (filter), a video scaler
  57         (convertor), an Ogg demuxer or a Vorbis decoder.
  58       </para>
  59       <para>
  60         Filter-like elements can have any number of source or sink pads. A
  61         video demuxer, for example, would have one sink pad and several
  62         (1-N) source pads, one for each elementary stream contained in the
  63         container format. Decoders, on the other hand, will only have one
  64         source and sink pads.
  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;"
  71               format="&IMAGE;"/>
  72             </imageobject>
  73           </mediaobject>
  74       </figure>
  75       <para>
  76         <xref linkend="section-element-filterimg"/> shows how we will
  77         visualise a filter-like element. This specific element has one source
  78         and one sink element. Sink pads, receiving input data, are depicted
  79         at the left of the element; source pads are still on the right.
  80       </para>
  81       <figure float="1" id="section-element-multifilterimg">
  82         <title>Visualisation of a filter element with
  83           more than one output pad</title>
  84         <mediaobject>
  85           <imageobject>
  86             <imagedata fileref="images/filter-element-multi.&image;"
  87             format="&IMAGE;" />
  88           </imageobject>
  89         </mediaobject>
  90       </figure>
  91       <para>
  92         <xref linkend="section-element-multifilterimg"/> shows another
  93         filter-like element, this one having more than one output (source)
  94         pad. An example of one such element could, for example, be an Ogg
  95         demuxer for an Ogg stream containing both audio and video. One
  96         source pad will contain the elementary video stream, another will
  97         contain the elementary audio stream. Demuxers will generally fire
  98         signals when a new pad is created. The application programmer can
  99         then handle the new elementary stream in the signal handler.
 100       </para>
 101     </sect2>
 102
 103     <sect2 id="section-elements-sink">
 104       <title>Sink elements</title>
 105       <para>
 106         Sink elements are end points in a media pipeline. They accept
 107         data but do not produce anything. Disk writing, soundcard playback,
 108         and video output would all be implemented by sink elements.
 109         <xref linkend="section-element-sinkimg"/> shows a sink element.
 110       </para>
 111       <figure float="1" id="section-element-sinkimg">
 112         <title>Visualisation of a sink element</title>
 113         <mediaobject>
 114           <imageobject>
 115             <imagedata fileref="images/sink-element.&image;"
 116             format="&IMAGE;" />
 117           </imageobject>
 118         </mediaobject>
 119       </figure>
 120     </sect2>
 121   </sect1>
 122
 123   <sect1 id="section-elements-create">
 124     <title>Creating a <classname>GstElement</classname></title>
 125     <para>
 126       The simplest way to create an element is to use <ulink type="http"
 127       url="&URLAPI;GstElementFactory.html#gst-element-factory-make"><function>gst_element_factory_make
 128       ()</function></ulink>. This function takes a factory name and an
 129       element name for the newly created element. The name of the element
 130       is something you can use later on to look up the element in a bin,
 131       for example. The name will also be used in debug output. You can
 132       pass <symbol>NULL</symbol> as the name argument to get a unique,
 133       default name.
 134     </para>
 135     <para>
 136       When you don't need the element anymore, you need to unref it using
 137       <ulink type="http"
 138       url="&URLAPI;GstObject.html#gst-object-unref"><function>gst_object_unref
 139       ()</function></ulink>. This decreases the reference count for the
 140       element by 1. An element has a refcount of 1 when it gets created.
 141       An element gets destroyed completely when the refcount is decreased
 142       to 0.
 143     </para>
 144     <para>
 145       The following example &EXAFOOT; shows how to create an element named
 146       <emphasis>source</emphasis> from the element factory named
 147       <emphasis>fakesrc</emphasis>.  It checks if the creation succeeded.
 148       After checking, it unrefs the element.
 149     </para>
 150     <programlisting><![CDATA[
 151 #include <gst/gst.h>
 152
 153 int
 154 main (int   argc,
 155       char *argv[])
 156 {
 157   GstElement *element;
 158
 159   /* init GStreamer */
 160   gst_init (&argc, &argv);
 161
 162   /* create element */
 163   element = gst_element_factory_make ("fakesrc", "source");
 164   if (!element) {
 165     g_print ("Failed to create element of type 'fakesrc'\n");
 166     return -1;
 167   }
 168
 169   gst_object_unref (GST_OBJECT (element));
 170
 171   return 0;
 172 }
 173     ]]></programlisting>
 174     <para>
 175       <function>gst_element_factory_make</function> is actually a shorthand
 176       for a combination of two functions. A <ulink type="http"
 177       url="&URLAPI;GstElement.html"><classname>GstElement</classname></ulink>
 178       object is created from a factory. To create the element, you have to
 179       get access to a <ulink type="http"
 180       url="&URLAPI;GstElementFactory.html"><classname>GstElementFactory</classname></ulink>
 181       object using a unique factory name. This is done with <ulink type="http"
 182       url="&URLAPI;GstElementFactory.html#gst-element-factory-find"><function>gst_element_factory_find
 183       ()</function></ulink>.
 184     </para>
 185     <para>
 186       The following code fragment is used to get a factory that can be used
 187       to create the <emphasis>fakesrc</emphasis> element, a fake data source.
 188       The function <ulink type="http"
 189       url="&URLAPI;GstElementFactory.html#gst-element-factory-create"><function>gst_element_factory_create
 190       ()</function></ulink> will use the element factory to create an
 191       element with the given name.
 192     </para>
 193     <programlisting><![CDATA[
 194 int
 195 main (int   argc,
 196       char *argv[])
 197 {
 198   GstElementFactory *factory;
 199   GstElement * element;
 200
 201   /* init GStreamer */
 202   gst_init (&argc, &argv);
 203
 204   /* create element, method #2 */
 205   factory = gst_element_factory_find ("fakesrc");
 206   if (!factory) {
 207     g_print ("Failed to find fctory of type 'fakesrc'\n");
 208     return -1;
 209   }
 210   element = gst_element_factory_create (factory, "source");
 211
 212   gst_object_unref (GST_OBJECT (element));
 213
 214   return 0;
 215 }
 216     ]]></programlisting>
 217   </sect1>
 218
 219   <sect1 id="section-elements-properties">
 220     <title>Using an element as a <classname>GObject</classname></title>
 221     <para>
 222       A <ulink type="http"
 223       url="&URLAPI;GstElement.html"><classname>GstElement</classname></ulink>
 224       can have several properties which are implemented using standard
 225       <classname>GObject</classname> properties. The usual
 226       <classname>GObject</classname> methods to query, set and get
 227       property values and <classname>GParamSpecs</classname> are
 228       therefore supported.
 229     </para>
 230     <para>
 231       Every <classname>GstElement</classname> inherits at least one
 232       property from its parent <classname>GstObject</classname>: the
 233       "name" property. This is the name you provide to the functions
 234       <function>gst_element_factory_make ()</function> or
 235       <function>gst_element_factory_create ()</function>. You can get
 236       and set this property using the functions
 237       <function>gst_object_set_name</function> and
 238       <function>gst_object_get_name</function> or use the
 239       <classname>GObject</classname> property mechanism as shown below.
 240     </para>
 241     <programlisting><![CDATA[
 242 #include <gst/gst.h>
 243
 244 int
 245 main (int   argc,
 246       char *argv[])
 247 {
 248   GstElement *element;
 249   const gchar *name;
 250
 251   /* init GStreamer */
 252   gst_init (&argc, &argv);
 253
 254   /* create element */
 255   element = gst_element_factory_make ("fakesrc", "source");
 256
 257   /* get name */
 258   g_object_get (G_OBJECT (element), "name", &name, NULL);
 259   g_print ("The name of the element is '%s'.\n", name);
 260
 261   gst_object_unref (GST_OBJECT (element));
 262
 263   return 0;
 264 }
 265     ]]></programlisting>
 266     <para>
 267       Most plugins provide additional properties to provide more information
 268       about their configuration or to configure the element.
 269       <command>gst-inspect</command> is a useful tool to query the properties
 270       of a particular element, it will also use property introspection to give
 271       a short explanation about the function of the property and about the
 272       parameter types and ranges it supports. See the appendix for details
 273       about <command>gst-inspect</command>.
 274     </para>
 275     <para>
 276       For more information about <classname>GObject</classname>
 277       properties we recommend you read the <ulink
 278       url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
 279       type="http">GObject manual</ulink> and an introduction to <ulink
 280       url="http://le-hacker.org/papers/gobject/index.html" type="http">The
 281       Glib Object system</ulink>.
 282     </para>
 283     <para>
 284       A <ulink type="http" url="&URLAPI;gstreamer/html/GstElementFactory.html">
 285       <classname>GstElement</classname></ulink> also provides various
 286       <classname>GObject</classname> signals that can be used as a flexible
 287       callback mechanism. Here, too, you can use <command>gst-inspect</command>
 288       to see which signals a specific elements supports. Together, signals
 289       and properties are the most basic way in which elements and
 290       applications interact.
 291     </para>
 292   </sect1>
 293
 294   <sect1 id="section-elements-factories">
 295     <title>More about element factories</title>
 296     <para>
 297       In the previous section, we briefly introduced the <ulink type="http"
 298       url="&URLAPI;GstElement.html"><classname>GstElementFactory</classname></ulink>
 299       object already as a way to create instances of an element. Element
 300       factories, however, are much more than just that. Element factories
 301       are the basic types retrieved from the &GStreamer; registry, they
 302       describe all plugins and elements that &GStreamer; can create. This
 303       means that element factories are useful for automated element
 304       instancing, such as what autopluggers do, and for creating lists
 305       of available elements, such as what pipeline editing applications
 306       (e.g. <ulink type="http"
 307       url="http://gstreamer.freedesktop.org/modules/gst-editor.html">&GStreamer;
 308       Editor</ulink>) do.
 309     </para>
 310
 311     <sect2 id="section-elements-factories-details">
 312       <title>Getting information about an element using a factory</title>
 313       <para>
 314         Tools like <command>gst-inspect</command> will provide some generic
 315         information about an element, such as the person that wrote the
 316         plugin, a descriptive name (and a shortname), a rank and a category.
 317         The category can be used to get the type of the element that can
 318         be created using this element factory. Examples of categories include
 319         <classname>Codec/Decoder/Video</classname> (video decoder),
 320         <classname>Codec/Encoder/Video</classname> (video encoder),
 321         <classname>Source/Video</classname> (a video generator),
 322         <classname>Sink/Video</classname> (a video output), and all these
 323         exist for audio as well, of course. Then, there's also
 324         <classname>Codec/Demuxer</classname> and
 325         <classname>Codec/Muxer</classname> and a whole lot more.
 326         <command>gst-inspect</command> will give a list of all factories, and
 327         <command>gst-inspect &lt;factory-name&gt;</command> will list all
 328         of the above information, and a lot more.
 329       </para>
 330       <programlisting><![CDATA[
 331 #include <gst/gst.h>
 332
 333 int
 334 main (int   argc,
 335       char *argv[])
 336 {
 337   GstElementFactory *factory;
 338
 339   /* init GStreamer */
 340   gst_init (&argc, &argv);
 341
 342   /* get factory */
 343   factory = gst_element_factory_find ("sinesrc");
 344   if (!factory) {
 345     g_print ("You don't have the 'sinesrc' element installed, go get it!\n");
 346     return -1;
 347   }
 348
 349   /* display information */
 350   g_print ("The '%s' element is a member of the category %s.\n"
 351            "Description: %s\n",
 352            gst_plugin_feature_get_name (GST_PLUGIN_FEATURE (factory)),
 353            gst_element_factory_get_klass (factory),
 354            gst_element_factory_get_description (factory));
 355
 356   return 0;
 357 }
 358       ]]></programlisting>
 359       <para>
 360         You can use <function>gst_registry_pool_feature_list (GST_TYPE_ELEMENT_FACTORY)</function>
 361         to get a list of all the element factories that &GStreamer; knows
 362         about.
 363       </para>
 364     </sect2>
 365
 366     <sect2 id="section-elements-factories-padtemplates">
 367       <title>Finding out what pads an element can contain</title>
 368       <para>
 369         Perhaps the most powerful feature of element factories is that
 370         they contain a full description of the pads that the element
 371         can generate, and the capabilities of those pads (in layman words:
 372         what types of media can stream over those pads), without actually
 373         having to load those plugins into memory. This can be used
 374         to provide a codec selection list for encoders, or it can be used
 375         for autoplugging purposes for media players. All current
 376         &GStreamer;-based media players and autopluggers work this way.
 377         We'll look closer at these features as we learn about
 378         <classname>GstPad</classname> and <classname>GstCaps</classname>
 379         in the next chapter: <xref linkend="chapter-pads"/>
 380       </para>
 381     </sect2>
 382   </sect1>
 383
 384   <sect1 id="section-elements-link" xreflabel="Linking elements">
 385     <title>Linking elements</title>
 386     <para>
 387       By linking a source element with zero or more filter-like
 388       elements and finally a sink element, you set up a media
 389       pipeline. Data will flow through the elements. This is the
 390       basic concept of media handling in &GStreamer;.
 391     </para>
 392     <figure float="1" id="section-link">
 393       <title>Visualisation of three linked elements</title>
 394         <mediaobject>
 395           <imageobject>
 396             <imagedata fileref="images/linked-elements.&image;"
 397             format="&IMAGE;"/>
 398           </imageobject>
 399         </mediaobject>
 400     </figure>
 401     <para>
 402       By linking these three elements, we have created a very simple
 403       chain of elements. The effect of this will be that the output of
 404       the source element (<quote>element1</quote>) will be used as input
 405       for the filter-like element (<quote>element2</quote>). The
 406       filter-like element will do something with the data and send the
 407       result to the final sink element (<quote>element3</quote>).
 408     </para>
 409     <para>
 410       Imagine the above graph as a simple Ogg/Vorbis audio decoder. The
 411       source is a disk source which reads the file from disc. The second
 412       element is a Ogg/Vorbis audio decoder. The sink element is your
 413       soundcard, playing back the decoded audio data. We will use this
 414       simple graph to construct an Ogg/Vorbis player later in this manual.
 415     </para>
 416     <para>
 417       In code, the above graph is written like this:
 418     </para>
 419     <programlisting>
 420 int
 421 main (int   argc,
 422       char *argv[])
 423 {
 424   GstElement *source, *filter, *sink;
 425
 426   /* init */
 427   gst_init (&amp;argc, &amp;argv);
 428
 429   /* create elements */
 430   source = gst_element_factory_make ("fakesrc", "source");
 431   filter = gst_element_factory_make ("identity", "filter");
 432   sink = gst_element_factory_make ("fakesink", "sink");
 433
 434   /* link */
 435   gst_element_link_many (source, filter, sink, NULL);
 436
 437 [..]
 438 }
 439     </programlisting>
 440     <para>
 441       For more specific behaviour, there are also the functions
 442       <function>gst_element_link ()</function> and
 443       <function>gst_element_link_pads ()</function>. You can also obtain
 444       references to individual pads and link those using various
 445       <function>gst_pad_link_* ()</function> functions. See the API
 446       references for more details.
 447     </para>
 448   </sect1>
 449
 450   <sect1 id="section-elements-states">
 451     <title>Element States</title>
 452     <para>
 453       After being created, an element will not actually perform any actions
 454       yet. You need to change elements state to make it do something.
 455       &GStreamer; knows four element states, each with a very specific
 456       meaning. Those four states are:
 457     </para>
 458     <itemizedlist>
 459       <listitem>
 460         <para>
 461           <classname>GST_STATE_NULL</classname>: this is the default state.
 462           This state will deallocate all resources held by the element.
 463         </para>
 464       </listitem>
 465       <listitem>
 466         <para>
 467           <classname>GST_STATE_READY</classname>: in the ready state, an
 468           element has allocated all of its global resources, that is,
 469           resources that can be kept within streams. You can think about
 470           opening devices, allocating buffers and so on. However, the
 471           stream is not opened in this state, so the stream positions is
 472           automatically zero. If a stream was previously opened, it should
 473           be closed in this state, and position, properties and such should
 474           be reset.
 475         </para>
 476       </listitem>
 477       <listitem>
 478         <para>
 479           <classname>GST_STATE_PAUSED</classname>: in this state, an
 480           element has opened the stream, but is not actively processing
 481           it. An element should not modify the stream's position, data or
 482           anything else in this state. When set back to PLAYING, it should
 483           continue processing at the point where it left off as soon as
 484           possible.
 485         </para>
 486       </listitem>
 487       <listitem>
 488         <para>
 489           <classname>GST_STATE_PLAYING</classname>: in the PLAYING state,
 490           an element does exactly the same as in the PAUSED state, except
 491           that it actually processes data.
 492         </para>
 493       </listitem>
 494     </itemizedlist>
 495     <para>
 496       You can change the state of an element using the function
 497       <function>gst_element_set_state ()</function>. If you set an element
 498       to another state, &GStreamer; will internally traverse all intermediate
 499       states. So if you set an element from NULL to PLAYING, &GStreamer;
 500       will internally set the element to READY and PAUSED in between.
 501     </para>
 502     <para>
 503       Even though an element in <classname>GST_STATE_PLAYING</classname>
 504       is ready for data processing, it will not necessarily do that. If
 505       the element is placed in a thread (see <xref
 506       linkend="chapter-threads"/>), it will process data automatically.
 507       In other cases, however, you will need to <emphasis>iterate</emphasis>
 508       the element's container.
 509     </para>
 510   </sect1>
 511 </chapter>