mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-29 11:40:38 +00:00
519 lines
8.9 KiB
Text
519 lines
8.9 KiB
Text
<!-- ##### SECTION Title ##### -->
|
|
GstCaps
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Capabilities of pads
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
<programlisting>
|
|
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));
|
|
</programlisting>
|
|
|
|
The following code example is equivalent to the above example:
|
|
<programlisting>
|
|
GstCaps *caps;
|
|
|
|
caps = GST_CAPS_NEW (
|
|
"my_caps", /* capability name */
|
|
"audio/raw", /* mime type */
|
|
"format", GST_PROPS_STRING ("float"),
|
|
"channels", GST_PROPS_INT (5)
|
|
);
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
GstCaps are refcounted with gst_caps_ref() and gst_caps_unref().
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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:
|
|
|
|
<programlisting>
|
|
GstCaps *caps;
|
|
....
|
|
|
|
gst_caps_set (caps, "format", GST_PROPS_STRING ("int"), NULL);
|
|
gst_caps_set (caps, "channels", GST_PROPS_INT (20), NULL);
|
|
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
If you need a unique instance of a GstCaps you can use the convenient
|
|
GST_CAPS_FACTORY() macro as shown below.
|
|
<programlisting>
|
|
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);
|
|
|
|
...
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
If you want to check if a connection 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 connection between source and destination caps
|
|
might be possible, use gst_caps_intersect(), which returns an intersection
|
|
of the capabilities.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
#GstProps, #GstPad
|
|
</para>
|
|
|
|
<!-- ##### MACRO GST_TYPE_CAPS ##### -->
|
|
<para>
|
|
The GType of the caps boxed type, for use in GValues.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GST_CAPS_NEW ##### -->
|
|
<para>
|
|
A convenience macro to create a new GstCaps structure.
|
|
</para>
|
|
|
|
@name: the name of the caps structure
|
|
@type: the mime type of the caps structure
|
|
@a...: the properties of this caps stucture.
|
|
|
|
|
|
<!-- ##### MACRO GST_CAPS_FACTORY ##### -->
|
|
<para>
|
|
A convenience macro to create a GstCaps factory.
|
|
</para>
|
|
|
|
@factoryname: the name of the factory
|
|
@a...: the caps to create with this factory, usualy specified
|
|
with GST_CAPS_NEW()
|
|
|
|
|
|
<!-- ##### MACRO GST_CAPS_GET ##### -->
|
|
<para>
|
|
A convenience macro to get a GstCaps from the given capsfactory.
|
|
</para>
|
|
|
|
@fact: the factory to use.
|
|
|
|
|
|
<!-- ##### MACRO GST_CAPS_IS_CHAINED ##### -->
|
|
<para>
|
|
Check if the GstCaps is chained.
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
|
|
|
|
<!-- ##### MACRO GST_CAPS_IS_FIXED ##### -->
|
|
<para>
|
|
Check if the GstCaps has fixed properties, ie. it has no ranges or lists.
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
|
|
|
|
<!-- ##### STRUCT GstCaps ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@name: the name of the capability, for the application
|
|
@id: the typeid of the capability
|
|
@refcount: a refcounter for this caps structure
|
|
@fixed: a boolean indicating that this caps structure is fixed
|
|
@properties: the properties of the capability
|
|
@next: a pointer to the next caps.
|
|
|
|
<!-- ##### FUNCTION gst_caps_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@name:
|
|
@mime:
|
|
@props:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_new_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@name:
|
|
@id:
|
|
@props:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_destroy ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_ref ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_unref ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_copy ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_copy_1 ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_copy_on_write ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_chain ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Varargs:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_append ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@capstoadd:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_prepend ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@capstoadd:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_set_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@name:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_get_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_set_type_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@type_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_get_type_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_set_mime ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@mime:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_get_mime ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_set_props ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@props:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_get_props ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_is_always_compatible ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@fromcaps:
|
|
@tocaps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_has_property ##### -->
|
|
<para>
|
|
Check if the GstCaps has a property with the given name
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_has_fixed_property ##### -->
|
|
<para>
|
|
Check if the GstCaps has a fixed property with the given name
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_has_property_typed ##### -->
|
|
<para>
|
|
Check if the GstCaps has a property with the given type
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property
|
|
@type:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_normalize ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_set ##### -->
|
|
<para>
|
|
Set a property of a caps structure.
|
|
</para>
|
|
|
|
@caps: the caps structure to modify
|
|
@name: the name of the property to change
|
|
@args...: the new value of the property
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_get ##### -->
|
|
<para>
|
|
Get key/value pairs from the given GstCaps.
|
|
</para>
|
|
|
|
@caps: the caps to get the values from
|
|
@name: the name of the first key
|
|
@args...: a pointer to the variable that can hold the result followed by more key/value pairs.
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_intersect ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps1:
|
|
@caps2:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_get_boolean ##### -->
|
|
<para>
|
|
Get the value of the named property as a boolean.
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property to get
|
|
@res: a pointer to a gboolean to store the result
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_get_by_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_get_fourcc_int ##### -->
|
|
<para>
|
|
Get the value of the named property as a fourcc.
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property to get
|
|
@res: a pointer to a guint32 to store the fourcc value
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_get_int ##### -->
|
|
<para>
|
|
Get the value of the named property as an int.
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property to get
|
|
@res: a pointer to a gint to store the value
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_get_string ##### -->
|
|
<para>
|
|
Get the value of the named property as a string.
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property to get
|
|
@res: a pointer to a gchar* to store the string
|
|
|
|
|
|
<!-- ##### MACRO gst_caps_get_float ##### -->
|
|
<para>
|
|
Get the value of the named property as a float.
|
|
</para>
|
|
|
|
@caps: the caps to query
|
|
@name: the name of the property to get
|
|
@res: a pointer to a gfloat to store the result
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_save_thyself ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@parent:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_load_thyself ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@parent:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_debug ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@label:
|
|
|
|
|