Caps (capabilities) are lighweight refcounted objects describing media types.
They are composed of an array of Structure.
Caps are exposed on PadTemplate to describe all possible types a given pad can
handle. They are also stored in the Registry along with a description of the
Element.
Caps are exposed on the element pads using the get_caps pad function. This
function 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
set_caps. Caps attached to a
Buffer allow for format negotiation upstream and downstream.
A Caps can be constructed with the following code fragment:
Creating caps:
GstCaps *caps;
caps = gst_caps_new_simple ("video/x-raw-yuv",
"format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
"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 Caps is fixed when it has no properties with ranges or lists. Use
is_fixed to test for fixed caps. Only fixed caps can be set on a
Pad or Buffer.
Various methods exist to work with the media types such as subtracting or intersecting.
Last reviewed on 2007-02-13 (0.10.10)
- public void append (owned Caps caps2)
Appends the structures contained in caps2 to caps1
.
- public void append_structure (owned Structure structure)
Appends structure to caps.
- public bool can_intersect (Caps caps2)
Tries intersecting caps1 and caps2 and reports
whether the result would not be empty
- public Caps copy ()
Creates a new Caps as a copy of the old caps
.
- public Caps copy_nth (uint nth)
Creates a new Caps and appends a copy of the nth
structure contained in caps.
- public bool do_simplify ()
Modifies the given caps inplace into a representation that
represents the same set of formats, but in a simpler form.
- public uint get_size ()
Gets the number of structures contained in caps.
- public unowned Structure get_structure (uint index)
Finds the structure in caps that has the index index
, and returns it.
- public Caps intersect (Caps caps2)
Creates a new Caps that contains all the formats
that are common to both caps1 and caps2.
- public weak Caps intersect_full (Caps caps2, CapsIntersectMode mode)
Creates a new Caps that contains all the formats
that are common to both caps1 and caps2, the order is defined by the
CapsIntersectMode used.
- public bool is_always_compatible (Caps caps2)
A given Caps structure is always compatible with
another if every media format that is in the first is also contained in the second.
- public bool is_any ()
Determines if caps represents any media format.
- public bool is_empty ()
Determines if caps represents no media formats.
- public bool is_equal (Caps caps2)
Checks if the given caps represent the same set of caps.
- public bool is_equal_fixed (Caps caps2)
Tests if two Caps are equal.
- public bool is_fixed ()
Fixed Caps describe exactly one format, that is,
they have exactly one structure, and each field in the structure describes a fixed type.
- public bool is_simple ()
- public bool is_subset (Caps superset)
Checks if all caps represented by subset are also represented
by superset.
- public bool is_subset_structure (Structure structure)
Checks if structure is a subset of caps.
- public void make_writable ()
Returns a writable copy of caps.
- public void merge (owned Caps caps2)
Appends the structures contained in caps2 to caps1
if they are not yet expressed by caps1.
- public void merge_structure (owned Structure structure)
Appends structure to caps if its not already
expressed by caps.
- public Caps normalize ()
Creates a new Caps that represents the same set of
formats as caps, but contains no lists.
- public weak Caps @ref ()
Add a reference to a Caps object.
- public void remove_structure (uint idx)
removes the stucture with the given index from the list of structures
contained in caps.
- public void* save_thyself (void* parent)
Serializes a Caps to XML and adds it as a child
node of parent.
- public void set_simple (string field, ...)
Sets fields in a Caps.
- public void set_simple_valist (string field, void* varargs)
Sets fields in a Caps.
- public void set_value (string field, Value value)
Sets the given field on all structures of caps to
the given value.
- public unowned Structure steal_structure (uint index)
Retrieves the stucture with the given index from the list of structures
contained in caps.
- public Caps subtract (Caps subtrahend)
Subtracts the subtrahend from the minuend.
- public string to_string ()
Converts caps to a string representation.
- public void truncate ()
Destructively discard all but the first structure from caps.
- public Caps union (Caps caps2)
Creates a new Caps that contains all the formats
that are in either caps1 and caps2.
- public void unref ()
Unref a Caps and free all its structures and the
structures' values when the refcount reaches 0.
