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:
Spider no longer exists, and neither does gst-launch-ext.
Update examples to use decodebin and playbin and put
{
GMainLoop *loop;
GstElement *pipeline, *src, *sink, *filter, *csp;
+ GstCaps *caps;
GstPad *pad;
/* init GStreamer */
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",
- gst_caps_new_simple ("video/x-raw-rgb",
+ filtercaps = 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);
}
<!-- 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>
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,
</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>
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.
<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>
- and <quote>}</quote>) and bins (using brackets, so <quote>(</quote>
- and <quote>)</quote>). You can use dots to imply padnames on elements,
+ the use of threads (will be used automatically as required or as queue
+ elements are inserted in the pipeline) and bins (using brackets, so
+ <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
- ! oggdemux name=d { d. ! theoradec ! ffmpegcolorspace ! xvimagesink
- } { d. ! vorbisdec ! alsasink }</command> will play an Ogg file
+ all this, the pipeline
+ <command>gst-launch filesrc location=file.ogg ! oggdemux name=d
+ 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.
<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">
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>
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
- mainloop, which is almost certainly the application's main thread.
+ take care that the messages will be delivered in the context of a
+ 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
</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
</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.
<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>
<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>
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 \
- { demux.audio_00 ! queue ! a52dec ! audioconvert ! audioscale ! osssink } \
- { demux.video_00 ! queue ! mpeg2dec ! ffmpegcolorspace ! xvmagesink }
+gst-launch filesrc location=redpill.vob ! dvddemux name=demux \
+ demux.audio_00 ! queue ! a52dec ! audioconvert ! audioresample ! osssink \
+ demux.video_00 ! queue ! mpeg2dec ! ffmpegcolorspace ! xvimagesink
</screen>
</para>
{
GstElement *pipeline;
GstElement *filesrc;
+ GstMessage *msg;
+ GstBus *bus;
GError *error = NULL;
gst_init (&argc, &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->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;
}
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);
}
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);
</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>
</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>
projects / platform / upstream / gstreamer.git / commitdiff