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
10 <sect1 id="section-intro-basics-elements">
11 <title>Elements</title>
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;.
27 <sect1 id="section-intro-basics-pads">
30 <emphasis>Pads</emphasis> are element's input and output, where
31 you can connect other elements. They are used to negotiate links and
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>.
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.
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).
69 <sect1 id="section-intro-basics-bins">
70 <title>Bins and pipelines</title>
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).
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.
89 <figure float="1" id="section-pipeline-img">
90 <title>&GStreamer; pipeline for a simple ogg player</title>
93 <imagedata scale="75" fileref="images/simple-player.ℑ" format="&IMAGE;" />
100 <sect1 id="section-intro-basics-communication">
101 <title>Communication</title>
104 &GStreamer; provides several mechanisms for communication and data exchange
105 between the <emphasis>application</emphasis> and the <emphasis>pipeline</emphasis>.
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).
118 <emphasis>events</emphasis>: are objects send 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.
125 <emphasis>messages</emphasis>: are objects send from elements over the
126 bus to the application. Messages can be received synchronously, but
127 then from the streaming thread context of the sender or asynchronously
128 marshalled to the main thread of the application.
133 <emphasis>queries</emphasis>: allow application to request information
134 from the pipeline. Queries are answered synchronously. Also elements
135 can use queries. They can be used both ways, but most common are
141 <figure float="1" id="section-communication-img">
142 <title>&GStreamer; pipeline with different communication flows</title>
145 <imagedata scale="75" fileref="images/communication.ℑ" format="&IMAGE;" />