GStreamer Core Reference Manual
<<< Previous PageHomeUpNext Page >>>

GstCaps

Name

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

caps :

a capabilty

Returns :

The normalisation of the caps.

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.

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



<<< Previous PageHomeUpNext Page >>>
GstBufferPoolGstClock