From: Wim Taymans Date: Wed, 24 Jul 2002 19:46:42 +0000 (+0000) Subject: Documentation updates X-Git-Tag: BRANCH-RELEASE-0_4_1-ROOT~140 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=4afbf577a21b0ce2bf1e7e78d79cdb0c12214adc;p=platform%2Fupstream%2Fgstreamer.git Documentation updates Original commit message from CVS: Documentation updates --- diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml index f1592df..f691847 100644 --- a/docs/manual/basics-elements.xml +++ b/docs/manual/basics-elements.xml @@ -142,13 +142,86 @@ element = gst_element_factory_make ("mad", "decoder"); - An element can be destroyed with: FIXME talk about refcounting + When you don't need the element anymore, you need to unref it, as shown in the following + example. GstElement *element; ... - gst_element_destroy (element); + gst_element_unref (element); + + GstElement properties + + A GstElement can have several properties which are implemented using standard + GObject properties. The usual GObject methods to query, set and get property values + and GParamSpecs are therefore supported. + + + Every GstElement inherits at least one property of its parent GstObject, the "name" + property. This is the name you provide to gst_element_factory_make() or + gst_element_factory_create(). You can get and set this property using the + gst_object_set_name() and gst_object_get_name() or use the GObject property + mechanism as shown below. + + + GstElement *element; + GValue value = { 0, }; /* initialize the GValue for g_object_get() */ + + element = gst_element_factory_make ("mad", "decoder"); + g_object_set (G_OBJECT (element), "name", "mydecoder", NULL); + ... + + g_value_init (&value, G_TYPE_STRING); + g_object_get_property (G_OBJECT (element), "name", &value); + ... + + + Most plugins provide additional properties to provide more information + about their configuration or to configure the element. + gst-inspect is a useful tool to query the properties + of a perticular element, it will also use property introspection to give + a short explanation about the function of the property and about the + parameter types and ranges it supports. + + + For more information about GObject properties we recommend to read the GObject + manual. + + + + + GstElement signals + + A GstElement also provides various GObject signals that can be used as a flexible + callback mechanism. + + + + + More about GstElementFactory + + We talk some more about the GstElementFactory object. + + + + Getting information about an element using the factory details + + + + + + Finding out what pads an element can contain + + + + + + Different ways of querying the factories + + + + diff --git a/docs/manual/elements.xml b/docs/manual/elements.xml index f1592df..f691847 100644 --- a/docs/manual/elements.xml +++ b/docs/manual/elements.xml @@ -142,13 +142,86 @@ element = gst_element_factory_make ("mad", "decoder"); - An element can be destroyed with: FIXME talk about refcounting + When you don't need the element anymore, you need to unref it, as shown in the following + example. GstElement *element; ... - gst_element_destroy (element); + gst_element_unref (element); + + GstElement properties + + A GstElement can have several properties which are implemented using standard + GObject properties. The usual GObject methods to query, set and get property values + and GParamSpecs are therefore supported. + + + Every GstElement inherits at least one property of its parent GstObject, the "name" + property. This is the name you provide to gst_element_factory_make() or + gst_element_factory_create(). You can get and set this property using the + gst_object_set_name() and gst_object_get_name() or use the GObject property + mechanism as shown below. + + + GstElement *element; + GValue value = { 0, }; /* initialize the GValue for g_object_get() */ + + element = gst_element_factory_make ("mad", "decoder"); + g_object_set (G_OBJECT (element), "name", "mydecoder", NULL); + ... + + g_value_init (&value, G_TYPE_STRING); + g_object_get_property (G_OBJECT (element), "name", &value); + ... + + + Most plugins provide additional properties to provide more information + about their configuration or to configure the element. + gst-inspect is a useful tool to query the properties + of a perticular element, it will also use property introspection to give + a short explanation about the function of the property and about the + parameter types and ranges it supports. + + + For more information about GObject properties we recommend to read the GObject + manual. + + + + + GstElement signals + + A GstElement also provides various GObject signals that can be used as a flexible + callback mechanism. + + + + + More about GstElementFactory + + We talk some more about the GstElementFactory object. + + + + Getting information about an element using the factory details + + + + + + Finding out what pads an element can contain + + + + + + Different ways of querying the factories + + + + diff --git a/docs/manual/goals.xml b/docs/manual/goals.xml index f699fac..5d1fc2b 100644 --- a/docs/manual/goals.xml +++ b/docs/manual/goals.xml @@ -82,14 +82,15 @@ - Using GLib g_mem_chunk where possible to minimize dynamic memory - allocation. + Using GLib g_mem_chunk and fast non-blocking allocation algorithms + where possible to minimize dynamic memory allocation. Extremely light-weight connections between plugins. Data can travel - the pipeline with minimal overhead. + the pipeline with minimal overhead. Data passing between plugins only involves + a pointer dereference in a typical pipeline. @@ -108,7 +109,8 @@ The use of cothreads to minimize the threading overhead. Cothreads are a simple and fast - user-space method for switching between subtasks. + user-space method for switching between subtasks. Cothreads were measured to + consume as little as 600 cpu cycles. @@ -123,7 +125,24 @@ used. + + + All critical data passing is free of locks and mutexes. + + + + + Provide a framework for codec experimentation + + GStreamer also wants to be an easy framework where codec developers + can experiment with different algorithms, speeding up the development + of open and free multimedia codecs like tarking and vorbis. + + + + + diff --git a/docs/manual/init.xml b/docs/manual/init.xml index bae542d..30b90e9 100644 --- a/docs/manual/init.xml +++ b/docs/manual/init.xml @@ -28,16 +28,17 @@ main (int argc, char *argv[]) } - It is also possible to call the gst_init method with two NULL argumants. + It is also possible to call the gst_init method with two NULL arguments. Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO macros to - get the GStreamer version you are building against. + get the GStreamer version you are building against or + use gst_version() to get the version you are linked against. The popt interface - more info here + You can also use a popt table to initialize your own parameters as shown in the next code fragment: int diff --git a/docs/manual/intro-motivation.xml b/docs/manual/intro-motivation.xml index 69ea414..df4635b 100644 --- a/docs/manual/intro-motivation.xml +++ b/docs/manual/intro-motivation.xml @@ -56,7 +56,9 @@ Your typical media player might have a plugin for different media types. Two media players will typically implement their own plugin - mechanism so that the codecs cannot be easily exchanged. + mechanism so that the codecs cannot be easily exchanged. The plugin system + of the typical media player is also very tailored to the specific needs + of the application. The lack of a unified plugin mechanism also seriously hinders the @@ -67,7 +69,8 @@ While GStreamer also uses it own plugin system it offers a very rich framework for the plugin developper and ensures the plugin can be used in a wide range of applications, transparently interacting with other - plugins. + plugins. The Framework that GStreamer provides for the plugins is + flexible enough to host even the most demanding plugins. @@ -83,9 +86,10 @@ the GNOME object embedding using Bonobo. - While the GStreamer core does not use network transparent technologies - at the lowest level, it shouldn't be hard to create a wrapper around the - core components. + The GStreamer cores does not use network transparent technologies at the + lowest level as it only adds overhead for the local case. + That said, it shouldn't be hard to create a wrapper around the + core components. diff --git a/docs/manual/intro-preface.xml b/docs/manual/intro-preface.xml index 687b5ce..9deae18 100644 --- a/docs/manual/intro-preface.xml +++ b/docs/manual/intro-preface.xml @@ -27,7 +27,8 @@ very wide variety of formats including mp3, Ogg Vorbis, Mpeg1, Mpeg2, Avi, Quicktime, mod and so on. GStreamer, however, is much more than just another media player. Its - main advantages are that the pluggable components also make it possible + main advantages are that the pluggable components can be mixed and matched into + abitrary pipelines so that it's possible to write a full fledged video or audio editing application. @@ -48,6 +49,7 @@ This book is about GStreamer from a developer's point of view; it describes how to write a GStreamer application using the GStreamer libraries and tools. + For an explanation about writing plugins, we suggest the Plugin Writers Guide. diff --git a/docs/manual/intro.xml b/docs/manual/intro.xml index 687b5ce..9deae18 100644 --- a/docs/manual/intro.xml +++ b/docs/manual/intro.xml @@ -27,7 +27,8 @@ very wide variety of formats including mp3, Ogg Vorbis, Mpeg1, Mpeg2, Avi, Quicktime, mod and so on. GStreamer, however, is much more than just another media player. Its - main advantages are that the pluggable components also make it possible + main advantages are that the pluggable components can be mixed and matched into + abitrary pipelines so that it's possible to write a full fledged video or audio editing application. @@ -48,6 +49,7 @@ This book is about GStreamer from a developer's point of view; it describes how to write a GStreamer application using the GStreamer libraries and tools. + For an explanation about writing plugins, we suggest the Plugin Writers Guide. diff --git a/docs/manual/motivation.xml b/docs/manual/motivation.xml index 69ea414..df4635b 100644 --- a/docs/manual/motivation.xml +++ b/docs/manual/motivation.xml @@ -56,7 +56,9 @@ Your typical media player might have a plugin for different media types. Two media players will typically implement their own plugin - mechanism so that the codecs cannot be easily exchanged. + mechanism so that the codecs cannot be easily exchanged. The plugin system + of the typical media player is also very tailored to the specific needs + of the application. The lack of a unified plugin mechanism also seriously hinders the @@ -67,7 +69,8 @@ While GStreamer also uses it own plugin system it offers a very rich framework for the plugin developper and ensures the plugin can be used in a wide range of applications, transparently interacting with other - plugins. + plugins. The Framework that GStreamer provides for the plugins is + flexible enough to host even the most demanding plugins. @@ -83,9 +86,10 @@ the GNOME object embedding using Bonobo. - While the GStreamer core does not use network transparent technologies - at the lowest level, it shouldn't be hard to create a wrapper around the - core components. + The GStreamer cores does not use network transparent technologies at the + lowest level as it only adds overhead for the local case. + That said, it shouldn't be hard to create a wrapper around the + core components.