docs/random/caps

   1 During the course of a discussion on IRC, it turned out
   2 that there are many possible ways to handle the capabilities.
   3
   4 A capabilitiy is bascially a set of properties attached to a
   5 mimetype in order to more closely describe the mimetype.
   6 Capabiltities are supposed to be attached to pads so that the
   7 autoplugging algorithm has more specific information to connect
   8 compatible pads.
   9
  10 We present 3 possible implementation for the capabilities. we need
  11 to pick one of them.
  12
  13 1. static capabilities
  14 ----------------------
  15
  16 When an element is created, it creates its pads like:
  17
  18   mpg123->sinkpad = gst_pad_new ("sink", GST_PAD_SINK);
  19   gst_element_add_pad (GST_ELEMENT (mpg123), mpg123->sinkpad);
  20
  21   mpg123->srcpad = gst_pad_new ("src", GST_PAD_SRC);
  22   gst_element_add_pad (GST_ELEMENT (mpg123), mpg123->srcpad);
  23
  24 In the static capabilities case, it will attach a GstCaps* structure
  25 to the pad. The GstCaps structure in the above example might look like:
  26
  27   static GstCapsFactory mpg123_sink_caps = {
  28     "audio/mp3",
  29     "layer",   GST_CAPS_INT_RANGE (1, 3),
  30     "bitrate", GST_CAPS_INT_RANGE (8, 320),
  31     NULL
  32   };
  33
  34 with
  35
  36 mpg123sinkcaps  = gst_caps_register (mpg123_sink_caps);
  37
  38 the factory can be converted into a GstCaps* structure. The
  39 GstCaps* structure is attached to the pad with:
  40
  41 gst_pad_add_caps (mpg123->sinkpad, mpg123sinkcaps);
  42
  43 The GstElement would then have a sinkpad with the given
  44 mimetype (audio/mp3) and with the capabilitities of accepting
  45 mpeg layer 1 to 3 and a bitrate from 8 up to 320 Kbps.
  46
  47 Likewise, the src pad could be set up in the same way. An
  48 example capability factory could look like:
  49
  50   static GstCapsFactory mpg123_src_caps = {
  51     "audio/raw",
  52     "format",   GST_CAPS_BITFIELD (...),
  53     "depth",    GST_CAPS_INT (16),
  54     "rate",     GST_CAPS_INT_RANGE (4000, 96000),
  55     "channels", GST_CAPS_INT_RANGE (1, 2),
  56     NULL
  57   };
  58
  59 All GstElements would present their pads with the appropriate
  60 capabilities structure.
  61
  62 The autoplugger would then proceed (once the source media type
  63 is known with a typefind function) in finding all the elements
  64 with compatible pads and connecting them into a pipeline.
  65
  66 All elements of the complete pipeline could then be constructed
  67 with one single pass. No new elements should be added to the
  68 pipeline because we can figure out all the possibilities using the
  69 pad capabilities.
  70
  71 We call this the static case because the capabilities of the pads
  72 are supposed to stay the same after creating the element.
  73
  74 While the ability to completly setup the pipeline before actually
  75 starting playback is an advantage regarding performance, one obvious
  76 problem with this setup is that the static case may be too static in
  77 some cases. We can illustrate this with the following setup:
  78
  79   ----------)             (------------
  80    mpg123   !             !  audiosink
  81            src          sink
  82             !             !
  83   ----------)             (------------
  84
  85 The mpg123 element has its src capabilities set up as mpg123_src_caps
  86 in the above example.
  87
  88 The audio renderer has its capabilities set up with the following
  89 factory:
  90
  91   static GstCapsFactory audio_sink_caps = {
  92     "audio/raw",
  93     "format",   GST_CAPS_BITFIELD (...),
  94     "depth",    GST_CAPS_INT (16),
  95     "rate",     GST_CAPS_INT_RANGE (22000, 44000),
  96     "channels", GST_CAPS_INT_RANGE (1, 2),
  97     NULL
  98   };
  99
 100 The static autoplugger has to be carefull when connecting the mpg123
 101 element with the audiosink because it is theoretically possible that
 102 the mpg123 element outputs raw audio with a rate that cannot be
 103 handled by the audiosink (ex. 4000KHz). In the absense of another
 104 audiosink with more capabilities, the autoplugging of this simple
 105 pipeline will not be possible and would fail.
 106
 107 the autoplugging algorithm would probably select another element to
 108 insert between the mpg123 element and the audiosink in order to handle
 109 the (uncommon) case of a rate conversion (audioscaler).
 110
 111 It is clear that this static setup might even fail or work suboptimal
 112 for even the common case and should therefore be considered as too
 113 restrictive.
 114
 115
 116 2. dynamic capabilities
 117 -----------------------
 118
 119 The idea of dynamic capabilities is that the capabilities are not set
 120 at element create time but rather while the pipeline is running.
 121
 122 An element would still list its mime type using:
 123
 124   gst_pad_add_type_id(mpg123->sinkpad, mp3type);
 125
 126 The idea would then be that a rough draft of the pipeline would be
 127 built afer the media type of the stream has been detected with the
 128 typefind functions. The rough draft would consist of laying out a
 129 global plan to reach the renderer(s). this plan would basically list
 130 the set of conversions that have to be performed. (mime-type to
 131 mime-type conversion).
 132
 133 Elements that accept the src mime-type are tried by giving it a buffer.
 134 If the element accepts the buffer, it will set its capabilities for
 135 both the sink pad and the src pad. At that time other elements can be
 136 tried and added to the src pad, until we reach the renderer. As usual
 137 one has to be carefull to add just the minimum amount of elements to
 138 reach the renderer. The global plan will help with that.
 139
 140 Since we basically do not use the capabilities of the sink pad one has
 141 to question the need for sink pad capabilities in the first place.
 142
 143 We might also have a hard time trying different elements until we find
 144 a compatible one that does not cause a dead end at some point.
 145
 146
 147 3. combined setup
 148 -----------------
 149
 150 This combined setup will minimise the effort needed to try different
 151 elements encountered by option 2 while still allowing a more dynamic
 152 setup based on the actual media stream we are handling.
 153
 154 The combined setup will list/add the sink capabilities at create time.
 155 It will only set the mime-type of its src pads.
 156
 157 As with option2, a global plan will be built. At runtime the src pads
 158 will actually specify the capabilities they need for any element that
 159 wants to be connected to its source pads.
 160
 161 In this case we specifiy the capabilities for all the sink pads of an
 162 element at create time. The capabilities of the src pads would only
 163 become available when data has been processed by the element.
 164
 165 The autoplugger would then be able to choose an element that can handle
 166 the capability listed by the src pad.
 167
 168 in our previous example:
 169
 170   ----------)             (------------
 171    mpg123   !             !  audiosink
 172            src          sink
 173             !             !
 174   ----------)             (------------
 175
 176 the audiosink element would specify its sink pad capabilities at create
 177 time, while the mpg123 elements src pad would not yet have any capabilities
 178 set.
 179
 180 When data is handled by the mpg123 element, a capability would be added to
 181 the mpg123 src pad. This capability might be:
 182
 183   static GstCapsFactory mpg123_src_caps = {
 184     "audio/raw",
 185     "format",   GST_CAPS_INT (S16),
 186     "depth",    GST_CAPS_INT (16),
 187     "rate",     GST_CAPS_INT (44000),
 188     "channels", GST_CAPS_INT (2),
 189     NULL
 190   };
 191
 192 This capability would be compatible with the audiosinks sinkpad capabilities
 193 and the autoplugger would therefore be able to connect the two elements.
 194
 195 While allowing a more flexible setup with option3, compared to option1, we
 196 introduce a slightly higher overhead when we need to dynamically connect
 197 elements. This overhead will not be as big as option2 because we don't
 198 have to 'try' elements.
 199
 200 so:
 201
 202   src caps:  added at runtime to list the caps needed for an element that
 203              wants to connect to this pad.
 204   sink caps: the (static) capabilities that this sinkpad has.
 205