GStreamer Library Reference Manual (Core) | |||
---|---|---|---|
<<< 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); ... } |
#define GST_CAPS_LOCK(caps) (g_mutex_lock(GST_CAPS(caps)->lock)) |
Lock the caps structure
#define GST_CAPS_TRYLOCK(caps) (g_mutex_trylock(GST_CAPS(caps)->lock)) |
Try to lock the caps structure
#define GST_CAPS_UNLOCK(caps) (g_mutex_unlock(GST_CAPS(caps)->lock)) |
Unlock the caps structure
#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.
struct GstCaps { gchar *name; /* the name of this caps */ guint16 id; /* type id (major type) */ guint refcount; GMutex *lock; /* global lock for this capability */ gboolean fixed; /* this caps doesn't contain variable properties */ GstProps *properties; /* properties for this capability */ GstCaps *next; }; |
GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); |
Create a new capability with the given mime typei 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_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_check_compatibility (GstCaps *fromcaps, GstCaps *tocaps); |
Checks whether two capabilities are compatible.
#define gst_caps_has_property(caps, name) gst_props_has_property ((caps)->properties, name) |
#define gst_caps_set(caps, name, args...) gst_props_set ((caps)->properties, name, args) |
Set a property of a caps structure.
GstCaps* gst_caps_intersect (GstCaps *caps1, GstCaps *caps2); |
Make the intersection between two caps.
#define gst_caps_get_boolean(caps, name) gst_props_get_boolean ((caps)->properties, name) |
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) gst_props_get_fourcc_int ((caps)->properties, name) |
Get the value of the named property as a fourcc.
#define gst_caps_get_int(caps, name) gst_props_get_int ((caps)->properties, name) |
Get the value of the named property as an int.
#define gst_caps_get_string(caps, name) gst_props_get_string ((caps)->properties, name) |
Get the value of the named property as a string.
#define gst_caps_get_float(caps, name) gst_props_get_float ((caps)->properties, name) |
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.