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
parent
cf0a34528d
commit
78a7023543
280
docs/manual/factories.sgml
Normal file
280
docs/manual/factories.sgml
Normal 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>
|
||||
162
docs/manual/fig/mime-world.fig
Normal file
162
docs/manual/fig/mime-world.fig
Normal 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
|
||||
@ -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 ############# -->
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user