From c989ff928b088c54726839603830d92f5ed32a92 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Sebastian=20Dr=C3=B6ge?= Date: Sun, 31 Mar 2013 19:09:46 +0200 Subject: [PATCH] design: Add the caps features and describe how the caps operations actually work --- docs/design/part-caps.txt | 94 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 93 insertions(+), 1 deletion(-) diff --git a/docs/design/part-caps.txt b/docs/design/part-caps.txt index a768b6d..b65a940 100644 --- 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. + -- 2.7.4