From 30cfab511a3a3d03a250dfb55311d796c39021a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= Date: Sun, 11 Dec 2005 17:49:10 +0000 Subject: [PATCH] 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 | 19 ++++++++++ docs/manual/advanced-dataaccess.xml | 15 +++++--- docs/manual/appendix-checklist.xml | 26 ++++++++----- docs/manual/appendix-porting.xml | 47 +++++++++++++++++------ docs/manual/appendix-programs.xml | 56 ++++++++++++++++++++-------- docs/manual/basics-pads.xml | 6 +-- docs/manual/highlevel-components.xml | 2 +- docs/manual/manual.xml | 2 +- 8 files changed, 126 insertions(+), 47 deletions(-) diff --git a/ChangeLog b/ChangeLog index c69db482a2..4eaf5aa386 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,22 @@ +2005-12-11 Tim-Philipp Müller + + * 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 * docs/faq/using.xml: diff --git a/docs/manual/advanced-dataaccess.xml b/docs/manual/advanced-dataaccess.xml index bd1d518894..f1e5743741 100644 --- a/docs/manual/advanced-dataaccess.xml +++ b/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", - 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); @@ -105,7 +108,7 @@ main (gint argc, } - Compare that output with the output of gst-launch-0.9 + Compare that output with the output of gst-launch-0.10 videotestsrc ! xvimagesink, just so you know what you're looking for. @@ -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, diff --git a/docs/manual/appendix-checklist.xml b/docs/manual/appendix-checklist.xml index 2f778531e5..afb98d5552 100644 --- a/docs/manual/appendix-checklist.xml +++ b/docs/manual/appendix-checklist.xml @@ -105,12 +105,14 @@ - will disable color debugging. + 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) - disables debugging alltogether. + disables debugging altogether. @@ -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 @@ gst-launch is a simple script-like commandline application that can be used to test pipelines. For example, the - command gst-launch audiotestsrc ! alsasink will run + command gst-launch audiotestsrc ! audioconvert ! + audio/x-raw-int,channels=2 ! alsasink will run a pipeline which generates a sine-wave audio stream and plays it to your ALSA audio card. gst-launch also allows - the use of threads (using curly brackets, so { - and }) and bins (using brackets, so ( - and )). 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 + ( and )). You can use dots to imply + padnames on elements, or even omit the padname to automatically select a pad. Using - all this, the pipeline gst-launch filesrc location=file.ogg - ! oggdemux name=d { d. ! theoradec ! ffmpegcolorspace ! xvimagesink - } { d. ! vorbisdec ! alsasink } will play an Ogg file + all this, the pipeline + gst-launch filesrc location=file.ogg ! oggdemux name=d + d. ! queue ! theoradec ! ffmpegcolorspace ! xvimagesink + d. ! queue ! vorbisdec ! audioconvert ! audioresample ! alsasink + 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 gst-launch for more information. diff --git a/docs/manual/appendix-porting.xml b/docs/manual/appendix-porting.xml index 77d2c2afbf..fe2c8cb410 100644 --- a/docs/manual/appendix-porting.xml +++ b/docs/manual/appendix-porting.xml @@ -1,12 +1,12 @@ - Porting 0.8 applications to 0.9 + Porting 0.8 applications to 0.10 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. @@ -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 gst_element_get_pad (), gst_pad_get_name () 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). @@ -32,8 +34,8 @@ of errors, end-of-stream and other similar pipeline events. Instead, they should use the GstBus, which has been discussed in . 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 g_idle_add () in the signal handler and do the actual real work @@ -51,14 +53,27 @@ - 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 + gst_element_set_state () 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 gst_element_get_state (). 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 - Filtered caps -> caps-filter. + Filtered caps -> capsfilter element (the pipeline syntax for + gst-launch has not changed though). - libgstgconf-0.9.la does not exist. Use the + libgstgconf-0.10.la does not exist. Use the gconfvideosink and gconfaudiosink elements instead, which will do live-updates and require no library linking. @@ -100,6 +116,15 @@ pad-added and state-changed. + + + gst_init_get_popt_table () has been removed + in favour of the new GOption command line option API that was + added to GLib 2.6. gst_init_get_option_group () + is the new GOption-based equivalent to + gst_init_get_ptop_table (). + + diff --git a/docs/manual/appendix-programs.xml b/docs/manual/appendix-programs.xml index 07b27ee531..7e84a75b9c 100644 --- a/docs/manual/appendix-programs.xml +++ b/docs/manual/appendix-programs.xml @@ -3,15 +3,6 @@ - - <command>gst-register</command> - - gst-register 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 /etc/gstreamer/reg.xml. - - - <command>gst-launch</command> @@ -22,15 +13,15 @@ A simple commandline looks like: -gst-launch filesrc location=hello.mp3 ! mad ! osssink +gst-launch filesrc location=hello.mp3 ! mad ! audioresample ! osssink A more complex pipeline looks like: -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 @@ -49,6 +40,8 @@ main (int argc, char *argv[]) { GstElement *pipeline; GstElement *filesrc; + GstMessage *msg; + GstBus *bus; GError *error = NULL; gst_init (&argc, &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->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; } diff --git a/docs/manual/basics-pads.xml b/docs/manual/basics-pads.xml index fe707b5548..15cea0b94c 100644 --- a/docs/manual/basics-pads.xml +++ b/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); diff --git a/docs/manual/highlevel-components.xml b/docs/manual/highlevel-components.xml index a4088be508..b7e4a5a08a 100644 --- a/docs/manual/highlevel-components.xml +++ b/docs/manual/highlevel-components.xml @@ -168,7 +168,7 @@ main (gint argc, For convenience, it is possible to test playbin on - the commandline, using the command gst-launch-0.9 playbin + the commandline, using the command gst-launch-0.10 playbin uri=file:///path/to/file. diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml index 681f22da0a..1fc7e500cb 100644 --- a/docs/manual/manual.xml +++ b/docs/manual/manual.xml @@ -257,7 +257,7 @@ 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.