![]() | ![]() | ![]() | GStreamer Core Reference Manual | ![]() |
---|
GstCaps — Capabilities of pads
#include <gst/gst.h> #define GST_TYPE_CAPS #define GST_CAPS_NEW (name, type, ...) #define GST_CAPS_FACTORY (factoryname, ...) #define GST_CAPS_GET (fact) struct GstCaps; enum GstCapsFlags; #define GST_CAPS_FLAGS (caps) #define GST_CAPS_FLAG_IS_SET (caps,flag) #define GST_CAPS_FLAG_SET (caps,flag) #define GST_CAPS_FLAG_UNSET (caps,flag) #define GST_CAPS_IS_FLOATING (caps) #define GST_CAPS_IS_CHAINED (caps) #define GST_CAPS_IS_FIXED (caps) #define GST_CAPS_NEXT (caps) #define GST_CAPS_PROPERTIES (caps) #define GST_CAPS_REFCOUNT (caps) #define GST_CAPS_TRACE_NAME GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); GstCaps* gst_caps_new_id (const gchar *name, const GQuark id, GstProps *props); GstCaps* gst_caps_ref (GstCaps *caps); GstCaps* gst_caps_unref (GstCaps *caps); GstCaps* gst_caps_copy (GstCaps *caps); GstCaps* gst_caps_copy_1 (GstCaps *caps); GstCaps* gst_caps_copy_on_write (GstCaps *caps); GstCaps* gst_caps_chain (GstCaps *caps, ...); GstCaps* gst_caps_append (GstCaps *caps, GstCaps *capstoadd); GstCaps* gst_caps_prepend (GstCaps *caps, GstCaps *capstoadd); GstCaps* gst_caps_next (GstCaps *caps); void gst_caps_replace (GstCaps **oldcaps, GstCaps *newcaps); void gst_caps_replace_sink (GstCaps **oldcaps, GstCaps *newcaps); void gst_caps_sink (GstCaps *caps); void gst_caps_set_name (GstCaps *caps, const gchar *name); const gchar* gst_caps_get_name (GstCaps *caps); void gst_caps_set_mime (GstCaps *caps, const gchar *mime); const gchar* gst_caps_get_mime (GstCaps *caps); GstCaps* gst_caps_set_props (GstCaps *caps, GstProps *props); GstProps* gst_caps_get_props (GstCaps *caps); gboolean gst_caps_is_always_compatible (GstCaps *fromcaps, GstCaps *tocaps); gboolean gst_caps_has_property (GstCaps *caps, const gchar *name); gboolean gst_caps_has_fixed_property (GstCaps *caps, const gchar *name); gboolean gst_caps_has_property_typed (GstCaps *caps, const gchar *name, GstPropsType type); GstCaps* gst_caps_normalize (GstCaps *caps); #define gst_caps_set (caps, ...) #define gst_caps_get (caps, ...) GstCaps* gst_caps_intersect (GstCaps *caps1, GstCaps *caps2); #define gst_caps_get_boolean (caps,name,res) GstCaps* gst_caps_get_by_name (GstCaps *caps, const gchar *name); #define gst_caps_get_fourcc_int (caps,name,res) #define gst_caps_get_int (caps,name,res) #define gst_caps_get_string (caps,name,res) #define gst_caps_get_float (caps,name,res) xmlNodePtr gst_caps_save_thyself (GstCaps *caps, xmlNodePtr parent); GstCaps* gst_caps_load_thyself (xmlNodePtr parent); void gst_caps_debug (GstCaps *caps, const gchar *label);
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"), "channels", GST_PROPS_INT (5), NULL));
The following code example is equivalent to the above example:
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. |
struct GstCaps { /* --- public --- */ gchar *name; /* the name of this caps */ GQuark 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
typedef enum { GST_CAPS_UNUSED = (1 << 0), /* unused flag */ GST_CAPS_FLOATING = (1 << 1) /* caps is floating */ } GstCapsFlags;
Flags for this caps.
GST_CAPS_UNUSED | |
GST_CAPS_FLOATING | the caps is not owned by anyone |
#define GST_CAPS_FLAGS(caps) ((caps)->flags)
Get the flags of the caps
caps : | The caps to get the flags of |
#define GST_CAPS_FLAG_IS_SET(caps,flag) (GST_CAPS_FLAGS (caps) & (flag))
Test is a flag is set
caps : | The caps to test |
flag : | The flag to check |
#define GST_CAPS_FLAG_SET(caps,flag) (GST_CAPS_FLAGS (caps) |= (flag))
Set a flag on the caps
caps : | The caps to modify |
flag : | The flag to set |
#define GST_CAPS_FLAG_UNSET(caps,flag) (GST_CAPS_FLAGS (caps) &= ~(flag))
Unset a flag on the caps
caps : | The caps to modify |
flag : | The flag to unset |
#define GST_CAPS_IS_FLOATING(caps) (GST_CAPS_FLAG_IS_SET ((caps), GST_CAPS_FLOATING))
Test if a caps is floating
caps : | The caps to test |
#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)
Check if the GstCaps has fixed properties, ie. it has no ranges or lists.
caps : | the caps to query |
#define GST_CAPS_NEXT(caps) ((caps)->next)
Get a pointer to the next chained caps
caps : | The caps to query |
#define GST_CAPS_PROPERTIES(caps) ((caps)->properties)
Get the properties of the caps
caps : | The caps to query |
#define GST_CAPS_REFCOUNT(caps) ((caps)->refcount)
Get the refcount of the caps.
caps : | The caps to query |
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 GQuark 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 |
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 floating 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 floating 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 |
GstCaps* gst_caps_next (GstCaps *caps);
Get the next caps of this chained caps.
caps : | the caps to query |
Returns : | the next caps or NULL if the chain ended. |
void gst_caps_replace (GstCaps **oldcaps, GstCaps *newcaps);
Replace the pointer to the caps, doing proper refcounting.
oldcaps : | the caps to take replace |
newcaps : | the caps to take replace |
void gst_caps_replace_sink (GstCaps **oldcaps, GstCaps *newcaps);
Replace the pointer to the caps and take ownership.
oldcaps : | the caps to take replace |
newcaps : | the caps to take replace |
void gst_caps_sink (GstCaps *caps);
Take ownership of a GstCaps
caps : | the caps to take ownership of |
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_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.
gboolean gst_caps_has_property (GstCaps *caps, const gchar *name);
Figure out whether this caps contains the requested property.
Check if the GstCaps has a property with the given name
caps : | the caps to query |
name : | the name of the property to search for |
Returns : | true if the caps contains the property. |
gboolean gst_caps_has_fixed_property (GstCaps *caps, const gchar *name);
Figure out whether this caps contains the requested property, and whether this property is fixed.
Check if the GstCaps has a fixed property with the given name
caps : | the caps to query |
name : | the name of the property to search for |
Returns : | true if the caps contains the fixed property. |
gboolean gst_caps_has_property_typed (GstCaps *caps, const gchar *name, GstPropsType type);
Figure out whether this caps contains the requested property, and whether this property is of the requested type.
Check if the GstCaps has a property with the given type
caps : | the caps to query |
name : | the name of the property to search for |
type : | the type of the property to search for |
Returns : | true if the caps contains the typed property. |
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. unref the caps after use.
caps : | a capabilty |
Returns : | The normalisation of the caps. Unref after usage. |
#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. unref the caps after use. |
#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 |
void gst_caps_debug (GstCaps *caps, const gchar *label);
Print out the contents of the caps structure. Useful for debugging.
caps : | the caps to print out |
label : | a label to put on the printout, or NULL |
<< GstConfig | GstClock >> |