GstCaps

Name

GstCaps -- Capabilities of pads

Synopsis


#include <gst/gst.h>


#define     GST_CAPS_LOCK                   (caps)
#define     GST_CAPS_TRYLOCK                (caps)
#define     GST_CAPS_UNLOCK                 (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_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)
GstCaps*    gst_caps_normalize              (GstCaps *caps);
#define     gst_caps_set                    (caps, name, args...)
GstCaps*    gst_caps_intersect              (GstCaps *caps1,
                                             GstCaps *caps2);
#define     gst_caps_get_boolean            (caps, name)
GstCaps*    gst_caps_get_by_name            (GstCaps *caps,
                                             const gchar *name);
#define     gst_caps_get_fourcc_int         (caps, name)
#define     gst_caps_get_int                (caps, name)
#define     gst_caps_get_string             (caps, name)
#define     gst_caps_get_float              (caps, name)
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_CAPS_LOCK()

#define GST_CAPS_LOCK(caps)    (g_mutex_lock(GST_CAPS(caps)->lock))

Lock the caps structure

caps :The caps structure to lock


GST_CAPS_TRYLOCK()

#define GST_CAPS_TRYLOCK(caps) (g_mutex_trylock(GST_CAPS(caps)->lock))

Try to lock the caps structure

caps :The caps structure to try to lock


GST_CAPS_UNLOCK()

#define GST_CAPS_UNLOCK(caps)  (g_mutex_unlock(GST_CAPS(caps)->lock))

Unlock the caps structure

caps :The caps structure to unlock


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)

caps : 


GST_CAPS_IS_FIXED()

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

caps : 


struct GstCaps

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

gchar *namethe name of the capability, for the application
guint16 idthe typeid of the capability
guint refcounta refcounter for this caps structure
GMutex *lockthe lock for this caps structure
gboolean 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 typei 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_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_check_compatibility ()

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

Checks whether two capabilities are compatible.

fromcaps : a capabilty
tocaps : a capabilty
Returns : TRUE if compatible, FALSE otherwise


gst_caps_has_property()

#define		gst_caps_has_property(caps, name)	gst_props_has_property ((caps)->properties, name)

caps : 
name : 


gst_caps_normalize ()

GstCaps*    gst_caps_normalize              (GstCaps *caps);

caps : 
Returns : 


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

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

Make the intersection between two caps.

caps1 : a capabilty
caps2 : a capabilty
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)	gst_props_get_boolean ((caps)->properties, name)

Get the value of the named property as a boolean.

caps :the caps to query
name :the name of the property to get


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)	gst_props_get_fourcc_int ((caps)->properties, name)

Get the value of the named property as a fourcc.

caps :the caps to query
name :the name of the property to get


gst_caps_get_int()

#define		gst_caps_get_int(caps, name)		gst_props_get_int ((caps)->properties, name)

Get the value of the named property as an int.

caps :the caps to query
name :the name of the property to get


gst_caps_get_string()

#define		gst_caps_get_string(caps, name)		gst_props_get_string ((caps)->properties, name)

Get the value of the named property as a string.

caps :the caps to query
name :the name of the property to get


gst_caps_get_float()

#define		gst_caps_get_float(caps, name)		gst_props_get_float ((caps)->properties, name)

Get the value of the named property as a float.

caps :the caps to query
name :the name of the property to get


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