| 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 altogether 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. |