gstreamermm: Gst::Caps Class Reference

A class that describes sets of media formats. More...

Inheritance diagram for Gst::Caps:

Collaboration diagram for Gst::Caps:

Public Member Functions
void	reference () const
	Increment the reference count for this object. More...

void	unreference () const
	Decrement the reference count for this object. More...

GstCaps*	gobj ()
	Provides access to the underlying C instance. More...

const GstCaps*	gobj () const
	Provides access to the underlying C instance. More...

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

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

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

void	append (Glib::RefPtr< Gst::Caps >& caps)
	Appends the structures contained in caps to this object. More...

Glib::RefPtr< Gst::Caps >	merge (Glib::RefPtr< Gst::Caps >& caps)
	Appends the structures contained in caps to an object if they are not yet expressed by this object. More...

void	append_structure (const Structure& structure)
	Appends a structure to caps. More...

void	append_structure (const Structure& structure, const CapsFeatures& features)
	Appends a structure to caps. More...

Glib::RefPtr< Gst::Caps >	merge_structure (const Structure& structure)
	Appends a structure to caps if its not already expressed by caps. More...

Glib::RefPtr< Gst::Caps >	merge_structure (const Structure& structure, const CapsFeatures& features)
	Appends a structure to caps if its not already expressed by caps. More...

const Structure	get_structure (guint idx) const
	Finds the structure in caps that has the index idx, and returns it. More...

void	remove_structure (guint idx)
	removes the stucture with the given index from the list of structures contained in caps. More...

guint	size () const
	Gets the number of structures contained in caps. More...

Structure	steal_structure (guint index)
	Retrieves the structure with the given index from the list of structures contained in caps. More...

void	set_simple (const Glib::ustring& name, const Glib::ValueBase& value)
	Sets fields in a simple Gst::Caps. More...

template<class DataType >
void	set_simple (const Glib::ustring& name, const DataType& data)
	Sets fields in a simple Gst::Caps. More...

void	set_simple (const Glib::ustring& name, const char* data)
	Sets fields in a simple Gst::Caps. More...

void	set_value (const Glib::ustring& field, const Glib::ValueBase& value)
	Sets the given field on all structures of caps to the given value. More...

template<class DataType >
void	set_value (const Glib::ustring& name, const DataType& data)
	Sets the given field on all structures to the given value. More...

bool	is_any () const
	Determines if caps represents any media format. More...

bool	empty () const
	Determines if caps represents no media formats. More...

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

bool	equals (const Glib::RefPtr< const Gst::Caps >& other_caps) const
	Checks if the given caps represent the same set of caps. More...

bool	equals_fixed (const Glib::RefPtr< const Gst::Caps >& other_caps) const
	Tests if two Gst::Caps are equal. More...

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

bool	is_subset (const Glib::RefPtr< const Gst::Caps >& superset_caps) const
	Checks if all caps represented by subset are also represented by superset. More...

bool	can_intersect (const Glib::RefPtr< const Gst::Caps >& caps2) const
	Tries intersecting caps1 and caps2 and reports whether the result would not be empty. More...

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

Glib::RefPtr< Gst::Caps >	get_intersect (const Glib::RefPtr< const Gst::Caps >& other_caps, CapsIntersectMode p2) const
	Creates a new Gst::Caps that contains all the formats that are common to both caps1 and caps2, the order is defined by the Gst::CapsIntersectMode used. More...

Glib::RefPtr< Gst::Caps >	get_normal () const
	Returns a Gst::Caps that represents the same set of formats as caps, but contains no lists. More...

Glib::RefPtr< Gst::Caps >	simplify ()
	Converts the given caps into a representation that represents the same set of formats, but in a simpler form. More...

Glib::ustring	to_string () const
	Converts caps to a string representation. More...

Glib::RefPtr< Gst::Caps >	get_difference (const Glib::RefPtr< const Gst::Caps >& subtrahend_caps) const
	Subtracts the subtrahend from the minuend. More...

