docs/random/types2

   1 OUTDATED
   2 --------
   3
   4
   5 1. Introduction
   6 ---------------
   7
   8 The type system is used to attach meaning to the bytes in a GstBuffer.
   9 A plugin can decide to add metadata to the GstBuffer, this metadata
  10 will carry an associated typeid.
  11
  12 Types are also used by the plugins to expose the type of their pads to
  13 the type system.
  14
  15 Types are essential for autoplugging.
  16
  17 We will explain the inner workings of the type system in this document, as
  18 well as the API used in the plugins.
  19
  20
  21 2. Type properties
  22 ------------------
  23
  24 a) identification of the type
  25
  26   Types are identified by one or more MIME types.
  27
  28 b) detection of types
  29
  30   The type of any given GstBuffer can be detected using
  31
  32     - a typefind function: a function that will inspect the bytes
  33            in the buffer and return a gboolean indicating the
  34            buffer is of the given type.
  35
  36     - a template for the bytes/bits in the data that must be
  37            satisfied in order for the GstBuffer to be of the given
  38            type.
  39
  40     - other properties that act more like a hint like:
  41            the extension of the source filename.
  42            the URI of the source.
  43
  44
  45 3. Type registration
  46 --------------------
  47
  48 a) the core libraries will create to types:
  49
  50    video/raw image/raw
  51    audio/raw
  52
  53 b) all other types will be provided by the plugins
  54
  55 before a type can become available to other plugins, the plugin
  56 has to register the type.
  57
  58 The system will keep a directed graph of the types and the plugins
  59 that operate on them.
  60
  61 example:
  62
  63                      video/mpeg
  64                          !
  65                      mpeg1parse
  66                       /     \
  67               video/mpeg1   audio/mp3 -----\
  68               !        !           \        !
  69          mpeg_play   mpeg2dec      mpg123   xing  ...
  70               \        /              \     /
  71               video/raw              audio/raw-----\
  72               !      !                   !         !
  73         videosink   SDLsink           audiosink    alsasink ...
  74
  75
  76 The system can find the needed plugins to convert video/mpeg to
  77 audio/raw using this graph.
  78
  79
  80 4. type equivalence
  81 -------------------
  82
  83 some types can have the same meaning for example:
  84
  85   audio/mp3 and audio/mpeg
  86
  87 or
  88
  89   video/raw and image/raw
  90
  91
  92 a plugin that exposes its output type as audio/mpeg and another plugins
  93 with input type audio/mp3 can be connected. The system has to know about
  94 the equivalence of both types, even it they have a different mime type.
  95
  96
  97 5. type hierarchy
  98 -----------------
  99
 100 some plugins can output a specific subset of an already existing type.
 101
 102 example:
 103
 104   mp3parse inputs audio/mp3 and packs the stream into mp3 audio frames
 105   with mime type: audio/mp3-frame
 106
 107   mpg123 only accepts audio/mp3-frame but not audio/mp3.
 108
 109   another mp3 decoder (libmpg123) can accept audio/mp3 (and thus also
 110   audio/mp3-frame)
 111
 112   it must be possible to connect both libmpg123 and mpg123 to the mp3parse
 113   element.
 114   it must not be possible to connect mpg123 to an element that outputs only
 115   audio/mp3 but not audio/mp3-frame.
 116
 117
 118 We say that audio/mp3-frame is a more specific subset of type audio/mp3.
 119
 120 we can create a type hierarchy:
 121
 122           audio/mp3
 123          /        \
 124   audio/mp3-frame  audio/mp3-layer12
 125                      /        \
 126            audio/mp3-layer1    audio/mp3-layer2
 127
 128
 129 6. multi-type pads
 130 ------------------
 131
 132 certain plugins might accept multiple non equivalent types in one of their
 133 input pads. Consequently a plugin might output non equivalent types in
 134 its output pad.
 135
 136 It must therefore be possible to specify multiple types for a pad.
 137
 138 example:
 139
 140   mpegdemux may be able to demux both MPEG1 and MPEG2 system streams.
 141   we show the type hierarchy of the video/mpeg as follows:
 142
 143                           video/mpeg
 144                          /        \
 145                video/mpeg1         video/mpeg2 ---------------\
 146                /    \                    /    \               !
 147       mpeg1-system*  mpeg1-video    mpeg2-ts   mpeg2-ps*    mpeg2-video
 148
 149
 150   the mpegdemux element might specify the type of the input pad as
 151   one of video/mpeg1-system and video/mpeg2-ts
 152
 153
 154
 155 7. definition of types
 156 ----------------------
 157
 158 A plugin will provide the following information to the type system:
 159
 160  - a mime type string describing the hierarchy and where the types
 161    they provide are located in that hierarchy.
 162
 163  - typefind functions for some of the types.
 164
 165  - extensions for some of the types
 166
 167 We will propose a syntax to define the type hierarchy
 168
 169 a) equivalent types :
 170
 171    separated with a | sign
 172
 173    ( audio/mp3 | audio/mpeg )
 174
 175 b) type hierarchy :
 176
 177    in braces:
 178
 179    ( audio/mp3 ( audio/mp3-frame))
 180
 181 c) multi-type pads
 182
 183   ( mpegdemux ( video/mpeg1-system + video/mpeg2-ps) )
 184
 185   the pad will have type mpegdemux which is the parent for
 186   type video/mpeg1-system or video/mpeg2-ps
 187
 188                   mpegdemux
 189                   /       \
 190  video/mpeg1-system      video/mpeg2-ps
 191
 192
 193
 194 once the type hierarchy has been registered, the typeid of each
 195 element can be obtained with:
 196
 197   guint16 gst_type_find_by_mime (gchar *mime)
 198
 199 extra typefind functions and/or extensions can be added to the
 200 typeid afterwards.
 201
 202
 203 8. type matching
 204 ----------------
 205
 206 The more specific typefind functions, the functions associated with
 207 types in the leaf nodes, are tried first.
 208
 209 when a specific type has been found ex. video/mpeg1-system elements
 210 that can handle this type or one of its parents are selected:
 211
 212   mpegdemux:                     mpeg1parse:                    supermpegdecoder:
 213
 214     video/mpeg                       video/mpeg                   video/mpeg
 215      !                                  !
 216     mpegdemux                        video/mpeg1-system
 217      !
 218     video/mpeg1-system
 219
 220 In the above case, also the super mpeg element is selected because it stated
 221 that it can handle all sorts of video/mpeg data.
 222
 223
 224 example 2:
 225
 226    suppose the typefind functions finds an mp3 stream, following elements
 227    are selected:
 228
 229        libmpg123              mp3parse:
 230
 231        audio/mp3              audio/mp3
 232
 233    mpg123 is not selected because its pad type is too specific (audio/mp3-frame):
 234
 235        mpg123
 236
 237        audio/mp3
 238          !
 239        audio/mp3-frame
 240
 241    if the typefind would find a mp3-frame type, all three objects would be selected.
 242
 243
 244 8. consideration
 245 ----------------
 246
 247 It is clear that clear indications have to be given to the type hierarchy,
 248 especially for the top nodes.
 249
 250 The more specific an element is in its mime type specification, the more flexible
 251 and extendible the plugin system can be.
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282