Caps
- class Caps(*args, **kwargs)
Caps (capabilities) are lightweight refcounted objects describing media types.
They are composed of an array of Structure
.
Caps are exposed on PadTemplate
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 using the query_caps()
pad
function. This function describes the possible types that the pad can
handle or produce at runtime.
A Caps
can be constructed with the following code fragment:
GstCaps *caps = gst_caps_new_simple ("video/x-raw",
"format", G_TYPE_STRING, "I420",
"framerate", GST_TYPE_FRACTION, 25, 1,
"pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
"width", G_TYPE_INT, 320,
"height", G_TYPE_INT, 240,
NULL);
A Caps
is fixed when it has no fields with ranges or lists. Use
is_fixed()
to test for fixed caps. Fixed caps can be used in a
caps event to notify downstream elements of the current media type.
Various methods exist to work with the media types such as subtracting or intersecting.
Be aware that until 1.20 the Caps
/ Structure
serialization into string
had limited support for nested Caps
/ Structure
fields. It could only
support one level of nesting. Using more levels would lead to unexpected
behavior when using serialization features, such as to_string()
or
value_serialize()
and their counterparts.
Constructors
Methods
- class Caps
- append(caps2: Caps) None
Appends the structures contained in
caps2
tocaps1
. The structures incaps2
are not copied – they are transferred tocaps1
, and thencaps2
is freed. If either caps is ANY, the resulting caps will be ANY.- Parameters:
caps2 – the
Caps
to append
- append_structure(structure: Structure) None
Appends
structure
tocaps
. The structure is not copied;caps
becomes the owner ofstructure
.- Parameters:
structure – the
Structure
to append
- append_structure_full(structure: Structure, features: CapsFeatures | None = None) None
Appends
structure
withfeatures
tocaps
. The structure is not copied;caps
becomes the owner ofstructure
.Added in version 1.2.
- Parameters:
structure – the
Structure
to appendfeatures – the
CapsFeatures
to append
- can_intersect(caps2: Caps) bool
Tries intersecting
caps1
andcaps2
and reports whether the result would not be empty- Parameters:
caps2 – a
Caps
to intersect
- filter_and_map_in_place(func: Callable[[...], bool], *user_data: Any) None
Calls the provided function once for each structure and caps feature in the
Caps
. In contrast toforeach()
, the function may modify the structure and features. In contrast tofilter_and_map_in_place()
, the structure and features are removed from the caps ifFalse
is returned from the function. The caps must be mutable.Added in version 1.6.
- Parameters:
func – a function to call for each field
user_data – private data
- fixate() Caps
Modifies the given
caps
into a representation with only fixed values. First the caps will be truncated and then the first structure will be fixated withfixate()
.This function takes ownership of
caps
and will callcaps_make_writable()
on it so you must not usecaps
afterwards unless you keep an additional reference to it with gst_caps_ref().Note that it is not guaranteed that the returned caps have exactly one structure. If
caps
are empty caps then the returned caps will be the empty too and contain no structure at all.Calling this function with ANY caps is not allowed.
- foreach(func: Callable[[...], bool], *user_data: Any) bool
Calls the provided function once for each structure and caps feature in the
Caps
. The function must not modify the fields. Also seemap_in_place()
andfilter_and_map_in_place()
.Added in version 1.6.
- Parameters:
func – a function to call for each field
user_data – private data
- from_string(string: str) Caps | None
Converts
caps
from a string representation.The implementation of serialization up to 1.20 would lead to unexpected results when there were nested
Caps
/Structure
deeper than one level.- Parameters:
string – a string to convert to
Caps
- get_features(index: int) CapsFeatures | None
Finds the features in
caps
atindex
, and returns it.WARNING: This function takes a
const GstCaps *
, but returns a non-constGstCapsFeatures *
. This is for programming convenience – the caller should be aware that features inside a constantCaps
should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable withcaps_make_writable()
, you may modify the features returned in the usual way, e.g. with functions likeadd()
.Added in version 1.2.
- Parameters:
index – the index of the structure
- get_structure(index: int) Structure
Finds the structure in
caps
atindex
, and returns it.WARNING: This function takes a
const GstCaps *
, but returns a non-constGstStructure *
. This is for programming convenience – the caller should be aware that structures inside a constantCaps
should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable withcaps_make_writable()
, you may modify the structure returned in the usual way, e.g. with functions likeset()
.- Parameters:
index – the index of the structure
- intersect(caps2: Caps) Caps
Creates a new
Caps
that contains all the formats that are common to bothcaps1
andcaps2
. Defaults toZIG_ZAG
mode.- Parameters:
caps2 – a
Caps
to intersect
- intersect_full(caps2: Caps, mode: CapsIntersectMode) Caps
Creates a new
Caps
that contains all the formats that are common to bothcaps1
andcaps2
, the order is defined by theCapsIntersectMode
used.- Parameters:
caps2 – a
Caps
to intersectmode – The intersection algorithm/mode to use
- is_always_compatible(caps2: Caps) bool
A given
Caps
structure is always compatible with another if every media format that is in the first is also contained in the second. That is,caps1
is a subset ofcaps2
.- Parameters:
caps2 – the
Caps
to test
- is_equal(caps2: Caps) bool
Checks if the given caps represent the same set of caps.
- Parameters:
caps2 – another
Caps
- is_equal_fixed(caps2: Caps) bool
Tests if two
Caps
are equal. This function only works on fixedCaps
.- Parameters:
caps2 – the
Caps
to test
- is_fixed() bool
Fixed
Caps
describe exactly one format, that is, they have exactly one structure, and each field in the structure describes a fixed type. Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
- is_strictly_equal(caps2: Caps) bool
Checks if the given caps are exactly the same set of caps.
- Parameters:
caps2 – another
Caps
- is_subset(superset: Caps) bool
Checks if all caps represented by
subset
are also represented bysuperset
.- Parameters:
superset – a potentially greater
Caps
- is_subset_structure(structure: Structure) bool
Checks if
structure
is a subset ofcaps
. Seeis_subset()
for more information.- Parameters:
structure – a potential
Structure
subset ofcaps
- is_subset_structure_full(structure: Structure, features: CapsFeatures | None = None) bool
Checks if
structure
is a subset ofcaps
. Seeis_subset()
for more information.Added in version 1.2.
- Parameters:
structure – a potential
Structure
subset ofcaps
features – a
CapsFeatures
forstructure
- map_in_place(func: Callable[[...], bool], *user_data: Any) bool
Calls the provided function once for each structure and caps feature in the
Caps
. In contrast toforeach()
, the function may modify but not delete the structures and features. The caps must be mutable.Added in version 1.6.
- Parameters:
func – a function to call for each field
user_data – private data
- merge(caps2: Caps) Caps
Appends the structures contained in
caps2
tocaps1
if they are not yet expressed bycaps1
. The structures incaps2
are not copied – they are transferred to a writable copy ofcaps1
, and thencaps2
is freed. If either caps is ANY, the resulting caps will be ANY.- Parameters:
caps2 – the
Caps
to merge in
- merge_structure(structure: Structure) Caps
Appends
structure
tocaps
if it is not already expressed bycaps
.- Parameters:
structure – the
Structure
to merge
- merge_structure_full(structure: Structure, features: CapsFeatures | None = None) Caps
Appends
structure
withfeatures
tocaps
if its not already expressed bycaps
.Added in version 1.2.
- Parameters:
structure – the
Structure
to mergefeatures – the
CapsFeatures
to merge
- normalize() Caps
Returns a
Caps
that represents the same set of formats ascaps
, but contains no lists. Each list is expanded into separateStructure
.This function takes ownership of
caps
and will callcaps_make_writable()
on it so you must not usecaps
afterwards unless you keep an additional reference to it with gst_caps_ref().
- remove_structure(idx: int) None
Removes the structure with the given index from the list of structures contained in
caps
.- Parameters:
idx – Index of the structure to remove
- serialize(flags: SerializeFlags) str
Converts
caps
to a string representation. This string representation can be converted back to aCaps
byfrom_string()
.This prints the caps in human readable form.
This version of the caps serialization function introduces support for nested structures and caps but the resulting strings won’t be parsable with GStreamer prior to 1.20 unless
GST_SERIALIZE_FLAG_BACKWARD_COMPAT
is passed asflag
.Added in version 1.20.
- Parameters:
flags – a
SerializeFlags
- set_features(index: int, features: CapsFeatures | None = None) None
Sets the
features
for the structure atindex
.Added in version 1.2.
- Parameters:
index – the index of the structure
features – the
CapsFeatures
to set
- set_features_simple(features: CapsFeatures | None = None) None
Sets the
features
for all the structures ofcaps
.Added in version 1.16.
- Parameters:
features – the
CapsFeatures
to set
- set_value(field: str, value: Any) None
Sets the given
field
on all structures ofcaps
to the givenvalue
. This is a convenience function for callingset_value()
on all structures ofcaps
.- Parameters:
field – name of the field to set
value – value to set the field to
- simplify() Caps
Converts the given
caps
into a representation that represents the same set of formats, but in a simpler form. Component structures that are identical are merged. Component structures that have values that can be merged are also merged.This function takes ownership of
caps
and will callcaps_make_writable()
on it if necessary, so you must not usecaps
afterwards unless you keep an additional reference to it with gst_caps_ref().This method does not preserve the original order of
caps
.
- subtract(subtrahend: Caps) Caps
Subtracts the
subtrahend
from theminuend
. > This function does not work reliably if optional properties for caps > are included on one caps and omitted on the other.- Parameters:
subtrahend –
Caps
to subtract
- to_string() str
Converts
caps
to a string representation. This string representation can be converted back to aCaps
byfrom_string()
.For debugging purposes its easier to do something like this:
GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
This prints the caps in human readable form.
The implementation of serialization up to 1.20 would lead to unexpected results when there were nested
Caps
/Structure
deeper than one level.
- truncate() Caps
Discards all but the first structure from
caps
. Useful when fixating.This function takes ownership of
caps
and will callcaps_make_writable()
on it if necessary, so you must not usecaps
afterwards unless you keep an additional reference to it with gst_caps_ref().Note that it is not guaranteed that the returned caps have exactly one structure. If
caps
is any or empty caps then the returned caps will be the same and contain no structure at all.
Fields
- class Caps
- mini_object
The parent type