docs/random/bbb/optional-properties: Some analysis on optional properties.

Original commit message from CVS:
* docs/random/bbb/optional-properties:
Some analysis on optional properties.

diff --git a/ChangeLog b/ChangeLog
index e31f4d0..032d11a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2005-04-13  Ronald S. Bultje  <rbultje@ronald.bitfreak.net>
+
+       * docs/random/bbb/optional-properties:
+         Some analysis on optional properties.
+
 2005-04-12  Ronald S. Bultje  <rbultje@ronald.bitfreak.net>
 
        * docs/gst/tmpl/gstelementfactory.sgml:

diff --git a/docs/random/bbb/optional-properties b/docs/random/bbb/optional-properties
new file mode 100644 (file)
index 0000000..f6471a0
--- /dev/null
+++ b/docs/random/bbb/optional-properties
@@ -0,0 +1,76 @@
+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.