docs/random/bbb/optional-properties - imx-gstreamer - Git at Google

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