From: Tim-Philipp Müller Date: Fri, 5 May 2006 21:44:57 +0000 (+0000) Subject: docs/manual/: Some typo fixes, some additions, some clarifications. X-Git-Tag: RELEASE-0_10_6~40 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=e5bd4d9b7df84af8f49e0401bdeca1e348fcfd75;p=platform%2Fupstream%2Fgstreamer.git docs/manual/: Some typo fixes, some additions, some clarifications. Original commit message from CVS: * docs/manual/basics-bins.xml: * docs/manual/basics-bus.xml: * docs/manual/basics-pads.xml: Some typo fixes, some additions, some clarifications. --- diff --git a/ChangeLog b/ChangeLog index 8a5f4ed..2940d77 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ 2006-05-05 Tim-Philipp Müller + * docs/manual/basics-bins.xml: + * docs/manual/basics-bus.xml: + * docs/manual/basics-pads.xml: + Some typo fixes, some additions, some clarifications. + +2006-05-05 Tim-Philipp Müller + * tools/gst-inspect.c: (main): * tools/gst-launch.c: (main): * tools/gst-run.c: (main): diff --git a/docs/manual/basics-bins.xml b/docs/manual/basics-bins.xml index c164877..c21724b 100644 --- a/docs/manual/basics-bins.xml +++ b/docs/manual/basics-bins.xml @@ -36,17 +36,16 @@ - There is one specialized types of bins available to the + There is one specialized type of bin available to the &GStreamer; programmer: A pipeline: a generic container that allows scheduling of the - containing elements. The toplevel bin has to be a pipeline. - Every application thus needs at least one of these. Applications - can iterate pipelines using gst_bin_iterate - () to make it process data while in the playing state. + containing elements. The toplevel bin has to be a pipeline, + every application thus needs at least one of these. Pipelines will + automatically run themselves in a background thread when started. diff --git a/docs/manual/basics-bus.xml b/docs/manual/basics-bus.xml index b958aa5..3035e17 100644 --- a/docs/manual/basics-bus.xml +++ b/docs/manual/basics-bus.xml @@ -19,12 +19,36 @@ How to use a bus - To use a bus, attach a message handler to the default bus of a pipeline - using gst_bus_add_watch (). This handler will be - called whenever the pipeline emits a message to the bus. In this - handler, check the signal type (see next section) and do something - accordingly. The return value of the handler should be TRUE to remove - the message from the bus. + There are two different ways to use a bus: + + + + Run a GLib/Gtk+ main loop (or iterate the defauly GLib main + context yourself regularly) and attach some kind of watch to the + bus. This way the GLib main loop will check the bus for new + messages and notify you whenever there are messages. + + + Typically you would use gst_bus_add_watch () + or gst_bus_add_signal_watch () in this case. + + + To use a bus, attach a message handler to the bus of a pipeline + using gst_bus_add_watch (). This handler will + be called whenever the pipeline emits a message to the bus. In this + handler, check the signal type (see next section) and do something + accordingly. The return value of the handler should be TRUE to + remove the message from the bus. + + + + + Check for messages on the bus yourself. This can be done using + gst_bus_peek () and/or + gst_bus_poll (). + + + #include <gst/gst.h> @@ -68,14 +92,16 @@ main (gint argc, { GMainLoop *loop; GstElement *pipeline; + GstBus *bus; /* init */ gst_init (&argc, &argv); /* create pipeline, add handler */ pipeline = gst_pipeline_new ("my_pipeline"); - gst_bus_add_watch (gst_pipeline_get_bus (GST_PIPELINE (pipeline)), - my_bus_callback, NULL); + bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); + gst_bus_add_watch (bus, my_bus_callback, NULL); + gst_object_unref (bus); [..] @@ -98,18 +124,23 @@ main (gint argc, should be done in the pipeline context, which is easiest by writing a &GStreamer; plug-in. It is very useful for its primary purpose, though: passing messages from pipeline to application. + The advantage of this approach is that all the threading that + &GStreamer; does internally is hidden from the application and the + application developer does not have to worry about thread issues at + all. - Note that if you're using the default GLib mainloop integration, - you can, instead of attaching a watch, connect to message - signal on the bus. This way you don't have to switch() - on all possible message types; just connect to the interesting - ones in form message::<type>, where <type> - is a specific message type (see the next section for explanation of + Note that if you're using the default GLib mainloop integration, you + can, instead of attaching a watch, connect to the message + signal on the bus. This way you don't have to + switch() + on all possible message types; just connect to the interesting signals + in form of message::<type>, where <type> + is a specific message type (see the next section for an explanation of message types). - The above snippet would be thus written as: + The above snippet could then also be written as: GstBus *bus; @@ -117,8 +148,9 @@ GstBus *bus; [..] bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline); -g_signal_connect(G_OBJECT(bus), "message::error", G_CALLBACK(cb_message_error)); -g_signal_connect(G_OBJECT(bus), "message::eos", G_CALLBACK(cb_message_eos)); +gst_bus_add_signal_watch (bus); +g_signal_connect (bus, "message::error", G_CALLBACK (cb_message_error), NULL); +g_signal_connect (bus, "message::eos", G_CALLBACK (cb_message_eos), NULL); [..] @@ -135,7 +167,7 @@ g_signal_connect(G_OBJECT(bus), "message::eos", G_CALLBACK(cb_message_eos)); Message types &GStreamer; has a few pre-defined message types that can be passed - over the bus. The messages are extendible, however. Plug-ins can + over the bus. The messages are extensible, however. Plug-ins can define additional messages, and applications can decide to either have specific code for those or ignore them. All applications are strongly recommended to at least handle error messages by providing @@ -156,7 +188,7 @@ g_signal_connect(G_OBJECT(bus), "message::eos", G_CALLBACK(cb_message_eos)); by elements if a message should be shown to the user about the state of the pipeline. Error messages are fatal and terminate the data-passing. The error should be repaired to resume pipeline - acvitity. Warnings are not fatal, but imply a problem nevertheless. + activity. Warnings are not fatal, but imply a problem nevertheless. Information messages are for non-problem notifications. All those messages contain a GError with the main error type and message, and optionally a debug string. Both @@ -184,7 +216,8 @@ g_signal_connect(G_OBJECT(bus), "message::eos", G_CALLBACK(cb_message_eos)); stream-information, such as samplerate and bitrate). Applications should cache metadata internally. gst_message_parse_tag () should be used to parse the taglist, which should - be dereferenced after use. + be gst_tag_list_free ()'ed when no longer + needed. @@ -199,16 +232,34 @@ g_signal_connect(G_OBJECT(bus), "message::eos", G_CALLBACK(cb_message_eos)); Buffering: emitted during caching of network-streams. One can manually extract the progress (in percent) from the message by extracting the buffer-percent property from the - structure returned by gst_message_parse_structure + structure returned by gst_message_get_structure (). - Other application-specific messages: any information on those can - be extracted by getting a structure (see above) and reading - properties. In most cases, such messages can conveniently be - ignored. + Element messages: these are special messages that are unique to + certain elements and usually represent additional features. The + element's documentation should mention in detail which + element messages a particular element may send. As an example, + the 'qtdemux' QuickTime demuxer element may send a 'redirect' + element message on certain occasions if the stream contains a + redirect instruction. + + + + + Application-specific messages: any information on those can + be extracted by getting the message structure (see above) and + reading its fields. Usually these messages can safely be ignored. + + + Application messages are primarily meant for internal + use in applications in case the application needs to marshal + information from some thread into the main thread. This is + particularly useful when the application is making use of element + signals (as those signals will be emitted in the context of the + streaming thread). diff --git a/docs/manual/basics-pads.xml b/docs/manual/basics-pads.xml index db8123b..55e397e 100644 --- a/docs/manual/basics-pads.xml +++ b/docs/manual/basics-pads.xml @@ -174,8 +174,9 @@ link_to_multiplexer (GstPad *tolink_pad, GstElement *mux) { GstPad *pad; - gchar *srcname = gst_pad_get_name (tolink_pad), *sinkname; + gchar *srcname, *sinkname; + srcname = gst_pad_get_name (tolink_pad); pad = gst_element_get_compatible_pad (mux, tolink_pad); gst_pad_link (tolinkpad, pad); sinkname = gst_pad_get_name (pad);