docs/random/types3

   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 2. major types
  17 --------------
  18
  19 major types are identified with mime types and are used to denote a
  20 family of types.
  21
  22 More specific information about the type is given using properties. This
  23 will allow us to be very specific without creating a lot of mime types.
  24
  25 3. API
  26 ------
  27
  28 Both a simple array based specification and a real API will be
  29 provided to build the capabilities.
  30
  31 In the array based approach, we basically build an array of pointers.
  32 Some macros will be available to specify ranges, boolean values, lists
  33 and id's. (not sure if this can be done)
  34
  35 #define GST_TYPE_INT_RANGE(a, b) GST_TYPE_RANGE,(a),(b)
  36 #define GST_TYPE_BOOLEAN(a) GST_TYPE_BOOLEAN,(a)
  37 #define GST_TYPE_LIST(a...) GST_TYPE_LIST,(##a),NULL
  38
  39 for example:
  40
  41   static GstTypeCapsFactory mpg123_sink_caps[] = {
  42     "audio/mp3",
  43     "layer",    GST_TYPE_INT_RANGE (1, 3),
  44     "bitrate",  GST_TYPE_INT_RANGE (8, 320),
  45     "framed",   GST_TYPE_BOOLEAN (true),
  46     NULL
  47   };
  48
  49 will expand to the array:
  50
  51   static GstTypeCapsFactory mpg123_sink_caps[] = {
  52     "audio/mp3",
  53     "layer",    GST_TYPE_RANGE,1,3,
  54     "bitrate",  GST_TYPE_RANGE,8,320,
  55     "famed",    GST_TYPE_BOOLEAN,true,
  56     NULL,
  57   };
  58
  59 when we register the caps factory, the strings will be converted
  60 into GQuarks and be stored into a GData Keyed Data List.
  61
  62 This will result in a GstTypeCaps structure:
  63
  64 struct _GstTypeCaps {
  65   guint16 id;                 // if of the major type
  66
  67   GData *properties;
  68 }
  69
  70 4. example using arrays
  71 -----------------------
  72
  73 mpg123: an mpeg audio decoder.
  74
  75   // a factory for the major type we use
  76   static GstTypeFactory mp3factory = {
  77     "audio/mp3",                // major type
  78     ".mp3 .mp2 .mp1 .mpga",     // extenstions
  79     NULL,                       // typefind function
  80   };
  81
  82   // capabilities of the sink pad
  83   static GstTypeCapsFactory mpg123_sink_caps[] = {
  84     "audio/mp3",
  85     "layer",    GST_TYPE_INT_RANGE (1, 3),
  86     "bitrate",  GST_TYPE_INT_RANGE (8, 320),
  87     "framed",   GST_TYPE_BOOLEAN (true),
  88     NULL
  89   };
  90
  91   // capabilities of the source pad
  92   static GstTypeCapsFactory mpg123_src_caps[] = {
  93     "audio/raw",
  94     "rate",     GST_TYPE_INT_RANGE (8000, 48000),
  95     "channels", GST_TYPE_INT_RANGE (1, 2),
  96     NULL
  97   };
  98
  99   static GstTypeCaps *sinkcaps = NULL, *rawcaps = NULL;
 100
 101   static gst_mpg123_init (GstMpg123 *mpg123)
 102   {
 103     mpg123->sinpad = gst_pad_new ("sink", GST_PAD_SINK);
 104     gst_element_add_pad (GST_ELEMENT (mpg123), mpg123->sinkpad);
 105     gst_pad_set_caps (mpg123->sinkpad, sinkcaps);
 106
 107     ...
 108   }
 109
 110   GstPlugin *plugin_init (GModule *module)
 111   {
 112     ...
 113     plugin = gst_plugin_new ("mpg123");
 114
 115     gst_plugin_add_type_factory (plugin, mp3factory);
 116
 117     ...
 118     sinkcaps = gst_type_register_caps (mpg123_sink_caps, NULL);
 119     rawcaps  = gst_type_register_caps (mpg123_src_caps, NULL);
 120     ...
 121   }
 122
 123 mpeg2dec: an mpeg video decoder that can do mpeg1 and mpeg2.
 124
 125   static GstTypeFactory mpegfactory = {
 126     "video/mpeg",               // major type
 127     ".mpg .mpeg",               // extenstions
 128     NULL,                       // typefind function
 129   };
 130
 131   static GstTypeCapsFactory mpeg2dec_sink_caps[] = {
 132     "video/mpeg",
 133     "mpegtype", GST_TYPE_LIST (
 134                         GST_TYPE_INT(1),
 135                         GST_TYPE_INT(2),
 136                         ),
 137     NULL
 138   };
 139
 140   static GstTypeCapsFactory mpeg2dec_src_caps[] = {
 141     "video/raw",
 142     "fourcc",   GST_TYPE_LIST (
 143                         GST_TYPE_INT32 (0x32315659),
 144                         GST_TYPE_INT32 (0x32...),
 145                         ),
 146     "width",    GST_TYPE_INT_RANGE (16, 4096),
 147     "height",   GST_TYPE_INT_RANGE (16, 4096),
 148     NULL
 149   };
 150
 151   static GstTypeCaps *sinkcaps = NULL, *rawcaps = NULL;
 152
 153   GstPlugin *plugin_init (GModule *module)
 154   {
 155     ...
 156     plugin = gst_plugin_new ("mpeg2dec");
 157
 158     ...
 159     sinkcaps = gst_type_register_caps (mpeg2dec_sink_caps, NULL);
 160     rawcaps  = gst_type_register_caps (mpeg2dec_src_caps, NULL);
 161     ...
 162   }
 163
 164
 165 5. capabilty compatibility
 166 --------------------------
 167
 168 Two pads are compatible if:
 169
 170 - The major types are equal
 171 - range of the sink pad contains the range of the src pad
 172
 173