8.3. What capabilities are used for

Capabilities describe the type of data that is streamed between two pads, or that one pad (template) supports. This makes them very useful for various purposes:

8.3.1. Using capabilities for metadata

A pad can have a set (i.e. one or more) of capabilities attached to it. You can get values of properties in a set of capabilities by querying individual properties of one structure. You can get a structure from a caps using gst_caps_get_structure ():


static void
read_video_props (GstCaps *caps)
{
  gint width, height;
  const GstStructure *str;

  str = gst_caps_get_structure (caps);
  if (!gst_structure_get_int (str, "width", &width) ||
      !gst_structure_get_int (str, "height", &height)) {
    g_print ("No width/height available\n");
    return;
  }

  g_print ("The video size of this set of capabilities is %dx%d\n",
	   width, height);
}
      

8.3.2. Creating capabilities for filtering

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, especially when using filtered caps. When you're using filtered caps or fixation, you're limiting the allowed types of media that can stream between two pads to a subset of their supported media types. You do this by filtering using your own set of capabilities. In order to do this, you need to create your own GstCaps. The simplest way to do this is by using the convenience function gst_caps_new_simple ():


static void
link_pads_with_filter (GstPad *one,
		       GstPad *other)
{
  GstCaps *caps;

  caps = gst_caps_new_simple ("video/x-raw-yuv",
			      "width", G_TYPE_INT, 384,
			      "height", G_TYPE_INT, 288,
			      "framerate", GST_TYPE_FRACTION, 25, 1,
			      NULL);
  gst_pad_link_filtered (one, other, caps);
}
      

In some cases, you will want to create a more elaborate set of capabilities to filter a link between two pads. Then, this function is too simplistic and you'll want to use the method gst_caps_new_full ():


static void
link_pads_with_filter (GstPad *one,
                       GstPad *other)
{
  GstCaps *caps;
                                                                                
  caps = gst_caps_new_full (
      gst_structure_new ("video/x-raw-yuv",
			 "width", G_TYPE_INT, 384,
			 "height", G_TYPE_INT, 288,
			 "framerate", GST_TYPE_FRACTION, 25, 1,
			 NULL),
      gst_structure_new ("video/x-raw-rgb",
			 "width", G_TYPE_INT, 384,
			 "height", G_TYPE_INT, 288,
			 "framerate", GST_TYPE_FRACTION, 25, 1,
			 NULL),
      NULL);

  gst_pad_link_filtered (one, other, caps);
}
      

See the API references for the full API of GstStructure and GstCaps.