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)
	`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:

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 properties 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 the current Gst.Caps / Gst.Structure serialization into string has limited support for nested Gst.Caps / Gst.Structure fields. It can only support one level of nesting. Using more levels will 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 current implementation of serialization will lead to unexpected results when there are 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. Caller is responsible for unreffing the returned caps.

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. Caller is responsible for unreffing the returned caps.

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().

When you are finished with the caps, call gst_caps_unref() on it.

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.filter_and_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 then 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 that has the index index, and returns it.

WARNING: This function takes a const Gst.Caps *, but returns a non-const Gst.CapsFeatures *. 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 features returned in the usual way, e.g. with functions like Gst.CapsFeatures.add().

You do not need to free or unref the structure returned, it belongs to the Gst.Caps.

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 that has the index index, and returns it.

WARNING: This function takes a const Gst.Caps *, but returns a non-const Gst.Structure *. 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().

You do not need to free or unref the structure returned, it belongs to the Gst.Caps.

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 its 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 GstStructures.

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.

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 Gst.CapsFeatures 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 Gst.CapsFeatures 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:

GST_LOG ("caps are %" GST_PTR_FORMAT, caps);

This prints the caps in human readable form.

The current implementation of serialization will lead to unexpected results when there are nested Gst.Caps / Gst.Structure deeper than one level.

truncate()[source]¶

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

Discard 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 then returned caps will be the same and contain no structure at all.