docs/random/types2

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