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_check_compatibility    (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);

    ...
  }

Details

GST_TYPE_CAPS

#define GST_TYPE_CAPS  (_get_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.


GST_CAPS_FACTORY()

#define     GST_CAPS_FACTORY(factoryname, a...)

A convenience macro to create a GstCaps factory.


GST_CAPS_GET()

#define GST_CAPS_GET(fact) (fact)()

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


GST_CAPS_IS_CHAINED()

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

Check if the GstCaps is chained.


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.


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 */
};


gst_caps_new ()

GstCaps*    gst_caps_new                    (const gchar *name,
                                             const gchar *mime,
                                             GstProps *props);

Create a new capability with the given mime typei and properties.


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.


gst_caps_destroy ()

void        gst_caps_destroy                (GstCaps *caps);

Frees the memory used by this caps structure and all the chained caps and properties.


gst_caps_ref ()

GstCaps*    gst_caps_ref                    (GstCaps *caps);

Increase the refcount of this caps structure


gst_caps_unref ()

GstCaps*    gst_caps_unref                  (GstCaps *caps);

Decrease the refcount of this caps structure, destroying it when the refcount is 0


gst_caps_copy ()

GstCaps*    gst_caps_copy                   (GstCaps *caps);

Copies the caps.


gst_caps_copy_1 ()

GstCaps*    gst_caps_copy_1                 (GstCaps *caps);

Copies the caps, not copying any chained caps.


gst_caps_copy_on_write ()

GstCaps*    gst_caps_copy_on_write          (GstCaps *caps);

Copies the caps if the refcount is greater than 1


gst_caps_chain ()

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

chains the given capabilities


gst_caps_append ()

GstCaps*    gst_caps_append                 (GstCaps *caps,
                                             GstCaps *capstoadd);

Appends a capability to the existing capability.


gst_caps_prepend ()

GstCaps*    gst_caps_prepend                (GstCaps *caps,
                                             GstCaps *capstoadd);

prepend the capability to the list of capabilities


gst_caps_set_name ()

void        gst_caps_set_name               (GstCaps *caps,
                                             const gchar *name);

Set the name of a caps.


gst_caps_get_name ()

const gchar* gst_caps_get_name              (GstCaps *caps);

Get the name of a GstCaps structure.


gst_caps_set_type_id ()

void        gst_caps_set_type_id            (GstCaps *caps,
                                             guint16 type_id);

Set the type id of the caps.


gst_caps_get_type_id ()

guint16     gst_caps_get_type_id            (GstCaps *caps);

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


gst_caps_get_mime ()

const gchar* gst_caps_get_mime              (GstCaps *caps);

Get the mime type of the caps as a string.


gst_caps_set_props ()

GstCaps*    gst_caps_set_props              (GstCaps *caps,
                                             GstProps *props);

Set the properties to the given caps.


gst_caps_get_props ()

GstProps*   gst_caps_get_props              (GstCaps *caps);

Get the properties of the given caps.


gst_caps_check_compatibility ()

gboolean    gst_caps_check_compatibility    (GstCaps *fromcaps,
                                             GstCaps *tocaps);

Checks whether two capabilities are compatible.


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


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


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


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.


gst_caps_set()

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

Set a property of a caps structure.


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.


gst_caps_intersect ()

GstCaps*    gst_caps_intersect              (GstCaps *caps1,
                                             GstCaps *caps2);

Make the intersection between two caps.


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.


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.


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.


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.


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.


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.


gst_caps_save_thyself ()

xmlNodePtr  gst_caps_save_thyself           (GstCaps *caps,
                                             xmlNodePtr parent);

Save the capability into an XML representation.


gst_caps_load_thyself ()

GstCaps*    gst_caps_load_thyself           (xmlNodePtr parent);

Load a new caps from the XML representation.


gst_caps_debug ()

void        gst_caps_debug                  (GstCaps *caps,
                                             const gchar *label);

Print out the contents of the caps structure. Useful for debugging.

See Also

GstProps, GstPad