Gst.Caps¶

Fields¶

Name	Type	Access	Description
mini_object	`Gst.MiniObject`	r/w	the parent type

Methods¶

class	`from_string` (string)
class	`new_any` ()
class	`new_empty` ()
class	`new_empty_simple` (media_type)
	`append` (caps2)
	`append_structure` (structure)
	`append_structure_full` (structure, features)
	`can_intersect` (caps2)
	`copy` ()
	`copy_nth` (nth)
	`filter_and_map_in_place` (func, *user_data)
	`fixate` ()
	`foreach` (func, *user_data)
	`get_features` (index)
	`get_size` ()
	`get_structure` (index)
	`intersect` (caps2)
	`intersect_full` (caps2, mode)
	`is_always_compatible` (caps2)
	`is_any` ()
	`is_empty` ()
	`is_equal` (caps2)
	`is_equal_fixed` (caps2)
	`is_fixed` ()
	`is_strictly_equal` (caps2)
	`is_subset` (superset)
	`is_subset_structure` (structure)
	`is_subset_structure_full` (structure, features)
	`map_in_place` (func, *user_data)
	`merge` (caps2)
	`merge_structure` (structure)
	`merge_structure_full` (structure, features)
	`normalize` ()
	`remove_structure` (idx)
	`serialize` (flags)
	`set_features` (index, features)
	`set_features_simple` (features)
	`set_value` (field, value)
	`simplify` ()
	`steal_structure` (index)
	`subtract` (subtrahend)
	`to_string` ()
	`truncate` ()

Details¶

class Gst.Caps¶

Caps (capabilities) are lightweight refcounted objects describing media types. They are composed of an array of Gst.Structure.

Caps are exposed on Gst.PadTemplate to describe all possible types a given pad can handle. They are also stored in the Gst.Registry along with a description of the Gst.Element.

Caps are exposed on the element pads using the Gst.Pad.query_caps() pad function. This function describes the possible types that the pad can handle or produce at runtime.

A Gst.Caps can be constructed with the following code fragment:

`` C

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 Gst.Caps is fixed when it has no fields with ranges or lists. Use Gst.Caps.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 Gst.Caps / Gst.Structure serialization into string had limited support for nested Gst.Caps / Gst.Structure fields. It could only support one level of nesting. Using more levels would lead to unexpected behavior when using serialization features, such as Gst.Caps.to_string() or Gst.value_serialize() and their counterparts.

classmethod from_string(string)[source]¶

Parameters:: string (str) – a string to convert to Gst.Caps
Returns:: a newly allocated Gst.Caps
Return type:: Gst.Caps or None

Converts caps from a string representation.

The implementation of serialization up to 1.20 would lead to unexpected results when there were nested Gst.Caps / Gst.Structure deeper than one level.

classmethod new_any()[source]¶

Returns:: the new Gst.Caps
Return type:: Gst.Caps

Creates a new Gst.Caps that indicates that it is compatible with any media format.

classmethod new_empty()[source]¶

Returns:: the new Gst.Caps
Return type:: Gst.Caps

Creates a new Gst.Caps that is empty. That is, the returned Gst.Caps contains no media formats. The Gst.Caps is guaranteed to be writable.

classmethod new_empty_simple(media_type)[source]¶

Parameters:: media_type (str) – the media type of the structure
Returns:: the new Gst.Caps
Return type:: Gst.Caps

Creates a new Gst.Caps that contains one Gst.Structure with name media_type.

append(caps2)[source]¶

Parameters:: caps2 (Gst.Caps) – the Gst.Caps to append

Appends the structures contained in caps2 to self. The structures in caps2 are not copied – they are transferred to self, and then caps2 is freed. If either caps is ANY, the resulting caps will be ANY.

append_structure(structure)[source]¶

Parameters:: structure (Gst.Structure) – the Gst.Structure to append

Appends structure to self. The structure is not copied; self becomes the owner of structure.

append_structure_full(structure, features)[source]¶

Parameters:

structure (Gst.Structure) – the Gst.Structure to append
features (Gst.CapsFeatures or None) – the Gst.CapsFeatures to append

Appends structure with features to self. The structure is not copied; self becomes the owner of structure.

New in version 1.2.

can_intersect(caps2)[source]¶

Parameters:: caps2 (Gst.Caps) – a Gst.Caps to intersect
Returns:: True if intersection would be not empty
Return type:: bool

Tries intersecting self and caps2 and reports whether the result would not be empty

copy()[source]¶

Returns:: the new Gst.Caps
Return type:: Gst.Caps

Creates a new Gst.Caps as a copy of the old self. The new caps will have a refcount of 1, owned by the caller. The structures are copied as well.

Note that this function is the semantic equivalent of a gst_caps_ref() followed by a gst_caps_make_writable(). If you only want to hold on to a reference to the data, you should use gst_caps_ref().

copy_nth(nth)[source]¶

Parameters:: nth (int) – the nth structure to copy
Returns:: the new Gst.Caps
Return type:: Gst.Caps

