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, for 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 scale="75" 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 scale="75" 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 scale="75" 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 scale="75" 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><!-- example-begin elementmake.c --><![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     ]]><!-- example-end elementmake.c --></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><!-- example-begin elementcreate.c --><![CDATA[
 194 #include <gst/gst.h>
 195
 196 int
 197 main (int   argc,
 198       char *argv[])
 199 {
 200   GstElementFactory *factory;
 201   GstElement * element;
 202
 203   /* init GStreamer */
 204   gst_init (&argc, &argv);
 205
 206   /* create element, method #2 */
 207   factory = gst_element_factory_find ("fakesrc");
 208   if (!factory) {
 209     g_print ("Failed to find factory of type 'fakesrc'\n");
 210     return -1;
 211   }
 212   element = gst_element_factory_create (factory, "source");
 213   if (!element) {
 214     g_print ("Failed to create element, even though its factory exists!\n");
 215     return -1;
 216   }
 217
 218   gst_object_unref (GST_OBJECT (element));
 219
 220   return 0;
 221 }
 222     ]]><!-- example-end elementcreate.c --></programlisting>
 223   </sect1>
 224
 225   <sect1 id="section-elements-properties">
 226     <title>Using an element as a <classname>GObject</classname></title>
 227     <para>
 228       A <ulink type="http"
 229       url="&URLAPI;GstElement.html"><classname>GstElement</classname></ulink>
 230       can have several properties which are implemented using standard
 231       <classname>GObject</classname> properties. The usual
 232       <classname>GObject</classname> methods to query, set and get
 233       property values and <classname>GParamSpecs</classname> are
 234       therefore supported.
 235     </para>
 236     <para>
 237       Every <classname>GstElement</classname> inherits at least one
 238       property from its parent <classname>GstObject</classname>: the
 239       "name" property. This is the name you provide to the functions
 240       <function>gst_element_factory_make ()</function> or
 241       <function>gst_element_factory_create ()</function>. You can get
 242       and set this property using the functions
 243       <function>gst_object_set_name</function> and
 244       <function>gst_object_get_name</function> or use the
 245       <classname>GObject</classname> property mechanism as shown below.
 246     </para>
 247     <programlisting><!-- example-begin elementget.c --><![CDATA[
 248 #include <gst/gst.h>
 249
 250 int
 251 main (int   argc,
 252       char *argv[])
 253 {
 254   GstElement *element;
 255   gchar *name;
 256
 257   /* init GStreamer */
 258   gst_init (&argc, &argv);
 259
 260   /* create element */
 261   element = gst_element_factory_make ("fakesrc", "source");
 262
 263   /* get name */
 264   g_object_get (G_OBJECT (element), "name", &name, NULL);
 265   g_print ("The name of the element is '%s'.\n", name);
 266   g_free (name);
 267
 268   gst_object_unref (GST_OBJECT (element));
 269
 270   return 0;
 271 }
 272     ]]><!-- example-end elementget.c --></programlisting>
 273     <para>
 274       Most plugins provide additional properties to provide more information
 275       about their configuration or to configure the element.
 276       <command>gst-inspect</command> is a useful tool to query the properties
 277       of a particular element, it will also use property introspection to give
 278       a short explanation about the function of the property and about the
 279       parameter types and ranges it supports. See
 280       <xref linkend="section-applications-inspect"/>
 281       in the appendix for details about <command>gst-inspect</command>.
 282     </para>
 283     <para>
 284       For more information about <classname>GObject</classname>
 285       properties we recommend you read the <ulink
 286       url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
 287       type="http">GObject manual</ulink> and an introduction to <ulink
 288       url="http://developer.gnome.org/doc/API/2.0/gobject/pr01.html" type="http">
 289         The Glib Object system</ulink>.
 290     </para>
 291     <para>
 292       A <ulink type="http" url="&URLAPI;GstElementFactory.html">
 293       <classname>GstElement</classname></ulink> also provides various
 294       <classname>GObject</classname> signals that can be used as a flexible
 295       callback mechanism. Here, too, you can use <command>gst-inspect</command>
 296       to see which signals a specific element supports. Together, signals
 297       and properties are the most basic way in which elements and
 298       applications interact.
 299     </para>
 300   </sect1>
 301
 302   <sect1 id="section-elements-factories">
 303     <title>More about element factories</title>
 304     <para>
 305       In the previous section, we briefly introduced the <ulink type="http"
 306       url="&URLAPI;GstElement.html"><classname>GstElementFactory</classname></ulink>
 307       object already as a way to create instances of an element. Element
 308       factories, however, are much more than just that. Element factories
 309       are the basic types retrieved from the &GStreamer; registry, they
 310       describe all plugins and elements that &GStreamer; can create. This
 311       means that element factories are useful for automated element
 312       instancing, such as what autopluggers do, and for creating lists
 313       of available elements, such as what pipeline editing applications
 314       (e.g. <ulink type="http"
 315       url="http://gstreamer.freedesktop.org/modules/gst-editor.html">&GStreamer;
 316       Editor</ulink>) do.
 317     </para>
 318
 319     <sect2 id="section-elements-factories-details">
 320       <title>Getting information about an element using a factory</title>
 321       <para>
 322         Tools like <command>gst-inspect</command> will provide some generic
 323         information about an element, such as the person that wrote the
 324         plugin, a descriptive name (and a shortname), a rank and a category.
 325         The category can be used to get the type of the element that can
 326         be created using this element factory. Examples of categories include
 327         <classname>Codec/Decoder/Video</classname> (video decoder),
 328         <classname>Codec/Encoder/Video</classname> (video encoder),
 329         <classname>Source/Video</classname> (a video generator),
 330         <classname>Sink/Video</classname> (a video output), and all these
 331         exist for audio as well, of course. Then, there's also
 332         <classname>Codec/Demuxer</classname> and
 333         <classname>Codec/Muxer</classname> and a whole lot more.
 334         <command>gst-inspect</command> will give a list of all factories, and
 335         <command>gst-inspect &lt;factory-name&gt;</command> will list all
 336         of the above information, and a lot more.
 337       </para>
 338       <programlisting><!-- example-begin elementfactory.c --><![CDATA[
 339 #include <gst/gst.h>
 340
 341 int
 342 main (int   argc,
 343       char *argv[])
 344 {
 345   GstElementFactory *factory;
 346
 347   /* init GStreamer */
 348   gst_init (&argc, &argv);
 349
 350   /* get factory */
 351   factory = gst_element_factory_find ("fakesrc");
 352   if (!factory) {
 353     g_print ("You don't have the 'fakesrc' element installed!\n");
 354     return -1;
 355   }
 356
 357   /* display information */
 358   g_print ("The '%s' element is a member of the category %s.\n"
 359            "Description: %s\n",
 360            gst_plugin_feature_get_name (GST_PLUGIN_FEATURE (factory)),
 361            gst_element_factory_get_klass (factory),
 362            gst_element_factory_get_description (factory));
 363
 364   return 0;
 365 }
 366       ]]><!-- example-end elementfactory.c --></programlisting>
 367       <para>
 368         You can use <function>gst_registry_pool_feature_list (GST_TYPE_ELEMENT_FACTORY)</function>
 369         to get a list of all the element factories that &GStreamer; knows
 370         about.
 371       </para>
 372     </sect2>
 373
 374     <sect2 id="section-elements-factories-padtemplates">
 375       <title>Finding out what pads an element can contain</title>
 376       <para>
 377         Perhaps the most powerful feature of element factories is that
 378         they contain a full description of the pads that the element
 379         can generate, and the capabilities of those pads (in layman words:
 380         what types of media can stream over those pads), without actually
 381         having to load those plugins into memory. This can be used
 382         to provide a codec selection list for encoders, or it can be used
 383         for autoplugging purposes for media players. All current
 384         &GStreamer;-based media players and autopluggers work this way.
 385         We'll look closer at these features as we learn about
 386         <classname>GstPad</classname> and <classname>GstCaps</classname>
 387         in the next chapter: <xref linkend="chapter-pads"/>
 388       </para>
 389     </sect2>
 390   </sect1>
 391
 392   <sect1 id="section-elements-link" xreflabel="Linking elements">
 393     <title>Linking elements</title>
 394     <para>
 395       By linking a source element with zero or more filter-like
 396       elements and finally a sink element, you set up a media
 397       pipeline. Data will flow through the elements. This is the
 398       basic concept of media handling in &GStreamer;.
 399     </para>
 400     <figure float="1" id="section-link">
 401       <title>Visualisation of three linked elements</title>
 402         <mediaobject>
 403           <imageobject>
 404             <imagedata scale="75" fileref="images/linked-elements.&image;"
 405             format="&IMAGE;"/>
 406           </imageobject>
 407         </mediaobject>
 408     </figure>
 409     <para>
 410       By linking these three elements, we have created a very simple
 411       chain of elements. The effect of this will be that the output of
 412       the source element (<quote>element1</quote>) will be used as input
 413       for the filter-like element (<quote>element2</quote>). The
 414       filter-like element will do something with the data and send the
 415       result to the final sink element (<quote>element3</quote>).
 416     </para>
 417     <para>
 418       Imagine the above graph as a simple Ogg/Vorbis audio decoder. The
 419       source is a disk source which reads the file from disc. The second
 420       element is a Ogg/Vorbis audio decoder. The sink element is your
 421       soundcard, playing back the decoded audio data. We will use this
 422       simple graph to construct an Ogg/Vorbis player later in this manual.
 423     </para>
 424     <para>
 425       In code, the above graph is written like this:
 426     </para>
 427     <programlisting><!-- example-begin elementlink.c a -->
 428 #include &lt;gst/gst.h&gt;
 429
 430 int
 431 main (int   argc,
 432       char *argv[])
 433 {
 434   GstElement *pipeline;
 435   GstElement *source, *filter, *sink;
 436
 437   /* init */
 438   gst_init (&amp;argc, &amp;argv);
 439
 440   /* create pipeline */
 441   pipeline = gst_pipeline_new ("my-pipeline");
 442
 443   /* create elements */
 444   source = gst_element_factory_make ("fakesrc", "source");
 445   filter = gst_element_factory_make ("identity", "filter");
 446   sink = gst_element_factory_make ("fakesink", "sink");
 447
 448   /* must add elements to pipeline before linking them */
 449   gst_bin_add_many (GST_BIN (pipeline), source, filter, sink, NULL);
 450
 451   /* link */
 452   if (!gst_element_link_many (source, filter, sink, NULL)) {
 453     g_warning ("Failed to link elements!");
 454   }
 455 <!-- example-end elementlink.c a -->
 456 [..]<!-- example-begin elementlink.c b --><!--
 457   return 0;
 458 --><!-- example-end elementlink.c b -->
 459 <!-- example-begin elementlink.c c -->
 460 }
 461     <!-- example-end elementlink.c c --></programlisting>
 462     <para>
 463       For more specific behaviour, there are also the functions
 464       <function>gst_element_link ()</function> and
 465       <function>gst_element_link_pads ()</function>. You can also obtain
 466       references to individual pads and link those using various
 467       <function>gst_pad_link_* ()</function> functions. See the API
 468       references for more details.
 469     </para>
 470     <para>
 471       Important: you must add elements to a bin or pipeline
 472       <emphasis>before</emphasis> linking them, since adding an element to
 473       a bin will disconnect any already existing links. Also, you cannot
 474       directly link elements that are not in the same bin or pipeline; if
 475       you want to link elements or pads at different hierarchy levels, you
 476       will need to use ghost pads (more about ghost pads later).
 477     </para>
 478   </sect1>
 479
 480   <sect1 id="section-elements-states">
 481     <title>Element States</title>
 482     <para>
 483       After being created, an element will not actually perform any actions
 484       yet. You need to change elements state to make it do something.
 485       &GStreamer; knows four element states, each with a very specific
 486       meaning. Those four states are:
 487     </para>
 488     <itemizedlist>
 489       <listitem>
 490         <para>
 491           <classname>GST_STATE_NULL</classname>: this is the default state.
 492           No resources are allocated in this state, so, transitioning to it
 493           will free all resources. The element must be in this state when
 494           its refcount reaches 0 and it is freed.
 495         </para>
 496       </listitem>
 497       <listitem>
 498         <para>
 499           <classname>GST_STATE_READY</classname>: in the ready state, an
 500           element has allocated all of its global resources, that is,
 501           resources that can be kept within streams. You can think about
 502           opening devices, allocating buffers and so on. However, the
 503           stream is not opened in this state, so the stream positions is
 504           automatically zero. If a stream was previously opened, it should
 505           be closed in this state, and position, properties and such should
 506           be reset.
 507         </para>
 508       </listitem>
 509       <listitem>
 510         <para>
 511           <classname>GST_STATE_PAUSED</classname>: in this state, an
 512           element has opened the stream, but is not actively processing
 513           it. An element is allowed to modify a stream's position, read
 514           and process data and such to prepare for playback as soon as
 515           state is changed to PLAYING, but it is <emphasis>not</emphasis>
 516           allowed to play the data which would make the clock run.
 517           In summary, PAUSED is the same as PLAYING but without a running
 518           clock.
 519          </para>
 520          <para>
 521           Elements going into the PAUSED state should prepare themselves
 522           for moving over to the PLAYING state as soon as possible. Video
 523           or audio outputs would, for example, wait for data to arrive and
 524           queue it so they can play it right after the state change. Also,
 525           video sinks can already play the first frame (since this does
 526           not affect the clock yet). Autopluggers could use this same
 527           state transition to already plug together a pipeline. Most other
 528           elements, such as codecs or filters, do not need to explicitely
 529           do anything in this state, however.
 530         </para>
 531       </listitem>
 532       <listitem>
 533         <para>
 534           <classname>GST_STATE_PLAYING</classname>: in the PLAYING state,
 535           an element does exactly the same as in the PAUSED state, except
 536           that the clock now runs.
 537         </para>
 538       </listitem>
 539     </itemizedlist>
 540     <para>
 541       You can change the state of an element using the function
 542       <function>gst_element_set_state ()</function>. If you set an element
 543       to another state, &GStreamer; will internally traverse all intermediate
 544       states. So if you set an element from NULL to PLAYING, &GStreamer;
 545       will internally set the element to READY and PAUSED in between.
 546     </para>
 547     <para>
 548       When moved to <classname>GST_STATE_PLAYING</classname>, pipelines
 549       will process data automatically. They do not need to be iterated in
 550       any form. Internally, &GStreamer; will start threads that take this
 551       task on to them. &GStreamer; will also take care of switching
 552       messages from the pipeline's thread into the application's own
 553       thread, by using a <ulink type="http"
 554       url="&URLAPI;GstBus.html"><classname>GstBus</classname></ulink>. See
 555       <xref linkend="chapter-bus"/> for details.
 556     </para>
 557     <para>
 558       When you set a bin or pipeline to a certain target state, it will usually
 559       propagate the state change to all elements within the bin or pipeline
 560       automatically, so it's usually only necessary to set the state of the
 561       top-level pipeline to start up the pipeline or shut it down. However,
 562       when adding elements dynamically to an already-running pipeline, e.g.
 563       from within a "pad-added" or "new-decoded-pad" signal callback, you
 564       need to set it to the desired target state yourself using
 565       <function>gst_element_set_state ()</function> or
 566       <function>gst_element_sync_state_with_parent ()</function>.
 567     </para>
 568   </sect1>
 569 </chapter>