GstCaps

Name

GstCaps -- Capabilities of pads

Synopsis


#include <gst/gst.h>


#define     GST_TYPE_CAPS
#define     GST_CAPS_NEW                    (name, type, a...)
#define     GST_CAPS_FACTORY                (factoryname, a...)
#define     GST_CAPS_GET                    (fact)
#define     GST_CAPS_IS_CHAINED             (caps)
#define     GST_CAPS_IS_FIXED               (caps)
struct      GstCaps;
GstCaps*    gst_caps_new                    (const gchar *name,
                                             const gchar *mime,
                                             GstProps *props);
GstCaps*    gst_caps_new_id                 (const gchar *name,
                                             const guint16 id,
                                             GstProps *props);
void        gst_caps_destroy                (GstCaps *caps);
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);
void        gst_caps_set_name               (GstCaps *caps,
                                             const gchar *name);
const gchar* gst_caps_get_name              (GstCaps *caps);
void        gst_caps_set_type_id            (GstCaps *caps,
                                             guint16 type_id);
guint16     gst_caps_get_type_id            (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);
#define     gst_caps_has_property           (caps, name)
#define     gst_caps_has_fixed_property     (caps, name)
#define     gst_caps_has_property_typed     (caps, name, type)
GstCaps*    gst_caps_normalize              (GstCaps *caps);
#define     gst_caps_set                    (caps, name, args...)
#define     gst_caps_get                    (caps, name, args...)
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);

Description

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));
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 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.

Details

GST_TYPE_CAPS

#define GST_TYPE_CAPS  (_gst_caps_type)

The GType of the caps boxed type, for use in GValues.


GST_CAPS_NEW()

#define     GST_CAPS_NEW(name, type, a...)

A convenience macro to create a new GstCaps structure.

name :the name of the caps structure
type :the mime type of the caps structure
a... :the properties of this caps stucture.


GST_CAPS_FACTORY()

#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()


GST_CAPS_GET()

#define GST_CAPS_GET(fact) (fact)()

A convenience macro to get a GstCaps from the given capsfactory.

fact :the factory to use.


GST_CAPS_IS_CHAINED()

#define GST_CAPS_IS_CHAINED(caps)  	((caps)->next)

Check if the GstCaps is chained.

caps :the caps to query


GST_CAPS_IS_FIXED()

#define GST_CAPS_IS_FIXED(caps)		((caps)->fixed)

Check if the GstCaps has fixed properties, ie. it has no ranges or lists.

caps :the caps to query


struct GstCaps

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 *namethe name of the capability, for the application
guint16 idthe typeid of the capability
guint refcounta refcounter for this caps structure
gboolean fixeda boolean indicating that this caps structure is fixed
GstProps *propertiesthe properties of the capability
GstCaps *nexta pointer to the next caps.


gst_caps_new ()

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


gst_caps_new_id ()

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


gst_caps_destroy ()

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


gst_caps_ref ()

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


gst_caps_unref ()

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


gst_caps_copy ()

GstCaps*    gst_caps_copy                   (GstCaps *caps);

Copies the caps.

caps : the caps to copy
Returns : a copy of the GstCaps structure.


gst_caps_copy_1 ()

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.


gst_caps_copy_on_write ()

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


gst_caps_chain ()

GstCaps*    gst_caps_chain                  (GstCaps *caps,
                                             ...);

chains the given capabilities

caps : a capabilty
... : more capabilities
Returns : the new capability


gst_caps_append ()

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


gst_caps_prepend ()

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


gst_caps_set_name ()

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


gst_caps_get_name ()

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


gst_caps_set_type_id ()

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


gst_caps_get_type_id ()

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


gst_caps_set_mime ()

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


gst_caps_get_mime ()

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


gst_caps_set_props ()

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


gst_caps_get_props ()

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


gst_caps_is_always_compatible ()

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.

fromcaps : a GstCaps capability to check compatibility of.
tocaps : the GstCaps capabilty to check compatibility with.
Returns : TRUE if compatible under all circumstances, FALSE otherwise.


gst_caps_has_property()

#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


gst_caps_has_fixed_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


gst_caps_has_property_typed()

#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 : 


gst_caps_normalize ()

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.


gst_caps_set()

#define		gst_caps_set(caps, name, args...)	gst_props_set ((caps)->properties, name, ##args)

Set a property of a caps structure.

caps :the caps structure to modify
name :the name of the property to change
args... :the new value of the property


gst_caps_get()

#define		gst_caps_get(caps, name, args...)	gst_props_get ((caps)->properties, name, ##args)

Get key/value pairs from the given GstCaps.

caps :the caps to get the values from
name :the name of the first key
args... :a pointer to the variable that can hold the result followed by more key/value pairs.


gst_caps_intersect ()

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.


gst_caps_get_boolean()

#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


gst_caps_get_by_name ()

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


gst_caps_get_fourcc_int()

#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


gst_caps_get_int()

#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


gst_caps_get_string()

#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


gst_caps_get_float()

#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


gst_caps_save_thyself ()

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


gst_caps_load_thyself ()

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


gst_caps_debug ()

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

See Also

GstProps, GstPad