GstCaps

GstCaps — Capabilities of pads

Synopsis


#include <gst/gst.h>


#define     GST_TYPE_CAPS
struct      GstCaps;
GstCaps*    gst_caps_copy                   (const GstCaps *caps);
GstCaps*    gst_caps_copy_1                 (const GstCaps *caps);
void        gst_caps_append                 (GstCaps *caps1,
                                             GstCaps *caps2);
void        gst_caps_replace                (GstCaps **caps,
                                             GstCaps *newcaps);
gboolean    gst_caps_is_always_compatible   (const GstCaps *caps1,
                                             const GstCaps *caps2);
GstCaps*    gst_caps_normalize              (const GstCaps *caps);
GstCaps*    gst_caps_intersect              (const GstCaps *caps1,
                                             const GstCaps *caps2);
xmlNodePtr  gst_caps_save_thyself           (const GstCaps *caps,
                                             xmlNodePtr parent);
GstCaps*    gst_caps_load_thyself           (xmlNodePtr parent);
GstCaps*    gst_caps_union                  (const GstCaps *caps1,
                                             const GstCaps *caps2);

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

The GType of the caps boxed type, for use in GValues.


struct GstCaps

struct GstCaps {

  GType type;

  guint16 flags;
  GPtrArray *structs;
};

The gstcaps structure


gst_caps_copy ()

GstCaps*    gst_caps_copy                   (const GstCaps *caps);

Deeply copies a GstCaps, including all structures and all the structures' values.

caps : the GstCaps to copy
Returns : the new GstCaps

gst_caps_copy_1 ()

GstCaps*    gst_caps_copy_1                 (const GstCaps *caps);

Creates a new GstCaps and appends a copy of the first structure contained in caps.

caps : the GstCaps to copy
Returns : the new GstCaps

gst_caps_append ()

void        gst_caps_append                 (GstCaps *caps1,
                                             GstCaps *caps2);

Appends the structures contained in caps2 to caps1. The structures in caps2 are not copied -- they are transferred to caps1, and then caps2 is freed.

caps1 : the GstCaps that will be appended to
caps2 : the GstCaps to append

gst_caps_replace ()

void        gst_caps_replace                (GstCaps **caps,
                                             GstCaps *newcaps);

Replaces *caps with newcaps. Frees the GstCaps in the location pointed to by caps, if applicable, then modifies caps to point to newcaps.

caps : a pointer to GstCaps
newcaps : a GstCaps to replace *caps

gst_caps_is_always_compatible ()

gboolean    gst_caps_is_always_compatible   (const GstCaps *caps1,
                                             const GstCaps *caps2);

caps1 : the GstCaps to test
caps2 : the GstCaps to test
Returns : TRUE if caps1 is a subset of caps2.

gst_caps_normalize ()

GstCaps*    gst_caps_normalize              (const GstCaps *caps);

Creates a new GstCaps that represents the same set of formats as caps, but contains no lists. Each list is expanded into separate GstStructures.

caps : a GstCaps to normalize
Returns : the new GstCaps

gst_caps_intersect ()

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

Creates a new GstCaps that contains all the formats that are common to both caps1 and caps2.

caps1 : a GstCaps to intersect
caps2 : a GstCaps to intersect
Returns : the new GstCaps

gst_caps_save_thyself ()

xmlNodePtr  gst_caps_save_thyself           (const GstCaps *caps,
                                             xmlNodePtr parent);

caps :
parent :
Returns :

gst_caps_load_thyself ()

GstCaps*    gst_caps_load_thyself           (xmlNodePtr parent);

parent :
Returns :

gst_caps_union ()

GstCaps*    gst_caps_union                  (const GstCaps *caps1,
                                             const GstCaps *caps2);

Creates a new GstCaps that contains all the formats that are in either caps1 and caps2.

caps1 : a GstCaps to union
caps2 : a GstCaps to union
Returns : the new GstCaps

See Also

GstProps, GstPad