mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-10-01 16:22:25 +00:00
110 lines
3.9 KiB
Text
110 lines
3.9 KiB
Text
Caps
|
|
----
|
|
|
|
Caps are lighweight refcounted objects describing media types.
|
|
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
|
|
a description of the element.
|
|
|
|
Caps are exposed on the element pads via CAPS and ACCEPT_CAPS queries.
|
|
|
|
This function describes the possible types that the pad can handle or
|
|
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.
|
|
|