docs/pwg/intro-basics.xml

   1 <!-- ############ chapter ############# -->
   2
   3 <chapter id="chapter-intro-basics" xreflabel="Basic Concepts">
   4   <title>Basic Concepts</title>
   5   <para>
   6     This chapter of the guide introduces the basic concepts of &GStreamer;.
   7     Understanding these concepts will help you grok the issues involved in
   8     extending &GStreamer;. Many of these concepts are explained in greater
   9     detail in the &GstAppDevMan;; the basic concepts presented here serve mainly
  10     to refresh your memory.
  11   </para>
  12
  13   <!-- ############ sect1 ############# -->
  14
  15   <sect1 id="section-basics-elements" xreflabel="Elements and Plugins">
  16     <title>Elements and Plugins</title>
  17     <para>
  18       Elements are at the core of &GStreamer;. In the context of plugin
  19       development, an <emphasis>element</emphasis> is an object derived from the
  20       <classname>GstElement</classname> class. Elements provide some sort of
  21       functionality when linked with other elements: For example, a source
  22       element provides data to a stream, and a filter element acts on the data
  23       in a stream. Without elements, &GStreamer; is just a bunch of conceptual
  24       pipe fittings with nothing to link. A large number of elements ship
  25       with &GStreamer;, but extra elements can also be written.
  26     </para>
  27     <para>
  28       Just writing a new element is not entirely enough, however: You will need
  29       to encapsulate your element in a <emphasis>plugin</emphasis> to enable
  30       &GStreamer; to use it. A plugin is essentially a loadable block of code,
  31       usually called a shared object file or a dynamically linked library. A
  32       single plugin may contain the implementation of several elements, or just
  33       a single one. For simplicity, this guide concentrates primarily on plugins
  34       containing one element.
  35     </para>
  36     <para>
  37       A <emphasis>filter</emphasis> is an important type of element that
  38       processes a stream of data. Producers and consumers of data are called
  39       <emphasis>source</emphasis> and <emphasis>sink</emphasis> elements,
  40       respectively. <emphasis>Bin</emphasis> elements contain other elements.
  41       One type of bin is responsible for scheduling the elements that they
  42       contain so that data flows smoothly. Another type of bin, called
  43       <emphasis>autoplugger</emphasis> elements, automatically add other
  44       elements to the bin and link them together so that they act as a
  45       filter between two arbitary stream types.
  46     </para>
  47     <para>
  48       The plugin mechanism is used everywhere in &GStreamer;, even if only the
  49       standard packages are being used. A few very basic functions reside in the
  50       core library, and all others are implemented in plugins. A plugin registry
  51       is used to store the details of the plugins in an XML file. This way, a
  52       program using &GStreamer; does not have to load all plugins to determine
  53       which are needed. Plugins are only loaded when their provided elements are
  54       requested.
  55     </para>
  56     <para>
  57       See the &GstLibRef; for the current implementation details of <ulink
  58       type="http"
  59       url="../gstreamer/gstelement.html"><classname>GstElement</classname></ulink>
  60       and <ulink type="http"
  61       url="../gstreamer/gstreamer-gstplugin.html"><classname>GstPlugin</classname></ulink>.
  62     </para>
  63   </sect1>
  64
  65   <!-- ############ sect1 ############# -->
  66
  67   <sect1 id="section-basics-pads" xreflabel="Pads">
  68     <title>Pads</title>
  69     <para>
  70       <emphasis>Pads</emphasis> are used to negotiate links and data flow
  71       between elements in &GStreamer;. A pad can be viewed as a
  72       <quote>place</quote> or <quote>port</quote> on an element where
  73       links may be made with other elements, and through which data can
  74       flow to or from those elements.  Pads have specific data handling
  75       capabilities: A pad can restrict the type of data that flows
  76       through it.  Links are only allowed between two pads when the
  77       allowed data types of the two pads are compatible.
  78     </para>
  79     <para>
  80       An analogy may be helpful here. A pad is similar to a plug or jack on a
  81       physical device. Consider, for example, a home theater system consisting
  82       of an amplifier, a DVD player, and a (silent) video projector. Linking
  83       the DVD player to the amplifier is allowed because both devices have audio
  84       jacks, and linking the projector to the DVD player is allowed because
  85       both devices have compatible video jacks. Links between the
  86       projector and the amplifier may not be made because the projector and
  87       amplifier have different types of jacks. Pads in &GStreamer; serve the
  88       same purpose as the jacks in the home theater system.
  89     </para>
  90     <para>
  91       For the most part, all data in &GStreamer; flows one way through a link
  92       between elements. Data flows out of one element through one or more
  93       <emphasis>source pads</emphasis>, and elements accept incoming data through
  94       one or more <emphasis>sink pads</emphasis>. Source and sink elements have
  95       only source and sink pads, respectively.
  96     </para>
  97     <para>
  98       See the &GstLibRef; for the current implementation details of a <ulink
  99       type="http"
 100       url="../gstreamer/gstreamer-gstpad.html"><classname>GstPad</classname></ulink>.
 101     </para>
 102   </sect1>
 103
 104   <!-- ############ sect1 ############# -->
 105
 106   <sect1 id="section-basics-data" xreflabel="Data, Buffers and Events">
 107     <title>Data, Buffers and Events</title>
 108     <para>
 109       All streams of data in &GStreamer; are chopped up into chunks that are
 110       passed from a source pad on one element to a sink pad on another element.
 111       <emphasis>Data</emphasis> are structures used to hold these chunks of
 112       data.
 113     </para>
 114     <para>
 115       Data contains the following important types:
 116       <itemizedlist>
 117         <listitem>
 118           <para>
 119             An exact type indicating what type of data (control, content, ...)
 120             this Data is.
 121           </para>
 122         </listitem>
 123         <listitem>
 124           <para>
 125             A reference count indicating the number of elements currently
 126             holding a reference to the buffer. When the buffer reference count
 127             falls to zero, the buffer will be unlinked, and its memory will be
 128             freed in some sense (see below for more details).
 129           </para>
 130         </listitem>
 131       </itemizedlist>
 132     </para>
 133     <para>
 134       There are two types of data defined: events (control) and buffers
 135       (content).
 136     </para>
 137     <para>
 138       Buffers may contain any sort of data that the two linked pads
 139       know how to handle. Normally, a buffer contains a chunk of some sort of
 140       audio or video data that flows from one element to another.
 141     </para>
 142     <para>
 143       Buffers also contain metadata describing the buffer's contents. Some of
 144       the important types of metadata are:
 145       <itemizedlist>
 146         <listitem>
 147           <para>
 148             A pointer to the buffer's data.
 149           </para>
 150         </listitem>
 151         <listitem>
 152           <para>
 153             An integer indicating the size of the buffer's data.
 154           </para>
 155         </listitem>
 156         <listitem>
 157           <para>
 158             A timestamp indicating the preferred display timestamp of the
 159             content in the buffer.
 160           </para>
 161         </listitem>
 162       </itemizedlist>
 163     </para>
 164     <para>
 165       Events
 166       contain information on the state of the stream flowing between the two
 167       linked pads. Events will only be sent if the element explicitely supports
 168       them, else the core will (try to) handle the events automatically. Events
 169       are used to indicate, for example, a clock discontinuity, the end of a
 170       media stream or that the cache should be flushed.
 171     </para>
 172     <para>
 173       Events may contain several of the following items:
 174       <itemizedlist>
 175         <listitem>
 176           <para>
 177             A subtype indicating the type of the contained event.
 178           </para>
 179         </listitem>
 180         <listitem>
 181           <para>
 182             The other contents of the event depend on the specific event type.
 183           </para>
 184         </listitem>
 185       </itemizedlist>
 186     </para>
 187     <para>
 188       See the &GstLibRef; for the current implementation details of a <ulink
 189       type="http"
 190       url="../gstreamer/gstreamer-gstdata.html"><classname>GstData</classname></ulink>, <ulink type="http"
 191       url="../gstreamer/gstreamer-gstbuffer.html"><classname>GstBuffer</classname></ulink> and <ulink type="http"
 192       url="../gstreamer/gstreamer-gstevent.html"><classname>GstEvent</classname></ulink>.
 193     </para>
 194
 195     <sect2 id="sect2-buffers-bufferpools" xreflabel="Buffer Allocation and
 196     Buffer Pools">
 197       <title>Buffer Allocation and Buffer Pools</title>
 198       <para>
 199         Buffers can be allocated using various schemes, and they may either be
 200         passed on by an element or unreferenced, thus freeing the memory used by
 201         the buffer. Buffer allocation and unlinking are important concepts when
 202         dealing with real time media processing, since memory allocation is
 203         relatively slow on most systems.
 204       </para>
 205       <para>
 206         To improve the latency in a media pipeline, many &GStreamer; elements
 207         use a <emphasis>buffer pool</emphasis> to handle buffer allocation and
 208         releasing. A buffer pool is a virtual representation of one or more
 209         buffers of which the data is not actually allocated by &GStreamer;
 210         itself. Examples of these include hardware framebuffer memory in video
 211         output elements or kernel-allocated DMA memory for video capture. The
 212         huge advantage of using these buffers instead of creating our own is
 213         that we do not have to copy memory from one place to another, thereby
 214         saving a noticeable number of CPU cycles. Elements should not provide
 215         a bufferpool to decrease the number of memory allocations: the kernel
 216         will generally take care of that - and will probably do that much more
 217         efficiently than we ever could. Using bufferpools in this way is highly
 218         discouraged.
 219       </para>
 220       <para>
 221         Normally in a media pipeline, most filter elements in &GStreamer; deal
 222         with a buffer in place, meaning that they do not create or destroy
 223         buffers. Sometimes, however, elements might need to alter the reference
 224         count of a buffer, either by copying or destroying the buffer, or by
 225         creating a new buffer. These topics are generally reserved for
 226         non-filter elements, so they will be addressed at that point.
 227       </para>
 228     </sect2>
 229   </sect1>
 230
 231   <!-- ############ sect1 ############# -->
 232
 233   <sect1 id="section-basics-types" xreflabel="Types and Properties">
 234     <title>Mimetypes and Properties</title>
 235     <para>
 236       &GStreamer; uses a type system to ensure that the data passed between
 237       elements is in a recognized format. The type system is also important
 238       for ensuring that the parameters required to fully specify a format match
 239       up correctly when linking pads between elements. Each link that is
 240       made between elements has a specified type and optionally a set of
 241       properties.
 242     </para>
 243
 244     <!-- ############ sect2 ############# -->
 245
 246     <sect2 id="sect2-types-basictypes" xreflabel="Basic Types">
 247       <title>The Basic Types</title>
 248       <para>
 249         &GStreamer; already supports many basic media types. Following is a
 250         table of a few of the the basic types used for buffers in
 251         &GStreamer;. The table contains the name ("mime type") and a
 252         description of the type, the properties associated with the type, and
 253         the meaning of each property. A full list of supported types is
 254         included in <xref linkend="section-types-definitions"/>.
 255       </para>
 256
 257       <table frame="all" id="table-basictypes" xreflabel="Table of Basic Types">
 258         <title>Table of Basic Types</title>
 259         <tgroup cols="6" align="left" colsep="1" rowsep="1">
 260
 261         <thead>
 262           <row>
 263             <entry>Mime Type</entry>
 264             <entry>Description</entry>
 265             <entry>Property</entry>
 266             <entry>Property Type</entry>
 267             <entry>Property Values</entry>
 268             <entry>Property Description</entry>
 269           </row>
 270         </thead>
 271
 272         <tbody valign="top">
 273
 274           <!-- ############ type ############# -->
 275
 276           <row>
 277             <entry morerows="1">audio/*</entry>
 278             <entry morerows="1">
 279               <emphasis>All audio types</emphasis>
 280             </entry>
 281             <entry>rate</entry>
 282             <entry>integer</entry>
 283             <entry>greater than 0</entry>
 284             <entry>
 285               The sample rate of the data, in samples (per channel) per second.
 286             </entry>
 287           </row>
 288           <row>
 289             <entry>channels</entry>
 290             <entry>integer</entry>
 291             <entry>greater than 0</entry>
 292             <entry>
 293               The number of channels of audio data.
 294             </entry>
 295           </row>
 296
 297           <!-- ############ type ############# -->
 298
 299           <row>
 300             <entry morerows="3">audio/x-raw-int</entry>
 301             <entry morerows="3">
 302               Unstructured and uncompressed raw integer audio data.
 303             </entry>
 304             <entry>endianness</entry>
 305             <entry>integer</entry>
 306             <entry>G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321)</entry>
 307             <entry>
 308               The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321)
 309               means <quote>little-endian</quote> (byte-order is <quote>least
 310               significant byte first</quote>). The value G_BIG_ENDIAN (1234)
 311               means <quote>big-endian</quote> (byte order is <quote>most
 312               significant byte first</quote>).
 313             </entry>
 314           </row>
 315           <row>
 316             <entry>signed</entry>
 317             <entry>boolean</entry>
 318             <entry>TRUE or FALSE</entry>
 319             <entry>
 320               Whether the values of the integer samples are signed or not.
 321               Signed samples use one bit to indicate sign (negative or
 322               positive) of the value. Unsigned samples are always positive.
 323             </entry>
 324           </row>
 325           <row>
 326             <entry>width</entry>
 327             <entry>integer</entry>
 328             <entry>greater than 0</entry>
 329             <entry>
 330               Number of bits allocated per sample.
 331             </entry>
 332           </row>
 333           <row>
 334             <entry>depth</entry>
 335             <entry>integer</entry>
 336             <entry>greater than 0</entry>
 337             <entry>
 338               The number of bits used per sample. This must be less than or
 339               equal to the width: If the depth is less than the width, the
 340               low bits are assumed to be the ones used. For example, a width
 341               of 32 and a depth of 24 means that each sample is stored in a
 342               32 bit word, but only the low 24 bits are actually used.
 343             </entry>
 344           </row>
 345
 346           <!-- ############ type ############# -->
 347
 348           <row>
 349             <entry morerows="3">audio/mpeg</entry>
 350             <entry morerows="3">
 351               Audio data compressed using the MPEG audio encoding scheme.
 352             </entry>
 353             <entry>mpegversion</entry>
 354             <entry>integer</entry>
 355             <entry>1, 2 or 4</entry>
 356             <entry>
 357               The MPEG-version used for encoding the data. The value 1 refers
 358               to MPEG-1, -2 and -2.5 layer 1, 2 or 3. The values 2 and 4 refer
 359               to the MPEG-AAC audio encoding schemes.
 360             </entry>
 361           </row>
 362           <row>
 363             <entry>framed</entry>
 364             <entry>boolean</entry>
 365             <entry>0 or 1</entry>
 366             <entry>
 367               A true value indicates that each buffer contains exactly one
 368               frame. A false value indicates that frames and buffers do not
 369               necessarily match up.
 370             </entry>
 371           </row>
 372           <row>
 373             <entry>layer</entry>
 374             <entry>integer</entry>
 375             <entry>1, 2, or 3</entry>
 376             <entry>
 377               The compression scheme layer used to compress the data
 378               <emphasis>(only if mpegversion=1)</emphasis>.
 379             </entry>
 380           </row>
 381           <row>
 382             <entry>bitrate</entry>
 383             <entry>integer</entry>
 384             <entry>greater than 0</entry>
 385             <entry>
 386               The bitrate, in bits per second. For VBR (variable bitrate)
 387               MPEG data, this is the average bitrate.
 388             </entry>
 389           </row>
 390
 391           <!-- ############ type ############# -->
 392
 393           <row>
 394             <entry>audio/x-vorbis</entry>
 395             <entry>Vorbis audio data</entry>
 396             <entry></entry>
 397             <entry></entry>
 398             <entry></entry>
 399             <entry>
 400               There are currently no specific properties defined for this type.
 401             </entry>
 402           </row>
 403         </tbody>
 404       </tgroup>
 405       </table>
 406     </sect2>
 407   </sect1>
 408 </chapter>