More manual about MIME types and factories...

Original commit message from CVS:
More manual about MIME types and factories...
This commit is contained in:
Wim Taymans 2000-08-19 16:36:24 +00:00
parent cf0a34528d
commit 78a7023543
5 changed files with 449 additions and 3 deletions

280
docs/manual/factories.sgml Normal file
View file

@ -0,0 +1,280 @@
<chapter id="cha-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.
</para>
<sect1>
<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 */
parse = gst_elementfactory_make("mp3parse","parse");
decoder = gst_elementfactory_make("mpg123","decoder");
...
</programlisting>
<para>
While this mechanism is quite effective it also has one big problems:
The elements are created base on their name. Indeed, we create an
element mpg123 by explicitly stating the mpg123 elements name.
Our little program therefore always uses the mpg123 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 added to the source and
sink pads.
</para>
</sect1>
<sect1>
<title>MIME Types</title>
<para>
GStreamer uses MIME types to indentify 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) types are a set of
string that donote 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>
In our helloworld example the elements we constructed would have the
following MIME types associated with their source and sink pads:
</para>
<figure float="1" id="sec-mime-img">
<title>The Hello world pipeline with MIME types</title>
<graphic fileref="images/mime-world" format="png"></graphic>
</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
me 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>
<title>GStreamer types</title>
<para>
GStreamer assigns a unique number to all registered MIME types. It
also maintains a list of all elements that either uses this type
as a source or as a sink. 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.
</para>
<para>
The type information is maintained in a list of
<classname>GstType</classname>. The definition of a
<classname>GstType</classname> is like:
</para>
<programlisting>
typedef gboolean (*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 */
GList *srcs; /* list of src objects for this type */
GList *sinks; /* list of sink objects for type */
};
</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.
</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 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>
</sect2>
<sect2>
<title>id to <classname>GstElement</classname> conversion</title>
<para>
When we have obtained a given type id using one of the above methods,
we can obtain a list of all the elements that operate on this MIME
type or extension.
</para>
<para>
Obtain a list of all the elements that use this id as source with:
</para>
<programlisting>
GList *list;
list = gst_type_gst_srcs(id);
</programlisting>
<para>
Obtain a list of all the elements that use this id as sink with:
</para>
<programlisting>
GList *list;
list = gst_type_gst_sinks(id);
</programlisting>
<para>
When you have a list of elements, you can simply take the first
element of the list to obtain an appropriate element.
</para>
<note>
<para>
As you can see, there might be a multitude of elements that
are able to operate on video/raw types. some might include:
<itemizedlist>
<listitem>
<para>
an MP3 audio encoder.
</para>
</listitem>
<listitem>
<para>
an audio sink.
</para>
</listitem>
<listitem>
<para>
an audio resampler.
</para>
</listitem>
<listitem>
<para>
a spectrum filter.
</para>
</listitem>
</itemizedlist>
Depending on the application, you might want to use a different
element. This is why GStreamer leaves that decision up to the
application programmer.
</para>
</note>
</sect2>
</sect1>
<sect1>
<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>

View file