Glib::RefPtr< Gst::Caps >	create_writable ()
	Returns a writable copy of . More...

Glib::RefPtr< Gst::Caps >	truncate ()
	Discard all but the first structure from caps. More...

CapsFeatures	get_features (guint index) const
	Finds the features in caps that has the index index , and returns it. More...

void	set_features (guint index, const CapsFeatures& features)
	Sets the Gst::CapsFeatures for the structure at index. More...

Public Member Functions inherited from Gst::MiniObject
void	reference () const
	Increment the reference count for this object. More...

void	unreference () const
	Decrement the reference count for this object. More...

GstMiniObject*	gobj ()
	Provides access to the underlying C instance. More...

const GstMiniObject*	gobj () const
	Provides access to the underlying C instance. More...

GstMiniObject*	gobj_copy () const
	Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...

	~MiniObject ()

guint	get_flags () const

void	set_flags (const guint& value)

gint	get_refcount () const

gint	get_lockstate () const

bool	lock (LockFlags flags)
	Lock the mini-object with the specified access mode in flags. More...

void	unlock (LockFlags flags)
	Unlock the mini-object with the specified access mode in flags. More...

bool	is_writable () const
	If mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE lock on object is the only one, this means that changes to the object will not be visible to any other object. More...

Glib::RefPtr< MiniObject >	create_writable ()
	Checks if a mini-object is writable. More...

void	set_qdata (GQuark quark, QuarkData* data)
	This sets an opaque, named pointer on a miniobject. More...

QuarkData*	get_qdata (GQuark quark) const
	This function gets back user data pointers stored via set_qdata(). More...

QuarkData*	steal_qdata (GQuark quark)
	This function gets back user data pointers stored via set_qdata() and removes the data from object without invoking its destroy() function (if any was set). More...

void	add_finalize_notifier (const SlotFinalizer& slot)
	Adds notifier when mini object is finalized. More...

void	remove_finalize_notifier ()
	Remove finalize notifier. More...

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

static Glib::RefPtr< Gst::Caps >	create_simple (const Glib::ustring& media_type)
	Creates a new Gst::Caps that contains one Gst::Structure. More...

static Glib::RefPtr< Gst::Caps >	create (const Structure& first_struct)
	Creates a new Gst::Caps and adds the given Gst::Structure. More...

static Glib::RefPtr< Gst::Caps >	create_from_string (const Glib::ustring&string)
	Converts caps from a string representation. More...

Protected Member Functions
	Caps ()

void	operator delete (void*, std::size_t)

Protected Member Functions inherited from Gst::MiniObject
	MiniObject ()

