docs/gst/tmpl/gsttype.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstType
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Identifies the data
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GstTypes exist to try to make sure data eveyrone is talking about the
  10 right kind of data.  They aid quite a bit in autoplugging, in fact make it
  11 possible.  Each well-formed type includes a function (typefind) that will
  12 take one or more buffers and determine whether or not it is indeed a
  13 stream of that type, and possible a metadata to go with it.  It may
  14 provide related metadata structure IDs (and must if it provides metadata
  15 from the typefind function).
  16 </para>
  17
  18 <para>
  19 Because multiple elements and plugins are very likely to be using the same
  20 types, the process of creating/finding types is designed to be done with a
  21 single function call.  All operations on GstTypes occur via their guint16
  22 ID numbers, with the GstType structure "private" to the GST library.  A
  23 plugin wishing to use a give type would contain a static struct of type
  24 GstTypeFactory, which lists the MIME type, possible extensions (which may
  25 overlap the mime-types file), a typefind function, and any other cruft I
  26 decide to add.
  27 </para>
  28
  29 <para>
  30 A plugin init function would take this typefactory and hand it to the
  31 gst_type_new() (FIXME: badly named) function, which would first search for
  32 that same MIME type in the current list.  If it found one, it would
  33 compare the two to see if the new one is "better".  Better is defined as
  34 having more extentions (to be merged) or a typefind function verses none.
  35 </para>
  36
  37 <para>
  38 The point of returning an existing MIME type is a result of the goal of
  39 unifying types enough to guarantee that, for instance, all MP3 decoders
  40 will work interchangably.  If MP3 decoder A says "MIME type 'audio/mpeg'
  41 with extensions 'mpeg3'" and decoder B says "MIME type 'audio/mpeg' with
  42 extensions 'mp3'", we don't want to have two types defined, possibly with
  43 two typefind functions. If we did, it's not obvious which of the two would
  44 be tried first (luck) and if both would really identify streams as mp3
  45 correctly in all cases.  And whichever wins, we're stuck using the
  46 associated decoder to play that stream.  We lose the choice between any
  47 valid mp3 decoder, and thus the whole point of the type system.
  48 </para>
  49
  50 <!-- ##### SECTION See_Also ##### -->
  51 <para>
  52
  53 </para>
  54
  55 <!-- ##### USER_FUNCTION GstTypeFindFunc ##### -->
  56 <para>
  57 This is the function that will be called when a typefind has to be
  58 performed by a plugin.
  59 </para>
  60
  61 @buf: the buffer with media on which to perform the typefind
  62 @priv: private; don't touch
  63 @Returns: a boolean indicating if the typedetection was successfull
  64
  65
  66 <!-- ##### STRUCT GstType ##### -->
  67 <para>
  68 A type.
  69 </para>
  70
  71 @id:
  72 @mime:
  73 @exts:
  74 @factories:
  75
  76 <!-- ##### STRUCT GstTypeFactory ##### -->
  77 <para>
  78 The struct with the typefactory information.
  79 </para>
  80
  81 @feature:
  82 @mime:
  83 @exts:
  84 @typefindfunc:
  85
  86 <!-- ##### FUNCTION gst_type_register ##### -->
  87 <para>
  88
  89 </para>
  90
  91 @factory:
  92 @Returns:
  93
  94
  95 <!-- ##### FUNCTION gst_type_find_by_mime ##### -->
  96 <para>
  97
  98 </para>
  99
 100 @mime:
 101 @Returns:
 102
 103
 104 <!-- ##### FUNCTION gst_type_find_by_ext ##### -->
 105 <para>
 106
 107 </para>
 108
 109 @ext:
 110 @Returns:
 111
 112
 113 <!-- ##### FUNCTION gst_type_find_by_id ##### -->
 114 <para>
 115
 116 </para>
 117
 118 @id:
 119 @Returns:
 120
 121
 122 <!-- ##### FUNCTION gst_type_get_list ##### -->
 123 <para>
 124
 125 </para>
 126
 127 @Returns:
 128
 129