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_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_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:

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_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.

filter_and_map_in_place(func, *user_data)[source]
Parameters:

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

foreach(func, *user_data)[source]
Parameters:
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:
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:
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:
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:
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:

Sets the Gst.CapsFeatures features for the structure at index.

New in version 1.2.

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