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 link 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 link 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 convenience macro to create a new GstCaps structure.
name : | the name of the caps structure |
type : | the mime type of the caps structure |
... : | the properties of this caps stucture. |
#define GST_CAPS_FACTORY(factoryname, ...) |
A convenience macro to create a GstCaps factory.
factoryname : | the name of the factory |
... : | 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.
fact : | the factory to use. |
#define GST_CAPS_IS_CHAINED(caps) (GST_CAPS_NEXT (caps) != NULL) |
Check if the GstCaps is chained.
caps : | the caps to query |
#define GST_CAPS_IS_FIXED(caps) (GST_CAPS_FLAGS (caps) & GST_CAPS_FIXED) |
Check if the GstCaps has fixed properties, ie. it has no ranges or lists.
caps : | the caps to query |
struct GstCaps { /* --- public ReadOnly --- */ gchar *name; /* the name of this caps */ guint16 id; /* type id (major type) representing the mime type, it's stored as a GQuark for speed/space reasons */ guint16 flags; /* flags */ guint refcount; GstProps *properties; /* properties for this capability */ GstCaps *next; /* not with a GList for efficiency */ }; |
The gstcaps structure
gchar *name | the name of the capability, for the application |
guint16 id | the typeid of the capability |
guint16 flags | |
guint refcount | a refcounter for this caps structure |
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.
name : | the name of this capability |
mime : | the mime type to attach to the capability |
props : | the properties to add to this capability |
Returns : | a new capability |
GstCaps* gst_caps_new_id (const gchar *name, const guint16 id, GstProps *props); |
Create a new capability with the given mime typeid and properties.
name : | the name of this capability |
id : | the id of the mime type |
props : | the properties to add to this capability |
Returns : | a new capability |
void gst_caps_destroy (GstCaps *caps); |
Frees the memory used by this caps structure and all the chained caps and properties.
caps : | the caps to destroy |
GstCaps* gst_caps_ref (GstCaps *caps); |
Increase the refcount of this caps structure
caps : | the caps to ref |
Returns : | the caps with the refcount incremented |
GstCaps* gst_caps_unref (GstCaps *caps); |
Decrease the refcount of this caps structure, destroying it when the refcount is 0
caps : | the caps to unref |
Returns : | caps or NULL if the refcount reached 0 |
GstCaps* gst_caps_copy (GstCaps *caps); |
Copies the caps.
caps : | the caps to copy |
Returns : | a copy of the GstCaps structure. |
GstCaps* gst_caps_copy_1 (GstCaps *caps); |
Copies the caps, not copying any chained caps.
caps : | the caps to copy |
Returns : | a copy of the GstCaps structure. |
GstCaps* gst_caps_copy_on_write (GstCaps *caps); |
Copies the caps if the refcount is greater than 1
caps : | the caps to copy |
Returns : | a pointer to a GstCaps strcuture that can be safely written to |
GstCaps* gst_caps_chain (GstCaps *caps, ...); |
chains the given capabilities
caps : | a capabilty |
... : | more capabilities |
Returns : | the new capability |
GstCaps* gst_caps_append (GstCaps *caps, GstCaps *capstoadd); |
Appends a capability to the existing capability.
caps : | a capabilty |
capstoadd : | the capability to append |
Returns : | the new capability |
GstCaps* gst_caps_prepend (GstCaps *caps, GstCaps *capstoadd); |
prepend the capability to the list of capabilities
caps : | a capabilty |
capstoadd : | a capabilty to prepend |
Returns : | the new capability |
void gst_caps_set_name (GstCaps *caps, const gchar *name); |
Set the name of a caps.
caps : | the caps to set the name to |
name : | the name to set |
const gchar* gst_caps_get_name (GstCaps *caps); |
Get the name of a GstCaps structure.
caps : | the caps to get the name from |
Returns : | the name of the caps |
void gst_caps_set_type_id (GstCaps *caps, guint16 type_id); |
Set the type id of the caps.
caps : | the caps to set the type id to |
type_id : | the type id to set |
guint16 gst_caps_get_type_id (GstCaps *caps); |
Get the type id of the caps.
caps : | the caps to get the type id from |
Returns : | 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.
caps : | the caps to set the mime type to |
mime : | the mime type to attach to the caps |
const gchar* gst_caps_get_mime (GstCaps *caps); |
Get the mime type of the caps as a string.
caps : | the caps to get the mime type from |
Returns : | the mime type of the caps |
GstCaps* gst_caps_set_props (GstCaps *caps, GstProps *props); |
Set the properties to the given caps.
caps : | the caps to attach the properties to |
props : | the properties to attach |
Returns : | the new caps structure |
GstProps* gst_caps_get_props (GstCaps *caps); |
Get the properties of the given caps.
caps : | the caps to get the properties from |
Returns : | the properties of the caps |
gboolean gst_caps_is_always_compatible (GstCaps *fromcaps, GstCaps *tocaps); |
Checks if a link is always possible from fromcaps to tocaps, for all possible capabilities.
fromcaps : | a GstCaps capability to check compatibility of. |
tocaps : | the GstCaps capability to check compatibility with. |
Returns : | TRUE if compatible under all circumstances, FALSE otherwise. |
#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
caps : | the caps to query |
name : | the name of the property |
#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
caps : | the caps to query |
name : | the name of the property |
#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
caps : | the caps to query |
name : | the name of the property |
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.
caps : | a capabilty |
Returns : | The normalisation of the caps. |
#define gst_caps_set(caps, ...) |
Set a property of a caps structure.
caps : | the caps structure to modify |
... : | the new value of the property |
#define gst_caps_get(caps, ...) |
Get key/value pairs from the given GstCaps.
caps : | the caps to get the values from |
... : | a pointer to the variable that can hold the result followed by more key/value pairs. |
GstCaps* gst_caps_intersect (GstCaps *caps1, GstCaps *caps2); |
Make the intersection between two caps.
caps1 : | a capability |
caps2 : | a capability |
Returns : | The intersection of the two caps or NULL if the intersection is empty. |
#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.
caps : | the caps to query |
name : | the name of the property to get |
res : | a pointer to a gboolean to store the result |
GstCaps* gst_caps_get_by_name (GstCaps *caps, const gchar *name); |
Get the capability with the given name from this chain of capabilities.
caps : | a capabilty |
name : | the name of the capability to get |
Returns : | the first capability in the chain with the given name |
#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.
caps : | the caps to query |
name : | the name of the property to get |
res : | a pointer to a guint32 to store the fourcc value |
#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.
caps : | the caps to query |
name : | the name of the property to get |
res : | a pointer to a gint to store the value |
#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.
caps : | the caps to query |
name : | the name of the property to get |
res : | a pointer to a gchar* to store the 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.
caps : | the caps to query |
name : | the name of the property to get |
res : | a pointer to a gfloat to store the result |
xmlNodePtr gst_caps_save_thyself (GstCaps *caps, xmlNodePtr parent); |
Save the capability into an XML representation.
caps : | a capabilty to save |
parent : | the parent XML node pointer |
Returns : | a new XML node pointer |
GstCaps* gst_caps_load_thyself (xmlNodePtr parent); |
Load a new caps from the XML representation.
parent : | the parent XML node pointer |
Returns : | a new capability |