GStreamer Core Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
GstCaps is used to attach capabilities to a pad. Capabilities are made of a mime-type and a set of properties. GstCaps can be named and chained into a list, which is then a GstCaps on its own.
GstCaps are created with gst_caps_new(), which takes a name, a mime type and a pointer to a GstProps. A convenience macro with a cleaner syntax is available to create a caps with GST_CAPS_NEW(). The following example shows how to create a GstCaps.
GstCaps *caps; caps = gst_caps_new ( "my_caps", /* capability name */ "audio/raw", /* mime type */ gst_props_new ( /* properties */ "format", GST_PROPS_STRING ("float"), "layout", GST_PROPS_INT (5), NULL)); |
GstCaps *caps; caps = GST_CAPS_NEW ( "my_caps", /* capability name */ "audio/raw", /* mime type */ "format", GST_PROPS_STRING ("float"), "channels", GST_PROPS_INT (5) ); |
GstCaps are refcounted with gst_caps_ref() and gst_caps_unref().
GstCaps can be chained with the gst_caps_append(), gst_caps_prepend() and gst_caps_chain() functions. Use gst_caps_get_by_name() to get a named caps structure from a chained list.
To get the properties of a caps structure the functions gst_caps_get_boolean(), gst_caps_get_fourcc_int(), gst_caps_get_int(), gst_caps_get_string(), gst_caps_get_float(), which all take a property name as an argument.
The properties of the caps structure can be modified with gst_caps_set, which takes a list of key value pairs in the GstProps syntax as shown by this example:
GstCaps *caps; .... gst_caps_set (caps, "format", GST_PROPS_STRING ("int"), NULL); gst_caps_set (caps, "channels", GST_PROPS_INT (20), NULL); |
before modifying a GstCaps, it is a good idea to make a copy if it first with gst_caps_copy_on_write(). This will copy the GstCaps if the refcount is >1.
If you need a unique instance of a GstCaps you can use the convenient GST_CAPS_FACTORY() macro as shown below.
GST_CAPS_FACTORY (my_caps, GST_CAPS_NEW ( "caps1", "audio/raw", "format", GST_PROPS_STRING ("float"), "channels", GST_PROPS_INT (5) ), GST_CAPS_NEW ( "caps2", "audio/raw", "format", GST_PROPS_STRING ("int"), "channels", GST_PROPS_INT (5) ) ) void some_function (void) { GstCaps *caps = GST_CAPS_GET (my_caps); ... } |
If you want to check if a connection between source and destination caps is always possible, use gst_caps_is_always_compatible(), which returns a boolean. If you want to check if a connection between source and destination caps might be possible, use gst_caps_intersect(), which returns an intersection of the capabilities.
#define GST_TYPE_CAPS (_gst_caps_type) |
The GType of the caps boxed type, for use in GValues.
#define GST_CAPS_NEW(name, type, a...) |
A convenience macro to create a new GstCaps structure.
#define GST_CAPS_FACTORY(factoryname, a...) |
A convenience macro to create a GstCaps factory.
factoryname : | the name of the factory |
a... : | the caps to create with this factory, usualy specified with GST_CAPS_NEW() |
#define GST_CAPS_GET(fact) (fact)() |
A convenience macro to get a GstCaps from the given capsfactory.
#define GST_CAPS_IS_CHAINED(caps) ((caps)->next) |
Check if the GstCaps is chained.
#define GST_CAPS_IS_FIXED(caps) ((caps)->fixed) |
Check if the GstCaps has fixed properties, ie. it has no ranges or lists.
struct GstCaps { gchar *name; /* the name of this caps */ guint16 id; /* type id (major type) representing the mime type */ guint refcount; gboolean fixed; /* this caps doesn't contain variable properties */ GstProps *properties; /* properties for this capability */ GstCaps *next; /* not with a GList for efficiency */ }; |
gchar *name | the name of the capability, for the application |
guint16 id | the typeid of the capability |
guint refcount | a refcounter for this caps structure |
gboolean fixed | a boolean indicating that this caps structure is fixed |
GstProps *properties | the properties of the capability |
GstCaps *next | a pointer to the next caps. |
GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); |
Create a new capability with the given mime type and properties.
GstCaps* gst_caps_new_id (const gchar *name, const guint16 id, GstProps *props); |
Create a new capability with the given mime typeid and properties.
void gst_caps_destroy (GstCaps *caps); |
Frees the memory used by this caps structure and all the chained caps and properties.
GstCaps* gst_caps_unref (GstCaps *caps); |
Decrease the refcount of this caps structure, destroying it when the refcount is 0
GstCaps* gst_caps_copy_1 (GstCaps *caps); |
Copies the caps, not copying any chained caps.
GstCaps* gst_caps_copy_on_write (GstCaps *caps); |
Copies the caps if the refcount is greater than 1
GstCaps* gst_caps_append (GstCaps *caps, GstCaps *capstoadd); |
Appends a capability to the existing capability.
GstCaps* gst_caps_prepend (GstCaps *caps, GstCaps *capstoadd); |
prepend the capability to the list of capabilities
void gst_caps_set_name (GstCaps *caps, const gchar *name); |
Set the name of a caps.
const gchar* gst_caps_get_name (GstCaps *caps); |
Get the name of a GstCaps structure.
void gst_caps_set_type_id (GstCaps *caps, guint16 type_id); |
Set the type id of the caps.
void gst_caps_set_mime (GstCaps *caps, const gchar *mime); |
Set the mime type of the caps as a string.
const gchar* gst_caps_get_mime (GstCaps *caps); |
Get the mime type of the caps as a string.
GstCaps* gst_caps_set_props (GstCaps *caps, GstProps *props); |
Set the properties to the given caps.
GstProps* gst_caps_get_props (GstCaps *caps); |
Get the properties of the given caps.
gboolean gst_caps_is_always_compatible (GstCaps *fromcaps, GstCaps *tocaps); |
Checks if a connection is always possible from fromcaps to tocaps, for all possible capabilities.
#define gst_caps_has_property(caps, name) gst_props_has_property ((caps)->properties, name) |
Check if the GstCaps has a property with the given name
#define gst_caps_has_fixed_property(caps, name) gst_props_has_fixed_property ((caps)->properties, name) |
Check if the GstCaps has a fixed property with the given name
#define gst_caps_has_property_typed(caps, name, type) gst_props_has_property_typed ((caps)->properties, name, type) |
Check if the GstCaps has a property with the given type
GstCaps* gst_caps_normalize (GstCaps *caps); |
Make the normalisation of the caps. This will return a new caps that is equivalent to the input caps with the exception that all lists are unrolled. This function is useful when you want to iterate the caps.
#define gst_caps_set(caps, name, args...) gst_props_set ((caps)->properties, name, ##args) |
Set a property of a caps structure.
#define gst_caps_get(caps, name, args...) gst_props_get ((caps)->properties, name, ##args) |
Get key/value pairs from the given GstCaps.
GstCaps* gst_caps_intersect (GstCaps *caps1, GstCaps *caps2); |
Make the intersection between two caps.
#define gst_caps_get_boolean(caps,name,res) gst_props_entry_get_boolean(gst_props_get_entry((caps)->properties,name),res) |
Get the value of the named property as a boolean.
GstCaps* gst_caps_get_by_name (GstCaps *caps, const gchar *name); |
Get the capability with the given name from this chain of capabilities.
#define gst_caps_get_fourcc_int(caps,name,res) gst_props_entry_get_fourcc_int(gst_props_get_entry((caps)->properties,name),res) |
Get the value of the named property as a fourcc.
#define gst_caps_get_int(caps,name,res) gst_props_entry_get_int(gst_props_get_entry((caps)->properties,name),res) |
Get the value of the named property as an int.
#define gst_caps_get_string(caps,name,res) gst_props_entry_get_string(gst_props_get_entry((caps)->properties,name),res) |
Get the value of the named property as a string.
#define gst_caps_get_float(caps,name,res) gst_props_entry_get_float(gst_props_get_entry((caps)->properties,name),res) |
Get the value of the named property as a float.
xmlNodePtr gst_caps_save_thyself (GstCaps *caps, xmlNodePtr parent); |
Save the capability into an XML representation.
GstCaps* gst_caps_load_thyself (xmlNodePtr parent); |
Load a new caps from the XML representation.
void gst_caps_debug (GstCaps *caps, const gchar *label); |
Print out the contents of the caps structure. Useful for debugging.