design: Add the caps features and describe how the caps operations actually work

diff --git a/docs/design/part-caps.txt b/docs/design/part-caps.txt
index a768b6d..b65a940 100644 (file)
--- a/docs/design/part-caps.txt
+++ b/docs/design/part-caps.txt
@@ -2,7 +2,8 @@ Caps
 ----
 
 Caps are lighweight refcounted objects describing media types.
-They are composed of an array of GstStructures.
+They are composed of an array of GstStructures plus optionally
+a GstCapsFeatures set for the GstStructure.
 
 Caps are exposed on GstPadTemplates to describe all possible types a
 given pad can handle. They are also stored in the registry along with
@@ -16,3 +17,94 @@ produce (see part-pads.txt and part-negotiation.txt).
 Various methods exist to work with the media types such as subtracting
 or intersecting.
 
+Operations
+~~~~~~~~~~
+Fixating
+--------
+Caps are fixed if they only contain a single structure and this
+structure is fixed. A structure is fixed if none of the fields of the
+structure is a unfixed types, for example a range, list or array.
+
+For fixating caps only the first structure is kept as the order of
+structures is meant to express the preferences for the different
+structures.
+Afterwards each unfixed field of this structure is set to a value
+that makes most sense for the media format by the element or pad
+implementation and afterwards every remaining unfixed fields is set to
+an arbitrary value that would be a subset of the unfixed field value.
+
+EMPTY caps are fixed caps, ANY caps are not fixed.
+
+Subset
+------
+One caps "A" is the subset of another caps "B" if for each structure in
+"A" there exists a structure in "B" that is a superset of the structure
+in "A".
+
+A structure "a" is the subset of a structure "b" if it has the same 
+structure name, the same caps features and each field in "b" exists
+in "a" and the value of the field in "a" is a subset of the value of
+the field in "b". "a" can have additional fields that are not in "b".
+
+EMPTY caps are a subset of every other caps, every caps are a subset of
+ANY caps.
+
+Equality
+--------
+Caps "A" and "B" are equal if "A" is a subset of "B" and "B" is a subset
+of "A". This means that both caps are expressing the same possibilities
+but their structures can still be different if they contain unfixed
+fields.
+
+Intersection
+------------
+The intersection of caps "A" and caps "B" are the caps that contain the
+intersection of all their structures with each other.
+
+The intersection of structure "a" and structure "b" is empty if their
+structure name or their caps features are not equal, or if "a" and "b"
+contain the same field but the intersection of both field values is empty.
+If one structure contains a field that is not existing in the other
+structure it will be copied over to the intersection with the same
+value.
+
+The intersection with ANY caps is always the other caps, the
+intersection with EMPTY caps is always EMPTY.
+
+Union
+-----
+The union of caps "A" and caps "B" are the caps that contain the union
+of all their structures with each other.
+
+The union of structure "a" and structure "b" are the two structures "a"
+and "b" if the structure names or caps features are not equal. Otherwise
+the union is the structure that contains the union of each fields value.
+If a field is only in one of the two structures it is not contained in
+the union.
+
+The union with ANY caps is always ANY, the union with EMPTY caps is
+always the other caps.
+
+Subtraction
+-----------
+The subtraction of caps "A" from caps "B" is the most generic subset
+of "B" that has an empty intersection with "A" but only contains
+structures with names and caps features that are existing in "B".
+
+Basic Rules
+~~~~~~~~~~~
+
+Compatibility of caps
+---------------------
+
+Pads can be linked when the caps of both caps are compatible. This is
+the case when their intersection is not empty.
+
+For checking if a pad actually supports a fixed caps an intersection is
+not enough. Instead the fixed caps must be at least a subset of the
+pad's caps but pads can introduce additional constraints which would be
+checked in the ACCEPT_CAPS query handler.
+
+Data flow can only happen after pads have decided on a common, fixed
+caps.
+