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::Capscopy () const
 Creates a new Gst::Caps as a copy of the old caps.
Glib::RefPtr<Gst::Capscopy_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 (const Structure& structure)
 Appends a structure to caps if its not already expressed by caps.
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<Gst::Caps>& other_caps) const
 Checks if the given caps represent the same set of caps.
bool equals_fixed (const Glib::RefPtr<Gst::Caps>& other_caps) const
 Tests if two Gst::Caps are equal.
bool is_always_compatible (const Glib::RefPtr<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<Gst::Caps>& superset_caps) const
 Checks if all caps represented by subset are also represented by superset.
Glib::RefPtr<Gst::Capsget_intersect (const Glib::RefPtr<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::Capsget_union (const Glib::RefPtr<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::Capsget_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::Capsget_difference (const Glib::RefPtr<const Gst::Caps>& subtrahend_caps) const
 Subtracts the subtrahend from the minuend.
Glib::RefPtr<Gst::Capsmake_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<Capscreate ()
static Glib::RefPtr<Gst::Capscreate_any ()
 Creates a new Gst::Caps that indicates that it is compatible with any media format.
static Glib::RefPtr<Gst::Capscreate_simple (const Glib::ustring& media_type)
 Creates a new Gst::Caps that contains one Gst::Structure.
static Glib::RefPtr<Gst::Capscreate (const Structure& first_struct)
 Creates a new Gst::Caps and adds the given Gst::Structure.
static Glib::RefPtr<Gst::Capscreate_from_string (const Glib::ustring& string)
 Converts caps from a string representation.
static Glib::RefPtr<Gst::Capsload (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::Capswrap (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.

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

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

Glib::RefPtr<Gst::Caps> Gst::Caps::make_writable (  ) 

Returns: the same Gst::Caps object.

Returns:
The same Gst::Caps object.

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 ( const 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:

Generated on Thu Jan 15 09:33:12 2009 for gstreamermm by  doxygen 1.5.7.1