docs/random/omega/caps2

   1 The elementfactory for a given element will contain some information about the capabilities of element's
   2 pads or potential pads.  An indication will be provided as to whether the pad always exists, always
   3 exists once data is present, or *might* exist once data is present (the latter case is for things like
   4 the MPEG system parsers, where an audio stream might or might not exist).
   5
   6
   7 First, an entirely normal example:
   8 ----------------------------------
   9
  10 (-----------)        (----------)        (-------------)
  11 ! disksrc   !        ! mpg123   !        ! audiosink   !
  12 !         src        sink     src        sink          !
  13 !           !        !          !        !             !
  14 (-----------)        (----------)        (-------------)
  15
  16 We start with only the disksrc.  The typefind filter is attached to the disksrc, and via typefind magic
  17 the properties of the disksrc are found to be:
  18
  19   disksrc->src->caps = {
  20     "audio/mp3",
  21     "layer",   GST_CAPS_INT (3),
  22     "bitrate", GST_CAPS_INT (128),
  23     NULL
  24   };
  25
  26 A look through the plugin registry shows that we have an element called mpg123 that has the following
  27 caps:
  28
  29   static GstCapsFactory mpg123_sink_caps = {
  30     "audio/mp3",
  31     "layer",   GST_CAPS_INT_RANGE (1, 3),
  32     "bitrate", GST_CAPS_INT_RANGE (8, 320),
  33     NULL
  34   };
  35
  36 The caps of the disksrc fit within those parameters, so we instantiate an mpg123 and attach it to the
  37 disksrc.  The connection succeeds negotiation and as a result the mpg123 specifies its output caps as:
  38
  39   mpg123->src->caps = {
  40     "audio/raw",
  41     "format",   GST_CAPS_BITFIELD (S16),
  42     "depth",    GST_CAPS_INT (16),
  43     "rate",     GST_CAPS_INT (44100),
  44     "channels", GST_CAPS_INT (2),
  45     NULL
  46   };
  47
  48 Again from the plugin registry we find an element audiosink that has appropriate caps:
  49
  50   static GstCapsFactory audiosink_src_caps = {
  51     "audio/raw",
  52     "format",   GST_CAPS_BITFIELD (S16,....),
  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 A copy of the audiosink is instantiated and attached, negotiation goes smoothly, and we're done.  No
  60 dataflow has occured, no failure found, etc.  An ideal autoplug.
  61
  62
  63 Now, a slightly more convoluted example:
  64 ----------------------------------------
  65
  66 Start with the same graph:
  67
  68 (-----------)        (----------)        (-------------)
  69 ! disksrc   !        ! mpg123   !        ! audiosink   !
  70 !         src        sink     src        sink          !
  71 !           !        !          !        !             !
  72 (-----------)        (----------)        (-------------)
  73
  74 Run typefind on the disksrc's output, get the same output caps:
  75
  76   disksrc->src->caps = {
  77     "audio/mp3",
  78     "layer",   GST_CAPS_INT (3),
  79     "bitrate", GST_CAPS_INT (128),
  80     NULL
  81   };
  82
  83 Find and attach mpg123, get the following output caps this time:
  84
  85   mpg123->src->caps = {
  86     "audio/raw",
  87     "format",   GST_CAPS_BITFIELD (S16),
  88     "depth",    GST_CAPS_INT (16),
  89     "rate",     GST_CAPS_INT (44100),
  90     "channels", GST_CAPS_INT (1),
  91     NULL
  92   };
  93
  94 Note that this time we have a mono output.  A look into the audiosink caps shows that we have a match.
  95 So we instantiate a copy.  Oops.  We now find that the caps for the input pad on our audiosink have
  96 changed:
  97
  98   mpg123->src->caps = {
  99     "audio/raw",
 100     "format",   GST_CAPS_BITFIELD (S16,...),
 101     "depth",    GST_CAPS_INT (16),
 102     "rate",     GST_CAPS_INT (11025, 48000),
 103     "channels", GST_CAPS_INT (2),
 104     NULL
 105   };
 106
 107 Whoops.  It seems that the sound card we've got in this machine (FIXME how on earth to deal with
 108 multiple sound cards???) doesn't support mono output *at all*.  This is a problem.  We now find that we
 109 hae no options as far as directly matching the mpg123 to the audiosink.
 110
 111 A look through our (ficticious) plugin registry shows at least one element that at least has audio/raw
 112 on both input and ouput (since both mpg123 and audiosink have open pads with this mime type).  A closerlook shows that its caps are:
 113
 114   static GstCapsFactory mono2stereo_sink_caps = {
 115     "audio/raw",
 116     "channels", GST_CAPS_INT (1),
 117     NULL
 118   };
 119   static GstCapsFactory mono2stereo_src_caps = {
 120     "audio/raw",
 121     "channels", GST_CAPS_INT (2),
 122     NULL
 123   };
 124
 125 Wow, that's a perfect match.  Instantiate, attach to mpg123, no problems.  Attach to audiosink, no
 126 problems.  Done.  When we start up the pipeline, we should get absolutely no callbacks from pads saying
 127 "help me, I've fallen and..., er, I don't like this buffer!".
 128
 129
 130 A really messy case:
 131 --------------------
 132
 133 Start with a disksrc, typefind it, get the following:
 134
 135   disksrc->src->caps = {
 136     "audio/mp3",
 137     "layer",   GST_CAPS_INT (3),
 138     "bitrate", GST_CAPS_INT (128),
 139     NULL
 140   };
 141
 142 Look through the plugin registry, find mpg123.  Instantiate it, attach it.  It spits out audio
 143 parameters as usual:
 144
 145   mpg123->src->caps = {
 146     "audio/raw",
 147     "format",   GST_CAPS_BITFIELD (S16),
 148     "depth",    GST_CAPS_INT (16),
 149     "rate",     GST_CAPS_INT (44100),
 150     "channels", GST_CAPS_INT (2),
 151     NULL
 152   };
 153
 154 Now we instantiate an audiosink plugin.  This time, we're sunk:
 155
 156   mpg123->src->caps = {
 157     "audio/raw",
 158     "format",   GST_CAPS_BITFIELD (S8,U8),
 159     "depth",    GST_CAPS_INT (8),
 160     "rate",     GST_CAPS_INT_RANGE (11025, 22050),
 161     "channels", GST_CAPS_INT (1),
 162     NULL
 163   };
 164
 165 ACK!  It's one of those Disney Sound Source things.  We've got a problem here that isn't obviously
 166 solvable.  However, there happens to be another mp3 decoder sitting around.  It's got the same
 167 properties as mpg123, but a lower merit value.  Let's instantiate one and attach it.  We get the
 168 following output pad caps:
 169
 170   mp3decoder->src->caps = {
 171     "audio/raw",
 172     "format",   GST_CAPS_BITFIELD (S8,S16),
 173     "depth",    GST_CAPS_INT_RANGE (8,16),
 174     "rate",     GST_CAPS_INT_RANGE (8000, 44100),
 175     "channels", GST_CAPS_INT (1,2),
 176     NULL
 177   };
 178
 179 Well, that matches the audiosink.  We try attaching it, and during negotiation the mp3decoder finds
 180 sufficient common ground with the castrated audiosink and sets its output pad to match the best of the
 181 options: S8 at 22050 KHz.
 182
 183
 184
 185 Next to impossible scenario: DVD
 186 --------------------------------
 187
 188 Start with a dvdsrc.  It's output pad caps are:
 189
 190   static GstCapsFactory dvdsrc_src_caps = {
 191     "video/mpeg",
 192     "mpegversion",  GST_CAPS_INT (2),
 193     "systemstream", GST_CAPS_BOOLEAN (TRUE),
 194     NULL
 195   };
 196
 197 The type would be classified as incomplete via some mechanism.  This might cause the autoplug code to go
 198 and run the typefind function.  It would flesh the type out to the following:
 199
 200   dvdsrc->src->caps = {
 201     "video/mpeg",
 202     "mpegversion",  GST_CAPS_INT (2),
 203     "systemstream", GST_CAPS_BOOLEAN (TRUE),
 204     "videostreams", GST_CAPS_INT (1),
 205     "audiostreams", GST_CAPS_INT (3),
 206     "bitrate",      GST_CAPS_INT (40960),
 207     NULL,
 208   };
 209
 210 Wow, that helped a lot.  A check through the plugin registry shows that the mpeg2parse will match those
 211 properties:
 212
 213   static GstCapsFactory mpeg2parse_sink_caps = {
 214     "video/mpeg",
 215     "mpegversion",  GST_CAPS_INT (2),
 216     "systemstream", GST_CAPS_BOOLEAN (TRUE),
 217     NULL
 218   };
 219
 220 (In retrospect, it may not be necessary to run typefind if there's match this good right away.  Only run
 221 typefind when there's no exact match.)
 222 Since there are no output pads yet, we have to actually push data through the pipeline.  The moment a
 223 buffer or two get to the mpeg2parse element, it promptly goes and creates an output pad, probably of the
 224 following caps:
 225
 226   mpeg2parse_video_src_caps = {
 227     "video/mpeg",
 228     "mpegversion",  GST_CAPS_RANGE (1,2),
 229     "systemstream", GST_CAPS_BOOLEAN (FALSE),
 230     NULL
 231   };
 232
 233 This seems to be a task for typefind again.  But since data is flowing, we have to be careful with the
 234 buffers.  (This is the case in any typefind maneuver, but moreso when one really can't rewind the
 235 source without consequences)  The autoplug system attaches a special pseudo-element to mpeg2parse's new
 236 output pad, and attaches the typefind element to the end of that.  The pseudo-element takes the buffer,
 237 stores it, and passes a copy off to the attached element, in this case typefind.  This repeats until
 238 typefind has determined the type, at which point the typefind is removed, and the newly found element is
 239 attached instead.
 240
 241 The pseudo-element is 'rewound' and the stored buffers flow out and into the newly attached element.
 242 When the cache of buffers is gone, a signal fires and the autoplug system removes the pseudo-element and
 243 reconnects the pipeline.
 244
 245 In this case, the typefind function will find the following:
 246
 247   mpeg2parse_video_src_caps = {
 248     "video/mpeg",
 249     "mpegversion",  GST_CAPS_INT (2),
 250     "systemstream", GST_CAPS_BOOLEAN (FALSE),
 251     "bitrate",      GST_CAPS_INT (36864),
 252     "width",        GST_CAPS_INT (720),
 253     "height",       GST_CAPS_INT (480),
 254     "framerate",    GST_CAPS_FLOAT (29.97002997),
 255     "chromaformat", GST_CAPS_INT (1),           [GST_CAPS_STRING ("4:2:0") ?]
 256     NULL
 257   };
 258
 259 Back to the plugin registry, we find our only choice is mpeg2dec, which has input caps of:
 260
 261   static GstCapsFactory mpeg2dec_sink_caps = {
 262     "video/mpeg",
 263     "mpegversion",  GST_CAPS_RANGE (1,2),
 264     "systemstream", GST_CAPS_BOOLEAN (FALSE),
 265     NULL
 266   };
 267
 268 Once again it just so happens that we really didn't need to do the typefind at all.  But it can't hurt
 269 unless the typefind is slow and painful, which we can guess won't be the case since the choices are
 270 rather limited by the fact that there's already a MIME type attached, meaning we can drastically reduce
 271 the number of typefind functions we try (down to one, actually).
 272
 273 However, since we *have* run the typefind, upon attachment of the input pad of mpeg2dec, the output pad
 274 looks like the following:
 275
 276   mpeg2dec_src_caps = {
 277     "video/raw",
 278     "fourcc",    GST_CAPS_LIST (
 279                         GST_CAPS_FOURCC ("YV12"),       [identical...]
 280                         GST_CAPS_FOURCC ("IYUV"),
 281                         GST_CAPS_FOURCC ("I420"),
 282                  ),
 283     "width",     GST_CAPS_INT (720),
 284     "height",    GST_CAPS_INT (480),
 285     "framerate", GST_CAPS_FLOAT (29.97002997),
 286     NULL
 287   };
 288
 289 Currently only videosink supports the output of video/raw.  It claims a list of FOURCCs but nothing
 290 more:
 291
 292   static GstCapsFactory videosink_sink_caps = {
 293     "video/raw",
 294     "fourcc", GST_CAP_LIST ( GST_CAPS_FOURCC ("YV12"),
 295                 GST_CAPS_FOURCC ("IYUV"), GST_CAPS_FOURCC ("I420"),
 296                 GST_CAPS_FOURCC ("YUY2"), GST_CAPS_FOURCC ("UYVY"),
 297                 [ etc... ],
 298               ),
 299     NULL
 300   };
 301
 302 When instantiated, we potentially have the same problem as with the audiosink: we don't necessarily know
 303 which hardware output to use.  Somehow we have to solve the problem of setting some element arguments
 304 before we can get useful information out of them as to the properties.  In this case anyway, if the
 305 videosink were to find only one output possibility, it would trim the list of FOURCCs it can deal with
 306 to what the hardware can handle, as well as add further properties:
 307
 308   videosink_sink_caps = {
 309     "video/raw",
 310     "fourcc", GST_CAPS_LIST (GST_CAPS_FOURCC ("YV12"),
 311                         GST_CAPS_FOURCC ("YUY2"),
 312               ),
 313     "width",  GST_CAPS_INT_RANGE (4,1020),
 314     "height", GST_CAPS_INT_RANGE (4,1020),
 315     NULL
 316   };
 317
 318 We can now connect the mpeg2dec output to the videosink, and we now have displaying video.
 319
 320 . . . .