Creates a new Gst.Caps and appends a copy of the nth structure contained in self.

New in version 1.16.

filter_and_map_in_place(func, *user_data)[source]¶

Parameters:

func (Gst.CapsFilterMapFunc) – a function to call for each field
user_data (object or None) – private data

Calls the provided function once for each structure and caps feature in the Gst.Caps. In contrast to Gst.Caps.foreach(), the function may modify the structure and features. In contrast to Gst.Caps.map_in_place(), the structure and features are removed from the caps if False is returned from the function. The caps must be mutable.

New in version 1.6.

fixate()[source]¶

Returns:: the fixated caps
Return type:: Gst.Caps

Modifies the given self into a representation with only fixed values. First the caps will be truncated and then the first structure will be fixated with Gst.Structure.fixate().

This function takes ownership of self and will call gst_caps_make_writable() on it so you must not use self 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 self 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, *user_data)[source]¶

Parameters:

func (Gst.CapsForeachFunc) – a function to call for each field
user_data (object or None) – private data

Returns:

True if the supplied function returns True for each call, False otherwise.

Return type:

bool

Calls the provided function once for each structure and caps feature in the Gst.Caps. The function must not modify the fields. Also see Gst.Caps.map_in_place() and Gst.Caps.filter_and_map_in_place().

New in version 1.6.

get_features(index)[source]¶

Parameters:: index (int) – the index of the structure
Returns:: a pointer to the Gst.CapsFeatures corresponding to index
Return type:: Gst.CapsFeatures or None

Finds the features in self at index, and returns it.

WARNING: This function takes a const GstCaps *, but returns a non-const GstCapsFeatures *. This is for programming convenience – the caller should be aware that features inside a constant Gst.Caps should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable with gst_caps_make_writable(), you may modify the features returned in the usual way, e.g. with functions like Gst.CapsFeatures.add().

New in version 1.2.

get_size()[source]¶

Returns:: the number of structures that self contains
Return type:: int

Gets the number of structures contained in self.

get_structure(index)[source]¶

Parameters:: index (int) – the index of the structure
Returns:: a pointer to the Gst.Structure corresponding to index
Return type:: Gst.Structure

Finds the structure in self at index, and returns it.

WARNING: This function takes a const GstCaps *, but returns a non-const GstStructure *. This is for programming convenience – the caller should be aware that structures inside a constant Gst.Caps should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable with gst_caps_make_writable(), you may modify the structure returned in the usual way, e.g. with functions like gst_structure_set().

intersect(caps2)[source]¶

Parameters:: caps2 (Gst.Caps) – a Gst.Caps to intersect
Returns:: the new Gst.Caps
Return type:: Gst.Caps

Creates a new Gst.Caps that contains all the formats that are common to both self and caps2. Defaults to Gst.CapsIntersectMode.ZIG_ZAG mode.

intersect_full(caps2, mode)[source]¶

Parameters:

caps2 (Gst.Caps) – a Gst.Caps to intersect
mode (Gst.CapsIntersectMode) – The intersection algorithm/mode to use

Returns:

the new Gst.Caps

Return type:

Gst.Caps

Creates a new Gst.Caps that contains all the formats that are common to both self and caps2, the order is defined by the Gst.CapsIntersectMode used.

is_always_compatible(caps2)[source]¶

Parameters:: caps2 (Gst.Caps) – the Gst.Caps to test
Returns:: True if self is a subset of caps2.
Return type:: bool

A given Gst.Caps structure is always compatible with another if every media format that is in the first is also contained in the second. That is, self is a subset of caps2.

is_any()[source]¶

Returns:: True if self represents any format.
Return type:: bool

Determines if self represents any media format.

is_empty()[source]¶

Returns:: True if self represents no formats.
Return type:: bool

Determines if self represents no media formats.

is_equal(caps2)[source]¶

Parameters:: caps2 (Gst.Caps) – another Gst.Caps
Returns:: True if both caps are equal.
Return type:: bool

Checks if the given caps represent the same set of caps.

is_equal_fixed(caps2)[source]¶

Parameters:: caps2 (Gst.Caps) – the Gst.Caps to test
Returns:: True if the arguments represent the same format
Return type:: bool

Tests if two Gst.Caps are equal. This function only works on fixed Gst.Caps.

is_fixed()[source]¶

Returns:: True if self is fixed
Return type:: bool

Fixed Gst.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)[source]¶

Parameters:: caps2 (Gst.Caps) – another Gst.Caps
Returns:: True if both caps are strictly equal.
Return type:: bool

Checks if the given caps are exactly the same set of caps.

is_subset(superset)[source]¶

Parameters:: superset (Gst.Caps) – a potentially greater Gst.Caps
Returns:: True if self is a subset of superset
Return type:: bool

Checks if all caps represented by self are also represented by superset.

is_subset_structure(structure)[source]¶

Parameters:: structure (Gst.Structure) – a potential Gst.Structure subset of self
Returns:: True if structure is a subset of self
Return type:: bool

