mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-09 05:38:58 +00:00
Original commit message from CVS: * docs/random/bbb/optional-properties: Some analysis on optional properties.
76 lines
4.3 KiB
Text
76 lines
4.3 KiB
Text
Optional properties in caps:
|
|
|
|
During the 0.8 series of GStreamer, we regularly felt the need to add
|
|
properties to caps, thereby sometimes breaking specific caps negotiation
|
|
cases or annoying developers. This document outlines problems it could
|
|
lead to and tries to explain in which cases properties can be added and
|
|
when they can't. It also explains when properties can be optional (both
|
|
temporarily and permanently) and when they cannot.
|
|
|
|
--
|
|
|
|
There's two cases where optional properties could be added:
|
|
1) to fix an issue that makes any case fail
|
|
2) to fix an issue that makes some cases fail
|
|
|
|
Case 1 can be compared to not providing extra_data in caps for WMA. The caps
|
|
are defined, but it will never work because you cannot decode WMA audio
|
|
without the sequence header. In this case, adding the property breaks
|
|
caps compatibility, but it is still allowed because there is no regression
|
|
and it fixes a bug. No optional property should be added here, it should be
|
|
made a required property directly. Another example here is channel-positions
|
|
for channels>2.
|
|
|
|
Case 2 is more complex. There's various subcases:
|
|
a] not providing this property means ANY (or don't care, or unknown, each
|
|
of which is another way of saying ANY)
|
|
b] not providing this property means a specific value
|
|
.] adding this property will lead to unwanted behaviour
|
|
.] adding this property will not lead to unwanted behaviour
|
|
|
|
An example case for 2a is the buffer-frames property in float audio or the
|
|
frames property in MPEG audio. Buffer-frames is 0 (which should be removed)
|
|
means ANY. The reason that it should not be zero is because connecting an
|
|
element with buffer-frames=SOME_VALUE should be allowed to connect to any
|
|
element out there that has no buffer-frames requirement. The opposite is
|
|
true reversely: an element with no buffer-frames property should never be
|
|
allowed to connect to any element requesting a specific buffer-frames value.
|
|
For MPEG audio, it is TRUE likewise. Mathematically, buffer-frames=0 does not
|
|
exist. It implies ANY. Similarly, framed=FALSE cannot exist, because it
|
|
implies framed={FALSE,TRUE} (in words: an element cannot require non-framed
|
|
MPEG audio, because framed MPEG audio is a subset of non-framed MPEG audio
|
|
and thus valid input). In all those cases for 2a, optional properties are
|
|
fine. Subtraction will not work, but as explained, values are subsets of
|
|
another value and thus subtraction is irrelevant (because the mathematical
|
|
value of the subtraction has no real value).
|
|
This same principle is true for rate/channels on (for example) MPEG audio.
|
|
Our caps negotiation already allows for all of this, and optional properties
|
|
are already being used for this.
|
|
|
|
2b is complex, since subtraction actually has a value here, and addition
|
|
of such properties may lead to regressions or crashes. Let's give another
|
|
two examples: stride (for raw video; not providing this value implies 4-byte
|
|
aligned video) and pixel-aspect-ratio (default value being 1/1). Adding p-a-r
|
|
was in this case an example of 2bII, whereas stride is 2bI. The reason for
|
|
this is simple: adding pixel-aspect-ratio to some element and not to others
|
|
could lead to misunderstanding size. However, this is not a regression,
|
|
because not adding it alltogether would lead to the same misunderstanding.
|
|
In both cases, the result would be wrongly sized video. Therefore, there
|
|
is no regression and there is a bugfix, so this is fine. Obviously, the
|
|
optional property is in this case very specifically a temporary solution.
|
|
As soon as we can, this property should become obligatory.
|
|
Stride is different, because elements have implicit associated behaviour
|
|
based on the previous beahviour. This hebaviour could break if some elements
|
|
do implement stride and others still don't. Therefore, adding an optional
|
|
property as a temporary hack is, in this case, not a good idea and should
|
|
be disallowed. A proper fix should be done in the same timeframe as 2bII. In
|
|
this case, optional properties should not be added. Another example of this
|
|
case was adding channel-positions to audio caps with channels=1,2, which
|
|
was rejected for the same reason: it would break a perfectly-working set
|
|
of rules in a stable series.
|
|
|
|
--
|
|
|
|
Obviously, with all of the above, people will start fighting about which
|
|
group their specific properties change belongs to. General consensus is
|
|
the only way to get around that problem. Long live politics.
|