docs/manual/factories.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 what 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   decoder = gst_element_factory_make ("mad", "decoder");
  25   ...
  26     </programlisting>
  27
  28     <para>
  29       While this mechanism is quite effective it also has some big problems:
  30       The elements are created based on their name. Indeed, we create an
  31       element, mad, by explicitly stating the mad element's name.  Our little
  32       program therefore always uses the mad decoder element to decode
  33       the MP3 audio stream, even if there are three other MP3 decoders in the
  34       system. We will see how we can use a more general way to create an
  35       MP3 decoder element.
  36     </para>
  37     <para>
  38       We have to introduce the concept of MIME types and capabilities
  39       added to the source and sink pads.
  40     </para>
  41   </sect1>
  42
  43   <sect1>
  44     <title>More on MIME Types</title>
  45     <para>
  46       GStreamer uses MIME types to identify the different types of data
  47       that can be handled by the elements. They are the high level
  48       mechanisms to make sure that everyone is talking about the right
  49       kind of data.
  50     </para>
  51     <para>
  52       A MIME (Multipurpose Internet Mail Extension) type is a pair of
  53       strings that denote a certain type of data. Examples include:
  54       <itemizedlist>
  55         <listitem>
  56           <para>
  57             audio/raw : raw audio samples
  58           </para>
  59         </listitem>
  60         <listitem>
  61           <para>
  62             audio/mpeg : MPEG audio
  63           </para>
  64         </listitem>
  65         <listitem>
  66           <para>
  67             video/mpeg : MPEG video
  68           </para>
  69         </listitem>
  70       </itemizedlist>
  71     </para>
  72     <para>
  73       An element must associate a MIME type to its source and sink pads
  74       when it is loaded into the system. GStreamer knows about the
  75       different elements and what type of data they expect and emit.
  76       This allows for very dynamic and extensible element creation as we
  77       will see.
  78     </para>
  79     <para>
  80       As we have seen in the previous chapter, MIME types are added
  81       to the Capability structure of a pad.
  82     </para>
  83
  84     <para>
  85       In our helloworld example the elements we constructed would have the
  86       following MIME types associated with their source and sink pads:
  87     </para>
  88     <figure float="1" id="sec-mime-img">
  89       <title>The Hello world pipeline with MIME types</title>
  90       <mediaobject>
  91         <imageobject>
  92           <imagedata fileref="images/mime-world.&magic;" format="&MAGIC;" />
  93         </imageobject>
  94       </mediaobject>
  95
  96     </figure>
  97     <para>
  98       We will see how you can create an element based on the MIME types
  99       of its source and sink pads. This way the end-user will have the
 100       ability to choose his/her favorite audio/mpeg decoder without
 101       you even having to care about it.
 102     </para>
 103     <para>
 104       The typing of the source and sink pads also makes it possible to
 105       'autoplug' a pipeline. We will have the ability to say: "construct
 106       me a pipeline that does an audio/mpeg to audio/raw conversion".
 107     </para>
 108     <note>
 109       <para>
 110         The basic GStreamer library does not try to solve all of your
 111         autoplug problems. It leaves the hard decisions to the application
 112         programmer, where they belong.
 113       </para>
 114     </note>
 115
 116   </sect1>
 117
 118   <sect1>
 119     <title>GStreamer types</title>
 120     <para>
 121       GStreamer assigns a unique number to all registered MIME types.
 122       GStreamer also keeps a reference to
 123       a function that can be used to determine if a given buffer is of
 124       the given MIME type.
 125     </para>
 126     <para>
 127       There is also an association between a MIME type and a file extension,
 128       but the use of typefind functions (similar to file(1)) is preferred.
 129     </para>
 130     <para>
 131       The type information is maintained in a list of
 132       <classname>GstType</classname>. The definition of a
 133       <classname>GstType</classname> is like:
 134     </para>
 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     <para>
 152       All operations on <classname>GstType</classname> occur
 153       via their <classname>guint16 id</classname> numbers, with
 154       the <classname>GstType</classname> structure private to the GStreamer
 155       library.
 156     </para>
 157
 158     <sect2>
 159     <title>MIME type to id conversion</title>
 160
 161       <para>
 162         We can obtain the id for a given MIME type
 163         with the following piece of code:
 164       </para>
 165       <programlisting>
 166   guint16 id;
 167
 168   id = gst_type_find_by_mime ("audio/mpeg");
 169       </programlisting>
 170       <para>
 171         This function will return 0 if the type was not known.
 172       </para>
 173     </sect2>
 174
 175     <sect2>
 176     <title>id to <classname>GstType</classname> conversion</title>
 177       <para>
 178         We can obtain the <classname>GstType</classname> for a given id
 179         with the following piece of code:
 180       </para>
 181       <programlisting>
 182   GstType *type;
 183
 184   type = gst_type_find_by_id (id);
 185       </programlisting>
 186       <para>
 187         This function will return NULL if the id was not associated with
 188         any known <classname>GstType</classname>
 189       </para>
 190     </sect2>
 191
 192     <sect2>
 193     <title>extension to id conversion</title>
 194       <para>
 195         We can obtain the id for a given file extension
 196         with the following piece of code:
 197       </para>
 198       <programlisting>
 199   guint16 id;
 200
 201   id = gst_type_find_by_ext (".mp3");
 202       </programlisting>
 203       <para>
 204         This function will return 0 if the extension was not known.
 205       </para>
 206       <para>
 207         For more information, see <xref linkend="cha-autoplug"/>.
 208       </para>
 209     </sect2>
 210   </sect1>
 211
 212   <sect1>
 213     <title>Creating elements with the factory</title>
 214     <para>
 215       In the previous section we described how you could obtain
 216       an element factory using MIME types. One the factory has been
 217       obtained, you can create an element using:
 218     </para>
 219     <programlisting>
 220   GstElementFactory *factory;
 221   GstElement *element;
 222
 223   // obtain the factory
 224   factory = ...
 225
 226   element = gst_element_factory_create (factory, "name");
 227     </programlisting>
 228     <para>
 229       This way, you do not have to create elements by name which
 230       allows the end-user to select the elements he/she prefers for the
 231       given MIME types.
 232     </para>
 233   </sect1>
 234
 235   <sect1>
 236     <title>GStreamer basic types</title>
 237     <para>
 238       GStreamer only has two builtin types:
 239     </para>
 240     <itemizedlist>
 241       <listitem>
 242         <para>
 243           audio/raw : raw audio samples
 244         </para>
 245       </listitem>
 246       <listitem>
 247         <para>
 248           video/raw and image/raw : raw video data
 249         </para>
 250       </listitem>
 251     </itemizedlist>
 252     <para>
 253       All other MIME types are maintained by the plugin elements.
 254     </para>
 255
 256   </sect1>
 257 </chapter>