docs/manual/basics-pads.xml

   1 <chapter id="chapter-pads">
   2   <title>Pads</title>
   3   <para>
   4     As we have seen in <xref linkend="chapter-elements"/>, the pads are the element's
   5     interface to the outside world.
   6   </para>
   7   <para>
   8     The specific type of media that the element can handle will be exposed by the pads.
   9     The description of this media type is done with capabilities(see
  10     <xref linkend="section-caps"/>)
  11   </para>
  12
  13   <para>
  14     Pads are either source or sink pads.  The terminology is defined from the
  15     view of the element itself: elements accept data on their sink pads, and
  16     send data out on their source pads.  Sink pads are drawn on the left,
  17     while source pads are drawn on the right of an element.  In general,
  18     data flows from left to right in the graph.<footnote>
  19       <para>
  20         In reality, there is no objection to data flowing from a
  21         source pad to the sink pad of an element upstream.  Data will, however,
  22         always flow from a source pad of one element to the sink pad of
  23         another.
  24       </para></footnote>
  25   </para>
  26
  27   <sect1 id="section-pads-type">
  28     <title>Types of pad</title>
  29
  30     <sect2 id="section-pads-dynamic">
  31       <title>Dynamic pads</title>
  32       <para>
  33         Some elements might not have all of their pads when the element is
  34         created. This
  35         can happen, for example, with an MPEG system demultiplexer. The
  36         demultiplexer will create its pads at runtime when it detects the
  37         different elementary streams in the MPEG system stream.
  38       </para>
  39       <para>
  40         Running <application>gst-inspect mpegdemux</application> will show that
  41         the element has only one pad: a sink pad called 'sink'. The other pads are
  42         "dormant".  You can see this in the pad template because there is
  43         an 'Exists: Sometimes'
  44         property. Depending on the type of MPEG file you play, the pads will
  45         be created. We
  46         will see that this is very important when you are going to create dynamic
  47         pipelines later on in this manual.
  48       </para>
  49     </sect2>
  50     <sect2 id="section-pads-request">
  51       <title>Request pads</title>
  52       <para>
  53         An element can also have request pads. These pads are not created
  54         automatically but are only created on demand. This is very useful
  55         for multiplexers, aggregators and tee elements.
  56       </para>
  57       <para>
  58         The tee element, for example, has one input pad and a request padtemplate for the
  59         output pads. Whenever an element wants to get an output pad from the tee element, it
  60         has to request the pad.
  61       </para>
  62     </sect2>
  63
  64   </sect1>
  65
  66   <sect1 id="section-caps">
  67     <title>Capabilities of a pad</title>
  68     <para>
  69       Since the pads play a very important role in how the element is viewed by the
  70       outside world, a mechanism is implemented to describe the data that can
  71       flow through the pad by using capabilities.
  72     </para>
  73     <para>
  74       We will briefly describe what capabilities are, enough for you to get a basic understanding
  75       of the concepts. You will find more information on how to create capabilities in the
  76       Plugin Writer's Guide.
  77     </para>
  78
  79     <sect2 id="section-pads-caps">
  80       <title>Capabilities</title>
  81       <para>
  82         Capabilities are attached to a pad in order to describe
  83         what type of media the pad can handle.
  84       </para>
  85       <para>
  86         Capabilities is shorthand for "capability chain".  A capability chain
  87         is a chain of one capability or more.
  88       </para>
  89       <para>
  90         The basic entity is a capability, and is defined by a name, a MIME
  91         type and a set of properties.  A capability can be chained to
  92         another capability, which is why we commonly refer to a chain of
  93         capability entities as "capabilities".
  94         <footnote>
  95           <para>
  96             It is important to understand that the term "capabilities" refers
  97             to a chain of one capability or more.  This will be clearer when
  98             you see the structure definition of a <ulink type="http"
  99             url="../../gstreamer/html/gstreamer-GstCaps.html"><classname>GstCaps
 100             </classname></ulink>element.
 101           </para>
 102         </footnote>
 103       </para>
 104       <para>
 105         Below is a dump of the capabilities of the element mad, as shown by
 106         <command>gst-inspect</command>.
 107         You can see two pads: sink and src. Both pads have capability information attached to them.
 108       </para>
 109       <para>
 110         The sink pad (input pad) is called 'sink' and takes data of MIME type 'audio/mp3'. It also has
 111         three properties: layer, bitrate and framed.
 112       </para>
 113       <para>
 114         The source pad (output pad) is called 'src' and outputs data of
 115         MIME type 'audio/raw'. It also has four properties: format, depth,
 116         rate and channels.
 117       </para>
 118       <programlisting>
 119 Pads:
 120   SINK template: 'sink'
 121     Availability: Always
 122     Capabilities:
 123       'mad_sink':
 124         MIME type: 'audio/mp3':
 125
 126   SRC template: 'src'
 127     Availability: Always
 128     Capabilities:
 129       'mad_src':
 130         MIME type: 'audio/raw':
 131         format: String: int
 132         endianness: Integer: 1234
 133         width: Integer: 16
 134         depth: Integer: 16
 135         channels: Integer range: 1 - 2
 136         law: Integer: 0
 137         signed: Boolean: TRUE
 138         rate: Integer range: 11025 - 48000
 139       </programlisting>
 140     </sect2>
 141     <sect2 id="section-pads-props">
 142       <title>What are properties ?</title>
 143       <para>
 144         Properties are used to describe extra information for
 145         capabilities. A property consists of a key (a string) and
 146         a value. There are different possible value types that can be used:
 147       </para>
 148
 149       <itemizedlist>
 150         <listitem>
 151           <para>
 152             basic types:
 153           </para>
 154           <itemizedlist>
 155             <listitem>
 156               <para>
 157                 an integer value: the property has this exact value.
 158               </para>
 159             </listitem>
 160             <listitem>
 161               <para>
 162                 a boolean value: the property is either TRUE or FALSE.
 163               </para>
 164             </listitem>
 165             <listitem>
 166               <para>
 167                 a fourcc value: this is a value that is commonly used to
 168                 describe an encoding for video,
 169                 as used for example by the AVI specification.
 170                 <footnote><para>
 171                   fourcc values consist of four bytes.
 172                   <ulink url="http://www.fourcc.org" type="http">The FOURCC
 173                   Definition List</ulink> is the most complete resource
 174                   on the allowed fourcc values.
 175                 </para></footnote>
 176               </para>
 177             </listitem>
 178             <listitem>
 179               <para>
 180                 a float value: the property has this exact floating point value.
 181               </para>
 182             </listitem>
 183             <listitem>
 184               <para>
 185                 a string value.
 186               </para>
 187             </listitem>
 188           </itemizedlist>
 189         </listitem>
 190
 191         <listitem>
 192           <para>
 193             range types:
 194           </para>
 195           <itemizedlist>
 196            <listitem>
 197               <para>
 198                 an integer range value: the property denotes a range of
 199                 possible integers. For example, the wavparse element has
 200                 a source pad where the "rate" property can go from 8000 to
 201                 48000.
 202               </para>
 203             </listitem>
 204             <listitem>
 205               <para>
 206                 a float range value: the property denotes a range of possible
 207                 floating point values.
 208               </para>
 209             </listitem>
 210           </itemizedlist>
 211         </listitem>
 212         <listitem>
 213           <para>
 214             a list value: the property can take any value from a list of
 215             basic value types or range types.
 216           </para>
 217         </listitem>
 218       </itemizedlist>
 219
 220     </sect2>
 221     <sect2 id="section-pads-caps-use">
 222       <title>What capabilities are used for</title>
 223       <para>
 224         Capabilities describe in great detail the type of media that is handled by the pads.
 225         They are mostly used for:
 226       </para>
 227       <itemizedlist>
 228         <listitem>
 229           <para>
 230             Autoplugging: automatically finding plugins for a set of capabilities
 231           </para>
 232         </listitem>
 233         <listitem>
 234           <para>
 235             Compatibility detection: when two pads are linked, <application>GStreamer</application>
 236             can verify if the two pads are talking about the same media types.
 237             The process of linking two pads and checking if they are compatible
 238             is called "caps negotiation".
 239           </para>
 240         </listitem>
 241       </itemizedlist>
 242     </sect2>
 243   </sect1>
 244 </chapter>