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

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.

struct GstCaps

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

gchar *namethe name of the capability, for the application
GQuark idthe typeid of the capability
guint16 flags
guint refcounta refcounter for this caps structure
GstProps *propertiesthe properties of the capability
GstCaps *nexta pointer to the next caps.

enum GstCapsFlags

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_FLOATINGthe caps is not owned by anyone

GST_CAPS_FLAGS()

#define GST_CAPS_FLAGS(caps)		((caps)->flags)

Get the flags of the caps

caps :The caps to get the flags of

GST_CAPS_FLAG_IS_SET()

#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

GST_CAPS_FLAG_SET()

#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

GST_CAPS_FLAG_UNSET()

#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

GST_CAPS_IS_FLOATING()

#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

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)

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

caps :the caps to query

GST_CAPS_NEXT()

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

Get a pointer to the next chained caps

caps :The caps to query

GST_CAPS_PROPERTIES()

#define GST_CAPS_PROPERTIES(caps)  	((caps)->properties)

Get the properties of the caps

caps :The caps to query

GST_CAPS_REFCOUNT()

#define GST_CAPS_REFCOUNT(caps)		((caps)->refcount)

Get the refcount of the caps.

caps :The caps to query

GST_CAPS_TRACE_NAME

#define	GST_CAPS_TRACE_NAME "GstCaps"

The name used for tracing


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

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

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.

gst_caps_replace ()

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

gst_caps_replace_sink ()

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

gst_caps_sink ()

void        gst_caps_sink                   (GstCaps *caps);

Take ownership of a GstCaps

caps : the caps to take ownership of

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

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.

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

gst_caps_has_property_typed ()

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.

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