docs/manual/advanced-autoplugging.xml

   1 <chapter id="cha-factories">
   2   <title>More on factories</title>
   3   <para>
   4     The small application we created in the previous chapter used the
   5     concept of a factory to create the elements. In this chapter we will
   6     show you how to use the factory concepts to create elements based
   7     on what they do instead of how they are called.
   8   </para>
   9
  10   <para>
  11     We will first explain the concepts involved before we move on
  12     to the reworked helloworld example using autoplugging.
  13   </para>
  14   <sect1>
  15     <title>The problems with the helloworld example</title>
  16     <para>
  17       If we take a look at how the elements were created in the previous
  18       example we used a rather crude mechanism:
  19     </para>
  20
  21     <programlisting>
  22   ...
  23   /* now it's time to get the parser */
  24   parse = gst_elementfactory_make ("mp3parse", "parse");
  25   decoder = gst_elementfactory_make ("mpg123", "decoder");
  26   ...
  27     </programlisting>
  28
  29     <para>
  30       While this mechanism is quite effective it also has some big problems:
  31       The elements are created based on their name. Indeed, we create an
  32       element mpg123 by explicitly stating the mpg123 elements name.
  33       Our little program therefore always uses the mpg123 decoder element
  34       to decode the MP3 audio stream, even if there are 3 other MP3 decoders
  35       in the system. We will see how we can use a more general way to create
  36       an MP3 decoder element.
  37     </para>
  38     <para>
  39       We have to introduce the concept of MIME types  and capabilities
  40       added to the source and sink pads.
  41     </para>
  42   </sect1>
  43
  44   <sect1>
  45     <title>more on MIME Types</title>
  46     <para>
  47       GStreamer uses MIME types to indentify the different types of data
  48       that can be handled by the elements. They are the high level
  49       mechanisms to make sure that everyone is talking about the right
  50       kind of data.
  51     </para>
  52     <para>
  53       A MIME (Multipurpose Internet Mail Extension) types are a set of
  54       string that denote a certain type of data. examples include:
  55       <itemizedlist>
  56         <listitem>
  57           <para>
  58             audio/raw : raw audio samples
  59           </para>
  60         </listitem>
  61         <listitem>
  62           <para>
  63             audio/mpeg : mpeg audio
  64           </para>
  65         </listitem>
  66         <listitem>
  67           <para>
  68             video/mpeg : mpeg video
  69           </para>
  70         </listitem>
  71       </itemizedlist>
  72     </para>
  73     <para>
  74       An element must associate a MIME type to its source and sink pads
  75       when it is loaded into the system. GStreamer knows about the
  76       different elements and what type of data they expect and emit.
  77       This allows for very dynamic and extensible element creation as we
  78       will see.
  79     </para>
  80     <para>
  81       As we have seen in the previous chapter, the MIME types are added
  82       to the Capability structure of a pad.
  83     </para>
  84
  85     <para>
  86       In our helloworld example the elements we constructed would have the
  87       following MIME types associated with their source and sink pads:
  88     </para>
  89     <figure float="1" id="sec-mime-img">
  90       <title>The Hello world pipeline with MIME types</title>
  91       <mediaobject>
  92         <imageobject>
  93           <imagedata fileref="images/mime-world.&magic;" format="&magic;" />
  94         </imageobject>
  95       </mediaobject>
  96
  97     </figure>
  98     <para>
  99       We will see how you can create an element based on the MIME types
 100       of its source and sink pads. This way the end-user will have the
 101       ability to choose his/her favorite audio/mpeg decoder without
 102       you even having to care about it.
 103     </para>
 104     <para>
 105       The typing of the source and sink pads also makes it possible to
 106       'autoplug' a pipeline. We will have the ability to say: "construct
 107       me a pipeline that does an audio/mpeg to audio/raw conversion".
 108     </para>
 109     <note>
 110       <para>
 111         The basic GStreamer library does not try to solve all of your
 112         autoplug problems. It leaves the hard decisions to the application
 113         programmer, where they belong.
 114       </para>
 115     </note>
 116
 117   </sect1>
 118
 119   <sect1>
 120     <title>GStreamer types</title>
 121     <para>
 122       GStreamer assigns a unique number to all registered MIME types.
 123       GStreamer also keeps a reference to
 124       a function that can be used to determine if a given buffer is of
 125       the given MIME type.
 126     </para>
 127     <para>
 128       There is also an association between a MIME type and a file
 129       extension.
 130     </para>
 131     <para>
 132       The type information is maintained in a list of
 133       <classname>GstType</classname>. The definition of a
 134       <classname>GstType</classname> is like:
 135     </para>
 136     <programlisting>
 137 typedef GstCaps (*GstTypeFindFunc) (GstBuffer *buf,gpointer *priv);
 138
 139 typedef struct _GstType GstType;
 140
 141 struct _GstType {
 142   guint16 id;                   /* type id (assigned) */
 143
 144   gchar *mime;                  /* MIME type */
 145   gchar *exts;                  /* space-delimited list of extensions */
 146
 147   GstTypeFindFunc typefindfunc; /* typefind function */
 148 };
 149     </programlisting>
 150     <para>
 151       All operations on <classname>GstType</classname> occur via their
 152       <classname>guint16 id</classname> numbers, with <classname>GstType</classname>
 153       structure private to the GStreamer library.
 154     </para>
 155
 156     <sect2>
 157     <title>MIME type to id conversion</title>
 158
 159       <para>
 160         We can obtain the id for a given MIME type
 161         with the following piece of code:
 162       </para>
 163       <programlisting>
 164   guint16 id;
 165
 166   id = gst_type_find_by_mime ("audio/mpeg");
 167       </programlisting>
 168       <para>
 169         This function will return 0 if the type was not known.
 170       </para>
 171     </sect2>
 172
 173     <sect2>
 174     <title>id to <classname>GstType</classname> conversion</title>
 175       <para>
 176         We can obtain the <classname>GstType</classname> for a given id
 177         with the following piece of code:
 178       </para>
 179       <programlisting>
 180   GstType *type;
 181
 182   type = gst_type_find_by_id (id);
 183       </programlisting>
 184       <para>
 185         This function will return NULL if the id was associated with
 186         any known <classname>GstType</classname>
 187       </para>
 188     </sect2>
 189
 190     <sect2>
 191     <title>extension to id conversion</title>
 192       <para>
 193         We can obtain the id for a given file extension
 194         with the following piece of code:
 195       </para>
 196       <programlisting>
 197   guint16 id;
 198
 199   id = gst_type_find_by_ext (".mp3");
 200       </programlisting>
 201       <para>
 202         This function will return 0 if the extension was not known.
 203       </para>
 204     </sect2>
 205
 206     <sect2>
 207       <title>id to <classname>GstElementFactory</classname> conversion</title>
 208       <para>
 209         When we have obtained a given type id using one of the above methods,
 210         we can obtain a list of all the elements that operate on this MIME
 211         type or extension.
 212       </para>
 213       <para>
 214         Obtain a list of all the elements that use this id as source with:
 215       </para>
 216       <programlisting>
 217   GList *list;
 218
 219   list = gst_type_gst_srcs (id);
 220       </programlisting>
 221
 222       <para>
 223         Obtain a list of all the elements that use this id as sink with:
 224       </para>
 225       <programlisting>
 226   GList *list;
 227
 228   list = gst_type_gst_sinks (id);
 229       </programlisting>
 230       <para>
 231         When you have a list of elements, you can simply take the first
 232         element of the list to obtain an appropriate element.
 233       </para>
 234       <note>
 235         <para>
 236           As you can see, there might be a multitude of elements that
 237           are able to operate on audio/raw types. some might include:
 238           <itemizedlist>
 239             <listitem>
 240               <para>
 241                 an MP3 audio encoder.
 242               </para>
 243             </listitem>
 244             <listitem>
 245               <para>
 246                 an audio sink.
 247               </para>
 248             </listitem>
 249             <listitem>
 250               <para>
 251                 an audio resampler.
 252               </para>
 253             </listitem>
 254             <listitem>
 255               <para>
 256                 a spectrum filter.
 257               </para>
 258             </listitem>
 259           </itemizedlist>
 260           Depending on the application, you might want to use a different
 261           element. This is why GStreamer leaves that decision up to the
 262           application programmer.
 263         </para>
 264       </note>
 265
 266     </sect2>
 267
 268     <sect2>
 269       <title>id to id path detection</title>
 270       <para>
 271         You can obtain a <classname>GList</classname> of elements that
 272         will transform the source id into the destination id.
 273       </para>
 274       <programlisting>
 275   GList *list;
 276
 277   list = gst_type_gst_sink_to_src (sourceid, sinkid);
 278       </programlisting>
 279       <para>
 280         This piece of code will give you the elements needed to construct
 281         a path from sourceid to sinkid. This function is mainly used in
 282         autoplugging the pipeline.
 283       </para>
 284     </sect2>
 285   </sect1>
 286
 287   <sect1>
 288     <title>creating elements with the factory</title>
 289     <para>
 290       In the previous section we described how you could obtain
 291       an element factory using MIME types. One the factory has been
 292       obtained, you can create an element using:
 293     </para>
 294     <programlisting>
 295   GstElementFactory *factory;
 296   GstElement *element;
 297
 298   // obtain the factory
 299   factory = ...
 300
 301   element = gst_elementfactory_create (factory, "name");
 302     </programlisting>
 303     <para>
 304       This way, you do not have to create elements by name which
 305       allows the end-user to select the elements he/she prefers for the
 306       given MIME types.
 307     </para>
 308   </sect1>
 309
 310   <sect1>
 311     <title>GStreamer basic types</title>
 312     <para>
 313       GStreamer only has two builtin types:
 314     </para>
 315     <itemizedlist>
 316       <listitem>
 317         <para>
 318           audio/raw : raw audio samples
 319         </para>
 320       </listitem>
 321       <listitem>
 322         <para>
 323           video/raw and image/raw : raw video data
 324         </para>
 325       </listitem>
 326     </itemizedlist>
 327     <para>
 328       All other MIME types are maintained by the plugin elements.
 329     </para>
 330
 331   </sect1>
 332 </chapter>