mobile/docs/manual/intro-basics.xml

   1 <chapter id="chapter-intro-basics">
   2   <title>Foundations</title>
   3   <para><!-- synchronize with PWG -->
   4     This chapter of the guide introduces the basic concepts of &GStreamer;.
   5     Understanding these concepts will be important in reading any of the
   6     rest of this guide, all of them assume understanding of these basic
   7     concepts.
   8   </para>
   9
  10   <sect1 id="section-intro-basics-elements">
  11     <title>Elements</title>
  12     <para>
  13       An <emphasis>element</emphasis> is the most important class of objects
  14       in &GStreamer;. You will usually create a chain of elements linked
  15       together and let data flow through this chain of elements. An element
  16       has one specific function, which can be the reading of data from a
  17       file, decoding of this data or outputting this data to your sound
  18       card (or anything else). By chaining together several such elements,
  19       you create a <emphasis>pipeline</emphasis> that can do a specific task,
  20       for example media playback or capture. &GStreamer; ships with a large
  21       collection of elements by default, making the development of a large
  22       variety of media applications possible. If needed, you can also write
  23       new elements. That topic is explained in great deal in the &GstPWG;.
  24     </para>
  25   </sect1>
  26
  27   <sect1 id="section-intro-basics-pads">
  28     <title>Pads</title>
  29     <para>
  30       <emphasis>Pads</emphasis> are element's input and output, where
  31       you can connect other elements. They are used to negotiate links and
  32       data flow
  33       between elements in &GStreamer;. A pad can be viewed as a
  34       <quote>plug</quote> or <quote>port</quote> on an element where
  35       links may be made with other elements, and through which data can
  36       flow to or from those elements. Pads have specific data handling
  37       capabilities: a pad can restrict the type of data that flows
  38       through it. Links are only allowed between two pads when the
  39       allowed data types of the two pads are compatible. Data types are
  40       negotiated between pads using a process called <emphasis>caps
  41       negotiation</emphasis>. Data types are described as a
  42       <classname>GstCaps</classname>.
  43     </para>
  44     <para>
  45       An analogy may be helpful here. A pad is similar to a plug or jack on a
  46       physical device. Consider, for example, a home theater system consisting
  47       of an amplifier, a DVD player, and a (silent) video projector. Linking
  48       the DVD player to the amplifier is allowed because both devices have audio
  49       jacks, and linking the projector to the DVD player is allowed because
  50       both devices have compatible video jacks. Links between the
  51       projector and the amplifier may not be made because the projector and
  52       amplifier have different types of jacks. Pads in &GStreamer; serve the
  53       same purpose as the jacks in the home theater system.
  54     </para>
  55     <para>
  56       For the most part, all data in &GStreamer; flows one way through a link
  57       between elements. Data flows out of one element through one or more
  58       <emphasis>source pads</emphasis>, and elements accept incoming data
  59       through one or more <emphasis>sink pads</emphasis>. Source and sink
  60       elements have only source and sink pads, respectively. Data usually
  61       means buffers (described by the <ulink type="http"
  62       url="&URLAPI;gstreamer-GstBuffer.html"><classname>GstBuffer
  63       </classname></ulink> object) and events (described by the <ulink
  64       type="http" url="&URLAPI;gstreamer-GstEvent.html"><classname>
  65       GstEvent</classname></ulink> object).
  66     </para>
  67   </sect1>
  68
  69   <sect1 id="section-intro-basics-bins">
  70     <title>Bins and pipelines</title>
  71
  72     <para>
  73       A <emphasis>bin</emphasis> is a container for a collection of elements.
  74       A <emphasis>pipeline</emphasis> is a special subtype of a bin that allows execution of all
  75       of its contained child elements. Since bins are subclasses of elements
  76       themselves, you can mostly control a bin as if it were an element,
  77       thereby abstracting away a lot of complexity for your application. You
  78       can, for example change state on all elements in a bin by changing the
  79       state of that bin itself. Bins also forward bus messages from their
  80       contained children (such as error messages, tag messages or EOS messages).
  81     </para>
  82     <para>
  83       A <emphasis>pipeline</emphasis> is a top-level bin. As you set it to PAUSED or PLAYING state,
  84       data flow will start and media processing will take place. Once started,
  85       pipelines will run in a separate thread until you stop them or the end
  86       of the data stream is reached.
  87     </para>
  88
  89     <figure float="1" id="section-pipeline-img">
  90       <title>&GStreamer; pipeline for a simple ogg player</title>
  91       <mediaobject>
  92         <imageobject>
  93           <imagedata scale="75" fileref="images/simple-player.&image;" format="&IMAGE;" />
  94         </imageobject>
  95       </mediaobject>
  96     </figure>
  97
  98   </sect1>
  99
 100   <sect1 id="section-intro-basics-communication">
 101     <title>Communication</title>
 102
 103     <para>
 104       &GStreamer; provides several mechanisms for communication and data exchange
 105       between the <emphasis>application</emphasis> and the <emphasis>pipeline</emphasis>.
 106     </para>
 107
 108     <itemizedlist>
 109       <listitem>
 110         <para>
 111           <emphasis>buffers</emphasis> are objects for passing streaming data
 112           between elements in the pipeline. Buffers always travel from sources
 113           to sinks (downstream).
 114         </para>
 115       </listitem>
 116       <listitem>
 117         <para>
 118           <emphasis>events</emphasis> are objects sent between elements or from
 119           the application to elements. Events can travel upstream and downstream.
 120           Downstream events can be synchronised to the data flow.
 121         </para>
 122       </listitem>
 123       <listitem>
 124         <para>
 125           <emphasis>messages</emphasis> are objects posted by elements on
 126           the pipeline's message bus, where they will be held for collection
 127           by the application. Messages can be intercepted synchronously from
 128           the streaming thread context of the element posting the message, but
 129           are usually handled asynchronously by the application from the
 130           application's main thread. Messages are used to transmit information
 131           such as errors, tags, state changes, buffering state, redirects etc.
 132           from elements to the application in a thread-safe way.
 133         </para>
 134       </listitem>
 135       <listitem>
 136         <para>
 137           <emphasis>queries</emphasis> allow applications to request information
 138           such as duration or current playback position from the pipeline.
 139           Queries are always answered synchronously. Elements can also use
 140           queries to request information from their peer elements (such as the
 141           file size or duration). They can be used both ways within a pipeline,
 142           but upstream queries are more common.
 143         </para>
 144       </listitem>
 145     </itemizedlist>
 146
 147     <figure float="1" id="section-communication-img">
 148       <title>&GStreamer; pipeline with different communication flows</title>
 149       <mediaobject>
 150         <imageobject>
 151           <imagedata scale="75" fileref="images/communication.&image;" format="&IMAGE;" />
 152         </imageobject>
 153       </mediaobject>
 154     </figure>
 155
 156   </sect1>
 157
 158 </chapter>