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 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.
A capability is attached to a pad in order to describe what type of media the pad can handle.
A capability is named and consists of a MIME type and a set of properties. Its data 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 */ };
Below is a dump of the capabilities of the element mad, as shown by gst-inspect. You can see two pads: sink and src. Both pads have capability information attached to them.
The sink pad (input pad) is called 'sink' and takes data of MIME type 'audio/mp3'. It also has three properties: layer, bitrate and framed.
The source pad (output pad) is called 'src' and outputs data of MIME type 'audio/raw'. It also has four properties: format, depth, rate and channels.
Pads: SINK template: 'sink' Availability: Always Capabilities: 'mad_sink': MIME type: 'audio/mp3': SRC template: 'src' Availability: Always Capabilities: 'mad_src': MIME type: 'audio/raw': format: String: int endianness: Integer: 1234 width: Integer: 16 depth: Integer: 16 channels: Integer range: 1 - 2 law: Integer: 0 signed: Boolean: TRUE rate: Integer range: 11025 - 48000
Properties are used to describe extra information for capabilities. The properties basically consist of a key (a string) and a value. There are different possibile value types that can be used:
An integer value: the property has this exact value.
An integer range value. The property denotes a range of possible values. In the case of the mad element, the source pad has a property rate that can go from 11025 to 48000.
A boolean value.
a fourcc value: this is a value that is commonly used to describe an encoding for video, as used by the AVI specification.
A list value: the property can take any value from a list.
A float value: the property has this exact floating point value.
A float range value: denotes a range of possible floating point values.
A string value.
Capabilities describe in great detail the type of media that is handled by the pads. They are mostly used for:
Autoplugging: automatically finding plugins for a set of capabilities
Compatibility detection: when two pads are linked, GStreamer can verify if the two pads are talking about the same media types.
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; } ...
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:
GST_PROPS_INT(a): An integer value
GST_PROPS_FLOAT(a): A floating point value
GST_PROPS_FOURCC(a): A fourcc value
GST_PROPS_BOOLEAN(a): A boolean value
GST_PROPS_STRING(a): A string value
The values can also be specified as ranges with:
GST_PROPS_INT_RANGE(a,b): An integer ragne from a to b
GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
All of the above values can be given with a list too, using:
GST_PROPS_LIST(a,...): A list of property values.
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) ) );