pwg-intro-basics.md

   1 ---
   2 title: Foundations
   3 ...
   4
   5 # Foundations
   6
   7 This chapter of the guide introduces the basic concepts of GStreamer.
   8 Understanding these concepts will help you grok the issues involved in
   9 extending GStreamer. Many of these concepts are explained in greater
  10 detail in the *GStreamer Application Development Manual*; the basic
  11 concepts presented here serve mainly to refresh your memory.
  12
  13 ## Elements and Plugins
  14
  15 Elements are at the core of GStreamer. In the context of plugin
  16 development, an *element* is an object derived from the [`
  17 GstElement`](../../gstreamer/html/GstElement.html) class. Elements
  18 provide some sort of functionality when linked with other elements: For
  19 example, a source element provides data to a stream, and a filter
  20 element acts on the data in a stream. Without elements, GStreamer is
  21 just a bunch of conceptual pipe fittings with nothing to link. A large
  22 number of elements ship with GStreamer, but extra elements can also be
  23 written.
  24
  25 Just writing a new element is not entirely enough, however: You will
  26 need to encapsulate your element in a *plugin* to enable GStreamer to
  27 use it. A plugin is essentially a loadable block of code, usually called
  28 a shared object file or a dynamically linked library. A single plugin
  29 may contain the implementation of several elements, or just a single
  30 one. For simplicity, this guide concentrates primarily on plugins
  31 containing one element.
  32
  33 A *filter* is an important type of element that processes a stream of
  34 data. Producers and consumers of data are called *source* and *sink*
  35 elements, respectively. *Bin* elements contain other elements. One type
  36 of bin is responsible for synchronization of the elements that they
  37 contain so that data flows smoothly. Another type of bin, called
  38 *autoplugger* elements, automatically add other elements to the bin and
  39 links them together so that they act as a filter between two arbitrary
  40 stream types.
  41
  42 The plugin mechanism is used everywhere in GStreamer, even if only the
  43 standard packages are being used. A few very basic functions reside in
  44 the core library, and all others are implemented in plugins. A plugin
  45 registry is used to store the details of the plugins in an binary
  46 registry file. This way, a program using GStreamer does not have to load
  47 all plugins to determine which are needed. Plugins are only loaded when
  48 their provided elements are requested.
  49
  50 See the *GStreamer Library Reference* for the current implementation
  51 details of [`GstElement`](../../gstreamer/html/GstElement.html) and
  52 [`GstPlugin`](../../gstreamer/html/GstPlugin.html).
  53
  54 ## Pads
  55
  56 *Pads* are used to negotiate links and data flow between elements in
  57 GStreamer. A pad can be viewed as a “place” or “port” on an element
  58 where links may be made with other elements, and through which data can
  59 flow to or from those elements. Pads have specific data handling
  60 capabilities: A pad can restrict the type of data that flows through it.
  61 Links are only allowed between two pads when the allowed data types of
  62 the two pads are compatible.
  63
  64 An analogy may be helpful here. A pad is similar to a plug or jack on a
  65 physical device. Consider, for example, a home theater system consisting
  66 of an amplifier, a DVD player, and a (silent) video projector. Linking
  67 the DVD player to the amplifier is allowed because both devices have
  68 audio jacks, and linking the projector to the DVD player is allowed
  69 because both devices have compatible video jacks. Links between the
  70 projector and the amplifier may not be made because the projector and
  71 amplifier have different types of jacks. Pads in GStreamer serve the
  72 same purpose as the jacks in the home theater system.
  73
  74 For the most part, all data in GStreamer flows one way through a link
  75 between elements. Data flows out of one element through one or more
  76 *source pads*, and elements accept incoming data through one or more
  77 *sink pads*. Source and sink elements have only source and sink pads,
  78 respectively.
  79
  80 See the *GStreamer Library Reference* for the current implementation
  81 details of a [`GstPad`](../../gstreamer/html/GstPad.html).
  82
  83 ## GstMiniObject, Buffers and Events
  84
  85 All streams of data in GStreamer are chopped up into chunks that are
  86 passed from a source pad on one element to a sink pad on another
  87 element. *GstMiniObject* is the structure used to hold these chunks of
  88 data.
  89
  90 GstMiniObject contains the following important types:
  91
  92   - An exact type indicating what type of data (event, buffer, ...) this
  93     GstMiniObject is.
  94
  95   - A reference count indicating the number of elements currently
  96     holding a reference to the miniobject. When the reference count
  97     falls to zero, the miniobject will be disposed, and its memory will
  98     be freed in some sense (see below for more details).
  99
 100 For data transport, there are two types of GstMiniObject defined: events
 101 (control) and buffers (content).
 102
 103 Buffers may contain any sort of data that the two linked pads know how
 104 to handle. Normally, a buffer contains a chunk of some sort of audio or
 105 video data that flows from one element to another.
 106
 107 Buffers also contain metadata describing the buffer's contents. Some of
 108 the important types of metadata are:
 109
 110   - Pointers to one or more GstMemory objects. GstMemory objects are
 111     refcounted objects that encapsulate a region of memory.
 112
 113   - A timestamp indicating the preferred display timestamp of the
 114     content in the buffer.
 115
 116 Events contain information on the state of the stream flowing between
 117 the two linked pads. Events will only be sent if the element explicitly
 118 supports them, else the core will (try to) handle the events
 119 automatically. Events are used to indicate, for example, a media type,
 120 the end of a media stream or that the cache should be flushed.
 121
 122 Events may contain several of the following items:
 123
 124   - A subtype indicating the type of the contained event.
 125
 126   - The other contents of the event depend on the specific event type.
 127
 128 Events will be discussed extensively in [Events: Seeking, Navigation and
 129 More](pwg-advanced-events.md). Until then, the only event that will
 130 be used is the *EOS* event, which is used to indicate the end-of-stream
 131 (usually end-of-file).
 132
 133 See the *GStreamer Library Reference* for the current implementation
 134 details of a
 135 [`GstMiniObject`](../../gstreamer/html/gstreamer-GstMiniObject.html),
 136 [`GstBuffer`](../../gstreamer/html/GstBuffer.html) and
 137 [`GstEvent`](../../gstreamer/html/GstEvent.html).
 138
 139 ### Buffer Allocation
 140
 141 Buffers are able to store chunks of memory of several different types.
 142 The most generic type of buffer contains memory allocated by malloc().
 143 Such buffers, although convenient, are not always very fast, since data
 144 often needs to be specifically copied into the buffer.
 145
 146 Many specialized elements create buffers that point to special memory.
 147 For example, the filesrc element usually maps a file into the address
 148 space of the application (using mmap()), and creates buffers that point
 149 into that address range. These buffers created by filesrc act exactly
 150 like generic buffers, except that they are read-only. The buffer freeing
 151 code automatically determines the correct method of freeing the
 152 underlying memory. Downstream elements that receive these kinds of
 153 buffers do not need to do anything special to handle or unreference it.
 154
 155 Another way an element might get specialized buffers is to request them
 156 from a downstream peer through a GstBufferPool or GstAllocator. Elements
 157 can ask a GstBufferPool or GstAllocator from the downstream peer
 158 element. If downstream is able to provide these objects, upstream can
 159 use them to allocate buffers. See more in [Memory
 160 allocation](pwg-allocation.md).
 161
 162 Many sink elements have accelerated methods for copying data to
 163 hardware, or have direct access to hardware. It is common for these
 164 elements to be able to create a GstBufferPool or GstAllocator for their
 165 upstream peers. One such example is ximagesink. It creates buffers that
 166 contain XImages. Thus, when an upstream peer copies data into the
 167 buffer, it is copying directly into the XImage, enabling ximagesink to
 168 draw the image directly to the screen instead of having to copy data
 169 into an XImage first.
 170
 171 Filter elements often have the opportunity to either work on a buffer
 172 in-place, or work while copying from a source buffer to a destination
 173 buffer. It is optimal to implement both algorithms, since the GStreamer
 174 framework can choose the fastest algorithm as appropriate. Naturally,
 175 this only makes sense for strict filters -- elements that have exactly
 176 the same format on source and sink pads.
 177
 178 ## Media types and Properties
 179
 180 GStreamer uses a type system to ensure that the data passed between
 181 elements is in a recognized format. The type system is also important
 182 for ensuring that the parameters required to fully specify a format
 183 match up correctly when linking pads between elements. Each link that is
 184 made between elements has a specified type and optionally a set of
 185 properties. See more about caps negotiation in [Caps
 186 negotiation](pwg-negotiation.md).
 187
 188 ### The Basic Types
 189
 190 GStreamer already supports many basic media types. Following is a table
 191 of a few of the basic types used for buffers in GStreamer. The table
 192 contains the name ("media type") and a description of the type, the
 193 properties associated with the type, and the meaning of each property. A
 194 full list of supported types is included in [List of Defined
 195 Types](pwg-building-types.md#list-of-defined-types).
 196
 197 <table>
 198 <caption>Table of Example Types</caption>
 199 <thead>
 200 <tr class="header">
 201 <th>Media Type</th>
 202 <th>Description</th>
 203 <th>Property</th>
 204 <th>Property Type</th>
 205 <th>Property Values</th>
 206 <th>Property Description</th>
 207 </tr>
 208 </thead>
 209 <tbody>
 210 <tr class="odd">
 211 <td>audio/*</td>
 212 <td><em>All audio types</em></td>
 213 <td>rate</td>
 214 <td>integer</td>
 215 <td>greater than 0</td>
 216 <td>The sample rate of the data, in samples (per channel) per second.</td>
 217 </tr>
 218 <tr class="even">
 219 <td>channels</td>
 220 <td>integer</td>
 221 <td>greater than 0</td>
 222 <td>The number of channels of audio data.</td>
 223 </tr>
 224 <tr class="odd">
 225 <td>audio/x-raw</td>
 226 <td>Unstructured and uncompressed raw integer audio data.</td>
 227 <td>format</td>
 228 <td>string</td>
 229 <td>S8 U8 S16LE S16BE U16LE U16BE S24_32LE S24_32BE U24_32LE U24_32BE S32LE S32BE U32LE U32BE S24LE S24BE U24LE U24BE S20LE S20BE U20LE U20BE S18LE S18BE U18LE U18BE F32LE F32BE F64LE F64BE</td>
 230 <td>The format of the sample data.</td>
 231 </tr>
 232 <tr class="even">
 233 <td>audio/mpeg</td>
 234 <td>Audio data compressed using the MPEG audio encoding scheme.</td>
 235 <td>mpegversion</td>
 236 <td>integer</td>
 237 <td>1, 2 or 4</td>
 238 <td>The MPEG-version used for encoding the data. The value 1 refers to MPEG-1, -2 and -2.5 layer 1, 2 or 3. The values 2 and 4 refer to the MPEG-AAC audio encoding schemes.</td>
 239 </tr>
 240 <tr class="odd">
 241 <td>framed</td>
 242 <td>boolean</td>
 243 <td>0 or 1</td>
 244 <td>A true value indicates that each buffer contains exactly one frame. A false value indicates that frames and buffers do not necessarily match up.</td>
 245 </tr>
 246 <tr class="even">
 247 <td>layer</td>
 248 <td>integer</td>
 249 <td>1, 2, or 3</td>
 250 <td>The compression scheme layer used to compress the data <em>(only if mpegversion=1)</em>.</td>
 251 </tr>
 252 <tr class="odd">
 253 <td>bitrate</td>
 254 <td>integer</td>
 255 <td>greater than 0</td>
 256 <td>The bitrate, in bits per second. For VBR (variable bitrate) MPEG data, this is the average bitrate.</td>
 257 </tr>
 258 <tr class="even">
 259 <td>audio/x-vorbis</td>
 260 <td>Vorbis audio data</td>
 261 <td></td>
 262 <td></td>
 263 <td></td>
 264 <td>There are currently no specific properties defined for this type.</td>
 265 </tr>
 266 </tbody>
 267 </table>
 268