## GstCaps

GstCaps — Capabilities of pads

## Synopsis

    #include <gst/gst.h>

    #define     GST_TYPE_CAPS
    #define     GST_CAPS_NEW                    (name, type, ...)
    #define     GST_CAPS_FACTORY                (factoryname, ...)
    #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, ...)
    #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);

## 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"),
    	    "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.

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

### GST_CAPS_FACTORY()

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

### 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)       (GST_CAPS_NEXT (caps) != NULL)

Check if the GstCaps is chained.

`caps` : | the caps to query

### GST_CAPS_IS_FIXED()

    #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

    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.

### 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 floating 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 floating 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 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.

### 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. unref the caps after use.

`caps` : | a capabilty
Returns : | The normalisation of the caps. Unref after usage.

### gst_caps_set()

    #define     gst_caps_set(caps, ...)

Set a property of a caps structure.

`caps` : | the caps structure to modify
`...` : | the new value of the property

### gst_caps_get()

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

### 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. unref the caps after use.

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