docs/manual/intro-basics.xml

   1 <chapter id="chapter-intro-basics">
   2   <title>Foundations</title>
   3   <para>
   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 Plugin
  24       Writer's Guide.
  25     </para>
  26   </sect1>
  27
  28   <sect1 id="section-intro-basics-bins">
  29     <title>Bins and pipelines</title>
  30
  31     <para>
  32       A <emphasis>bin</emphasis> is a container for a collection of elements.
  33       A pipeline is a special subtype of a bin that allows execution of all
  34       of its contained child elements. Since bins are subclasses of elements
  35       themselves, you can mostly control a bin as if it where an element,
  36       thereby abstracting away a lot of complexity for your application. You
  37       can, for example change state on all elements in a bin by changing the
  38       state of that bin itself. Bins also forward some signals from their
  39       contained childs (such as errors and tags).
  40     </para>
  41     <para>
  42       A pipeline is a bin that allows to <emphasis>run</emphasis> (technically
  43       referred to as <quote>iterating</quote>) its contained childs. By
  44       iterating a pipeline, data flow will start and media processing will
  45       take place. A pipeline requires iterating for anything to happen. you
  46       can also use threads, which automatically iterate the contained childs
  47       in a newly created threads. We will go into this in detail later on.
  48     </para>
  49   </sect1>
  50
  51   <sect1 id="section-intro-basics-pads">
  52     <title>Pads</title>
  53     <para>
  54       <emphasis>Pads</emphasis> are used to negotiate links and data flow
  55       between elements in &GStreamer;. A pad can be viewed as a
  56       <quote>plug</quote> or <quote>port</quote> on an element where
  57       links may be made with other elements, and through which data can
  58       flow to or from those elements. Pads have specific data handling
  59       capabilities: A pad can restrict the type of data that flows
  60       through it. Links are only allowed between two pads when the
  61       allowed data types of the two pads are compatible. Data types are
  62       negotiated between pads using a process called <emphasis>caps
  63       negotiation</emphasis>. Data types are described as a
  64       <classname>GstCaps</classname>.
  65     </para>
  66     <para>
  67       An analogy may be helpful here. A pad is similar to a plug or jack on a
  68       physical device. Consider, for example, a home theater system consisting
  69       of an amplifier, a DVD player, and a (silent) video projector. Linking
  70       the DVD player to the amplifier is allowed because both devices have audio
  71       jacks, and linking the projector to the DVD player is allowed because
  72       both devices have compatible video jacks. Links between the
  73       projector and the amplifier may not be made because the projector and
  74       amplifier have different types of jacks. Pads in &GStreamer; serve the
  75       same purpose as the jacks in the home theater system.
  76     </para>
  77     <para>
  78       For the most part, all data in &GStreamer; flows one way through a link
  79       between elements. Data flows out of one element through one or more
  80       <emphasis>source pads</emphasis>, and elements accept incoming data
  81       through one or more <emphasis>sink pads</emphasis>. Source and sink
  82       elements have only source and sink pads, respectively. Data is
  83       embodied in a <classname>GstData</classname> structure.
  84     </para>
  85   </sect1>
  86 </chapter>