docs/random/types3

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