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>
|
||||
|
||||
* 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>
|
||||
|
||||
<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:
|
||||
</para>
|
||||
<figure float="1" id="section-hello-img">
|
||||
|
|
@ -265,9 +265,8 @@ main (int argc, char *argv[])
|
|||
</para>
|
||||
<para>
|
||||
It should be clear from the example that we can very easily replace the
|
||||
filesrc element with an httpsrc element, giving you instant network
|
||||
streaming. An element could be built to handle icecast connections,
|
||||
for example.
|
||||
filesrc element with the gnomevfssrc element, giving you instant streaming
|
||||
from any gnomevfs URL.
|
||||
</para>
|
||||
<para>
|
||||
We can also choose to use another type of sink instead of the audiosink.
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@
|
|||
|
||||
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);
|
||||
...
|
||||
</programlisting>
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@
|
|||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
audio/raw : raw audio samples
|
||||
audio/x-raw-int : raw audio samples
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
|
|
@ -103,7 +103,7 @@
|
|||
<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".
|
||||
a pipeline that does an audio/mpeg to audio/x-raw-int conversion".
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -174,7 +174,7 @@ main (int argc, char *argv[])
|
|||
</programlisting>
|
||||
|
||||
<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:
|
||||
</para>
|
||||
<figure float="1" id="section-hello-img">
|
||||
|
|
@ -265,9 +265,8 @@ main (int argc, char *argv[])
|
|||
</para>
|
||||
<para>
|
||||
It should be clear from the example that we can very easily replace the
|
||||
filesrc element with an httpsrc element, giving you instant network
|
||||
streaming. An element could be built to handle icecast connections,
|
||||
for example.
|
||||
filesrc element with the gnomevfssrc element, giving you instant streaming
|
||||
from any gnomevfs URL.
|
||||
</para>
|
||||
<para>
|
||||
We can also choose to use another type of sink instead of the audiosink.
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@
|
|||
|
||||
</programlisting>
|
||||
<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:
|
||||
</para>
|
||||
<programlisting>
|
||||
|
|
@ -46,7 +46,8 @@
|
|||
</programlisting>
|
||||
<para>
|
||||
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>
|
||||
<programlisting>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue