</para>
</sect1>
- <sect1 id="section-intro-basics-bins">
- <title>Bins and pipelines</title>
-
- <para>
- A <emphasis>bin</emphasis> is a container for a collection of elements.
- A pipeline is a special subtype of a bin that allows execution of all
- of its contained child elements. Since bins are subclasses of elements
- themselves, you can mostly control a bin as if it were an element,
- thereby abstracting away a lot of complexity for your application. You
- can, for example change state on all elements in a bin by changing the
- state of that bin itself. Bins also forward bus messages from their
- contained children (such as error messages, tag messages or EOS messages).
- </para>
- <para>
- A pipeline is a top-level bin. As you set it to PAUSED or PLAYING state,
- data flow will start and media processing will take place. Once started,
- pipelines will run in a separate thread until you stop them or the end
- of the data stream is reached.
- </para>
- </sect1>
-
<sect1 id="section-intro-basics-pads">
<title>Pads</title>
<para>
- <emphasis>Pads</emphasis> are used to negotiate links and data flow
+ <emphasis>Pads</emphasis> are element's input and output, where
+ you can connect other elements. They are used to negotiate links and
+ data flow
between elements in &GStreamer;. A pad can be viewed as a
<quote>plug</quote> or <quote>port</quote> on an element where
links may be made with other elements, and through which data can
flow to or from those elements. Pads have specific data handling
- capabilities: A pad can restrict the type of data that flows
+ capabilities: a pad can restrict the type of data that flows
through it. Links are only allowed between two pads when the
allowed data types of the two pads are compatible. Data types are
negotiated between pads using a process called <emphasis>caps
through one or more <emphasis>sink pads</emphasis>. Source and sink
elements have only source and sink pads, respectively. Data usually
means buffers (described by the <ulink type="http"
- url="&URLAPI;/gstreamer-GstBuffer.html"><classname>GstBuffer
+ url="&URLAPI;gstreamer-GstBuffer.html"><classname>GstBuffer
</classname></ulink> object) and events (described by the <ulink
- type="http" url="&URLAPI;/gstreamer-GstEvent.html"><classname>
+ type="http" url="&URLAPI;gstreamer-GstEvent.html"><classname>
GstEvent</classname></ulink> object).
</para>
</sect1>
+
+ <sect1 id="section-intro-basics-bins">
+ <title>Bins and pipelines</title>
+
+ <para>
+ A <emphasis>bin</emphasis> is a container for a collection of elements.
+ A <emphasis>pipeline</emphasis> is a special subtype of a bin that allows execution of all
+ of its contained child elements. Since bins are subclasses of elements
+ themselves, you can mostly control a bin as if it were an element,
+ thereby abstracting away a lot of complexity for your application. You
+ can, for example change state on all elements in a bin by changing the
+ state of that bin itself. Bins also forward bus messages from their
+ contained children (such as error messages, tag messages or EOS messages).
+ </para>
+ <para>
+ A <emphasis>pipeline</emphasis> is a top-level bin. As you set it to PAUSED or PLAYING state,
+ data flow will start and media processing will take place. Once started,
+ pipelines will run in a separate thread until you stop them or the end
+ of the data stream is reached.
+ </para>
+
+ <figure float="1" id="section-pipeline-img">
+ <title>&GStreamer; pipeline for a simple ogg player</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="75" fileref="images/simple-player.ℑ" format="&IMAGE;" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </sect1>
+
+ <sect1 id="section-intro-basics-communication">
+ <title>Communication</title>
+
+ <para>
+ &GStreamer; provides several mechanisms for communication and data exchange
+ between the <emphasis>application</emphasis> and the <emphasis>pipeline</emphasis>.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>buffers</emphasis> are objects for passing streaming data
+ between elements in the pipeline. Buffers always travel from sources
+ to sinks (downstream).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>events</emphasis> are objects sent between elements or from
+ the application to elements. Events can travel upstream and downstream.
+ Downstream events can be synchronised to the data flow.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>messages</emphasis> are objects posted by elements on
+ the pipeline's message bus, where they will be held for collection
+ by the application. Messages can be intercepted synchronously from
+ the streaming thread context of the element posting the message, but
+ are usually handled asynchronously by the application from the
+ application's main thread. Messages are used to transmit information
+ such as errors, tags, state changes, buffering state, redirects etc.
+ from elements to the application in a thread-safe way.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>queries</emphasis> allow applications to request information
+ such as duration or current playback position from the pipeline.
+ Queries are always answered synchronously. Elements can also use
+ queries to request information from their peer elements (such as the
+ file size or duration). They can be used both ways within a pipeline,
+ but upstream queries are more common.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <figure float="1" id="section-communication-img">
+ <title>&GStreamer; pipeline with different communication flows</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="75" fileref="images/communication.ℑ" format="&IMAGE;" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </sect1>
+
</chapter>
projects / platform / upstream / gstreamer.git / blobdiff