@ -0,0 +1,162 @@
#FIG 3.2
Landscape
Center
Inches
Letter
100.00
Single
-2
1200 2
0 32 #414141
0 33 #868286
0 34 #c7c3c7
0 35 #8e8e8e
0 36 #c7c3c7
0 37 #868286
0 38 #8e8e8e
0 39 #414141
0 40 #868286
0 41 #c7c3c7
0 42 #e7e3e7
0 43 #c7b696
0 44 #effbff
0 45 #dfcba6
0 46 #aeaaae
0 47 #515551
0 48 #8e8e8e
0 49 #414141
0 50 #868286
0 51 #c7c3c7
0 52 #e7e3e7
0 53 #414141
0 54 #868286
0 55 #c7c3c7
0 56 #e7e3e7
0 57 #868286
0 58 #c7c3c7
0 59 #e7e3e7
0 60 #414141
0 61 #868286
0 62 #c7c3c7
0 63 #414141
0 64 #c7c3c7
0 65 #e7e3e7
0 66 #414141
0 67 #868286
0 68 #c7c3c7
0 69 #8e8e8e
0 70 #414141
0 71 #868286
0 72 #c7c3c7
0 73 #e7e3e7
0 74 #414141
0 75 #868286
0 76 #c7c3c7
0 77 #e7e3e7
0 78 #414141
0 79 #868286
0 80 #c7c3c7
0 81 #e7e3e7
0 82 #cfcfcf
0 83 #868286
0 84 #c7c3c7
0 85 #e7e3e7
0 86 #8e8e8e
0 87 #8e8e8e
0 88 #8e8e8e
0 89 #8e8e8e
0 90 #414541
0 91 #8e8e8e
0 92 #8e8e8e
0 93 #868286
0 94 #c7c3c7
0 95 #8e8e8e
0 96 #8e8e8e
0 97 #414141
0 98 #c7c3c7
0 99 #e7e3e7
0 100 #effbff
0 101 #e7e3e7
0 102 #8e8e8e
0 103 #414541
0 104 #aeaaae
0 105 #8e8e8e
0 106 #414541
0 107 #aeaaae
0 108 #515551
0 109 #8e8e8e
0 110 #414541
0 111 #c7c3c7
0 112 #e7e3e7
0 113 #8e8e8e
0 114 #414541
0 115 #8e8e8e
0 116 #414541
0 117 #8e8e8e
0 118 #414541
0 119 #868286
0 120 #c7c3c7
0 121 #e7e3e7
0 122 #c7c3c7
0 123 #e7e3e7
0 124 #8e8e8e
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
2100 2775 4050 2775 4050 4425 2100 4425 2100 2775
2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
3300 3600 4050 3600 4050 4125 3300 4125 3300 3600
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
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
4575 2775 6525 2775 6525 4425 4575 4425 4575 2775
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
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
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
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
7125 2775 9075 2775 9075 4425 7125 4425 7125 2775
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
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
9600 2775 11550 2775 11550 4425 9600 4425 9600 2775
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
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
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
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1950 1950 11700 1950 11700 4800 1950 4800 1950 1950
2 1 1 1 0 7 50 0 -1 5.000 0 0 -1 0 0 2
3675 4050 3675 5250
2 1 1 1 0 7 50 0 -1 5.000 0 0 -1 0 0 2
4875 4050 4875 5250
2 1 1 1 0 7 50 0 -1 5.000 0 0 -1 0 0 2
6150 4050 6150 5475
2 1 1 1 0 7 50 0 -1 5.000 0 0 -1 0 0 2
7500 4050 7500 5250
2 1 1 1 0 7 50 0 -1 5.000 0 0 -1 0 0 2
8775 4050 8775 5475
2 1 1 1 0 7 50 0 -1 5.000 0 0 -1 0 0 2
9975 4050 9975 5250
4 0 0 50 0 16 12 0.0000 4 135 255 2175 2250 bin\001
4 0 0 50 0 16 12 0.0000 4 105 255 3525 3975 src\001
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 50 0 0 12 0.0000 4 135 75 3675 5475 ?\001
4 0 0 50 0 0 12 0.0000 4 135 735 9825 5475 audio/raw\001
4 0 0 50 0 0 12 0.0000 4 180 855 4350 5325 audio/mpeg\001
4 0 0 50 0 0 12 0.0000 4 180 1395 5475 5625 audio/mpeg-frame\001
4 0 0 50 0 0 12 0.0000 4 135 735 8700 5625 audio/raw\001
4 0 0 50 0 0 12 0.0000 4 180 1395 6825 5325 audio/mpeg-frame\001

View file

@ -10,6 +10,7 @@
<!ENTITY STATES SYSTEM "states.sgml">
<!ENTITY HELLOWORLD SYSTEM "helloworld.sgml">
<!ENTITY FACTORIES SYSTEM "factories.sgml">
]>
@ -107,6 +108,8 @@
&HELLOWORLD;
&FACTORIES;
</part>
<!-- ############ Advanced GStreamer - part ############# -->

View file

@ -354,7 +354,7 @@ void eos(GstSrc *src)
We could use a disksink to write the raw samples to a file, for example.
It should also be clear that inserting filters, like a stereo effect,
into the pipeline is not that hard to do. The most important thing is
that you can reuse allready existing codecs.
that you can reuse allready existing elements.
</para>

View file

@ -31,8 +31,8 @@ Basic concepts
connecting elements
bin
(can contain elements)
pipeline
(a complete graph)
pipeline (a complete graph)
thread (theaded operation)
buffers
(pass between elements)
(contains data)
@ -48,6 +48,7 @@ Building apps
helloworld
(fdsrc->mp3decoder->audiosink)
(step by step explanation)
More on factories
advanced concepts
threads