<para>
While this mechanism is quite effective it also has some big problems:
- The elements are created based on their name. Indeed, we create an
- element mad by explicitly stating the mad element's name.
- Our little program therefore always uses the mad decoder element
- to decode the MP3 audio stream, even if there are 3 other MP3 decoders
- in the system. We will see how we can use a more general way to create
- an MP3 decoder element.
+ The elements are created based on their name. Indeed, we create an
+ element mad by explicitly stating the mad element's name. Our little
+ program therefore always uses the mad decoder element to decode
+ the MP3 audio stream, even if there are 3 other MP3 decoders in the
+ system. We will see how we can use a more general way to create an
+ MP3 decoder element.
</para>
<para>
We have to introduce the concept of MIME types and capabilities
the given MIME type.
</para>
<para>
- There is also an association between a MIME type and a file extension, but the use of typefind
- functions (similar to file(1)) is preferred..
+ There is also an association between a MIME type and a file extension,
+ but the use of typefind functions (similar to file(1)) is preferred..
</para>
<para>
The type information is maintained in a list of
};
</programlisting>
<para>
- All operations on <classname>GstType</classname> occur via their
- <classname>guint16 id</classname> numbers, with <classname>GstType</classname>
- structure private to the GStreamer library.
+ All operations on <classname>GstType</classname> occur
+ via their <classname>guint16 id</classname> numbers, with
+ <classname>GstType</classname> structure private to the GStreamer
+ library.
</para>
<sect2>
<sect1>
<title>Getting Started</title>
<para>
- The dparams subsystem is contained within the <filename>gstcontrol</filename> library.
-
+ The dparams subsystem is contained within the
+ <filename>gstcontrol</filename> library.
+
You need to include the header in your applications's source file:
</para>
<programlisting>
Your application should link to the shared library <filename>gstcontrol</filename>.
</para>
<para>
- The <filename>gstcontrol</filename> library needs to be initialised when your application is run.
- This can be done after the the GStreamer library has been initialised.
+ The <filename>gstcontrol</filename> library needs to be initialised
+ when your application is run. This can be done after the the GStreamer
+ library has been initialised.
</para>
<programlisting>
...
</itemizedlist>
</para>
<para>
- The scheduler is a plugable 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.
+ The scheduler is a plugable 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.
</para>
<para>
- There is usually no need to interact with the scheduler directly, however it some
- cases it is feasable to set a specific clock or force a specific plugin as the
- entry point in the pipeline.
+ There is usually no need to interact with the scheduler directly, however
+ it some cases it is feasable to set a specific clock or force a specific
+ plugin as the entry point in the pipeline.
</para>
</chapter>
</programlisting>
<para>
- The above program will create a thread with two elements in it. As soon as it is set to the
- PLAYING state, the thread will start to iterate itself. You never need to manually iterate a
- thread.
+ The above program will create a thread with two elements in it. As soon
+ as it is set to the PLAYING state, the thread will start to iterate
+ itself. You never need to manually iterate a thread.
</para>
<sect2>
<title>Constraints placed on the pipeline by the GstThread</title>
<para>
- Within the pipeline, everything is the same as in any other bin. The difference lies at the
- thread boundary, at the connection between the thread and the outside world (containing bin).
- Since GStreamer is fundamentally buffer-oriented rather than byte-oriented, the natural
- solution to this problem is an element that can "buffer" the buffers between the threads, in a
- thread-safe fashion. This element is the queue, described more fully in <xref
- linkend="cha-queues"/>. It doesn't matter if the queue is placed in the containing bin or in
- the thread itself, but it needs to be present on one side of the other to enable inter-thread
- communication.
+ Within the pipeline, everything is the same as in any other bin. The
+ difference lies at the thread boundary, at the connection between the
+ thread and the outside world (containing bin). Since GStreamer is
+ fundamentally buffer-oriented rather than byte-oriented, the natural
+ solution to this problem is an element that can "buffer" the buffers
+ between the threads, in a thread-safe fashion. This element is the
+ queue, described more fully in <xref linkend="cha-queues"/>. It doesn't
+ matter if the queue is placed in the containing bin or in the thread
+ itself, but it needs to be present on one side of the other to enable
+ inter-thread communication.
</para>
</sect2>
<sect2>
</para>
<para>
- You can also use the the parser in you own code. <application>GStreamer</application>
- provides a function gst_parse_launch () that you can use to construt a pipeline.
- The following programs lets you create an mp3 pipeline using the gst_parse_launch ()
- function:
+ You can also use the the parser in you own
+ code. <application>GStreamer</application> provides a function
+ gst_parse_launch () that you can use to construt a pipeline.
+ The following programs lets you create an mp3 pipeline using the
+ gst_parse_launch () function:
</para>
<programlisting>
#include <gst/gst.h>
... mad ...
</screen>
<para>
- A bare identifier (a string beginning with a letter and containing only letters,
- numbers, dashes, underscores, percent signs, or colons) will create an element from a
- given elementfactory. In this example, an instance of the "mad" mp3 decoding plugin will
- be created.
+ A bare identifier (a string beginning with a letter and containing
+ only letters, numbers, dashes, underscores, percent signs, or colons)
+ will create an element from a given elementfactory. In this example,
+ an instance of the "mad" mp3 decoding plugin will be created.
</para>
</sect3>
<sect3>
elements needed for the conversion.
</para>
<para>
- The autoplugger API is implemented in an abstract class. Autoplugger implementations
- reside in plugins and are therefore optional and can be optimized for a specific
- task. Two types of autopluggers exist: renderer ones and non
- renderer ones. the renderer autopluggers will not have any src pads while the
- non renderer ones do. The renderer autopluggers are mainly used for media
- playback while the non renderer ones are used for arbitrary format conversion.
+ The autoplugger API is implemented in an abstract class. Autoplugger
+ implementations reside in plugins and are therefore optional and can be
+ optimized for a specific task. Two types of autopluggers exist: renderer
+ ones and non renderer ones. the renderer autopluggers will not have any
+ src pads while the non renderer ones do. The renderer autopluggers are
+ mainly used for media playback while the non renderer ones are used for
+ arbitrary format conversion.
</para>
<sect1>
A list of all available autopluggers can be obtained with gst_autoplug_factory_get_list().
</para>
<para>
- If the autoplugger supports the RENDERER API, use gst_autoplug_to_renderers() call to
- create a bin that connects the src caps to the specified render elements. You can
- then add the bin to a pipeline and run it.
+ If the autoplugger supports the RENDERER API, use
+ gst_autoplug_to_renderers() call to create a bin that connects the
+ src caps to the specified render elements. You can then add the bin
+ to a pipeline and run it.
<programlisting>
</programlisting>
</para>
<para>
- If the autoplugger supports the CAPS API, use the gst_autoplug_to_caps() function to
- connect the src caps to the destination caps. The created bin will have src and sink
- pads compatible with the provided caps.
+ If the autoplugger supports the CAPS API, use the gst_autoplug_to_caps()
+ function to connect the src caps to the destination caps. The created
+ bin will have src and sink pads compatible with the provided caps.
<programlisting>
<orderedlist>
<listitem>
<para>
- Add the autoplugcache element to a bin and connect the sink pad to the src
- pad of an element with unknown caps.
+ Add the autoplugcache element to a bin and connect the sink pad
+ to the src pad of an element with unknown caps.
</para>
</listitem>
<listitem>
<para>
- Connect the src pad of the autoplugcache to the sink pad of the typefind
- element.
+ Connect the src pad of the autoplugcache to the sink pad of the
+ typefind element.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Remove the typefind element and add the plugins needed to play back the discovered
- media type to the autoplugcache src pad.
+ Remove the typefind element and add the plugins needed to play
+ back the discovered media type to the autoplugcache src pad.
</para>
</listitem>
<listitem>
<sect1>
<title>Another approach to autoplugging</title>
<para>
- The autoplug API is interesting, but often impractical. It is static; it cannot deal with
- dynamic pipelines (insert ref here). What one often wants is just an element to stick into a
- pipeline that will DWIM (ref). Enter the spider.
+ The autoplug API is interesting, but often impractical. It is static;
+ it cannot deal with dynamic pipelines (insert ref here). What one
+ often wants is just an element to stick into a pipeline that will DWIM
+ (ref). Enter the spider.
</para>
<sect2>
<title>The spider element</title>
</listitem>
<listitem>
<para>
- Has request pads on the src side. This means that it can autoplug one source stream
- into many sink streams. For example, a MPEG1 system stream can have audio as well as
- video; that pipeline would be represented in gst-launch syntax as
+ Has request pads on the src side. This means that it can autoplug
+ one source stream into many sink streams. For example, a MPEG1
+ system stream can have audio as well as video; that pipeline
+ would be represented in gst-launch syntax as
+
<programlisting>
$ gst-launch filesrc location=my.mpeg1 ! spider ! { queue ! osssink } spider.src_%d!
{ queue ! xvideosink }
<sect1 id="sec-bin-create">
<title>Creating a bin</title>
<para>
- Bins register themselves in the GStreamer registry, so they can be created in the normal way:
+ Bins register themselves in the GStreamer registry, so they can be
+ created in the normal way:
</para>
<programlisting>
GstElement *bin, *thread, *pipeline;
...
</programlisting>
<para>
- You can see that the name of the element becomes very handy for retrieving the
- element from an bin by using the element's name. gst_bin_get_by_name () will
- recursively search nested bins.
+ You can see that the name of the element becomes very handy
+ for retrieving the element from an bin by using the element's
+ name. gst_bin_get_by_name () will recursively search nested bins.
</para>
<para>
To get a list of elements in a bin, use:
...
</programlisting>
<para>
- To add many elements to a bin at the same time, try the gst_bin_add_many () API. Remember to
- pass NULL as the last argument.
+ To add many elements to a bin at the same time, try the gst_bin_add_many
+ () API. Remember to pass NULL as the last argument.
</para>
<programlisting>
GstElement *filesrc, *decoder, *audiosink;
<sect1 id="sec-bin-custom">
<title>Custom bins</title>
<para>
- The application programmer can create custom bins packed with elements to perform a
- specific task. This allow you to write an MPEG audio decoder with just the follwing lines
- of code:
+ The application programmer can create custom bins packed with elements
+ to perform a specific task. This allow you to write an MPEG audio
+ decoder with just the follwing lines of code:
</para>
<programlisting>
gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL);
</programlisting>
<para>
- Note that the above code assumes that the mp3player bin derives itself from a
- <classname>GstThread</classname>, which begins to play as soon as its state is set to PLAYING.
- Other bin types may need explicit iteration. For more information, see <xref
- linkend="cha-threads"/>.
-
- Custom bins can be created with a plugin or an XML description. You will find more
- information about creating custom bin in the Plugin Writers Guide (FIXME ref).
+ Note that the above code assumes that the mp3player bin derives itself
+ from a <classname>GstThread</classname>, which begins to play as soon
+ as its state is set to PLAYING. Other bin types may need explicit
+ iteration. For more information, see <xref linkend="cha-threads"/>.
+
+ Custom bins can be created with a plugin or an XML description. You
+ will find more information about creating custom bin in the Plugin
+ Writers Guide (FIXME ref).
</para>
</sect1>
</programlisting>
<para>
- In the above example, the bin now also has a pad: the pad called 'sink' of the
- given element. We can now, for example, connect the srcpad of a filesrc to the
- bin with:
+ In the above example, the bin now also has a pad: the pad called 'sink'
+ of the given element. We can now, for example, connect the srcpad of
+ a filesrc to the bin with:
</para>
<programlisting>
GstElement *filesrc;
<chapter id="cha-buffers">
<title>Buffers</title>
<para>
- Buffers contain the data that will flow through the pipeline you have created. A source
- element will typically create a new buffer and pass it through the pad to the next
- element in the chain.
- When using the GStreamer infrastructure to create a media pipeline you will not have
- to deal with buffers yourself; the elements will do that for you.
+ Buffers contain the data that will flow through the pipeline you have
+ created. A source element will typically create a new buffer and pass
+ it through the pad to the next element in the chain. When using the
+ GStreamer infrastructure to create a media pipeline you will not have
+ to deal with buffers yourself; the elements will do that for you.
</para>
<para>
The most important information in the buffer is:
</listitem>
<listitem>
<para>
- 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.
+ 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.
</para>
</listitem>
</itemizedlist>
</mediaobject>
</figure>
<para>
- Source elements do not accept data, they only generate data. You can see
- this in the figure because it only has a src pad. A src pad can only
- generate data.
+ Source elements do not accept data, they only generate data. You can
+ see this in the figure because it only has a src pad. A src pad can
+ only generate data.
</para>
</sect2>
<chapter id="cha-hello">
<title>Your first application</title>
<para>
- This chapter describes the most rudimentary aspects of a <application>GStreamer</application> application,
- including initializing the libraries, creating elements, packing them into
- a pipeline and playing, pause and stop the pipeline.
+ This chapter describes the most rudimentary aspects of a
+ <application>GStreamer</application> application, including initializing
+ the libraries, creating elements, packing them into a pipeline and playing,
+ pause and stop the pipeline.
</para>
<sect1>
<title>Hello world</title>
<para>
- We will create a simple first application, a complete MP3 player, using standard
- <application>GStreamer</application> components. The player will read from a file that is
- given as the first argument of the program.
+ We will create a simple first application, a complete MP3 player, using
+ standard <application>GStreamer</application> components. The player
+ will read from a file that is given as the first argument of the program.
</para>
<programlisting>
</programlisting>
<para>
- We are going to create 3 elements and one pipeline. Since all elements share the same base
- type, <classname>GstElement</classname>, we can define them as:
+ We are going to create 3 elements and one pipeline. Since all elements
+ share the same base type, <classname>GstElement</classname>, we can
+ define them as:
</para>
<programlisting>
...
</programlisting>
<para>
- Next, we are going to create an empty pipeline. As you have seen in the basic
- introduction, this pipeline will hold and manage all the elements we are
- going to stuff into it.
+ Next, we are going to create an empty pipeline. As you have seen in
+ the basic introduction, this pipeline will hold and manage all the
+ elements we are going to stuff into it.
</para>
<programlisting>
/* create a new pipeline to hold the elements */
while (gst_bin_iterate (GST_BIN (pipeline)));
</programlisting>
<para>
- The gst_bin_iterate() function will return TRUE as long as something interesting
- happended inside the pipeline. When the end-of-file has been reached the _iterate
- function will return FALSE and we can end the loop.
+ The gst_bin_iterate() function will return TRUE as long as something
+ interesting happended inside the pipeline. When the end-of-file has been
+ reached the _iterate function will return FALSE and we can end the loop.
</para>
<programlisting>
/* stop the pipeline */
you can create a custom MP3 element with a more high level API.
</para>
<para>
- It should be clear from the example that we can very easily replace the
+ It should be clear from the example that we can very easily replace the
filesrc element with an httpsrc, giving you instant network streaming.
An element could be build to handle icecast connections, for example.
</para>
This function will get the pad named "src" from the given element.
</para>
<para>
- Alternatively, you can also request a GList of pads from the element. The following
- code example will print the names of all the pads of an element.
+ Alternatively, you can also request a GList of pads from the element. The
+ following code example will print the names of all the pads of an
+ element.
</para>
<programlisting>
GList *pads;
get_pad_set_name().
</para>
<para>
- gst_pad_get_direction (GstPad *pad) can be used to query if the pad is a sink
- or a src pad. Remember a src pad is a pad that can output data and a sink pad is
- one that accepts data.
+ gst_pad_get_direction (GstPad *pad) can be used to query if the pad
+ is a sink or a src pad. Remember a src pad is a pad that can output
+ data and a sink pad is one that accepts data.
</para>
<para>
You can get the parent of the pad, this is the element that this pad belongs to,
<sect2 id="sec-pads-dynamic">
<title>Dynamic pads</title>
<para>
- Some elements might not have their pads when they are created. This can, for
- example, happen with an MPEG2 system demuxer. The demuxer will create its
- pads at runtime when it detects the different elementary streams in the MPEG2
- system stream.
+ Some elements might not have their pads when they are created. This
+ can, for example, happen with an MPEG2 system demuxer. The demuxer will
+ create its pads at runtime when it detects the different elementary
+ streams in the MPEG2 system stream.
</para>
<para>
Running <application>gst-inspect mpegdemux</application> will show that
<sect2 id="sec-pads-request">
<title>Request pads</title>
<para>
- An element can also have request pads. These pads are not created automatically
- but are only created on demand. This is very usefull for muxers, aggregators
- and tee elements.
+ An element can also have request pads. These pads are not created
+ automatically but are only created on demand. This is very usefull
+ for muxers, aggregators and tee elements.
</para>
<para>
The tee element, for example, has one input pad and a request padtemplate for the
</para>
<para>
It is also possible to request a pad that is compatible with another
- padtemplate. This is very usefull if you want to connect an element to
- a muxer element and you need to request a pad that is compatible. The
- gst_element_get_compatible_pad is used to request a compatible pad, as
- is shown in the next example.
+ padtemplate. This is very usefull if you want to connect an element to
+ a muxer element and you need to request a pad that is compatible. The
+ gst_element_get_compatible_pad is used to request a compatible pad,
+ as is shown in the next example.
</para>
<programlisting>
...
three properties: layer, bitrate and framed.
</para>
<para>
- The src pad (output pad) is called 'src' and outputs data of MIME type 'audio/raw'. It also has
- four properties: format, depth, rate and channels.
+ The src pad (output pad) is called 'src' and outputs data of MIME
+ type 'audio/raw'. It also has four properties: format, depth, rate
+ and channels.
</para>
<programlisting>
Pads:
<sect2 id="sec-pads-props">
<title>What are properties</title>
<para>
- Properties are used to describe extra information for the capabilities. The properties
- basically exist of a key (a string) and a value. There are different possibile value types
- that can be used:
+ Properties are used to describe extra information for the
+ capabilities. The properties basically exist of a key (a string) and
+ a value. There are different possibile value types that can be used:
</para>
<itemizedlist>
</listitem>
<listitem>
<para>
- An integer range value. The property denotes a range of possible values. In the case
- of the mad element: the src pad has a property rate that can go from 11025 to 48000.
+ An integer range value. The property denotes a range of possible
+ values. In the case of the mad element: the src pad has a property
+ rate that can go from 11025 to 48000.
</para>
</listitem>
<listitem>
<sect2 id="sec-pads-caps-create">
<title>Creating capabilities structures</title>
<para>
- While the capabilities are mainly used inside the plugin to describe the media type of the
- pads, the application programmer also has to have basic understanding of caps in order to
- interface with the plugins, specially when using the autopluggers.
+ While the capabilities are mainly used inside the plugin to describe
+ the media type of the pads, the application programmer also has
+ to have basic understanding of caps in order to interface with the
+ plugins, specially when using the autopluggers.
</para>
<para>
- As we said, a capability has a name, a mime-type and some properties. The signature of the
- function to create a new <classname>GstCaps</classname> structure is like:
+ As we said, a capability has a name, a mime-type and some
+ properties. The signature of the function to create a new
+ <classname>GstCaps</classname> structure is like:
+
<programlisting>
GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
</programlisting>
<sect1 id="sec-bin-create">
<title>Creating a bin</title>
<para>
- Bins register themselves in the GStreamer registry, so they can be created in the normal way:
+ Bins register themselves in the GStreamer registry, so they can be
+ created in the normal way:
</para>
<programlisting>
GstElement *bin, *thread, *pipeline;
...
</programlisting>
<para>
- You can see that the name of the element becomes very handy for retrieving the
- element from an bin by using the element's name. gst_bin_get_by_name () will
- recursively search nested bins.
+ You can see that the name of the element becomes very handy
+ for retrieving the element from an bin by using the element's
+ name. gst_bin_get_by_name () will recursively search nested bins.
</para>
<para>
To get a list of elements in a bin, use:
...
</programlisting>
<para>
- To add many elements to a bin at the same time, try the gst_bin_add_many () API. Remember to
- pass NULL as the last argument.
+ To add many elements to a bin at the same time, try the gst_bin_add_many
+ () API. Remember to pass NULL as the last argument.
</para>
<programlisting>
GstElement *filesrc, *decoder, *audiosink;
<sect1 id="sec-bin-custom">
<title>Custom bins</title>
<para>
- The application programmer can create custom bins packed with elements to perform a
- specific task. This allow you to write an MPEG audio decoder with just the follwing lines
- of code:
+ The application programmer can create custom bins packed with elements
+ to perform a specific task. This allow you to write an MPEG audio
+ decoder with just the follwing lines of code:
</para>
<programlisting>
gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL);
</programlisting>
<para>
- Note that the above code assumes that the mp3player bin derives itself from a
- <classname>GstThread</classname>, which begins to play as soon as its state is set to PLAYING.
- Other bin types may need explicit iteration. For more information, see <xref
- linkend="cha-threads"/>.
-
- Custom bins can be created with a plugin or an XML description. You will find more
- information about creating custom bin in the Plugin Writers Guide (FIXME ref).
+ Note that the above code assumes that the mp3player bin derives itself
+ from a <classname>GstThread</classname>, which begins to play as soon
+ as its state is set to PLAYING. Other bin types may need explicit
+ iteration. For more information, see <xref linkend="cha-threads"/>.
+
+ Custom bins can be created with a plugin or an XML description. You
+ will find more information about creating custom bin in the Plugin
+ Writers Guide (FIXME ref).
</para>
</sect1>
</programlisting>
<para>
- In the above example, the bin now also has a pad: the pad called 'sink' of the
- given element. We can now, for example, connect the srcpad of a filesrc to the
- bin with:
+ In the above example, the bin now also has a pad: the pad called 'sink'
+ of the given element. We can now, for example, connect the srcpad of
+ a filesrc to the bin with:
</para>
<programlisting>
GstElement *filesrc;
<chapter id="cha-buffers">
<title>Buffers</title>
<para>
- Buffers contain the data that will flow through the pipeline you have created. A source
- element will typically create a new buffer and pass it through the pad to the next
- element in the chain.
- When using the GStreamer infrastructure to create a media pipeline you will not have
- to deal with buffers yourself; the elements will do that for you.
+ Buffers contain the data that will flow through the pipeline you have
+ created. A source element will typically create a new buffer and pass
+ it through the pad to the next element in the chain. When using the
+ GStreamer infrastructure to create a media pipeline you will not have
+ to deal with buffers yourself; the elements will do that for you.
</para>
<para>
The most important information in the buffer is:
</listitem>
<listitem>
<para>
- 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.
+ 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.
</para>
</listitem>
</itemizedlist>
</mediaobject>
</figure>
<para>
- By connecting these three elements, we have created a very simple pipeline. The effect
- of this will be that the output of the source element (element1) will be used as input
- for the filter element (element2). The filter element will do something with the data and
- send the result to the final sink element (element3).
+ By connecting these three elements, we have created a very simple
+ pipeline. The effect of this will be that the output of the source element
+ (element1) will be used as input for the filter element (element2). The
+ filter element will do something with the data and send the result to
+ the final sink element (element3).
</para>
<para>
- Imagine the above graph as a simple mpeg audio decoder. The source element is a
- disk source, the filter element is the mpeg decoder and the sink element is your
- audiocard. We will use this simple graph to construct an mpeg player later
- in this manual.
+ Imagine the above graph as a simple mpeg audio decoder. The source
+ element is a disk source, the filter element is the mpeg decoder and
+ the sink element is your audiocard. We will use this simple graph to
+ construct an mpeg player later in this manual.
</para>
<sect1 id="sec-conn-basic">
You can query if a pad is connected with GST_PAD_IS_CONNECTED (pad).
</para>
<para>
- To query for the <classname>GstPad</classname> this srcpad is connected to, use
- gst_pad_get_peer (srcpad).
+ To query for the <classname>GstPad</classname> this srcpad is connected
+ to, use gst_pad_get_peer (srcpad).
</para>
</sect1>
</para>
<para>
- When the request for a buffer cannot immediatly 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 the execution trace can
- get fairly complex using cothreads when there are multiple input/output pads for the
- loop-based element. Cothread switches are performed within the call to gst_pad_pull and
- gst_pad_push; from the perspective of the loop-based element, it just "appears" that
- gst_pad_push (or _pull) might take a long time to return.
+ When the request for a buffer cannot immediatly 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 the execution trace can get
+ fairly complex using cothreads when there are multiple input/output
+ pads for the loop-based element. Cothread switches are performed within
+ the call to gst_pad_pull and gst_pad_push; from the perspective of
+ the loop-based element, it just "appears" that gst_pad_push (or _pull)
+ might take a long time to return.
</para>
<para>
- Loop based elements are mainly used for the more complex elements that need a specific amount
- of data before they can start to produce output. An example of such an element is the mpeg
- video decoder. the element will pull a buffer, performs some decoding on it and optionally
- requests more buffers to decode, when a complete video frame has been decoded, a buffer is
- send out. For example, any plugin using the bytestream library will need to be loop-based.
+ Loop based elements are mainly used for the more complex elements
+ that need a specific amount of data before they can start to produce
+ output. An example of such an element is the mpeg video decoder. the
+ element will pull a buffer, performs some decoding on it and optionally
+ requests more buffers to decode, when a complete video frame has
+ been decoded, a buffer is send out. For example, any plugin using the
+ bytestream library will need to be loop-based.
</para>
<para>
There is no problem in putting cothreaded elements into a <classname>GstThread</classname> to
<sect1>
<title>Getting Started</title>
<para>
- The dparams subsystem is contained within the <filename>gstcontrol</filename> library.
-
+ The dparams subsystem is contained within the
+ <filename>gstcontrol</filename> library.
+
You need to include the header in your applications's source file:
</para>
<programlisting>
Your application should link to the shared library <filename>gstcontrol</filename>.
</para>
<para>
- The <filename>gstcontrol</filename> library needs to be initialised when your application is run.
- This can be done after the the GStreamer library has been initialised.
+ The <filename>gstcontrol</filename> library needs to be initialised
+ when your application is run. This can be done after the the GStreamer
+ library has been initialised.
</para>
<programlisting>
...
<chapter id="cha-dynamic">
<title>Dynamic pipelines</title>
<para>
- In this chapter we will see how you can create a dynamic pipeline. A dynamic
- pipeline is a pipeline that is updated or created while media is flowing
- through it. We will create a partial pipeline first and add more elements
- while the pipeline is playing. Dynamic pipelines cause all sorts of
- scheduling issues and will remain a topic of research for a long time in
- GStreamer.
+ In this chapter we will see how you can create a dynamic pipeline. A
+ dynamic pipeline is a pipeline that is updated or created while media
+ is flowing through it. We will create a partial pipeline first and add
+ more elements while the pipeline is playing. Dynamic pipelines cause
+ all sorts of scheduling issues and will remain a topic of research for
+ a long time in GStreamer.
</para>
<para>
We will show how to create an mpeg1 video player using dynamic pipelines.
</mediaobject>
</figure>
<para>
- Source elements do not accept data, they only generate data. You can see
- this in the figure because it only has a src pad. A src pad can only
- generate data.
+ Source elements do not accept data, they only generate data. You can
+ see this in the figure because it only has a src pad. A src pad can
+ only generate data.
</para>
</sect2>
<para>
While this mechanism is quite effective it also has some big problems:
- The elements are created based on their name. Indeed, we create an
- element mad by explicitly stating the mad element's name.
- Our little program therefore always uses the mad decoder element
- to decode the MP3 audio stream, even if there are 3 other MP3 decoders
- in the system. We will see how we can use a more general way to create
- an MP3 decoder element.
+ The elements are created based on their name. Indeed, we create an
+ element mad by explicitly stating the mad element's name. Our little
+ program therefore always uses the mad decoder element to decode
+ the MP3 audio stream, even if there are 3 other MP3 decoders in the
+ system. We will see how we can use a more general way to create an
+ MP3 decoder element.
</para>
<para>
We have to introduce the concept of MIME types and capabilities
the given MIME type.
</para>
<para>
- There is also an association between a MIME type and a file extension, but the use of typefind
- functions (similar to file(1)) is preferred..
+ There is also an association between a MIME type and a file extension,
+ but the use of typefind functions (similar to file(1)) is preferred..
</para>
<para>
The type information is maintained in a list of
};
</programlisting>
<para>
- All operations on <classname>GstType</classname> occur via their
- <classname>guint16 id</classname> numbers, with <classname>GstType</classname>
- structure private to the GStreamer library.
+ All operations on <classname>GstType</classname> occur
+ via their <classname>guint16 id</classname> numbers, with
+ <classname>GstType</classname> structure private to the GStreamer
+ library.
</para>
<sect2>
<partintro>
<para>
- <application>GStreamer</application> comes prepackaged with a few programs.
- and some usefull debugging options.
+ <application>GStreamer</application> comes prepackaged with a few
+ programs. and some usefull debugging options.
</para>
</partintro>
<chapter id="cha-hello">
<title>Your first application</title>
<para>
- This chapter describes the most rudimentary aspects of a <application>GStreamer</application> application,
- including initializing the libraries, creating elements, packing them into
- a pipeline and playing, pause and stop the pipeline.
+ This chapter describes the most rudimentary aspects of a
+ <application>GStreamer</application> application, including initializing
+ the libraries, creating elements, packing them into a pipeline and playing,
+ pause and stop the pipeline.
</para>
<sect1>
<title>Hello world</title>
<para>
- We will create a simple first application, a complete MP3 player, using standard
- <application>GStreamer</application> components. The player will read from a file that is
- given as the first argument of the program.
+ We will create a simple first application, a complete MP3 player, using
+ standard <application>GStreamer</application> components. The player
+ will read from a file that is given as the first argument of the program.
</para>
<programlisting>
</programlisting>
<para>
- We are going to create 3 elements and one pipeline. Since all elements share the same base
- type, <classname>GstElement</classname>, we can define them as:
+ We are going to create 3 elements and one pipeline. Since all elements
+ share the same base type, <classname>GstElement</classname>, we can
+ define them as:
</para>
<programlisting>
...
</programlisting>
<para>
- Next, we are going to create an empty pipeline. As you have seen in the basic
- introduction, this pipeline will hold and manage all the elements we are
- going to stuff into it.
+ Next, we are going to create an empty pipeline. As you have seen in
+ the basic introduction, this pipeline will hold and manage all the
+ elements we are going to stuff into it.
</para>
<programlisting>
/* create a new pipeline to hold the elements */
while (gst_bin_iterate (GST_BIN (pipeline)));
</programlisting>
<para>
- The gst_bin_iterate() function will return TRUE as long as something interesting
- happended inside the pipeline. When the end-of-file has been reached the _iterate
- function will return FALSE and we can end the loop.
+ The gst_bin_iterate() function will return TRUE as long as something
+ interesting happended inside the pipeline. When the end-of-file has been
+ reached the _iterate function will return FALSE and we can end the loop.
</para>
<programlisting>
/* stop the pipeline */
you can create a custom MP3 element with a more high level API.
</para>
<para>
- It should be clear from the example that we can very easily replace the
+ It should be clear from the example that we can very easily replace the
filesrc element with an httpsrc, giving you instant network streaming.
An element could be build to handle icecast connections, for example.
</para>
<title>Turning GstElements into XML</title>
<para>
- We create a simple pipeline and write it to stdout with gst_xml_write_file (). The following
- code constructs an mp3 player pipeline with two threads and then writes out the XML both to
- stdout and to a file. Use this program with one argument: the mp3 file on disk.
+ We create a simple pipeline and write it to stdout with
+ gst_xml_write_file (). The following code constructs an mp3 player
+ pipeline with two threads and then writes out the XML both to stdout
+ and to a file. Use this program with one argument: the mp3 file on disk.
</para>
<programlisting>
<para>
In addition to loading a file, you can also load a from a xmlDocPtr and
an in memory buffer using gst_xml_parse_doc and gst_xml_parse_memory
- respectivily. both of these methods return a gboolean indicating success
- or failure of the requested action.
+ respectivily. both of these methods return a gboolean indicating
+ success or failure of the requested action.
</para>
</sect1>
<sect1 id="sec-xml-custom">
<para>
It is possible to add custom XML tags to the core XML created with
gst_xml_write. This feature can be used by an application to add more
- information to the save plugins. the editor will for example insert
+ information to the save plugins. the editor will for example insert
the position of the elements on the screen using the custom XML tags.
</para>
<para>
</programlisting>
<para>
- Whenever a new object has been loaded, the xml_loaded function will be
- called. this function looks like:
+ Whenever a new object has been loaded, the xml_loaded function will
+ be called. this function looks like:
</para>
<programlisting>
static void
This function will get the pad named "src" from the given element.
</para>
<para>
- Alternatively, you can also request a GList of pads from the element. The following
- code example will print the names of all the pads of an element.
+ Alternatively, you can also request a GList of pads from the element. The
+ following code example will print the names of all the pads of an
+ element.
</para>
<programlisting>
GList *pads;
get_pad_set_name().
</para>
<para>
- gst_pad_get_direction (GstPad *pad) can be used to query if the pad is a sink
- or a src pad. Remember a src pad is a pad that can output data and a sink pad is
- one that accepts data.
+ gst_pad_get_direction (GstPad *pad) can be used to query if the pad
+ is a sink or a src pad. Remember a src pad is a pad that can output
+ data and a sink pad is one that accepts data.
</para>
<para>
You can get the parent of the pad, this is the element that this pad belongs to,
<sect2 id="sec-pads-dynamic">
<title>Dynamic pads</title>
<para>
- Some elements might not have their pads when they are created. This can, for
- example, happen with an MPEG2 system demuxer. The demuxer will create its
- pads at runtime when it detects the different elementary streams in the MPEG2
- system stream.
+ Some elements might not have their pads when they are created. This
+ can, for example, happen with an MPEG2 system demuxer. The demuxer will
+ create its pads at runtime when it detects the different elementary
+ streams in the MPEG2 system stream.
</para>
<para>
Running <application>gst-inspect mpegdemux</application> will show that
<sect2 id="sec-pads-request">
<title>Request pads</title>
<para>
- An element can also have request pads. These pads are not created automatically
- but are only created on demand. This is very usefull for muxers, aggregators
- and tee elements.
+ An element can also have request pads. These pads are not created
+ automatically but are only created on demand. This is very usefull
+ for muxers, aggregators and tee elements.
</para>
<para>
The tee element, for example, has one input pad and a request padtemplate for the
</para>
<para>
It is also possible to request a pad that is compatible with another
- padtemplate. This is very usefull if you want to connect an element to
- a muxer element and you need to request a pad that is compatible. The
- gst_element_get_compatible_pad is used to request a compatible pad, as
- is shown in the next example.
+ padtemplate. This is very usefull if you want to connect an element to
+ a muxer element and you need to request a pad that is compatible. The
+ gst_element_get_compatible_pad is used to request a compatible pad,
+ as is shown in the next example.
</para>
<programlisting>
...
three properties: layer, bitrate and framed.
</para>
<para>
- The src pad (output pad) is called 'src' and outputs data of MIME type 'audio/raw'. It also has
- four properties: format, depth, rate and channels.
+ The src pad (output pad) is called 'src' and outputs data of MIME
+ type 'audio/raw'. It also has four properties: format, depth, rate
+ and channels.
</para>
<programlisting>
Pads:
<sect2 id="sec-pads-props">
<title>What are properties</title>
<para>
- Properties are used to describe extra information for the capabilities. The properties
- basically exist of a key (a string) and a value. There are different possibile value types
- that can be used:
+ Properties are used to describe extra information for the
+ capabilities. The properties basically exist of a key (a string) and
+ a value. There are different possibile value types that can be used:
</para>
<itemizedlist>
</listitem>
<listitem>
<para>
- An integer range value. The property denotes a range of possible values. In the case
- of the mad element: the src pad has a property rate that can go from 11025 to 48000.
+ An integer range value. The property denotes a range of possible
+ values. In the case of the mad element: the src pad has a property
+ rate that can go from 11025 to 48000.
</para>
</listitem>
<listitem>
<sect2 id="sec-pads-caps-create">
<title>Creating capabilities structures</title>
<para>
- While the capabilities are mainly used inside the plugin to describe the media type of the
- pads, the application programmer also has to have basic understanding of caps in order to
- interface with the plugins, specially when using the autopluggers.
+ While the capabilities are mainly used inside the plugin to describe
+ the media type of the pads, the application programmer also has
+ to have basic understanding of caps in order to interface with the
+ plugins, specially when using the autopluggers.
</para>
<para>
- As we said, a capability has a name, a mime-type and some properties. The signature of the
- function to create a new <classname>GstCaps</classname> structure is like:
+ As we said, a capability has a name, a mime-type and some
+ properties. The signature of the function to create a new
+ <classname>GstCaps</classname> structure is like:
+
<programlisting>
GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
</programlisting>
</para>
<para>
- You can also use the the parser in you own code. <application>GStreamer</application>
- provides a function gst_parse_launch () that you can use to construt a pipeline.
- The following programs lets you create an mp3 pipeline using the gst_parse_launch ()
- function:
+ You can also use the the parser in you own
+ code. <application>GStreamer</application> provides a function
+ gst_parse_launch () that you can use to construt a pipeline.
+ The following programs lets you create an mp3 pipeline using the
+ gst_parse_launch () function:
</para>
<programlisting>
#include <gst/gst.h>
... mad ...
</screen>
<para>
- A bare identifier (a string beginning with a letter and containing only letters,
- numbers, dashes, underscores, percent signs, or colons) will create an element from a
- given elementfactory. In this example, an instance of the "mad" mp3 decoding plugin will
- be created.
+ A bare identifier (a string beginning with a letter and containing
+ only letters, numbers, dashes, underscores, percent signs, or colons)
+ will create an element from a given elementfactory. In this example,
+ an instance of the "mad" mp3 decoding plugin will be created.
</para>
</sect3>
<sect3>
</programlisting>
<para>
- The following mp3 player shows you how to create the above pipeline using a
- thread and a queue.
+ The following mp3 player shows you how to create the above pipeline
+ using a thread and a queue.
</para>
<programlisting>
</itemizedlist>
</para>
<para>
- The scheduler is a plugable 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.
+ The scheduler is a plugable 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.
</para>
<para>
- There is usually no need to interact with the scheduler directly, however it some
- cases it is feasable to set a specific clock or force a specific plugin as the
- entry point in the pipeline.
+ There is usually no need to interact with the scheduler directly, however
+ it some cases it is feasable to set a specific clock or force a specific
+ plugin as the entry point in the pipeline.
</para>
</chapter>
<chapter id="cha-states">
<title>Element states</title>
<para>
- One you have created a pipeline packed with elements, nothing will happen yet.
- This is where the different states come into play.
+ One you have created a pipeline packed with elements, nothing will
+ happen yet. This is where the different states come into play.
</para>
<sect1 id="sec-states">
</para>
<para>
- 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 internally go throught the intermediate states.
+ 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
+ internally go throught the intermediate states.
</para>
<para>
The state of an element can be changed with the following code:
</para>
<note>
<para>
- You can also go from the NULL to PLAYING state directly without going through the READY
- state. this is a shortcut, the framework will internally go through the READY and the
- PAUSED state for you.
+ You can also go from the NULL to PLAYING state directly without
+ going through the READY state. this is a shortcut, the framework
+ will internally go through the READY and the PAUSED state for you.
</para>
</note>
</sect1>
</para>
<note>
<para>
- The PAUSED state is available for temporarily freezing the pipeline.
- Elements will typically not free their resources in the PAUSED state.
- Use the NULL state if you want to stop the data flow permanantly.
+ The PAUSED state is available for temporarily freezing the pipeline.
+ Elements will typically not free their resources in the PAUSED state.
+ Use the NULL state if you want to stop the data flow permanantly.
</para>
</note>
<para>
</programlisting>
<para>
- The above program will create a thread with two elements in it. As soon as it is set to the
- PLAYING state, the thread will start to iterate itself. You never need to manually iterate a
- thread.
+ The above program will create a thread with two elements in it. As soon
+ as it is set to the PLAYING state, the thread will start to iterate
+ itself. You never need to manually iterate a thread.
</para>
<sect2>
<title>Constraints placed on the pipeline by the GstThread</title>
<para>
- Within the pipeline, everything is the same as in any other bin. The difference lies at the
- thread boundary, at the connection between the thread and the outside world (containing bin).
- Since GStreamer is fundamentally buffer-oriented rather than byte-oriented, the natural
- solution to this problem is an element that can "buffer" the buffers between the threads, in a
- thread-safe fashion. This element is the queue, described more fully in <xref
- linkend="cha-queues"/>. It doesn't matter if the queue is placed in the containing bin or in
- the thread itself, but it needs to be present on one side of the other to enable inter-thread
- communication.
+ Within the pipeline, everything is the same as in any other bin. The
+ difference lies at the thread boundary, at the connection between the
+ thread and the outside world (containing bin). Since GStreamer is
+ fundamentally buffer-oriented rather than byte-oriented, the natural
+ solution to this problem is an element that can "buffer" the buffers
+ between the threads, in a thread-safe fashion. This element is the
+ queue, described more fully in <xref linkend="cha-queues"/>. It doesn't
+ matter if the queue is placed in the containing bin or in the thread
+ itself, but it needs to be present on one side of the other to enable
+ inter-thread communication.
</para>
</sect2>
<sect2>
<chapter id="cha-typedetection">
<title>Typedetection</title>
<para>
- Sometimes the capabilities of a pad are not specificied. The filesrc, for
- example, does not know what type of file it is reading. Before you can attach
- an element to the pad of the filesrc, you need to determine the media type in
- order to be able to choose a compatible element.
+ Sometimes the capabilities of a pad are not specificied. The filesrc,
+ for example, does not know what type of file it is reading. Before you
+ can attach an element to the pad of the filesrc, you need to determine
+ the media type in order to be able to choose a compatible element.
</para>
<para>
To solve this problem, a plugin can provide the <application>GStreamer</application>
}
</programlisting>
<para>
- We create a very simple pipeline with only a filesrc and the typefind element
- in it. The sinkpad of the typefind element has been connected to the src pad
- of the filesrc.
+ We create a very simple pipeline with only a filesrc and the typefind
+ element in it. The sinkpad of the typefind element has been connected
+ to the src pad of the filesrc.
</para>
<para>
We attached a signal 'have_type' to the typefind element which will be called
when the type of the media stream as been detected.
</para>
<para>
- the typefind function will loop over all the registered types and will execute
- each of the typefind functions. As soon as a function returns a GstCaps pointer,
- the type_found function will be called:
+ the typefind function will loop over all the registered types and will
+ execute each of the typefind functions. As soon as a function returns
+ a GstCaps pointer, the type_found function will be called:
</para>
<programlisting>
<title>Turning GstElements into XML</title>
<para>
- We create a simple pipeline and write it to stdout with gst_xml_write_file (). The following
- code constructs an mp3 player pipeline with two threads and then writes out the XML both to
- stdout and to a file. Use this program with one argument: the mp3 file on disk.
+ We create a simple pipeline and write it to stdout with
+ gst_xml_write_file (). The following code constructs an mp3 player
+ pipeline with two threads and then writes out the XML both to stdout
+ and to a file. Use this program with one argument: the mp3 file on disk.
</para>
<programlisting>
<para>
In addition to loading a file, you can also load a from a xmlDocPtr and
an in memory buffer using gst_xml_parse_doc and gst_xml_parse_memory
- respectivily. both of these methods return a gboolean indicating success
- or failure of the requested action.
+ respectivily. both of these methods return a gboolean indicating
+ success or failure of the requested action.
</para>
</sect1>
<sect1 id="sec-xml-custom">
<para>
It is possible to add custom XML tags to the core XML created with
gst_xml_write. This feature can be used by an application to add more
- information to the save plugins. the editor will for example insert
+ information to the save plugins. the editor will for example insert
the position of the elements on the screen using the custom XML tags.
</para>
<para>
</programlisting>
<para>
- Whenever a new object has been loaded, the xml_loaded function will be
- called. this function looks like:
+ Whenever a new object has been loaded, the xml_loaded function will
+ be called. this function looks like:
</para>
<programlisting>
static void
projects / platform / upstream / gstreamer.git / commitdiff