mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-01-22 15:18:21 +00:00
docs/manual/: fixes for out of date info, incorrect info and grammar
Original commit message from CVS: 2004-07-16 Zaheer Abbas Merali <zaheerabbas at merali dot org> * docs/manual/bins-api.xml: * docs/manual/factories.xml: * docs/manual/helloworld.xml: * docs/manual/links-api.xml: fixes for out of date info, incorrect info and grammar
This commit is contained in:
Zaheer Abbas Merali
parent
e684907eb2
commit
895f68b86b
7 changed files with 20 additions and 270 deletions
|
|
@ -1,3 +1,11 @@
|
||||||
|
2004-07-16 Zaheer Abbas Merali <zaheerabbas at merali dot org>
|
||||||
|
|
||||||
|
* docs/manual/bins-api.xml:
|
||||||
|
* docs/manual/factories.xml:
|
||||||
|
* docs/manual/helloworld.xml:
|
||||||
|
* docs/manual/links-api.xml:
|
||||||
|
fixes for out of date info, incorrect info and grammar
|
||||||
|
|
||||||
2004-07-15 Zaheer Abbas Merali <zaheerabbas at merali dot>
|
2004-07-15 Zaheer Abbas Merali <zaheerabbas at merali dot>
|
||||||
|
|
||||||
* docs/manual/pads.xml:
|
* docs/manual/pads.xml:
|
||||||
|
|
|
||||||
|
|
@ -1,257 +0,0 @@
|
||||||
<chapter id="chapter-factories">
|
|
||||||
<title>More on factories</title>
|
|
||||||
<para>
|
|
||||||
The small application we created in the previous chapter used the
|
|
||||||
concept of a factory to create the elements. In this chapter we will
|
|
||||||
show you how to use the factory concepts to create elements based
|
|
||||||
on what they do instead of what they are called.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
We will first explain the concepts involved before we move on
|
|
||||||
to the reworked helloworld example using autoplugging.
|
|
||||||
</para>
|
|
||||||
<sect1 id="section-factories-helloworld-problems">
|
|
||||||
<title>The problems with the helloworld example</title>
|
|
||||||
<para>
|
|
||||||
If we take a look at how the elements were created in the previous
|
|
||||||
example we used a rather crude mechanism:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
...
|
|
||||||
/* now it's time to get the parser */
|
|
||||||
decoder = gst_element_factory_make ("mad", "decoder");
|
|
||||||
...
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
<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 three 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
|
|
||||||
added to the source and sink pads.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="section-factories-mime">
|
|
||||||
<title>More on MIME Types</title>
|
|
||||||
<para>
|
|
||||||
GStreamer uses MIME types to identify the different types of data
|
|
||||||
that can be handled by the elements. They are the high level
|
|
||||||
mechanisms to make sure that everyone is talking about the right
|
|
||||||
kind of data.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
A MIME (Multipurpose Internet Mail Extension) type is a pair of
|
|
||||||
strings that denote a certain type of data. Examples include:
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
audio/raw : raw audio samples
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
audio/mpeg : MPEG audio
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
video/mpeg : MPEG video
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
An element must associate a MIME type to its source and sink pads
|
|
||||||
when it is loaded into the system. GStreamer knows about the
|
|
||||||
different elements and what type of data they expect and emit.
|
|
||||||
This allows for very dynamic and extensible element creation as we
|
|
||||||
will see.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
As we have seen in the previous chapter, MIME types are added
|
|
||||||
to the Capability structure of a pad.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<xref linkend="section-mime-img"/> shows the MIME types associated with
|
|
||||||
each pad from the "hello world" example.
|
|
||||||
</para>
|
|
||||||
<figure float="1" id="section-mime-img">
|
|
||||||
<title>The Hello world pipeline with MIME types</title>
|
|
||||||
<mediaobject>
|
|
||||||
<imageobject>
|
|
||||||
<imagedata fileref="images/mime-world.ℑ" format="&IMAGE;" />
|
|
||||||
</imageobject>
|
|
||||||
</mediaobject>
|
|
||||||
|
|
||||||
</figure>
|
|
||||||
<para>
|
|
||||||
We will see how you can create an element based on the MIME types
|
|
||||||
of its source and sink pads. This way the end-user will have the
|
|
||||||
ability to choose his/her favorite audio/mpeg decoder without
|
|
||||||
you even having to care about it.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The typing of the source and sink pads also makes it possible to
|
|
||||||
'autoplug' a pipeline. We will have the ability to say: "construct
|
|
||||||
a pipeline that does an audio/mpeg to audio/raw conversion".
|
|
||||||
</para>
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
The basic GStreamer library does not try to solve all of your
|
|
||||||
autoplug problems. It leaves the hard decisions to the application
|
|
||||||
programmer, where they belong.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="section-factories-gstreamer-types">
|
|
||||||
<title>GStreamer types</title>
|
|
||||||
<para>
|
|
||||||
GStreamer assigns a unique number to all registered MIME types.
|
|
||||||
GStreamer also keeps a reference to
|
|
||||||
a function that can be used to determine if a given buffer is of
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The type information is maintained in a list of
|
|
||||||
<classname>GstType</classname>. The definition of a
|
|
||||||
<classname>GstType</classname> is like:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<programlisting>
|
|
||||||
typedef GstCaps (*GstTypeFindFunc) (GstBuffer *buf,gpointer *priv);
|
|
||||||
|
|
||||||
typedef struct _GstType GstType;
|
|
||||||
|
|
||||||
struct _GstType {
|
|
||||||
guint16 id; /* type id (assigned) */
|
|
||||||
|
|
||||||
gchar *mime; /* MIME type */
|
|
||||||
gchar *exts; /* space-delimited list of extensions */
|
|
||||||
|
|
||||||
GstTypeFindFunc typefindfunc; /* typefind function */
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
All operations on <classname>GstType</classname> occur
|
|
||||||
via their <classname>guint16 id</classname> numbers, with
|
|
||||||
the <classname>GstType</classname> structure private to the GStreamer
|
|
||||||
library.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>MIME type to id conversion</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
We can obtain the id for a given MIME type
|
|
||||||
with the following piece of code:
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
guint16 id;
|
|
||||||
|
|
||||||
id = gst_type_find_by_mime ("audio/mpeg");
|
|
||||||
</programlisting>
|
|
||||||
<para>
|
|
||||||
This function will return 0 if the type was not known.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>id to <classname>GstType</classname> conversion</title>
|
|
||||||
<para>
|
|
||||||
We can obtain the <classname>GstType</classname> for a given id
|
|
||||||
with the following piece of code:
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
GstType *type;
|
|
||||||
|
|
||||||
type = gst_type_find_by_id (id);
|
|
||||||
</programlisting>
|
|
||||||
<para>
|
|
||||||
This function will return NULL if the id was not associated with
|
|
||||||
any known <classname>GstType</classname>
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2>
|
|
||||||
<title>extension to id conversion</title>
|
|
||||||
<para>
|
|
||||||
We can obtain the id for a given file extension
|
|
||||||
with the following piece of code:
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
guint16 id;
|
|
||||||
|
|
||||||
id = gst_type_find_by_ext (".mp3");
|
|
||||||
</programlisting>
|
|
||||||
<para>
|
|
||||||
This function will return 0 if the extension was not known.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
For more information, see <xref linkend="chapter-autoplug"/>.
|
|
||||||
</para>
|
|
||||||
</sect2>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="section-factories-create">
|
|
||||||
<title>Creating elements with the factory</title>
|
|
||||||
<para>
|
|
||||||
In the previous section we described how you could obtain
|
|
||||||
an element factory using MIME types. One the factory has been
|
|
||||||
obtained, you can create an element using:
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
GstElementFactory *factory;
|
|
||||||
GstElement *element;
|
|
||||||
|
|
||||||
// obtain the factory
|
|
||||||
factory = ...
|
|
||||||
|
|
||||||
element = gst_element_factory_create (factory, "name");
|
|
||||||
</programlisting>
|
|
||||||
<para>
|
|
||||||
This way, you do not have to create elements by name which
|
|
||||||
allows the end-user to select the elements he/she prefers for the
|
|
||||||
given MIME types.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="section-factories-basic-types">
|
|
||||||
<title>GStreamer basic types</title>
|
|
||||||
<para>
|
|
||||||
GStreamer only has two builtin types:
|
|
||||||
</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
audio/raw : raw audio samples
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
video/raw and image/raw : raw video data
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
<para>
|
|
||||||
All other MIME types are maintained by the plugin elements.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</sect1>
|
|
||||||
</chapter>
|
|
||||||
|
|
@ -174,7 +174,7 @@ main (int argc, char *argv[])
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
We now have a created a complete pipeline. We can visualise the
|
We now have created a complete pipeline. We can visualise the
|
||||||
pipeline as follows:
|
pipeline as follows:
|
||||||
</para>
|
</para>
|
||||||
<figure float="1" id="section-hello-img">
|
<figure float="1" id="section-hello-img">
|
||||||
|
|
@ -265,9 +265,8 @@ main (int argc, char *argv[])
|
||||||
</para>
|
</para>
|
||||||
<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 element, giving you instant network
|
filesrc element with the gnomevfssrc element, giving you instant streaming
|
||||||
streaming. An element could be built to handle icecast connections,
|
from any gnomevfs URL.
|
||||||
for example.
|
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
We can also choose to use another type of sink instead of the audiosink.
|
We can also choose to use another type of sink instead of the audiosink.
|
||||||
|
|
|
||||||
|
|
@ -33,7 +33,7 @@
|
||||||
|
|
||||||
bin = gst_bin_new ("mybin");
|
bin = gst_bin_new ("mybin");
|
||||||
|
|
||||||
element = gst_element_factory_make ("mpg123", "decoder");
|
element = gst_element_factory_make ("mad", "decoder");
|
||||||
gst_bin_add (GST_BIN (bin), element);
|
gst_bin_add (GST_BIN (bin), element);
|
||||||
...
|
...
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
|
||||||
|
|
@ -54,7 +54,7 @@
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
audio/raw : raw audio samples
|
audio/x-raw-int : raw audio samples
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
|
|
@ -103,7 +103,7 @@
|
||||||
<para>
|
<para>
|
||||||
The typing of the source and sink pads also makes it possible to
|
The typing of the source and sink pads also makes it possible to
|
||||||
'autoplug' a pipeline. We will have the ability to say: "construct
|
'autoplug' a pipeline. We will have the ability to say: "construct
|
||||||
a pipeline that does an audio/mpeg to audio/raw conversion".
|
a pipeline that does an audio/mpeg to audio/x-raw-int conversion".
|
||||||
</para>
|
</para>
|
||||||
<note>
|
<note>
|
||||||
<para>
|
<para>
|
||||||
|
|
|
||||||
|
|
@ -174,7 +174,7 @@ main (int argc, char *argv[])
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
We now have a created a complete pipeline. We can visualise the
|
We now have created a complete pipeline. We can visualise the
|
||||||
pipeline as follows:
|
pipeline as follows:
|
||||||
</para>
|
</para>
|
||||||
<figure float="1" id="section-hello-img">
|
<figure float="1" id="section-hello-img">
|
||||||
|
|
@ -265,9 +265,8 @@ main (int argc, char *argv[])
|
||||||
</para>
|
</para>
|
||||||
<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 element, giving you instant network
|
filesrc element with the gnomevfssrc element, giving you instant streaming
|
||||||
streaming. An element could be built to handle icecast connections,
|
from any gnomevfs URL.
|
||||||
for example.
|
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
We can also choose to use another type of sink instead of the audiosink.
|
We can also choose to use another type of sink instead of the audiosink.
|
||||||
|
|
|
||||||
|
|
@ -32,7 +32,7 @@
|
||||||
|
|
||||||
</programlisting>
|
</programlisting>
|
||||||
<para>
|
<para>
|
||||||
An even more convenient shortcut for single-source, single-sink elements is the
|
An even more convenient shortcut but only works for single-source, single-sink elements is the
|
||||||
gst_element_link () function:
|
gst_element_link () function:
|
||||||
</para>
|
</para>
|
||||||
<programlisting>
|
<programlisting>
|
||||||
|
|
@ -46,7 +46,8 @@
|
||||||
</programlisting>
|
</programlisting>
|
||||||
<para>
|
<para>
|
||||||
If you have more than one element to link, the gst_element_link_many () function takes
|
If you have more than one element to link, the gst_element_link_many () function takes
|
||||||
a NULL-terminated list of elements:
|
a NULL-terminated list of elements. Again this only works for single-source single-sink
|
||||||
|
elements:
|
||||||
</para>
|
</para>
|
||||||
<programlisting>
|
<programlisting>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue