docs: fix some typos and add some missing links in the app dev manual

[platform/upstream/gstreamer.git] / docs / manual / intro-basics.xml

diff --git a/docs/manual/intro-basics.xml b/docs/manual/intro-basics.xml
index 2e5c6c0..b0c2806 100644 (file)
--- a/docs/manual/intro-basics.xml
+++ b/docs/manual/intro-basics.xml
@@ -28,13 +28,13 @@
     <title>Pads</title>
     <para>
       <emphasis>Pads</emphasis> are element's input and output, where
-      you can connect other elements. They used to negotiate links and
+      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
@@ -59,9 +59,9 @@
       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>
@@ -97,4 +97,62 @@
 
   </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>