docs/manual/intro-basics.xml - mtk-gstreamer-debian - Git at Google

 <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.
       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. It provides a bus for
       the application and manages the synchronization for its children.
       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.&image;" 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.&image;" format="&IMAGE;" />
         </imageobject>
       </mediaobject>
     </figure>

   </sect1>

 </chapter>
	<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.
	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. It provides a bus for
	the application and manages the synchronization for its children.
	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.&image;" 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.&image;" format="&IMAGE;" />
	</imageobject>
	</mediaobject>
	</figure>

	</sect1>

	</chapter>