From 3b7659725f091f256f745ac50daa132bd9a8e9ee Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Thu, 9 Oct 2003 12:42:49 +0000 Subject: [PATCH] typos and style fixes Original commit message from CVS: typos and style fixes --- docs/manual/advanced-autoplugging.xml | 6 +- docs/manual/advanced-schedulers.xml | 2 +- docs/manual/advanced-threads.xml | 2 +- docs/manual/appendix-gnome.xml | 16 +-- docs/manual/appendix-integration.xml | 16 +-- docs/manual/appendix-programs.xml | 6 - docs/manual/appendix-quotes.xml | 2 +- docs/manual/autoplugging.xml | 14 +- docs/manual/basics-bins.xml | 31 ++--- docs/manual/basics-data.xml | 13 +- docs/manual/basics-elements.xml | 33 +++-- docs/manual/basics-helloworld.xml | 4 +- docs/manual/basics-pads.xml | 182 ++++++++++++++++++-------- docs/manual/bins.xml | 31 ++--- docs/manual/buffers.xml | 13 +- docs/manual/cothreads.xml | 2 +- docs/manual/dynamic.xml | 4 - docs/manual/elements.xml | 33 +++-- docs/manual/factories.xml | 6 +- docs/manual/filter-element-multi.fig | 2 +- docs/manual/filter-element.fig | 2 +- docs/manual/gnome.xml | 16 +-- docs/manual/goals.xml | 48 +++++-- docs/manual/helloworld.xml | 4 +- docs/manual/highlevel-xml.xml | 22 +--- docs/manual/init.xml | 7 +- docs/manual/intro-motivation.xml | 14 +- docs/manual/intro-preface.xml | 13 +- docs/manual/intro.xml | 13 +- docs/manual/linked-elements.fig | 6 +- docs/manual/links.xml | 4 +- docs/manual/manual.xml | 4 +- docs/manual/motivation.xml | 14 +- docs/manual/pads.xml | 182 ++++++++++++++++++-------- docs/manual/programs.xml | 6 - docs/manual/queues.xml | 10 +- docs/manual/quotes.xml | 2 +- docs/manual/schedulers.xml | 2 +- docs/manual/sink-element.fig | 2 +- docs/manual/src-element.fig | 2 +- docs/manual/states.xml | 24 ++-- docs/manual/thread.fig | 60 ++++----- docs/manual/threads.xml | 2 +- docs/manual/typedetection.xml | 13 +- docs/manual/xml.xml | 22 +--- 45 files changed, 533 insertions(+), 379 deletions(-) diff --git a/docs/manual/advanced-autoplugging.xml b/docs/manual/advanced-autoplugging.xml index 19dae27ed1..91a7ffbbb8 100644 --- a/docs/manual/advanced-autoplugging.xml +++ b/docs/manual/advanced-autoplugging.xml @@ -82,8 +82,8 @@ - In our helloworld example the elements we constructed would have the - following MIME types associated with their source and sink pads: + shows the MIME types associated with + each pad from the "hello world" example.
The Hello world pipeline with MIME types @@ -103,7 +103,7 @@ The typing of the source and sink pads also makes it possible to 'autoplug' a pipeline. We will have the ability to say: "construct - me a pipeline that does an audio/mpeg to audio/raw conversion". + a pipeline that does an audio/mpeg to audio/raw conversion". diff --git a/docs/manual/advanced-schedulers.xml b/docs/manual/advanced-schedulers.xml index c676d92ce0..b86e72f20b 100644 --- a/docs/manual/advanced-schedulers.xml +++ b/docs/manual/advanced-schedulers.xml @@ -28,7 +28,7 @@ - The scheduler is a plugable component; this means that alternative + The scheduler is a pluggable component; this means that alternative schedulers can be written and plugged into GStreamer. The default scheduler uses cothreads to schedule the plugins in a pipeline. Cothreads are fast and lightweight user-space threads. diff --git a/docs/manual/advanced-threads.xml b/docs/manual/advanced-threads.xml index 17d3e5b976..f11cd2547b 100644 --- a/docs/manual/advanced-threads.xml +++ b/docs/manual/advanced-threads.xml @@ -63,7 +63,7 @@ an audio pipeline. - A thread can be visualised as below + shows how a thread can be visualised.
A thread diff --git a/docs/manual/appendix-gnome.xml b/docs/manual/appendix-gnome.xml index ad7ffd665f..fc7c5b9bd9 100644 --- a/docs/manual/appendix-gnome.xml +++ b/docs/manual/appendix-gnome.xml @@ -1,24 +1,24 @@ - Gnome integration + GNOME integration - GStreamer is fairly easy to integrate with Gnome applications. + GStreamer is fairly easy to integrate with GNOME applications. GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other - Gnome applications. - There are however some basic issues you need to address in your Gnome + GNOME applications. + There are however some basic issues you need to address in your GNOME applications. Command line options - Gnome applications call gnome_program_init () to parse command-line + GNOME applications call gnome_program_init () to parse command-line options and initialize the necessary gnome modules. GStreamer applications normally call gst_init (&argc, &argv) to do the same for GStreamer. Each of these two swallows the program options passed to the program, - so we need a different way to allow both Gnome and GStreamer to parse + so we need a different way to allow both GNOME and GStreamer to parse the command-line options. This is shown in the following example. @@ -34,7 +34,7 @@ main (int argc, char **argv) { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL }, POPT_TABLEEND }; - GnomeProgram *program; + GNOMEProgram *program; poptContext context; const gchar **argvn; @@ -63,7 +63,7 @@ main (int argc, char **argv) If you try out this program, you will see that when called with - --help, it will print out both GStreamer and Gnome help arguments. + --help, it will print out both GStreamer and GNOME help arguments. All of the arguments that didn't belong to either end up in the argvn pointer array. diff --git a/docs/manual/appendix-integration.xml b/docs/manual/appendix-integration.xml index ad7ffd665f..fc7c5b9bd9 100644 --- a/docs/manual/appendix-integration.xml +++ b/docs/manual/appendix-integration.xml @@ -1,24 +1,24 @@ - Gnome integration + GNOME integration - GStreamer is fairly easy to integrate with Gnome applications. + GStreamer is fairly easy to integrate with GNOME applications. GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other - Gnome applications. - There are however some basic issues you need to address in your Gnome + GNOME applications. + There are however some basic issues you need to address in your GNOME applications. Command line options - Gnome applications call gnome_program_init () to parse command-line + GNOME applications call gnome_program_init () to parse command-line options and initialize the necessary gnome modules. GStreamer applications normally call gst_init (&argc, &argv) to do the same for GStreamer. Each of these two swallows the program options passed to the program, - so we need a different way to allow both Gnome and GStreamer to parse + so we need a different way to allow both GNOME and GStreamer to parse the command-line options. This is shown in the following example. @@ -34,7 +34,7 @@ main (int argc, char **argv) { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL }, POPT_TABLEEND }; - GnomeProgram *program; + GNOMEProgram *program; poptContext context; const gchar **argvn; @@ -63,7 +63,7 @@ main (int argc, char **argv) If you try out this program, you will see that when called with - --help, it will print out both GStreamer and Gnome help arguments. + --help, it will print out both GStreamer and GNOME help arguments. All of the arguments that didn't belong to either end up in the argvn pointer array. diff --git a/docs/manual/appendix-programs.xml b/docs/manual/appendix-programs.xml index 897529a0a9..0c22496593 100644 --- a/docs/manual/appendix-programs.xml +++ b/docs/manual/appendix-programs.xml @@ -247,11 +247,5 @@ Element Signals: gst-inspect gstelements - - <command>gst-play</command> - - A sample media player. - - diff --git a/docs/manual/appendix-quotes.xml b/docs/manual/appendix-quotes.xml index da45bf10be..cc88ad101d 100644 --- a/docs/manual/appendix-quotes.xml +++ b/docs/manual/appendix-quotes.xml @@ -5,7 +5,7 @@ GStreamer is a lively project, with developers from around the globe very actively contributing. We often hang out on the #gstreamer IRC channel on - irc.openprojects.net: the following are a selection of amusing + irc.freenode.org: the following are a selection of amusing No guarantee of sense of humour compatibility is given. quotes from our conversations. diff --git a/docs/manual/autoplugging.xml b/docs/manual/autoplugging.xml index 80cc8ead57..00e17d71c2 100644 --- a/docs/manual/autoplugging.xml +++ b/docs/manual/autoplugging.xml @@ -95,11 +95,11 @@ Using the <classname>GstAutoplugCache</classname> element The GstAutoplugCache element is used to cache the - media stream when performing typedetection. As we have have seen in the - previous chapter (typedetection), the type typefind function consumes a - buffer to determine the media type of it. After we have set up the pipeline + media stream when performing typedetection. As we have seen in + , the typefind function consumes a + buffer to determine its media type. After we have set up the pipeline to play the media stream we should be able to 'replay' the previous buffer(s). - This is where the autoplugcache is used for. + This is what the autoplugcache is used for. The basic usage pattern for the autoplugcache in combination with the typefind @@ -151,9 +151,9 @@ Another approach to autoplugging The autoplug API is interesting, but often impractical. It is static; - it cannot deal with dynamic pipelines (insert ref here). What you - often want is just an element to stick into a pipeline that will DWIM - (Do What I Mean)(ref). Enter the spider. + it cannot deal with dynamic pipelines. An element that will + automatically figure out and decode the type is more useful. + Enter the spider. The spider element diff --git a/docs/manual/basics-bins.xml b/docs/manual/basics-bins.xml index d57ed4451b..54d018a4ba 100644 --- a/docs/manual/basics-bins.xml +++ b/docs/manual/basics-bins.xml @@ -1,11 +1,11 @@ Bins - A Bin is a container element. You can add elements to a bin. Since a bin is - an GstElement itself, it can also be added to another bin. + A bin is a container element. You can add elements to a bin. Since a bin is + an element itself, it can also be added to another bin. - Bins allow you to combine linked elements into one logical element. You do + Bins allow you to combine a group of linked elements into one logical element. You do not deal with the individual elements anymore but with just one element, the bin. We will see that this is extremely powerful when you are going to construct complex pipelines since it allows you to break up the pipeline in smaller chunks. @@ -17,7 +17,7 @@
- Visualisation of a <classname>GstBin</classname> element with some elements in it + Visualisation of a bin with some elements in it @@ -26,20 +26,21 @@
- There are two standard bins available to the GStreamer programmer: + There are two specialized bins available to the GStreamer programmer: - A pipeline (GstPipeline). Which is a generic container you will - use most of the time. The toplevel bin has to be a pipeline. + 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. - A thread (GstThread). The plan for the - GstThread will be run in a separate thread. You will have to use - this bin if you have to carefully synchronize audio and video, for example. You will learn + a thread: a bin that will be run in a separate execution thread. + You will have to use this bin if you have to carefully + synchronize audio and video, or for buffering. You will learn more about threads in . @@ -84,9 +85,8 @@ ... - Bins and threads can be added to other bins too. This allows you to create nested bins. Note - that it doesn't make very much sense to add a GstPipeline to anything, - as it's a toplevel bin that needs to be explicitly iterated. + Bins and threads can be added to other bins too. This allows you to create nested bins. Pipelines shouldn't be added to any other element, though. + They are toplevel bins and they are directly linked to the scheduler. To get an element from the bin you can use: @@ -180,7 +180,7 @@ Ghost pads - You can see from figure how a bin has no pads of its own. + You can see from how a bin has no pads of its own. This is where "ghost pads" come into play.
@@ -207,7 +207,8 @@
- Above is a representation of a ghost pad. The sink pad of element one is now also a pad + + is a representation of a ghost pad. The sink pad of element one is now also a pad of the bin. diff --git a/docs/manual/basics-data.xml b/docs/manual/basics-data.xml index 23b831abab..36bfd8057d 100644 --- a/docs/manual/basics-data.xml +++ b/docs/manual/basics-data.xml @@ -8,24 +8,29 @@ to deal with buffers yourself; the elements will do that for you. - The most important information in the buffer is: + A buffer consists of: - A pointer to a piece of memory. + a pointer to a piece of memory. - The size of the memory. + the size of the memory. + + + + + a timestamp for the buffer. A refcount that indicates how many elements are using this buffer. This refcount will be used to destroy the buffer when no - element is having a reference to it. + element has a reference to it. diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml index 4364e1770d..9fc8a90eaf 100644 --- a/docs/manual/basics-elements.xml +++ b/docs/manual/basics-elements.xml @@ -1,25 +1,29 @@ - GstElement + Elements The most important object in GStreamer for the application programmer is the GstElement object. - What is a GstElement + What is an element ? - GstElement is the basic building block for the - media pipeline. All the different components you are going to use are + An element is the basic building block for the media pipeline. + All the different high-level components you are going to use are derived from GstElement. This means that a lot of functions you are going to use operate on objects of this class. Elements, from the perspective of GStreamer, are viewed as "black boxes" with a number of different aspects. One of these aspects is the presence - of "pads", or link points. This terminology arises from soldering; + of "pads" (see ), or link points. This terminology arises from soldering; pads are where wires can be attached. + + + Types of elements + Source elements @@ -27,7 +31,8 @@ reading from disk or from a sound card. - Below you see how we will visualize the element. + shows how we will visualise + a source element. We always draw a source pad to the right of the element.
@@ -48,7 +53,7 @@ Filters and codecs - Filter elements both have input and output pads. They operate on + Filter elements have both input and output pads. They operate on data they receive in their sink pads and produce data on their source pads. For example, MPEG decoders and volume filters would fall into this category. @@ -67,7 +72,8 @@
- The above figure shows the visualisation of a filter element. + shows how we will visualise + a filter element. This element has one sink (input) pad and one source (output) pad. Sink pads are drawn on the left of the element. @@ -82,9 +88,9 @@
- The above figure shows the visualisation of a filter element with + shows the visualisation of a filter element with more than one output pad. An example of such a filter is the AVI - splitter (demultiplexer). This element will parse the input data and + demultiplexer. This element will parse the input data and extract the audio and video data. Most of these filters dynamically send out a signal when a new pad is created so that the application programmer can link an arbitrary element to the newly created pad. @@ -94,9 +100,10 @@ Sink elements - Sink elements are terminal points in a media pipeline. They accept + Sink elements are end points in a media pipeline. They accept data but do not produce anything. Disk writing, soundcard playback, and video output would all be implemented by sink elements. + shows a sink element.
Visualisation of a sink element @@ -207,7 +214,9 @@ For more information about GObject properties we recommend you read the GObject manual. + type="http">GObject manual and an introduction to + The Glib Object system. diff --git a/docs/manual/basics-helloworld.xml b/docs/manual/basics-helloworld.xml index f949115b08..780caf5146 100644 --- a/docs/manual/basics-helloworld.xml +++ b/docs/manual/basics-helloworld.xml @@ -178,7 +178,7 @@ main (int argc, char *argv[]) pipeline as follows:
- The Hello world pipeline + The "hello world" pipeline @@ -188,7 +188,7 @@ main (int argc, char *argv[])
- Everything is now set up to start the streaming. We use the following + Everything is now set up to start streaming. We use the following statements to change the state of the pipeline: diff --git a/docs/manual/basics-pads.xml b/docs/manual/basics-pads.xml index 43270bd177..391fe1b8de 100644 --- a/docs/manual/basics-pads.xml +++ b/docs/manual/basics-pads.xml @@ -1,12 +1,27 @@ - GstPad + Pads - As we have seen in the previous chapter (GstElement), the pads are the element's - links with the outside world. + As we have seen in , the pads are the element's + interface to the outside world. The specific type of media that the element can handle will be exposed by the pads. - The description of this media type is done with capabilities (GstCaps) + The description of this media type is done with capabilities(see + ) + + + + Pads are either source or sink pads. The terminology is defined from the + view of the element itself: elements accept data on their sink pads, and + send data out on their source pads. Sink pads are drawn on the left, + while source pads are drawn on the right of an element. In general, + data flows from left to right in the graph. + + In reality, there is no objection to data flowing from a + source pad to the sink pad of an element upstream. Data will, however, + always flow from a source pad of one element to the sink pad of + another. + @@ -58,19 +73,27 @@ GstElement. + + + + Types of pads + Dynamic pads - Some elements might not have their pads when they are created. This - can happen, for example, with an MPEG2 system demultiplexer. The + Some elements might not have all of their pads when the element is + created. This + can happen, for example, with an MPEG system demultiplexer. The demultiplexer will create its pads at runtime when it detects the - different elementary streams in the MPEG2 system stream. + different elementary streams in the MPEG system stream. Running gst-inspect mpegdemux will show that the element has only one pad: a sink pad called 'sink'. The other pads are - "dormant" as you can see in the padtemplates from the 'Exists: Sometimes' - property. Depending on the type of MPEG2 file you play, the pads are created. We + "dormant". You can see this in the pad template because there is + an 'Exists: Sometimes' + property. Depending on the type of MPEG file you play, the pads will + be created. We will see that this is very important when you are going to create dynamic pipelines later on in this manual. @@ -116,7 +139,7 @@ main(int argc, char *argv[]) - You need to set the pipeline to READY or NULL if you want to change it. + A pipeline cannot be changed in the PLAYING state. @@ -172,12 +195,15 @@ main(int argc, char *argv[]) ... + - - Capabilities of a GstPad + + + Capabilities of a pad Since the pads play a very important role in how the element is viewed by the - outside world, a mechanism is implemented to describe the pad by using capabilities. + outside world, a mechanism is implemented to describe the data that can + flow through the pad by using capabilities. We will briefly describe what capabilities are, enough for you to get a basic understanding @@ -186,14 +212,29 @@ main(int argc, char *argv[]) - What is a capability + What are capabilities ? - A capability is attached to a pad in order to describe what type of media the pad - can handle. + Capabilities are attached to a pad in order to describe + what type of media the pad can handle. - A capability is named and consists of a MIME type and a set of properties. Its data - structure is: + Capabilities is shorthand for "capability chain". A capability chain + is a chain of one capability or more. + + + The basic entity is a capability, and is defined by a name, a MIME + type and a set of properties. A capability can be chained to + another capability, which is why we commonly refer to a chain of + capability entities as "capabilities". + + It is important to understand that the term "capabilities" refers + to a chain of one capability or more. This will be clearer when + you see the structure definition of a GstCaps + element. + + + + Its structure is: struct _GstCaps { @@ -245,55 +286,80 @@ Pads: - What are properties + What are properties ? Properties are used to describe extra information for - capabilities. The properties basically consist of a key (a string) and - a value. There are different possibile value types that can be used: + capabilities. A property consists of a key (a string) and + a value. There are different possible value types that can be used: - An integer value: the property has this exact value. + basic types: + + + + an integer value: the property has this exact value. + + + + + a boolean value: the property is either TRUE or FALSE. + + + + + a fourcc value: this is a value that is commonly used to + describe an encoding for video, + as used for example by the AVI specification. + + fourcc values consist of four bytes. + The FOURCC + Definition List is the most complete resource + on the allowed fourcc values. + + + + + + a float value: the property has this exact floating point value. + + + + + a string value. + + + + + + + + range types: + + + + + an integer range value: the property denotes a range of + possible integer. For example, the wavparse element has + a source pad where the "rate" property can go from 8000 to + 48000. + + + + + a float range value: the property denotes a range of possible + floating point values. + + + - An integer range value. The property denotes a range of possible - values. In the case of the mad element, the source pad has a - property rate that can go from 11025 to 48000. - - - - - A boolean value. - - - - - a fourcc value: this is a value that is commonly used to describe an encoding for video, - as used by the AVI specification. - - - - - A list value: the property can take any value from a list. - - - - - A float value: the property has this exact floating point value. - - - - - A float range value: denotes a range of possible floating point values. - - - - - A string value. + a list value: the property can take any value from a list of + basic value types or range types. @@ -315,6 +381,8 @@ Pads: Compatibility detection: when two pads are linked, GStreamer can verify if the two pads are talking about the same media types. + The process of linking two pads and checking if they are compatible + is called "caps negotiation". @@ -407,7 +475,7 @@ GstProps* gst_props_new (const gchar *firstname, ...); - GST_PROPS_INT_RANGE(a,b): An integer ragne from a to b + GST_PROPS_INT_RANGE(a,b): An integer range from a to b diff --git a/docs/manual/bins.xml b/docs/manual/bins.xml index d57ed4451b..54d018a4ba 100644 --- a/docs/manual/bins.xml +++ b/docs/manual/bins.xml @@ -1,11 +1,11 @@ Bins - A Bin is a container element. You can add elements to a bin. Since a bin is - an GstElement itself, it can also be added to another bin. + A bin is a container element. You can add elements to a bin. Since a bin is + an element itself, it can also be added to another bin. - Bins allow you to combine linked elements into one logical element. You do + Bins allow you to combine a group of linked elements into one logical element. You do not deal with the individual elements anymore but with just one element, the bin. We will see that this is extremely powerful when you are going to construct complex pipelines since it allows you to break up the pipeline in smaller chunks. @@ -17,7 +17,7 @@
- Visualisation of a <classname>GstBin</classname> element with some elements in it + Visualisation of a bin with some elements in it @@ -26,20 +26,21 @@
- There are two standard bins available to the GStreamer programmer: + There are two specialized bins available to the GStreamer programmer: - A pipeline (GstPipeline). Which is a generic container you will - use most of the time. The toplevel bin has to be a pipeline. + 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. - A thread (GstThread). The plan for the - GstThread will be run in a separate thread. You will have to use - this bin if you have to carefully synchronize audio and video, for example. You will learn + a thread: a bin that will be run in a separate execution thread. + You will have to use this bin if you have to carefully + synchronize audio and video, or for buffering. You will learn more about threads in . @@ -84,9 +85,8 @@ ... - Bins and threads can be added to other bins too. This allows you to create nested bins. Note - that it doesn't make very much sense to add a GstPipeline to anything, - as it's a toplevel bin that needs to be explicitly iterated. + Bins and threads can be added to other bins too. This allows you to create nested bins. Pipelines shouldn't be added to any other element, though. + They are toplevel bins and they are directly linked to the scheduler. To get an element from the bin you can use: @@ -180,7 +180,7 @@ Ghost pads - You can see from figure how a bin has no pads of its own. + You can see from how a bin has no pads of its own. This is where "ghost pads" come into play.
@@ -207,7 +207,8 @@
- Above is a representation of a ghost pad. The sink pad of element one is now also a pad + + is a representation of a ghost pad. The sink pad of element one is now also a pad of the bin. diff --git a/docs/manual/buffers.xml b/docs/manual/buffers.xml index 23b831abab..36bfd8057d 100644 --- a/docs/manual/buffers.xml +++ b/docs/manual/buffers.xml @@ -8,24 +8,29 @@ to deal with buffers yourself; the elements will do that for you. - The most important information in the buffer is: + A buffer consists of: - A pointer to a piece of memory. + a pointer to a piece of memory. - The size of the memory. + the size of the memory. + + + + + a timestamp for the buffer. A refcount that indicates how many elements are using this buffer. This refcount will be used to destroy the buffer when no - element is having a reference to it. + element has a reference to it. diff --git a/docs/manual/cothreads.xml b/docs/manual/cothreads.xml index 3589a80432..18b55357f5 100644 --- a/docs/manual/cothreads.xml +++ b/docs/manual/cothreads.xml @@ -97,7 +97,7 @@ chain_function (GstPad *pad, GstBuffer *buffer) - When the request for a buffer cannot immediatly satisfied, the control + When the request for a buffer cannot be immediately satisfied, the control will be given to the source element of the loop-based element until it performs a push on its source pad. At that time the control is handed back to the loop-based element, etc... The execution trace can get diff --git a/docs/manual/dynamic.xml b/docs/manual/dynamic.xml index 86b8fc264c..3cc834fd37 100644 --- a/docs/manual/dynamic.xml +++ b/docs/manual/dynamic.xml @@ -188,8 +188,4 @@ main (int argc, char *argv[]) There are other possibilities to check the type of the pad, for example by using the MIME type and the properties of the pad. - - Note that the pipeline has to be in the PAUSED state before changes - can be made to its structure. - diff --git a/docs/manual/elements.xml b/docs/manual/elements.xml index 4364e1770d..9fc8a90eaf 100644 --- a/docs/manual/elements.xml +++ b/docs/manual/elements.xml @@ -1,25 +1,29 @@ - GstElement + Elements The most important object in GStreamer for the application programmer is the GstElement object. - What is a GstElement + What is an element ? - GstElement is the basic building block for the - media pipeline. All the different components you are going to use are + An element is the basic building block for the media pipeline. + All the different high-level components you are going to use are derived from GstElement. This means that a lot of functions you are going to use operate on objects of this class. Elements, from the perspective of GStreamer, are viewed as "black boxes" with a number of different aspects. One of these aspects is the presence - of "pads", or link points. This terminology arises from soldering; + of "pads" (see ), or link points. This terminology arises from soldering; pads are where wires can be attached. + + + Types of elements + Source elements @@ -27,7 +31,8 @@ reading from disk or from a sound card. - Below you see how we will visualize the element. + shows how we will visualise + a source element. We always draw a source pad to the right of the element.
@@ -48,7 +53,7 @@ Filters and codecs - Filter elements both have input and output pads. They operate on + Filter elements have both input and output pads. They operate on data they receive in their sink pads and produce data on their source pads. For example, MPEG decoders and volume filters would fall into this category. @@ -67,7 +72,8 @@
- The above figure shows the visualisation of a filter element. + shows how we will visualise + a filter element. This element has one sink (input) pad and one source (output) pad. Sink pads are drawn on the left of the element. @@ -82,9 +88,9 @@
- The above figure shows the visualisation of a filter element with + shows the visualisation of a filter element with more than one output pad. An example of such a filter is the AVI - splitter (demultiplexer). This element will parse the input data and + demultiplexer. This element will parse the input data and extract the audio and video data. Most of these filters dynamically send out a signal when a new pad is created so that the application programmer can link an arbitrary element to the newly created pad. @@ -94,9 +100,10 @@ Sink elements - Sink elements are terminal points in a media pipeline. They accept + Sink elements are end points in a media pipeline. They accept data but do not produce anything. Disk writing, soundcard playback, and video output would all be implemented by sink elements. + shows a sink element.
Visualisation of a sink element @@ -207,7 +214,9 @@ For more information about GObject properties we recommend you read the GObject manual. + type="http">GObject manual and an introduction to + The Glib Object system. diff --git a/docs/manual/factories.xml b/docs/manual/factories.xml index 19dae27ed1..91a7ffbbb8 100644 --- a/docs/manual/factories.xml +++ b/docs/manual/factories.xml @@ -82,8 +82,8 @@ - In our helloworld example the elements we constructed would have the - following MIME types associated with their source and sink pads: + shows the MIME types associated with + each pad from the "hello world" example.
The Hello world pipeline with MIME types @@ -103,7 +103,7 @@ The typing of the source and sink pads also makes it possible to 'autoplug' a pipeline. We will have the ability to say: "construct - me a pipeline that does an audio/mpeg to audio/raw conversion". + a pipeline that does an audio/mpeg to audio/raw conversion". diff --git a/docs/manual/filter-element-multi.fig b/docs/manual/filter-element-multi.fig index 9cd2a3e624..a27f243716 100644 --- a/docs/manual/filter-element-multi.fig +++ b/docs/manual/filter-element-multi.fig @@ -15,7 +15,7 @@ Single 6825 3225 7575 3225 7575 3750 6825 3750 6825 3225 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 6825 3825 7575 3825 7575 4350 6825 4350 6825 3825 -4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 demuxer\001 4 0 0 50 0 16 12 0.0000 4 135 330 5850 3975 sink\001 4 0 0 50 0 16 12 0.0000 4 135 465 6975 3600 video\001 4 0 0 50 0 16 12 0.0000 4 135 465 6975 4200 audio\001 diff --git a/docs/manual/filter-element.fig b/docs/manual/filter-element.fig index 335a54c3b6..e074faf49c 100644 --- a/docs/manual/filter-element.fig +++ b/docs/manual/filter-element.fig @@ -14,5 +14,5 @@ Single 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 5625 3600 6375 3600 6375 4125 5625 4125 5625 3600 4 0 0 50 0 16 12 0.0000 4 105 255 7050 3975 src\001 -4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 filter\001 4 0 0 50 0 16 12 0.0000 4 135 330 5850 3975 sink\001 diff --git a/docs/manual/gnome.xml b/docs/manual/gnome.xml index ad7ffd665f..fc7c5b9bd9 100644 --- a/docs/manual/gnome.xml +++ b/docs/manual/gnome.xml @@ -1,24 +1,24 @@ - Gnome integration + GNOME integration - GStreamer is fairly easy to integrate with Gnome applications. + GStreamer is fairly easy to integrate with GNOME applications. GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other - Gnome applications. - There are however some basic issues you need to address in your Gnome + GNOME applications. + There are however some basic issues you need to address in your GNOME applications. Command line options - Gnome applications call gnome_program_init () to parse command-line + GNOME applications call gnome_program_init () to parse command-line options and initialize the necessary gnome modules. GStreamer applications normally call gst_init (&argc, &argv) to do the same for GStreamer. Each of these two swallows the program options passed to the program, - so we need a different way to allow both Gnome and GStreamer to parse + so we need a different way to allow both GNOME and GStreamer to parse the command-line options. This is shown in the following example. @@ -34,7 +34,7 @@ main (int argc, char **argv) { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL }, POPT_TABLEEND }; - GnomeProgram *program; + GNOMEProgram *program; poptContext context; const gchar **argvn; @@ -63,7 +63,7 @@ main (int argc, char **argv) If you try out this program, you will see that when called with - --help, it will print out both GStreamer and Gnome help arguments. + --help, it will print out both GStreamer and GNOME help arguments. All of the arguments that didn't belong to either end up in the argvn pointer array. diff --git a/docs/manual/goals.xml b/docs/manual/goals.xml index 859c9d53b4..e2ee9a2401 100644 --- a/docs/manual/goals.xml +++ b/docs/manual/goals.xml @@ -38,8 +38,8 @@ Object oriented - Adhere to the GLib 2.0 object model. A programmer familiar with GLib 2.0 or older versions - of Gtk+ will be comfortable with GStreamer. + GStreamer adheres to the GLib 2.0 object model. A programmer familiar with GLib 2.0 or older versions + of GTK+ will be comfortable with GStreamer. GStreamer uses the mechanism of signals and object properties. @@ -48,6 +48,11 @@ All objects can be queried at runtime for their various properties and capabilities. + + GStreamer intends to be similar in programming methodology to GTK+. + This applies to the object model, ownership of objects, reference + counting, ... + @@ -69,7 +74,7 @@ have any header files installed for the plugins. - Special care has been taken to make plugins completely self contained. + Special care has been taken to make plugins completely selfcontained. All relevant aspects of plugins can be queried at run-time. @@ -82,57 +87,71 @@ - Using GLib g_mem_chunk and fast non-blocking allocation algorithms + using GLib's g_mem_chunk and fast non-blocking allocation algorithms where possible to minimize dynamic memory allocation. - Extremely light-weight links between plugins. Data can travel + extremely light-weight links between plugins. Data can travel the pipeline with minimal overhead. Data passing between plugins only involves a pointer dereference in a typical pipeline. - Providing a mechanism to directly work on the target memory. A plugin can for example + providing a mechanism to directly work on the target memory. A plugin can for example directly write to the X server's shared memory space. Buffers can also point to arbitrary memory, such as a sound card's internal hardware buffer. - Refcounting and copy on write minimize usage of memcpy(3). + refcounting and copy on write minimize usage of memcpy. Sub-buffers efficiently split buffers into manageable pieces. - The use of cothreads to minimize the threading overhead. Cothreads are a simple and fast + the use of cothreads to minimize the threading overhead. Cothreads are a simple and fast user-space method for switching between subtasks. Cothreads were measured to consume as little as 600 cpu cycles. - Allowing hardware acceleration by the use of specialized plugins. + allowing hardware acceleration by using specialized plugins. - Using a plugin registry with the specifications of the plugins so + using a plugin registry with the specifications of the plugins so that the plugin loading can be delayed until the plugin is actually used. - All critical data passing is free of locks and mutexes. + all critical data passing is free of locks and mutexes. + + Clean core/plugins separation + + The core of GStreamer is essentially media-agnostic. It only knows + about bytes and blocks, and only contains basic elements. + The core of GStreamer is functional enough to even implement low-level + system tools, like cp. + + + All of the media handling functionality is provided by plugins external + to the core. These tell the core how to handle specific types of media. + + + Provide a framework for codec experimentation @@ -142,6 +161,13 @@ url="http://www.xiph.org/ogg/index.html" type="http">tarkin and vorbis. + + 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 tarkin and + vorbis. + diff --git a/docs/manual/helloworld.xml b/docs/manual/helloworld.xml index f949115b08..780caf5146 100644 --- a/docs/manual/helloworld.xml +++ b/docs/manual/helloworld.xml @@ -178,7 +178,7 @@ main (int argc, char *argv[]) pipeline as follows:
- The Hello world pipeline + The "hello world" pipeline @@ -188,7 +188,7 @@ main (int argc, char *argv[])
- Everything is now set up to start the streaming. We use the following + Everything is now set up to start streaming. We use the following statements to change the state of the pipeline: diff --git a/docs/manual/highlevel-xml.xml b/docs/manual/highlevel-xml.xml index bcf9312873..7f72802dc7 100644 --- a/docs/manual/highlevel-xml.xml +++ b/docs/manual/highlevel-xml.xml @@ -70,27 +70,15 @@ main (int argc, char *argv[]) g_assert (decode != NULL); /* add objects to the main bin */ - gst_bin_add (GST_BIN (bin), filesrc); - gst_bin_add (GST_BIN (bin), queue); + gst_bin_add_many (GST_BIN (bin), filesrc, queue, NULL); - gst_bin_add (GST_BIN (thread), decode); - gst_bin_add (GST_BIN (thread), queue2); + gst_bin_add_many (GST_BIN (thread), decode, queue2, NULL); gst_bin_add (GST_BIN (thread2), osssink); - gst_pad_link (gst_element_get_pad (filesrc,"src"), - gst_element_get_pad (queue,"sink")); + gst_element_link_many (filesrc, queue, decode, queue2, osssink, NULL); - gst_pad_link (gst_element_get_pad (queue,"src"), - gst_element_get_pad (decode,"sink")); - gst_pad_link (gst_element_get_pad (decode,"src"), - gst_element_get_pad (queue2,"sink")); - - gst_pad_link (gst_element_get_pad (queue2,"src"), - gst_element_get_pad (osssink,"sink")); - - gst_bin_add (GST_BIN (bin), thread); - gst_bin_add (GST_BIN (bin), thread2); + gst_bin_add_many (GST_BIN (bin), thread, thread2, NULL); /* write the bin to stdout */ gst_xml_write_file (GST_ELEMENT (bin), stdout); @@ -204,7 +192,7 @@ xmlNsPtr ns; ... - When the thread is saved, the object_save method will be caled. Our example + When the thread is saved, the object_save method will be called. Our example will insert a comment tag: diff --git a/docs/manual/init.xml b/docs/manual/init.xml index 7c946a8728..7f73fde18b 100644 --- a/docs/manual/init.xml +++ b/docs/manual/init.xml @@ -6,7 +6,7 @@ access to the library functions. - Before the GStreamer libraries can be used + Before the GStreamer libraries can be used, gst_init has to be called from the main application. This call will perform the necessary initialization of the library as well as parse the GStreamer-specific command line options. @@ -41,11 +41,6 @@ main (int argc, char *argv[]) with two NULL arguments, in which case no command line options will parsed by GStreamer. - - Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO macros to - get the GStreamer version you are building against or - use gst_version() to get the version you are linked against. - The popt interface diff --git a/docs/manual/intro-motivation.xml b/docs/manual/intro-motivation.xml index f6a63d9a00..ea91d30d62 100644 --- a/docs/manual/intro-motivation.xml +++ b/docs/manual/intro-motivation.xml @@ -2,7 +2,7 @@ Motivation Linux has historically lagged behind other operating systems in the multimedia - arena. Microsoft's Windows[tm] and Apple's MacOS[tm] both have strong support + arena. Microsoft's Windows and Apple's MacOS both have strong support for multimedia devices, multimedia content creation, playback, and realtime processing. Linux, on the other hand, has a poorly integrated collection of multimedia utilities and applications available, which can hardly compete @@ -12,7 +12,7 @@ Current problems - We descibe the typical problems in todays media handling on Linux. + We describe the typical problems in today's media handling on Linux. Multitude of duplicate code @@ -37,9 +37,9 @@ filters or special effects to the video or audio data. - If I wanted to convert an MPEG2 video stream into an AVI file, my best + If you want to convert an MPEG2 video stream into an AVI file, your best option would be to take all of the MPEG2 decoding algorithms out - of the player and duplicate them into my own AVI encoder. These + of the player and duplicate them into your own AVI encoder. These algorithms cannot easily be shared accross applications. @@ -69,7 +69,7 @@ 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. The Framework that GStreamer provides for the plugins is + plugins. The framework that GStreamer provides for the plugins is flexible enough to host even the most demanding plugins. @@ -87,7 +87,7 @@ type="http">GNOME object embedding using Bonobo. - The GStreamer cores does not use network transparent technologies at the + The GStreamer core 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. @@ -95,7 +95,7 @@ - Catch up with the Windows(tm) world + Catch up with the <trademark>Windows</trademark> world We need solid media handling if we want to see Linux succeed on the desktop. diff --git a/docs/manual/intro-preface.xml b/docs/manual/intro-preface.xml index 1b1180007f..db6bd182bd 100644 --- a/docs/manual/intro-preface.xml +++ b/docs/manual/intro-preface.xml @@ -15,17 +15,20 @@ GStreamer's development framework makes it possible to write any type of - streaming multimedia application. The GStreamer framework is designed to make it easy to - write applications that handle either audio or video or both. The pipeline design is made to have - no extra overhead above what the applied filters induce. This makes GStreamer a good framework for designing - even high-end audio applications which puts high demands on latency. + streaming multimedia application. The GStreamer framework is designed + to make it easy to write applications that handle audio or video or both. + It isn't restricted to audio and video, and can process any kind of + data flow. + The pipeline design is made to have little overhead above what the + applied filters induce. This makes GStreamer a good framework for designing + even high-end audio applications which put high demands on latency. One of the the most obvious uses of GStreamer is using it to build a media player. GStreamer already includes components for building a media player that can support a very wide variety of formats, including - MP3, Ogg Vorbis, MPEG1, MPEG2, AVI, Quicktime, mod and so on. GStreamer, + MP3, Ogg Vorbis, MPEG1, MPEG2, AVI, Quicktime, mod, and more. GStreamer, however, is much more than just another media player. Its main advantages are that the pluggable components can be mixed and matched into arbitrary pipelines so that it's possible to write a full-fledged video or audio diff --git a/docs/manual/intro.xml b/docs/manual/intro.xml index 1b1180007f..db6bd182bd 100644 --- a/docs/manual/intro.xml +++ b/docs/manual/intro.xml @@ -15,17 +15,20 @@ GStreamer's development framework makes it possible to write any type of - streaming multimedia application. The GStreamer framework is designed to make it easy to - write applications that handle either audio or video or both. The pipeline design is made to have - no extra overhead above what the applied filters induce. This makes GStreamer a good framework for designing - even high-end audio applications which puts high demands on latency. + streaming multimedia application. The GStreamer framework is designed + to make it easy to write applications that handle audio or video or both. + It isn't restricted to audio and video, and can process any kind of + data flow. + The pipeline design is made to have little overhead above what the + applied filters induce. This makes GStreamer a good framework for designing + even high-end audio applications which put high demands on latency. One of the the most obvious uses of GStreamer is using it to build a media player. GStreamer already includes components for building a media player that can support a very wide variety of formats, including - MP3, Ogg Vorbis, MPEG1, MPEG2, AVI, Quicktime, mod and so on. GStreamer, + MP3, Ogg Vorbis, MPEG1, MPEG2, AVI, Quicktime, mod, and more. GStreamer, however, is much more than just another media player. Its main advantages are that the pluggable components can be mixed and matched into arbitrary pipelines so that it's possible to write a full-fledged video or audio diff --git a/docs/manual/linked-elements.fig b/docs/manual/linked-elements.fig index 0aff06c9f4..a2b3a526ca 100644 --- a/docs/manual/linked-elements.fig +++ b/docs/manual/linked-elements.fig @@ -31,6 +31,6 @@ Single 4 0 0 50 0 16 12 0.0000 4 135 330 5550 3975 sink\001 4 0 0 50 0 16 12 0.0000 4 135 330 8175 3975 sink\001 4 0 0 50 0 16 12 0.0000 4 105 255 6825 3975 src\001 -4 0 0 50 0 16 12 0.0000 4 135 750 5625 3075 element2\001 -4 0 0 50 0 16 12 0.0000 4 135 750 8250 3075 element3\001 -4 0 0 50 0 16 12 0.0000 4 135 750 3000 3075 element1\001 +4 0 0 50 0 16 12 0.0000 4 135 750 5625 3075 filter\001 +4 0 0 50 0 16 12 0.0000 4 135 750 8250 3075 sink_element\001 +4 0 0 50 0 16 12 0.0000 4 135 750 3000 3075 source_element\001 diff --git a/docs/manual/links.xml b/docs/manual/links.xml index 85d2c2193f..c9d1dd22fe 100644 --- a/docs/manual/links.xml +++ b/docs/manual/links.xml @@ -97,7 +97,9 @@ Making filtered links You can also force a specific media type on the link by using gst_pad_link_filtered () - and gst_element_link_filtered (). FIXME link to caps documentation. + and gst_element_link_filtered () with capabilities. + See for + an explanation of capabilities. diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml index a5503faafa..bf24936eed 100644 --- a/docs/manual/manual.xml +++ b/docs/manual/manual.xml @@ -143,10 +143,10 @@ &ELEMENTS; - &PLUGINS; - &PADS; + &PLUGINS; + &LINKS; &BINS; diff --git a/docs/manual/motivation.xml b/docs/manual/motivation.xml index f6a63d9a00..ea91d30d62 100644 --- a/docs/manual/motivation.xml +++ b/docs/manual/motivation.xml @@ -2,7 +2,7 @@ Motivation Linux has historically lagged behind other operating systems in the multimedia - arena. Microsoft's Windows[tm] and Apple's MacOS[tm] both have strong support + arena. Microsoft's Windows and Apple's MacOS both have strong support for multimedia devices, multimedia content creation, playback, and realtime processing. Linux, on the other hand, has a poorly integrated collection of multimedia utilities and applications available, which can hardly compete @@ -12,7 +12,7 @@ Current problems - We descibe the typical problems in todays media handling on Linux. + We describe the typical problems in today's media handling on Linux. Multitude of duplicate code @@ -37,9 +37,9 @@ filters or special effects to the video or audio data. - If I wanted to convert an MPEG2 video stream into an AVI file, my best + If you want to convert an MPEG2 video stream into an AVI file, your best option would be to take all of the MPEG2 decoding algorithms out - of the player and duplicate them into my own AVI encoder. These + of the player and duplicate them into your own AVI encoder. These algorithms cannot easily be shared accross applications. @@ -69,7 +69,7 @@ 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. The Framework that GStreamer provides for the plugins is + plugins. The framework that GStreamer provides for the plugins is flexible enough to host even the most demanding plugins. @@ -87,7 +87,7 @@ type="http">GNOME object embedding using Bonobo. - The GStreamer cores does not use network transparent technologies at the + The GStreamer core 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. @@ -95,7 +95,7 @@ - Catch up with the Windows(tm) world + Catch up with the <trademark>Windows</trademark> world We need solid media handling if we want to see Linux succeed on the desktop. diff --git a/docs/manual/pads.xml b/docs/manual/pads.xml index 43270bd177..391fe1b8de 100644 --- a/docs/manual/pads.xml +++ b/docs/manual/pads.xml @@ -1,12 +1,27 @@ - GstPad + Pads - As we have seen in the previous chapter (GstElement), the pads are the element's - links with the outside world. + As we have seen in , the pads are the element's + interface to the outside world. The specific type of media that the element can handle will be exposed by the pads. - The description of this media type is done with capabilities (GstCaps) + The description of this media type is done with capabilities(see + ) + + + + Pads are either source or sink pads. The terminology is defined from the + view of the element itself: elements accept data on their sink pads, and + send data out on their source pads. Sink pads are drawn on the left, + while source pads are drawn on the right of an element. In general, + data flows from left to right in the graph. + + In reality, there is no objection to data flowing from a + source pad to the sink pad of an element upstream. Data will, however, + always flow from a source pad of one element to the sink pad of + another. + @@ -58,19 +73,27 @@ GstElement. + + + + Types of pads + Dynamic pads - Some elements might not have their pads when they are created. This - can happen, for example, with an MPEG2 system demultiplexer. The + Some elements might not have all of their pads when the element is + created. This + can happen, for example, with an MPEG system demultiplexer. The demultiplexer will create its pads at runtime when it detects the - different elementary streams in the MPEG2 system stream. + different elementary streams in the MPEG system stream. Running gst-inspect mpegdemux will show that the element has only one pad: a sink pad called 'sink'. The other pads are - "dormant" as you can see in the padtemplates from the 'Exists: Sometimes' - property. Depending on the type of MPEG2 file you play, the pads are created. We + "dormant". You can see this in the pad template because there is + an 'Exists: Sometimes' + property. Depending on the type of MPEG file you play, the pads will + be created. We will see that this is very important when you are going to create dynamic pipelines later on in this manual. @@ -116,7 +139,7 @@ main(int argc, char *argv[]) - You need to set the pipeline to READY or NULL if you want to change it. + A pipeline cannot be changed in the PLAYING state. @@ -172,12 +195,15 @@ main(int argc, char *argv[]) ... + - - Capabilities of a GstPad + + + Capabilities of a pad Since the pads play a very important role in how the element is viewed by the - outside world, a mechanism is implemented to describe the pad by using capabilities. + outside world, a mechanism is implemented to describe the data that can + flow through the pad by using capabilities. We will briefly describe what capabilities are, enough for you to get a basic understanding @@ -186,14 +212,29 @@ main(int argc, char *argv[]) - What is a capability + What are capabilities ? - A capability is attached to a pad in order to describe what type of media the pad - can handle. + Capabilities are attached to a pad in order to describe + what type of media the pad can handle. - A capability is named and consists of a MIME type and a set of properties. Its data - structure is: + Capabilities is shorthand for "capability chain". A capability chain + is a chain of one capability or more. + + + The basic entity is a capability, and is defined by a name, a MIME + type and a set of properties. A capability can be chained to + another capability, which is why we commonly refer to a chain of + capability entities as "capabilities". + + It is important to understand that the term "capabilities" refers + to a chain of one capability or more. This will be clearer when + you see the structure definition of a GstCaps + element. + + + + Its structure is: struct _GstCaps { @@ -245,55 +286,80 @@ Pads: - What are properties + What are properties ? Properties are used to describe extra information for - capabilities. The properties basically consist of a key (a string) and - a value. There are different possibile value types that can be used: + capabilities. A property consists of a key (a string) and + a value. There are different possible value types that can be used: - An integer value: the property has this exact value. + basic types: + + + + an integer value: the property has this exact value. + + + + + a boolean value: the property is either TRUE or FALSE. + + + + + a fourcc value: this is a value that is commonly used to + describe an encoding for video, + as used for example by the AVI specification. + + fourcc values consist of four bytes. + The FOURCC + Definition List is the most complete resource + on the allowed fourcc values. + + + + + + a float value: the property has this exact floating point value. + + + + + a string value. + + + + + + + + range types: + + + + + an integer range value: the property denotes a range of + possible integer. For example, the wavparse element has + a source pad where the "rate" property can go from 8000 to + 48000. + + + + + a float range value: the property denotes a range of possible + floating point values. + + + - An integer range value. The property denotes a range of possible - values. In the case of the mad element, the source pad has a - property rate that can go from 11025 to 48000. - - - - - A boolean value. - - - - - a fourcc value: this is a value that is commonly used to describe an encoding for video, - as used by the AVI specification. - - - - - A list value: the property can take any value from a list. - - - - - A float value: the property has this exact floating point value. - - - - - A float range value: denotes a range of possible floating point values. - - - - - A string value. + a list value: the property can take any value from a list of + basic value types or range types. @@ -315,6 +381,8 @@ Pads: Compatibility detection: when two pads are linked, GStreamer can verify if the two pads are talking about the same media types. + The process of linking two pads and checking if they are compatible + is called "caps negotiation". @@ -407,7 +475,7 @@ GstProps* gst_props_new (const gchar *firstname, ...); - GST_PROPS_INT_RANGE(a,b): An integer ragne from a to b + GST_PROPS_INT_RANGE(a,b): An integer range from a to b diff --git a/docs/manual/programs.xml b/docs/manual/programs.xml index 897529a0a9..0c22496593 100644 --- a/docs/manual/programs.xml +++ b/docs/manual/programs.xml @@ -247,11 +247,5 @@ Element Signals: gst-inspect gstelements - - <command>gst-play</command> - - A sample media player. - - diff --git a/docs/manual/queues.xml b/docs/manual/queues.xml index 148360346b..75c8201e34 100644 --- a/docs/manual/queues.xml +++ b/docs/manual/queues.xml @@ -1,7 +1,7 @@ Queues - A GstQueue is a filter element. + A queue is a filter element. Queues can be used to link two elements in such way that the data can be buffered. @@ -11,10 +11,10 @@ element as soon as a gst_pad_pull () is called on the queue's source pad. - Queues are mostly used in conjunction with a GstThread to - provide an external link for the thread elements. You could have one - thread feeding buffers into a GstQueue and another - thread repeadedly calling gst_pad_pull () on the queue to feed its + Queues are mostly used in conjunction with a thread bin to + provide an external link for the thread's elements. You could have one + thread feeding buffers into a queue and another + thread repeatedly pulling on the queue to feed its internal elements. diff --git a/docs/manual/quotes.xml b/docs/manual/quotes.xml index da45bf10be..cc88ad101d 100644 --- a/docs/manual/quotes.xml +++ b/docs/manual/quotes.xml @@ -5,7 +5,7 @@ GStreamer is a lively project, with developers from around the globe very actively contributing. We often hang out on the #gstreamer IRC channel on - irc.openprojects.net: the following are a selection of amusing + irc.freenode.org: the following are a selection of amusing No guarantee of sense of humour compatibility is given. quotes from our conversations. diff --git a/docs/manual/schedulers.xml b/docs/manual/schedulers.xml index c676d92ce0..b86e72f20b 100644 --- a/docs/manual/schedulers.xml +++ b/docs/manual/schedulers.xml @@ -28,7 +28,7 @@ - The scheduler is a plugable component; this means that alternative + The scheduler is a pluggable component; this means that alternative schedulers can be written and plugged into GStreamer. The default scheduler uses cothreads to schedule the plugins in a pipeline. Cothreads are fast and lightweight user-space threads. diff --git a/docs/manual/sink-element.fig b/docs/manual/sink-element.fig index 0a52a1b504..4172cd1ba2 100644 --- a/docs/manual/sink-element.fig +++ b/docs/manual/sink-element.fig @@ -11,5 +11,5 @@ Single 5625 2775 7575 2775 7575 4425 5625 4425 5625 2775 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 5625 3600 6375 3600 6375 4125 5625 4125 5625 3600 -4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 sink_element\001 4 0 0 50 0 16 12 0.0000 4 135 330 5850 3975 sink\001 diff --git a/docs/manual/src-element.fig b/docs/manual/src-element.fig index 82264aa705..04c9fcba0d 100644 --- a/docs/manual/src-element.fig +++ b/docs/manual/src-element.fig @@ -12,4 +12,4 @@ Single 2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 5625 2775 7575 2775 7575 4425 5625 4425 5625 2775 4 0 0 50 0 16 12 0.0000 4 105 255 7050 3975 src\001 -4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 source_element\001 diff --git a/docs/manual/states.xml b/docs/manual/states.xml index 3cda7a935d..402cde5b18 100644 --- a/docs/manual/states.xml +++ b/docs/manual/states.xml @@ -8,7 +8,7 @@ The different element states - All elements can be in one of the following four states: + An element can be in one of the following four states: @@ -37,7 +37,7 @@ All elements start with the NULL state. The elements will go throught the following state changes: NULL -> READY -> PAUSED -> - PLAYING. Remember when going from PLAYING to READY, GStreamer will + PLAYING. When going from NULL to PLAYING, GStreamer will internally go throught the intermediate states. @@ -53,7 +53,7 @@ - You can set the following states to an element: + You can set the following states on an element: @@ -88,7 +88,7 @@ The NULL state When you created the pipeline all of the elements will be in the NULL state. There is - nothing spectacular about the NULL state. + nothing special about the NULL state. @@ -119,14 +119,6 @@ - - The PLAYING state - - A Pipeline that is in the READY state can be started by setting it to the PLAYING state. At - that time data will start to flow all the way through the pipeline. - - - The PAUSED state @@ -148,5 +140,13 @@ in the pipeline. We will cover dynamic pipeline behaviour in . + + The PLAYING state + + A Pipeline that is in the READY state can be started by setting it to the PLAYING state. At + that time data will start to flow all the way through the pipeline. + + + diff --git a/docs/manual/thread.fig b/docs/manual/thread.fig index e532c14a20..eb55648b06 100644 --- a/docs/manual/thread.fig +++ b/docs/manual/thread.fig @@ -8,44 +8,44 @@ Single -2 1200 2 2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 90.00 120.00 - 4050 3750 4575 3750 + 1 1 1.00 77.53 103.38 + 3759 3501 4212 3501 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 - 4575 3600 5325 3600 5325 4125 4575 4125 4575 3600 + 4212 3371 4858 3371 4858 3824 4212 3824 4212 3371 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 - 5775 3600 6525 3600 6525 4125 5775 4125 5775 3600 + 5245 3371 5892 3371 5892 3824 5245 3824 5245 3371 2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 90.00 120.00 - 6525 3750 7125 3750 + 1 1 1.00 77.53 103.38 + 5892 3501 6408 3501 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 - 7125 3600 7875 3600 7875 4125 7125 4125 7125 3600 + 6408 3371 7055 3371 7055 3824 6408 3824 6408 3371 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 - 8325 3600 9075 3600 9075 4125 8325 4125 8325 3600 + 7442 3371 8088 3371 8088 3824 7442 3824 7442 3371 2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 - 9600 3600 10350 3600 10350 4125 9600 4125 9600 3600 + 8541 3371 9187 3371 9187 3824 8541 3824 8541 3371 2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 90.00 120.00 - 9075 3750 9600 3750 + 1 1 1.00 77.53 103.38 + 8088 3501 8541 3501 2 2 0 1 0 6 49 0 20 0.000 0 0 -1 0 0 5 - 3300 3600 4050 3600 4050 4125 3300 4125 3300 3600 + 3113 3371 3759 3371 3759 3824 3113 3824 3113 3371 2 2 0 1 0 7 50 0 20 0.000 0 0 -1 0 0 5 - 2100 2775 4050 2775 4050 4425 2100 4425 2100 2775 + 2079 2661 3759 2661 3759 4082 2079 4082 2079 2661 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 - 4575 2775 6525 2775 6525 4425 4575 4425 4575 2775 + 4212 2661 5892 2661 5892 4082 4212 4082 4212 2661 +2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 + 6408 2661 8088 2661 8088 4082 6408 4082 6408 2661 +2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 + 8541 2661 10221 2661 10221 4082 8541 4082 8541 2661 2 2 0 1 0 7 100 0 19 0.000 0 0 -1 0 0 5 - 1950 1950 11700 1950 11700 4800 1950 4800 1950 1950 -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 - 7125 2775 9075 2775 9075 4425 7125 4425 7125 2775 -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 - 9600 2775 11550 2775 11550 4425 9600 4425 9600 2775 -4 0 0 50 0 16 12 0.0000 4 135 330 4725 3975 sink\001 -4 0 0 50 0 16 12 0.0000 4 105 255 6075 3975 src\001 -4 0 0 50 0 16 12 0.0000 4 135 330 7350 3975 sink\001 -4 0 0 50 0 16 12 0.0000 4 105 255 8625 3975 src\001 -4 0 0 50 0 16 12 0.0000 4 135 330 9750 3975 sink\001 -4 0 0 50 0 16 12 0.0000 4 165 1005 2250 3075 disk_source\001 -4 0 0 50 0 16 12 0.0000 4 150 465 4725 3075 parse\001 -4 0 0 50 0 16 12 0.0000 4 135 690 7275 3075 decoder\001 -4 0 0 50 0 16 12 0.0000 4 180 930 9750 3075 play_audio\001 -4 0 0 48 0 16 12 0.0000 4 105 255 3525 3975 src\001 -4 0 0 50 0 16 12 0.0000 4 135 525 2175 2250 thread\001 + 1950 1950 10350 1950 10350 4405 1950 4405 1950 1950 +4 0 0 50 0 16 10 0.0000 4 116 284 4341 3694 sink\001 +4 0 0 50 0 16 10 0.0000 4 90 220 5504 3694 src\001 +4 0 0 50 0 16 10 0.0000 4 116 284 6602 3694 sink\001 +4 0 0 50 0 16 10 0.0000 4 90 220 7701 3694 src\001 +4 0 0 50 0 16 10 0.0000 4 116 284 8670 3694 sink\001 +4 0 0 50 0 16 10 0.0000 4 142 866 2208 2919 disk_source\001 +4 0 0 50 0 16 10 0.0000 4 129 401 4341 2919 parse\001 +4 0 0 50 0 16 10 0.0000 4 116 594 6538 2919 decoder\001 +4 0 0 50 0 16 10 0.0000 4 155 801 8670 2919 play_audio\001 +4 0 0 48 0 16 10 0.0000 4 90 220 3307 3694 src\001 +4 0 0 50 0 16 10 0.0000 4 116 452 2144 2208 thread\001 diff --git a/docs/manual/threads.xml b/docs/manual/threads.xml index 17d3e5b976..f11cd2547b 100644 --- a/docs/manual/threads.xml +++ b/docs/manual/threads.xml @@ -63,7 +63,7 @@ an audio pipeline. - A thread can be visualised as below + shows how a thread can be visualised.
A thread diff --git a/docs/manual/typedetection.xml b/docs/manual/typedetection.xml index b98a044e7e..0ac08be645 100644 --- a/docs/manual/typedetection.xml +++ b/docs/manual/typedetection.xml @@ -1,5 +1,5 @@ - Typedetection + Type Detection Sometimes the capabilities of a pad are not specificied. The filesrc element, for example, does not know what type of file it is reading. Before @@ -8,7 +8,7 @@ To solve this problem, a plugin can provide the GStreamer - core library with a typedefinition library with a typedefinition. The typedefinition + core library with a type definition. The type definition will contain the following information: @@ -43,7 +43,8 @@ typedef GstCaps *(*GstTypeFindFunc) (GstBuffer *buf, gpointer priv); understand the buffer contents, it will return NULL. - GStreamer has a typefind element in its core elements + GStreamer has a typefind element in the set + of core elements that can be used to determine the type of a given pad. @@ -82,14 +83,12 @@ main(int argc, char *argv[]) g_assert (typefind != NULL); /* add objects to the main pipeline */ - gst_bin_add (GST_BIN (bin), filesrc); - gst_bin_add (GST_BIN (bin), typefind); + gst_bin_add_many (GST_BIN (bin), filesrc, typefind, NULL); g_signal_connect (G_OBJECT (typefind), "have_type", G_CALLBACK (type_found), NULL); - gst_pad_link (gst_element_get_pad (filesrc, "src"), - gst_element_get_pad (typefind, "sink")); + gst_element_link (filesrc, typefind); /* start playing */ gst_element_set_state (GST_ELEMENT (bin), GST_STATE_PLAYING); diff --git a/docs/manual/xml.xml b/docs/manual/xml.xml index bcf9312873..7f72802dc7 100644 --- a/docs/manual/xml.xml +++ b/docs/manual/xml.xml @@ -70,27 +70,15 @@ main (int argc, char *argv[]) g_assert (decode != NULL); /* add objects to the main bin */ - gst_bin_add (GST_BIN (bin), filesrc); - gst_bin_add (GST_BIN (bin), queue); + gst_bin_add_many (GST_BIN (bin), filesrc, queue, NULL); - gst_bin_add (GST_BIN (thread), decode); - gst_bin_add (GST_BIN (thread), queue2); + gst_bin_add_many (GST_BIN (thread), decode, queue2, NULL); gst_bin_add (GST_BIN (thread2), osssink); - gst_pad_link (gst_element_get_pad (filesrc,"src"), - gst_element_get_pad (queue,"sink")); + gst_element_link_many (filesrc, queue, decode, queue2, osssink, NULL); - gst_pad_link (gst_element_get_pad (queue,"src"), - gst_element_get_pad (decode,"sink")); - gst_pad_link (gst_element_get_pad (decode,"src"), - gst_element_get_pad (queue2,"sink")); - - gst_pad_link (gst_element_get_pad (queue2,"src"), - gst_element_get_pad (osssink,"sink")); - - gst_bin_add (GST_BIN (bin), thread); - gst_bin_add (GST_BIN (bin), thread2); + gst_bin_add_many (GST_BIN (bin), thread, thread2, NULL); /* write the bin to stdout */ gst_xml_write_file (GST_ELEMENT (bin), stdout); @@ -204,7 +192,7 @@ xmlNsPtr ns; ... - When the thread is saved, the object_save method will be caled. Our example + When the thread is saved, the object_save method will be called. Our example will insert a comment tag: