diff --git a/docs/manual/factories.sgml b/docs/manual/factories.sgml new file mode 100644 index 0000000000..d9423325c0 --- /dev/null +++ b/docs/manual/factories.sgml @@ -0,0 +1,280 @@ + + More on factories + + 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. + + + + The problems with the helloworld example + + If we take a look at how the elements were created in the previous + example we used a rather crude mechanism: + + + + ... + /* now it's time to get the parser */ + parse = gst_elementfactory_make("mp3parse","parse"); + decoder = gst_elementfactory_make("mpg123","decoder"); + ... + + + + 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. + + + We have to introduce the concept of MIME types added to the source and + sink pads. + + + + + MIME Types + + 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. + + + A MIME (Multipurpose Internet Mail Extension) types are a set of + string that donote a certain type of data. examples include: + + + + audio/raw : raw audio samples + + + + + audio/mpeg : mpeg audio + + + + + video/mpeg : mpeg video + + + + + + 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. + + + + In our helloworld example the elements we constructed would have the + following MIME types associated with their source and sink pads: + +
+ The Hello world pipeline with MIME types + +
+ + 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. + + + 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". + + + + 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. + + + + + + + GStreamer types + + 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. + + + There is also an association between a MIME type and a file + extension. + + + The type information is maintained in a list of + GstType. The definition of a + GstType is like: + + +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 */ +}; + + + All operations on GstType occur via their + guint16 id numbers, with GstType + structure private to the GStreamer library. + + + + MIME type to id conversion + + + We can obtain the id for a given MIME type + with the following piece of code: + + + guint16 id; + + id = gst_type_find_by_mime("audio/mpeg"); + + + This function will return 0 if the type was not known. + + + + + id to <classname>GstType</classname> conversion + + We can obtain the GstType for a given id + with the following piece of code: + + + GstType *type; + + type = gst_type_find_by_id(id); + + + This function will return NULL if the id was associated with + any known GstType + + + + + extension to id conversion + + We can obtain the id for a given file extension + with the following piece of code: + + + guint16 id; + + id = gst_type_find_by_ext(".mp3"); + + + This function will return 0 if the extension was not known. + + + + + id to <classname>GstElement</classname> conversion + + 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. + + + Obtain a list of all the elements that use this id as source with: + + + GList *list; + + list = gst_type_gst_srcs(id); + + + + Obtain a list of all the elements that use this id as sink with: + + + GList *list; + + list = gst_type_gst_sinks(id); + + + When you have a list of elements, you can simply take the first + element of the list to obtain an appropriate element. + + + + As you can see, there might be a multitude of elements that + are able to operate on video/raw types. some might include: + + + + an MP3 audio encoder. + + + + + an audio sink. + + + + + an audio resampler. + + + + + a spectrum filter. + + + + Depending on the application, you might want to use a different + element. This is why GStreamer leaves that decision up to the + application programmer. + + + + + + + GStreamer basic types + + GStreamer only has two builtin types: + + + + + audio/raw : raw audio samples + + + + + video/raw and image/raw : raw video data + + + + + All other MIME types are maintained by the plugin elements. + + + + diff --git a/docs/manual/fig/mime-world.fig b/docs/manual/fig/mime-world.fig new file mode 100644 index 0000000000..61814797c8 --- /dev/null +++ b/docs/manual/fig/mime-world.fig @@ -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 diff --git a/docs/manual/gstreamer-manual.sgml b/docs/manual/gstreamer-manual.sgml index 635e9f70c2..c80881776c 100644 --- a/docs/manual/gstreamer-manual.sgml +++ b/docs/manual/gstreamer-manual.sgml @@ -10,6 +10,7 @@ + ]> @@ -107,6 +108,8 @@ &HELLOWORLD; + &FACTORIES; + diff --git a/docs/manual/helloworld.sgml b/docs/manual/helloworld.sgml index ab47368299..9b8709774e 100644 --- a/docs/manual/helloworld.sgml +++ b/docs/manual/helloworld.sgml @@ -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. diff --git a/docs/manual/outline.txt b/docs/manual/outline.txt index 092c19a89f..3cbe975562 100644 --- a/docs/manual/outline.txt +++ b/docs/manual/outline.txt @@ -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