Checks if structure is a subset of self. See Gst.Caps.is_subset() for more information.

is_subset_structure_full(structure, features)[source]¶

Parameters:

structure (Gst.Structure) – a potential Gst.Structure subset of self
features (Gst.CapsFeatures or None) – a Gst.CapsFeatures for structure

Returns:

True if structure is a subset of self

Return type:

bool

Checks if structure is a subset of self. See Gst.Caps.is_subset() for more information.

New in version 1.2.

map_in_place(func, *user_data)[source]¶

Parameters:

func (Gst.CapsMapFunc) – a function to call for each field
user_data (object or None) – private data

Returns:

True if the supplied function returns True for each call, False otherwise.

Return type:

bool

Calls the provided function once for each structure and caps feature in the Gst.Caps. In contrast to Gst.Caps.foreach(), the function may modify but not delete the structures and features. The caps must be mutable.

New in version 1.6.

merge(caps2)[source]¶

Parameters:: caps2 (Gst.Caps) – the Gst.Caps to merge in
Returns:: the merged caps.
Return type:: Gst.Caps

Appends the structures contained in caps2 to self if they are not yet expressed by self. The structures in caps2 are not copied – they are transferred to a writable copy of self, and then caps2 is freed. If either caps is ANY, the resulting caps will be ANY.

merge_structure(structure)[source]¶

Parameters:: structure (Gst.Structure) – the Gst.Structure to merge
Returns:: the merged caps.
Return type:: Gst.Caps

Appends structure to self if it is not already expressed by self.

merge_structure_full(structure, features)[source]¶

Parameters:

structure (Gst.Structure) – the Gst.Structure to merge
features (Gst.CapsFeatures or None) – the Gst.CapsFeatures to merge

Returns:

the merged caps.

Return type:

Gst.Caps

Appends structure with features to self if its not already expressed by self.

New in version 1.2.

normalize()[source]¶

Returns:: the normalized Gst.Caps
Return type:: Gst.Caps

Returns a Gst.Caps that represents the same set of formats as self, but contains no lists. Each list is expanded into separate Gst.Structure.

This function takes ownership of self and will call gst_caps_make_writable() on it so you must not use self afterwards unless you keep an additional reference to it with gst_caps_ref().

remove_structure(idx)[source]¶

Parameters:: idx (int) – Index of the structure to remove

Removes the structure with the given index from the list of structures contained in self.

serialize(flags)[source]¶

Parameters:: flags (Gst.SerializeFlags) – a Gst.SerializeFlags
Returns:: a newly allocated string representing self.
Return type:: str

Converts self to a string representation. This string representation can be converted back to a Gst.Caps by Gst.Caps.from_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.SerializeFlags.BACKWARD_COMPAT is passed as flag.

New in version 1.20.

set_features(index, features)[source]¶

Parameters:

index (int) – the index of the structure
features (Gst.CapsFeatures or None) – the Gst.CapsFeatures to set

Sets the features for the structure at index.

New in version 1.2.

set_features_simple(features)[source]¶

Parameters:: features (Gst.CapsFeatures or None) – the Gst.CapsFeatures to set

Sets the features for all the structures of self.

New in version 1.16.

set_value(field, value)[source]¶

Parameters:

field (str) – name of the field to set
value (GObject.Value) – value to set the field to

Sets the given field on all structures of self to the given value. This is a convenience function for calling Gst.Structure.set_value() on all structures of self.

simplify()[source]¶

Returns:: The simplified caps.
Return type:: Gst.Caps

Converts the given self 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 self and will call gst_caps_make_writable() on it if necessary, so you must not use self afterwards unless you keep an additional reference to it with gst_caps_ref().

This method does not preserve the original order of self.

steal_structure(index)[source]¶

Parameters:: index (int) – Index of the structure to retrieve
Returns:: a pointer to the Gst.Structure corresponding to index.
Return type:: Gst.Structure or None

Retrieves the structure with the given index from the list of structures contained in self. The caller becomes the owner of the returned structure.

subtract(subtrahend)[source]¶

Parameters:: subtrahend (Gst.Caps) – Gst.Caps to subtract
Returns:: the resulting caps
Return type:: Gst.Caps

Subtracts the subtrahend from the self.

This function does not work reliably if optional properties for caps are included on one caps and omitted on the other.

to_string()[source]¶

Returns:: a newly allocated string representing self.
Return type:: str

Converts self to a string representation. This string representation can be converted back to a Gst.Caps by Gst.Caps.from_string().

For debugging purposes its easier to do something like this:

`` C 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 Gst.Caps / Gst.Structure deeper than one level.

truncate()[source]¶

Returns:: truncated caps
Return type:: Gst.Caps

Discards all but the first structure from self. Useful when fixating.

This function takes ownership of self and will call gst_caps_make_writable() on it if necessary, so you must not use self 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 self is any or empty caps then the returned caps will be the same and contain no structure at all.