mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-08 13:18:52 +00:00
158 lines
7.2 KiB
XML
158 lines
7.2 KiB
XML
<chapter id="chapter-intro-basics">
|
|
<title>Foundations</title>
|
|
<para><!-- synchronize with PWG -->
|
|
This chapter of the guide introduces the basic concepts of &GStreamer;.
|
|
Understanding these concepts will be important in reading any of the
|
|
rest of this guide, all of them assume understanding of these basic
|
|
concepts.
|
|
</para>
|
|
|
|
<sect1 id="section-intro-basics-elements">
|
|
<title>Elements</title>
|
|
<para>
|
|
An <emphasis>element</emphasis> is the most important class of objects
|
|
in &GStreamer;. You will usually create a chain of elements linked
|
|
together and let data flow through this chain of elements. An element
|
|
has one specific function, which can be the reading of data from a
|
|
file, decoding of this data or outputting this data to your sound
|
|
card (or anything else). By chaining together several such elements,
|
|
you create a <emphasis>pipeline</emphasis> that can do a specific task,
|
|
for example media playback or capture. &GStreamer; ships with a large
|
|
collection of elements by default, making the development of a large
|
|
variety of media applications possible. If needed, you can also write
|
|
new elements. That topic is explained in great deal in the &GstPWG;.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="section-intro-basics-pads">
|
|
<title>Pads</title>
|
|
<para>
|
|
<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
|
|
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
|
|
negotiation</emphasis>. Data types are described as a
|
|
<classname>GstCaps</classname>.
|
|
</para>
|
|
<para>
|
|
An analogy may be helpful here. A pad is similar to a plug or jack on a
|
|
physical device. Consider, for example, a home theater system consisting
|
|
of an amplifier, a DVD player, and a (silent) video projector. Linking
|
|
the DVD player to the amplifier is allowed because both devices have audio
|
|
jacks, and linking the projector to the DVD player is allowed because
|
|
both devices have compatible video jacks. Links between the
|
|
projector and the amplifier may not be made because the projector and
|
|
amplifier have different types of jacks. Pads in &GStreamer; serve the
|
|
same purpose as the jacks in the home theater system.
|
|
</para>
|
|
<para>
|
|
For the most part, all data in &GStreamer; flows one way through a link
|
|
between elements. Data flows out of one element through one or more
|
|
<emphasis>source pads</emphasis>, and elements accept incoming data
|
|
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
|
|
</classname></ulink> object) and events (described by the <ulink
|
|
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>
|