docs/manual/: Update for 0.10: s/0.9/0.10/; s/audioscale/audiorsample/; add converters in front of pipelines; remove ...

Original commit message from CVS:
* docs/manual/advanced-dataaccess.xml:
* docs/manual/appendix-checklist.xml:
* docs/manual/appendix-programs.xml:
* docs/manual/basics-pads.xml:
* docs/manual/highlevel-components.xml:
* docs/manual/manual.xml:
Update for 0.10: s/0.9/0.10/; s/audioscale/audiorsample/;
add converters in front of pipelines; remove curly
brackets for threads stuff, they no longer exist; use
GST_TYPE_FRACTION for framerates; update some pieces of
code to 0.10, but there's plenty more to do.
* docs/manual/appendix-porting.xml:
Expand on asynchroneous state changes; s/0.9/0.10/;
mention disappearance of gst_init_get_popt_table()
(fixes #322916).

ChangeLog

@@ -1,3 +1,22 @@
+2005-12-11  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/manual/advanced-dataaccess.xml:
+	* docs/manual/appendix-checklist.xml:
+	* docs/manual/appendix-programs.xml:
+	* docs/manual/basics-pads.xml:
+	* docs/manual/highlevel-components.xml:
+	* docs/manual/manual.xml:
+	  Update for 0.10: s/0.9/0.10/; s/audioscale/audiorsample/;
+	  add converters in front of pipelines; remove curly
+	  brackets for threads stuff, they no longer exist; use
+	  GST_TYPE_FRACTION for framerates; update some pieces of
+	  code to 0.10, but there's plenty more to do.
+
+	* docs/manual/appendix-porting.xml:
+	  Expand on asynchroneous state changes; s/0.9/0.10/;
+	  mention disappearance of gst_init_get_popt_table()
+	  (fixes #322916).
+
 2005-12-11  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* docs/faq/using.xml:

docs/manual/advanced-dataaccess.xml

@@ -66,6 +66,7 @@ main (gint   argc,
 {
   GMainLoop *loop;
   GstElement *pipeline, *src, *sink, *filter, *csp;
+  GstCaps *caps;
   GstPad *pad;
 
   /* init GStreamer */
@@ -80,15 +81,17 @@ main (gint   argc,
   sink = gst_element_factory_make ("xvimagesink", "sink");
   gst_bin_add_many (GST_BIN (pipeline), src, filter, csp, sink, NULL);
   gst_element_link_many (src, filter, csp, sink, NULL);
-  g_object_set (G_OBJECT (filter), "caps",
+  filtercaps = gst_caps_new_simple ("video/x-raw-rgb",
-      gst_caps_new_simple ("video/x-raw-rgb",
 			   "width", G_TYPE_INT, 384,
 			   "height", G_TYPE_INT, 288,
-			   "framerate", G_TYPE_DOUBLE, (gdouble) 25.0,
+			   "framerate", GST_TYPE_FRACTION, 25, 1,
 			   "bpp", G_TYPE_INT, 16,
 			   "depth", G_TYPE_INT, 16,
 			   "endianness", G_TYPE_INT, G_BYTE_ORDER,
-			   NULL), NULL);
+			   NULL);
+  g_object_set (G_OBJECT (filter), "caps", filtercaps, NULL);
+  gst_caps_unref (filtercaps);
+
   pad = gst_element_get_pad (src, "src");
   gst_pad_add_buffer_probe (pad, G_CALLBACK (cb_have_data), NULL);
   gst_object_unref (pad);
@@ -105,7 +108,7 @@ main (gint   argc,
 }
     <!-- example-end probe.c --></programlisting>
     <para>
-      Compare that output with the output of <quote>gst-launch-0.9
+      Compare that output with the output of <quote>gst-launch-0.10
       videotestsrc ! xvimagesink</quote>, just so you know what you're
       looking for.
     </para>
@@ -239,7 +242,7 @@ main (gint   argc,
   		gst_caps_new_simple ("video/x-raw-rgb",
 				     "width", G_TYPE_INT, 384,
 				     "height", G_TYPE_INT, 288,
-				     "framerate", G_TYPE_DOUBLE, (gdouble) 1.0,
+				     "framerate", GST_TYPE_FRACTION, 1, 1,
 				     "bpp", G_TYPE_INT, 16,
 				     "depth", G_TYPE_INT, 16,
 				     "endianness", G_TYPE_INT, G_BYTE_ORDER,

docs/manual/appendix-checklist.xml

@@ -105,12 +105,14 @@
        </listitem>
        <listitem>
          <para>
-          <option>--gst-debug-no-color</option> will disable color debugging.
+          <option>--gst-debug-no-color</option> will disable color debugging
+          (you can also set the GST_DEBUG_NO_COLOR environment variable to 1
+           if you want to disable colored debug output permanently)
          </para>
        </listitem>
        <listitem>
          <para>
-          <option>--gst-debug-disable</option> disables debugging alltogether.
+          <option>--gst-debug-disable</option> disables debugging altogether.
          </para>
        </listitem>
        <listitem>
@@ -130,7 +132,7 @@
       applications will find useful. Specifically, those are videoscalers
       (videoscale), colorspace convertors (ffmpegcolorspace), audio format
       convertors and channel resamplers (audioconvert) and audio samplerate
-      convertors (audioscale). Those convertors don't do anything when not
+      convertors (audioresample). Those convertors don't do anything when not
       required, they will act in passthrough mode. They will activate when
       the hardware doesn't support a specific request, though. All
       applications are recommended to use those elements.
@@ -150,16 +152,20 @@
       <para>
         <command>gst-launch</command> is a simple script-like commandline
         application that can be used to test pipelines. For example, the
-        command <command>gst-launch audiotestsrc ! alsasink</command> will run
+        command <command>gst-launch audiotestsrc ! audioconvert ! 
+        audio/x-raw-int,channels=2 ! alsasink</command> will run
         a pipeline which generates a sine-wave audio stream and plays it
         to your ALSA audio card. <command>gst-launch</command> also allows
-        the use of threads (using curly brackets, so <quote>{</quote>
+        the use of threads (will be used automatically as required or as queue
-        and <quote>}</quote>) and bins (using brackets, so <quote>(</quote>
+        elements are inserted in the pipeline) and bins (using brackets, so 
-        and <quote>)</quote>). You can use dots to imply padnames on elements,
+        <quote>(</quote> and <quote>)</quote>). You can use dots to imply
+        padnames on elements,
         or even omit the padname to automatically select a pad. Using
-        all this, the pipeline <command>gst-launch filesrc location=file.ogg
+        all this, the pipeline
-        ! oggdemux name=d { d. ! theoradec ! ffmpegcolorspace ! xvimagesink
+        <command>gst-launch filesrc location=file.ogg ! oggdemux name=d
-        } { d. ! vorbisdec ! alsasink }</command> will play an Ogg file
+         d. ! queue ! theoradec ! ffmpegcolorspace ! xvimagesink
+         d. ! queue ! vorbisdec ! audioconvert ! audioresample ! alsasink
+        </command> will play an Ogg file
         containing a Theora video-stream and a Vorbis audio-stream. You can
         also use autopluggers such as decodebin on the commandline. See the
         manual page of <command>gst-launch</command> for more information.

docs/manual/appendix-porting.xml

@@ -1,12 +1,12 @@
 <chapter id="chapter-porting">
-  <title>Porting 0.8 applications to 0.9</title>
+  <title>Porting 0.8 applications to 0.10</title>
   <para>
     This section of the appendix will discuss shortly what changes to
     applications will be needed to quickly and conveniently port most
-    applications from &GStreamer;-0.8 to &GStreamer;-0.9, with references
+    applications from &GStreamer;-0.8 to &GStreamer;-0.10, with references
     to the relevant sections in this Application Development Manual
     where needed. With this list, it should be possible to port simple
-    applications to &GStreamer;-0.9 in less than a day.
+    applications to &GStreamer;-0.10 in less than a day.
   </para>
 
   <sect1 id="section-porting-objects">
@@ -17,13 +17,15 @@
           Most functions returning an object or an object property have
           been changed to return its own reference rather than a constant
           reference of the one owned by the object itself. The reason for
-          this change is primarily threadsafety. This means, effectively,
+          this change is primarily thread safety. This means, effectively,
           that return values of functions such as
           <function>gst_element_get_pad ()</function>,
           <function>gst_pad_get_name ()</function> and many more like these
           have to be free'ed or unreferenced after use. Check the API
           references of each function to know for sure whether return
-          values should be free'ed or not.
+          values should be free'ed or not. It is important that all objects
+          derived from GstObject are ref'ed/unref'ed using gst_object_ref()
+          and gst_object_unref() respectively (instead of g_object_ref/unref).
         </para>
       </listitem>
       <listitem>
@@ -32,8 +34,8 @@
           of errors, end-of-stream and other similar pipeline events.
           Instead, they should use the <classname>GstBus</classname>, which
           has been discussed in <xref linkend="chapter-bus"/>. The bus will
-          take care that the messages will be delivered in the context of
+          take care that the messages will be delivered in the context of a
-          mainloop, which is almost certainly the application's main thread.
+          main loop, which is almost certainly the application's main thread.
           The big advantage of this is that applications no longer need to
           be thread-aware; they don't need to use <function>g_idle_add
           ()</function> in the signal handler and do the actual real work
@@ -51,14 +53,27 @@
       </listitem>
       <listitem>
         <para>
-          State changes can be delayed; ASYNC.
+          State changes can be delayed (ASYNC). Due to the new fully threaded
+          nature of GStreamer-0.10, state changes are not always immediate,
+          in particular changes including the transition from READY to PAUSED
+          state. This means two things in the context of porting applications:
+          first of all, it is no longer always possible to do
+          <function>gst_element_set_state ()</function> and check for a return
+          value of GST_STATE_CHANGE_SUCCESS, as the state change might be
+          delayed (ASYNC) and the result will not be known until later. You
+          should still check for GST_STATE_CHANGE_FAILURE right away, it is
+          just no longer possible to assume that everything that is not SUCCESS
+          means failure. Secondly, state changes might not be immediate, so
+          your code needs to take that into account. You can wait for a state
+          change to complete if you use GST_CLOCK_TIME_NONE as timeout interval
+          with <function>gst_element_get_state ()</function>.
         </para>
       </listitem>
       <listitem>
         <para>
           In 0.8, events and queries had to manually be sent to sinks in
           pipelines (unless you were using playbin). This is no longer
-          the case in 0.9. In 0.9, queries and events can be sent to
+          the case in 0.10. In 0.10, queries and events can be sent to
           toplevel pipelines, and the pipeline will do the dispatching
           internally for you. This means less bookkeeping in your
           application. For a short code example, see <xref
@@ -82,12 +97,13 @@
       </listitem>
       <listitem>
         <para>
-          Filtered caps -> caps-filter.
+          Filtered caps -> capsfilter element (the pipeline syntax for
+          gst-launch has not changed though).
         </para>
       </listitem>
       <listitem>
         <para>
-          libgstgconf-0.9.la does not exist. Use the
+          libgstgconf-0.10.la does not exist. Use the
           <quote>gconfvideosink</quote> and <quote>gconfaudiosink</quote>
           elements instead, which will do live-updates and require no library
           linking.
@@ -100,6 +116,15 @@
           <quote>pad-added</quote> and <quote>state-changed</quote>.
         </para>
       </listitem>
+      <listitem>
+        <para>
+          <function>gst_init_get_popt_table ()</function> has been removed
+          in favour of the new GOption command line option API that was
+          added to GLib 2.6. <function>gst_init_get_option_group ()</function>
+          is the new GOption-based equivalent to
+          <function>gst_init_get_ptop_table ()</function>.
+        </para>
+      </listitem>
     </itemizedlist>
   </sect1>
 </chapter>

docs/manual/appendix-programs.xml

@@ -3,15 +3,6 @@
   <para> 
   </para>
 
-  <sect1 id="section-programs-gst-register">
-    <title><command>gst-register</command></title>
-    <para> 
-      <command>gst-register</command> is used to rebuild the database of plugins.
-      It is used after a new plugin has been added to the system. The plugin database
-      can be found, by default, in <filename>/etc/gstreamer/reg.xml</filename>.
-    </para>
-  </sect1>
-
   <sect1 id="section-programs-gst-launch">
     <title><command>gst-launch</command></title>
     <para> 
@@ -22,15 +13,15 @@
       A simple commandline looks like:
 
     <screen>
-gst-launch filesrc location=hello.mp3 ! mad ! osssink
+gst-launch filesrc location=hello.mp3 ! mad ! audioresample ! osssink
     </screen>
 
       A more complex pipeline looks like:
 
     <screen>
-gst-launch filesrc location=redpill.vob ! mpegdemux name=demux \
+gst-launch filesrc location=redpill.vob ! dvddemux name=demux \
- { demux.audio_00 ! queue ! a52dec ! audioconvert ! audioscale ! osssink } \
+ demux.audio_00 ! queue ! a52dec ! audioconvert ! audioresample ! osssink \
- { demux.video_00 ! queue !  mpeg2dec ! ffmpegcolorspace ! xvmagesink }
+ demux.video_00 ! queue ! mpeg2dec ! ffmpegcolorspace ! xvimagesink
     </screen>
 
     </para>
@@ -49,6 +40,8 @@ main (int argc, char *argv[])
 {
   GstElement *pipeline;
   GstElement *filesrc;
+  GstMessage *msg;
+  GstBus *bus;
   GError *error = NULL;
 
   gst_init (&amp;argc, &amp;argv);
@@ -65,13 +58,46 @@ main (int argc, char *argv[])
   }
   
   filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
-  g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
+  g_object_set (filesrc, "location", argv[1], NULL);
 
   gst_element_set_state (pipeline, GST_STATE_PLAYING);
 
-  while (gst_bin_iterate (GST_BIN (pipeline)));
+  bus = gst_element_get_bus (pipeline);
+
+  /* wait until we either get an EOS or an ERROR message. Note that in a real
+   * program you would probably not use gst_bus_poll(), but rather set up an
+   * async signal watch on the bus and run a main loop and connect to the
+   * bus's signals to catch certain messages or all messages */
+  msg = gst_bus_poll (bus, GST_MESSAGE_EOS | GST_MESSAGE_ERROR, -1);
+
+  switch (GST_MESSAGE_TYPE (msg)) {
+    case GST_MESSAGE_EOS: {
+      g_print ("EOS\n");
+      break;
+    }
+    case GST_MESSAGE_ERROR: {
+      GError *err = NULL; /* error to show to users                 */
+      gchar *dbg = NULL;  /* additional debug string for developers */
+
+      gst_message_parse_error (msg, &err, &dbg);
+      if (err) {
+        g_printerr ("ERROR: %s\n", err-&gt;message);
+        g_error_free (err);
+      }
+      if (dbg) {
+        g_printerr ("[Debug details: %s]\n", dbg);
+        g_free (dbg);
+      }
+    }
+    default:
+      g_printerr ("Unexpected message of type %d", GST_MESSAGE_TYPE (msg));
+      break;
+  }
+  gst_message_unref (msg);
 
   gst_element_set_state (pipeline, GST_STATE_NULL);
+  gst_object_unref (pipeline);
+  gst_object_unref (bus);
 
   return 0;
 }

docs/manual/basics-pads.xml

@@ -451,7 +451,7 @@ link_pads_with_filter (GstPad *one,
   caps = gst_caps_new_simple ("video/x-raw-yuv",
 			      "width", G_TYPE_INT, 384,
 			      "height", G_TYPE_INT, 288,
-			      "framerate", G_TYPE_DOUBLE, 25.,
+			      "framerate", GST_TYPE_FRACTION, 25, 1,
 			      NULL);
   gst_pad_link_filtered (one, other, caps);
 }
@@ -473,12 +473,12 @@ link_pads_with_filter (GstPad *one,
       gst_structure_new ("video/x-raw-yuv",
 			 "width", G_TYPE_INT, 384,
 			 "height", G_TYPE_INT, 288,
-			 "framerate", G_TYPE_DOUBLE, 25.,
+			 "framerate", GST_TYPE_FRACTION, 25, 1,
 			 NULL),
       gst_structure_new ("video/x-raw-rgb",
 			 "width", G_TYPE_INT, 384,
 			 "height", G_TYPE_INT, 288,
-			 "framerate", G_TYPE_DOUBLE, 25.,
+			 "framerate", GST_TYPE_FRACTION, 25, 1,
 			 NULL),
       NULL);
 

docs/manual/highlevel-components.xml

@@ -168,7 +168,7 @@ main (gint   argc,
     </itemizedlist>
     <para>
       For convenience, it is possible to test <quote>playbin</quote> on
-      the commandline, using the command <quote>gst-launch-0.9 playbin
+      the commandline, using the command <quote>gst-launch-0.10 playbin
       uri=file:///path/to/file</quote>.
     </para>
   </sect1>

docs/manual/manual.xml

@@ -257,7 +257,7 @@
       </para>
       <para>
         In addition, we also provide a porting guide which will explain
-        easily how to port &GStreamer;-0.8 applications to &GStreamer;-0.9.
+        easily how to port &GStreamer;-0.8 applications to &GStreamer;-0.10.
       </para>
     </partintro>