Capabilities of a pad

Since the pads play a very important role in how the element is viewed by the outside world, a mechanism is implemented to describe the data that can flow through the pad by using capabilities.

We will briefly describe what capabilities are, enough for you to get a basic understanding of the concepts. You will find more information on how to create capabilities in the Plugin Writer's Guide.

Capabilities

Capabilities are attached to a pad in order to describe what type of media the pad can handle.

Its structure is:


struct _GstCaps {
  gchar *name;                  /* the name of this caps */
  guint16 id;                   /* type id (major type) */

  guint refcount; 		/* caps are refcounted */

  GstProps *properties;         /* properties for this capability */

  GstCaps *next;		/* caps can be chained together */
};
      

Getting the capabilities of a pad

A pad can have a chain of capabilities attached to it. You can get the capabilities chain with:


 GstCaps *caps;
    ...
 caps = gst_pad_get_caps (pad);

 g_print ("pad name %s\n", gst_pad_get_name (pad));
 
 while (caps) {
   g_print (" Capability name %s, MIME type %s\n", 
   				gst_caps_get_name (cap), 
                                gst_caps_get_mime (cap));
   
   caps = caps->next;
 }
    ...
    

Creating capability structures

While capabilities are mainly used inside a plugin to describe the media type of the pads, the application programmer also has to have basic understanding of capabilities in order to interface with the plugins, specially when using the autopluggers.

As we said, a capability has a name, a mime-type and some properties. The signature of the function to create a new GstCaps structure is:


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

You can therefore create a new capability with no properties like this:


  GstCaps *newcaps;
  
  newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
    

GstProps basically consist of a set of key-value pairs and are created with a function with this signature:


GstProps*     gst_props_new   (const gchar *firstname, ...);
    

The keys are given as strings and the values are given with a set of macros:

The values can also be specified as ranges with:

All of the above values can be given with a list too, using:

A more complex capability with properties is created like this:


  GstCaps *newcaps;
  
  newcaps = gst_caps_new ("my_caps", 
                          "audio/wav", 
  			  gst_props_new (
			    "bitrate", GST_PROPS_INT_RANGE (11025,22050),
			    "depth",   GST_PROPS_INT (16),
			    "signed",  GST_PROPS_LIST (
			     		 GST_PROPS_BOOLEAN (TRUE),
			     		 GST_PROPS_BOOLEAN (FALSE)
				       ),
			    NULL
			  );
        
Optionally, the convenient shortcut macro can be used. The above complex capability can be created with:

  GstCaps *newcaps;
  
  newcaps = GST_CAPS_NEW ("my_caps", 
                          "audio/wav", 
			    "bitrate", GST_PROPS_INT_RANGE (11025,22050),
			    "depth",   GST_PROPS_INT (16),
			    "signed",  GST_PROPS_LIST (
			     		 GST_PROPS_BOOLEAN (TRUE),
			     		 GST_PROPS_BOOLEAN (FALSE)
				       )
			  );