void	operator delete (void*, std::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. More...

Related Functions inherited from Gst::MiniObject
Glib::RefPtr< Gst::MiniObject >	wrap (GstMiniObject* object, bool take_copy=false)
	A Glib::wrap() method for this object. More...

Additional Inherited Members
Public Types inherited from Gst::MiniObject
typedef sigc::slot< void >	SlotFinalizer

Detailed Description

A class that describes sets of media formats.

Caps (capabilities) are lightweight objects describing media formats. 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::get_caps() method. This method describes the possible types that the pad can handle or produce at runtime.

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 ( Glib::RefPtr< Gst::Caps >& caps )

Appends the structures contained in caps to this object.

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

Parameters

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

void Gst::Caps::append_structure	(	const Structure&	structure,
		const CapsFeatures&	features
	)

Appends a structure to caps.

Parameters

structure	The Gst::Structure to append.
features	The Gst::CapsFeatures to append.

bool Gst::Caps::can_intersect ( const Glib::RefPtr< const Gst::Caps >& caps2 ) const

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

Parameters

caps2 A Gst::Caps to intersect.

Returns: true if intersection would be not empty.

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

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<Caps> Gst::Caps::create ( )

static

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<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 a writable copy of .

If there is only one reference count on Gst::Caps object , the caller must be the owner, and so this function will return the caps object unchanged. If on the other hand there is more than one reference on the object, a new caps object will be returned.

Returns: A buffer (possibly the same pointer) that is writable.

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.

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

Returns: The resulting caps.

CapsFeatures Gst::Caps::get_features ( guint index ) const

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

Parameters

index the index of the structure.

Returns: The new Gst::CapsFeatures corresponding to index.

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.

Defaults to Gst::CAPS_INTERSECT_ZIG_ZAG mode.

Parameters

caps2 A Gst::Caps to intersect.

Returns: The new Gst::Caps.

Glib::RefPtr<Gst::Caps> Gst::Caps::get_intersect	(	const Glib::RefPtr< const Gst::Caps >&	other_caps,
		CapsIntersectMode	p2
	)		const

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

Parameters

caps2	A Gst::Caps to intersect.
mode	The intersection algorithm/mode to use.

Returns: The new Gst::Caps.

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

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

Each list is expanded into separate GstStructures.

This function takes ownership of caps.

Returns: The normalized 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.

GstCaps* Gst::Caps::gobj ( )

Provides access to the underlying C instance.

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

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.

Parameters

superset A potentially greater Gst::Caps.

Returns: true if subset is a subset of superset.

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

Appends the structures contained in caps to an object if they are not yet expressed by this object.

The structures in caps are not copied – they are transferred to a writable copy of this object, and then caps is freed. If either caps is ANY, the resulting caps will be ANY.

Parameters

caps	The Gst::Caps to merge in.

Returns: The merged caps.

Glib::RefPtr<Gst::Caps> 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.

Glib::RefPtr<Gst::Caps> Gst::Caps::merge_structure	(	const Structure&	structure,
		const CapsFeatures&	features
	)

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

Parameters

structure	The Gst::Structure to merge.
features	The Gst::CapsFeatures to merge.

void Gst::Caps::operator delete	(	void *	,
		std::size_t
	)

protected

void Gst::Caps::reference ( ) const

Increment the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

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.

void Gst::Caps::set_features	(	guint	index,
		const CapsFeatures&	features
	)

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

Parameters

index	The index of the structure.
features	The Gst::CapsFeatures to set.

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.

template <class DataType >

void Gst::Caps::set_simple	(	const Glib::ustring &	name,
		const DataType &	data
	)

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

void Gst::Caps::set_value	(	const Glib::ustring &	field,
		const Glib::ValueBase &	value
	)

Sets the given field on all structures of caps to the given value.

This is a convenience function for calling Gst::Structure::set_value() on all structures of caps.

Parameters

field	Name of the field to set.
value	Value to set the field to.

template <class DataType >

void Gst::Caps::set_value	(	const Glib::ustring &	name,
		const DataType &	data
	)

Sets the given field on all structures to the given value.

This is a convenience function for calling Gst::Structure::set_value() on all structures.

Parameters

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

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

Converts the given caps 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 method does not preserve the original order of caps.

Returns: The simplified caps.

guint Gst::Caps::size ( ) const

Gets the number of structures contained in caps.

Returns: The number of structures that caps contains.

Structure Gst::Caps::steal_structure ( guint index )

Retrieves the structure with the given index from the list of structures contained in caps.

The caller becomes the owner of the returned structure.

Parameters

index Index of the structure to retrieve.

Returns: A pointer to the Gst::Structure corresponding to index.

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

For debugging purposes its easier to do something like this:

[C example ellipted] This prints the caps in human readable form.

Returns: A newly allocated string representing caps.

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

Discard all but the first structure from caps.

Useful when fixating.

Returns: Truncated caps.

void Gst::Caps::unreference ( ) const

Decrement the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

Friends And Related Function Documentation

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

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:

gstreamermm/caps.h

gstreamermm: Gst::Caps Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation