# Gst::Caps Class Reference

Gst::Caps (capabilities) are lightweight objects describing media formats. More...

`#include <caps.h>`

List of all members.

## Public Member Functions
void | reference () const
void | unreference () const
GstCaps* | gobj ()
| Provides access to the underlying C instance.
const GstCaps* | gobj () const
| Provides access to the underlying C instance.
GstCaps* | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::RefPtr<Gst::Caps> | copy () const
| Creates a new Gst::Caps as a copy of the old caps.
Glib::RefPtr<Gst::Caps> | copy_nth (guint nth) const
| Creates a new Gst::Caps and appends a copy of the nth structure contained in caps.
void | append (const Glib::RefPtr<Gst::Caps>& caps)
| Appends the structures contained in caps2 to caps1.
void | merge (const Glib::RefPtr<Gst::Caps>& caps)
| Appends the structures contained in caps2 to caps1 if they are not yet expressed by caps1.
void | append_structure (const Structure& structure)
| Appends a structure to caps.
void | merge_structure (Structure& structure)
| Appends a structure to caps if its not already expressed by caps.
const Structure | get_structure (guint idx) const
| Finds the structure in caps that has the index idx, and returns it.
void | remove_structure (guint idx)
| removes the stucture with the given index from the list of structures contained in caps.
guint | size () const
| Gets the number of structures contained in caps.
void | set_simple (const Glib::ustring& name, const Glib::ValueBase& value)
| Sets fields in a simple Gst::Caps.
template<class DataType >
void | set_simple (const Glib::ustring& name, const DataType& data)
| Sets fields in a simple Gst::Caps.
void | set_simple (const Glib::ustring& name, const char* data)
| Sets fields in a simple Gst::Caps.
bool | is_any () const
| Determines if caps represents any media format.
bool | empty () const
| Determines if caps represents no media formats.
bool | is_fixed () const
| Fixed Gst::Caps describe exactly one format, that is, they have exactly one structure, and each field in the structure describes a fixed type.
bool | equals (const Glib::RefPtr<const Gst::Caps>& other_caps) const
| Checks if the given caps represent the same set of caps.
bool | equals_fixed (const Glib::RefPtr<const Gst::Caps>& other_caps) const
| Tests if two Gst::Caps are equal.
bool | is_always_compatible (const Glib::RefPtr<const Gst::Caps>& other_caps) const
| 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.
bool | is_subset (const Glib::RefPtr<const Gst::Caps>& superset_caps) const
| Checks if all caps represented by subset are also represented by superset.
Glib::RefPtr<Gst::Caps> | get_intersect (const Glib::RefPtr<const Gst::Caps>& other_caps) const
| Creates a new Gst::Caps that contains all the formats that are common to both caps1 and caps2.
Glib::RefPtr<Gst::Caps> | get_union (const Glib::RefPtr<const Gst::Caps>& other_caps) const
| Creates a new Gst::Caps that contains all the formats that are in either caps1 and caps2.
Glib::RefPtr<Gst::Caps> | get_normal () const
| Creates a new Gst::Caps that represents the same set of formats as caps, but contains no lists.
bool | simplify ()
| Modifies the given caps inplace into a representation that represents the same set of formats, but in a simpler form.
xmlpp::Node* | save (xmlpp::Node* parent) const
| Serializes a Gst::Caps to XML and adds it as a child node of parent.
Glib::ustring | to_string () const
| Converts caps to a string representation.
Glib::RefPtr<Gst::Caps> | get_difference (const Glib::RefPtr<const Gst::Caps>& subtrahend_caps) const
| Subtracts the subtrahend from the minuend.
Glib::RefPtr<Gst::Caps> | create_writable ()
| Returns: the same Gst::Caps object.
void | truncate ()
| Destructively discard all but the first structure from caps.
## Static Public Member Functions
static Glib::RefPtr<Caps> | create ()
static Glib::RefPtr<Gst::Caps> | create_any ()
| Creates a new Gst::Caps that indicates that it is compatible with any media format.
static Glib::RefPtr<Gst::Caps> | create_simple (const Glib::ustring& media_type)
| Creates a new Gst::Caps that contains one Gst::Structure.
static Glib::RefPtr<Gst::Caps> | create (const Structure& first_struct)
| Creates a new Gst::Caps and adds the given Gst::Structure.
static Glib::RefPtr<Gst::Caps> | create_from_string (const Glib::ustring& string)
| Converts caps from a string representation.
static Glib::RefPtr<Gst::Caps> | load (xmlpp::Node* parent)
| Creates a Gst::Caps from its XML serialization.
## Protected Member Functions
| Caps ()
void | operator delete (void*, size_t)
## Related Functions
(Note that these are not member functions.)
Glib::RefPtr<Gst::Caps> | wrap (GstCaps* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

Gst::Caps (capabilities) are lightweight objects describing media formats.

They are composed of an array of Gst::Structure.

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

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

Gst::Caps are also attached to buffers to describe to content of the data pointed to by the buffer with Gst::Buffer::set_caps(). Gst::Caps attached to a Gst::Buffer allow for format negotiation upstream and downstream.

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

     Glib::RefPtr<Gst::Caps> caps = Gst::Caps::create_simple("video/x-raw-yuv");
     caps->set_simple("format", Gst::Fourcc('I', '4', '2', '0'));
     caps->set_simple("framerate", Gst::Fraction(25, 1));
     caps->set_simple("pixel-aspect-ratio", Gst::Fraction(1, 1));
     caps->set_simple("width", 320);
     caps->set_simple("height", 240);

## Constructor & Destructor Documentation

Gst::Caps::Caps | ( |  | ) | `[protected]`

## Member Function Documentation

void Gst::Caps::append | ( | const Glib::RefPtr<Gst::Caps>& | caps | ) |

Appends the structures contained in caps2 to caps1.

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

Parameters:

  | caps2 | The Gst::Caps to append.

void Gst::Caps::append_structure | ( | const Structure& | structure | ) |

Appends a structure to caps.

Parameters:

  | structure | The Gst::Structure to append.

Glib::RefPtr<Gst::Caps> Gst::Caps::copy | ( |  | ) | const

Creates a new Gst::Caps as a copy of the old caps.

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.

Returns:
  The new Gst::Caps.

Glib::RefPtr<Gst::Caps> Gst::Caps::copy_nth | ( | guint | nth | ) | const

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

Parameters:

  | nth | The nth structure to copy.

Returns:
  The new Gst::Caps.

static Glib::RefPtr<Gst::Caps> Gst::Caps::create | ( | const Structure& | first_struct | ) | `[static]`

Creates a new Gst::Caps and adds the given Gst::Structure.

Use append_structure() to add additional structures.

Parameters:

  | first_struct | The first structure to add.

Returns:
  Returns the new Gst::Caps.

static Glib::RefPtr<Caps> Gst::Caps::create | ( |  | ) | `[static]`

static Glib::RefPtr<Gst::Caps> Gst::Caps::create_any | ( |  | ) | `[static]`

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

Returns:
  The new Gst::Caps.

static Glib::RefPtr<Gst::Caps> Gst::Caps::create_from_string | ( | const Glib::ustring & | string | ) | `[static]`

Converts caps from a string representation.

Parameters:

  | string | A string to convert to Gst::Caps.

Returns:
  A newly allocated Gst::Caps.

static Glib::RefPtr<Gst::Caps> Gst::Caps::create_simple | ( | const Glib::ustring & | media_type | ) | `[static]`

Creates a new Gst::Caps that contains one Gst::Structure.

Parameters:

  | media_type | The media type of the structure.

Returns:
  The new Gst::Caps.

Glib::RefPtr<Gst::Caps> Gst::Caps::create_writable | ( |  | ) |

Returns: the same Gst::Caps object.

Returns:
  The same Gst::Caps object.

bool Gst::Caps::empty | ( |  | ) | const

Determines if caps represents no media formats.

Returns:
  `true` if caps represents no formats.

bool Gst::Caps::equals | ( | const Glib::RefPtr<const Gst::Caps>& | other_caps | ) | const

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

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

This function deals correctly with passing `0` for any of the caps.

Parameters:

  | caps2 | Another Gst::Caps.

Returns:
  `true` if both caps are equal.

bool Gst::Caps::equals_fixed | ( | const Glib::RefPtr<const Gst::Caps>& | other_caps | ) | const

Tests if two Gst::Caps are equal.

This function only works on fixed Gst::Caps.

Parameters:

  | caps2 | The Gst::Caps to test.

Returns:
  `true` if the arguments represent the same format.

Glib::RefPtr<Gst::Caps> Gst::Caps::get_difference | ( | const Glib::RefPtr<const Gst::Caps>& | subtrahend_caps | ) | const

Subtracts the subtrahend from the minuend.

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

Parameters:

  | subtrahend | Gst::Caps to substract.

Returns:
  The resulting caps.

Glib::RefPtr<Gst::Caps> Gst::Caps::get_intersect | ( | const Glib::RefPtr<const Gst::Caps>& | other_caps | ) | const

Creates a new Gst::Caps that contains all the formats that are common to both caps1 and caps2.

Parameters:

  | caps2 | A Gst::Caps to intersect.

Returns:
  The new Gst::Caps.

Glib::RefPtr<Gst::Caps> Gst::Caps::get_normal | ( |  | ) | const

Creates a new Gst::Caps that represents the same set of formats as caps, but contains no lists.

Each list is expanded into separate GstStructures.

Returns:
  The new Gst::Caps.

const Structure Gst::Caps::get_structure | ( | guint | idx | ) | const

Finds the structure in caps that has the index idx, and returns it.

Parameters:

  | index | The index of the structure.

Returns:
  The Gst::Structure corresponding to index.

Glib::RefPtr<Gst::Caps> Gst::Caps::get_union | ( | const Glib::RefPtr<const Gst::Caps>& | other_caps | ) | const

Creates a new Gst::Caps that contains all the formats that are in either caps1 and caps2.

Parameters:

  | caps2 | A Gst::Caps to union.

Returns:
  The new Gst::Caps.

const GstCaps* Gst::Caps::gobj | ( |  | ) | const

Provides access to the underlying C instance.

GstCaps* Gst::Caps::gobj | ( |  | ) |

Provides access to the underlying C instance.

GstCaps* Gst::Caps::gobj_copy | ( |  | ) | const

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

bool Gst::Caps::is_always_compatible | ( | const Glib::RefPtr<const Gst::Caps>& | other_caps | ) | const

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, caps1 is a subset of caps2.

Parameters:

  | caps2 | The Gst::Caps to test.

Returns:
  `true` if caps1 is a subset of caps2.

bool Gst::Caps::is_any | ( |  | ) | const

Determines if caps represents any media format.

Returns:
  `true` if caps represents any format.

bool Gst::Caps::is_fixed | ( |  | ) | const

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.

Returns:
  `true` if caps is fixed.

bool Gst::Caps::is_subset | ( | const Glib::RefPtr<const Gst::Caps>& | superset_caps | ) | const

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

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

Parameters:

  | superset | A potentially greater Gst::Caps.

Returns:
  `true` if subset is a subset of superset.

static Glib::RefPtr<Gst::Caps> Gst::Caps::load | ( | xmlpp::Node * | parent | ) | `[static]`

Creates a Gst::Caps from its XML serialization.

Parameters:

  | parent | A XML node.

Returns:
  A new Gst::Caps structure.

void Gst::Caps::merge | ( | const Glib::RefPtr<Gst::Caps>& | caps | ) |

Appends the structures contained in caps2 to caps1 if they are not yet expressed by caps1.

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

Since: 0.10.10

Parameters:

  | caps2 | The Gst::Caps to merge in.

void Gst::Caps::merge_structure | ( | Structure& | structure | ) |

Appends a structure to caps if its not already expressed by caps.

Parameters:

  | structure | The Gst::Structure to merge.

void Gst::Caps::operator delete | ( | void * | ,
|  | size_t |  |
| ) |  |  | `[protected]`

void Gst::Caps::reference | ( |  | ) | const

void Gst::Caps::remove_structure | ( | guint | idx | ) |

removes the stucture with the given index from the list of structures contained in caps.

Parameters:

  | idx | Index of the structure to remove.

xmlpp::Node* Gst::Caps::save | ( | xmlpp::Node * | parent | ) | const

Serializes a Gst::Caps to XML and adds it as a child node of parent.

Parameters:

  | parent | A XML parent node.

Returns:
  The parent XML Node.

void Gst::Caps::set_simple | ( | const Glib::ustring & | name,
|  | const char * | data |
| ) |  |  |

Sets fields in a simple Gst::Caps.

A simple Gst::Caps is one that only has one structure.

Parameters:

  | name | Field to set.
  | data | A C string (const char*) which the field should be set to.

template <class DataType >

void Gst::Caps::set_simple | ( | const Glib::ustring & | name,
|  | const DataType & | data |
| ) |  |  | `[inline]`

Sets fields in a simple Gst::Caps.

A simple Gst::Caps is one that only has one structure. This method, like the Gst::Structure::set_field() methods, translates certain GTypes to GStreamer specific GTypes for functional compatibility.

Parameters:

  | name | Field to set.
  | data | A value which the field should be set to (this can be any supported C++ type).

void Gst::Caps::set_simple | ( | const Glib::ustring & | name,
|  | const Glib::ValueBase & | value |
| ) |  |  |

Sets fields in a simple Gst::Caps.

A simple Gst::Caps is one that only has one structure. This method, like the Gst::Structure::set_field() methods, translates certain GTypes to GStreamer specific GTypes for functional compatibility.

Parameters:

  | name | Field to set.
  | value | The value which the field should be set to.

bool Gst::Caps::simplify | ( |  | ) |

Modifies the given caps inplace 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.

Returns:
  `true`, if the caps could be simplified.

guint Gst::Caps::size | ( |  | ) | const

Gets the number of structures contained in caps.

Returns:
  The number of structures that caps contains.

Glib::ustring Gst::Caps::to_string | ( |  | ) | const

Converts caps 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 readble form.

Returns:
  A newly allocated string representing caps.

void Gst::Caps::truncate | ( |  | ) |

Destructively discard all but the first structure from caps.

Useful when fixating. caps must be writable.

void Gst::Caps::unreference | ( |  | ) | const

## Friends And Related Function Documentation

Glib::RefPtr<Gst::Caps> wrap | ( | GstCaps * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- caps.h