docs/random/bbb/optional-properties

   1 Optional properties in caps:
   2
   3 During the 0.8 series of GStreamer, we regularly felt the need to add
   4 properties to caps, thereby sometimes breaking specific caps negotiation
   5 cases or annoying developers. This document outlines problems it could
   6 lead to and tries to explain in which cases properties can be added and
   7 when they can't. It also explains when properties can be optional (both
   8 temporarily and permanently) and when they cannot.
   9
  10 --
  11
  12 There's two cases where optional properties could be added:
  13 1) to fix an issue that makes any case fail
  14 2) to fix an issue that makes some cases fail
  15
  16 Case 1 can be compared to not providing extra_data in caps for WMA. The caps
  17 are defined, but it will never work because you cannot decode WMA audio
  18 without the sequence header. In this case, adding the property breaks
  19 caps compatibility, but it is still allowed because there is no regression
  20 and it fixes a bug. No optional property should be added here, it should be
  21 made a required property directly. Another example here is channel-positions
  22 for channels>2.
  23
  24 Case 2 is more complex. There's various subcases:
  25 a] not providing this property means ANY (or don't care, or unknown, each
  26    of which is another way of saying ANY)
  27 b] not providing this property means a specific value
  28  .] adding this property will lead to unwanted behaviour
  29  .] adding this property will not lead to unwanted behaviour
  30
  31 An example case for 2a is the buffer-frames property in float audio or the
  32 frames property in MPEG audio. Buffer-frames is 0 (which should be removed)
  33 means ANY. The reason that it should not be zero is because connecting an
  34 element with buffer-frames=SOME_VALUE should be allowed to connect to any
  35 element out there that has no buffer-frames requirement. The opposite is
  36 true reversely: an element with no buffer-frames property should never be
  37 allowed to connect to any element requesting a specific buffer-frames value.
  38 For MPEG audio, it is TRUE likewise. Mathematically, buffer-frames=0 does not
  39 exist. It implies ANY. Similarly, framed=FALSE cannot exist, because it
  40 implies framed={FALSE,TRUE} (in words: an element cannot require non-framed
  41 MPEG audio, because framed MPEG audio is a subset of non-framed MPEG audio
  42 and thus valid input). In all those cases for 2a, optional properties are
  43 fine. Subtraction will not work, but as explained, values are subsets of
  44 another value and thus subtraction is irrelevant (because the mathematical
  45 value of the subtraction has no real value).
  46 This same principle is true for rate/channels on (for example) MPEG audio.
  47 Our caps negotiation already allows for all of this, and optional properties
  48 are already being used for this.
  49
  50 2b is complex, since subtraction actually has a value here, and addition
  51 of such properties may lead to regressions or crashes. Let's give another
  52 two examples: stride (for raw video; not providing this value implies 4-byte
  53 aligned video) and pixel-aspect-ratio (default value being 1/1). Adding p-a-r
  54 was in this case an example of 2bII, whereas stride is 2bI. The reason for
  55 this is simple: adding pixel-aspect-ratio to some element and not to others
  56 could lead to misunderstanding size. However, this is not a regression,
  57 because not adding it alltogether would lead to the same misunderstanding.
  58 In both cases, the result would be wrongly sized video. Therefore, there
  59 is no regression and there is a bugfix, so this is fine. Obviously, the
  60 optional property is in this case very specifically a temporary solution.
  61 As soon as we can, this property should become obligatory.
  62 Stride is different, because elements have implicit associated behaviour
  63 based on the previous beahviour. This hebaviour could break if some elements
  64 do implement stride and others still don't. Therefore, adding an optional
  65 property as a temporary hack is, in this case, not a good idea and should
  66 be disallowed. A proper fix should be done in the same timeframe as 2bII. In
  67 this case, optional properties should not be added. Another example of this
  68 case was adding channel-positions to audio caps with channels=1,2, which
  69 was rejected for the same reason: it would break a perfectly-working set
  70 of rules in a stable series.
  71
  72 --
  73
  74 Obviously, with all of the above, people will start fighting about which
  75 group their specific properties change belongs to. General consensus is
  76 the only way to get around that problem. Long live politics.