mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-19 08:11:16 +00:00
9ba56f4181
Original commit message from CVS: Get the API docs back in shape. This batch of patches contain the updates that don't require source code comment changes.
396 lines
6.5 KiB
Text
396 lines
6.5 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(), 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>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
#GstProps, #GstPad
|
|
</para>
|
|
|
|
<!-- ##### MACRO GST_CAPS_LOCK ##### -->
|
|
<para>
|
|
Lock the caps structure
|
|
</para>
|
|
|
|
@caps: The caps structure to lock
|
|
|
|
|
|
<!-- ##### MACRO GST_CAPS_TRYLOCK ##### -->
|
|
<para>
|
|
Try to lock the caps structure
|
|
</para>
|
|
|
|
@caps: The caps structure to try to lock
|
|
|
|
|
|
<!-- ##### MACRO GST_CAPS_UNLOCK ##### -->
|
|
<para>
|
|
Unlock the caps structure
|
|
</para>
|
|
|
|
@caps: The caps structure to unlock
|
|
|
|
|
|
<!-- ##### 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.
|
|
|
|
|
|
<!-- ##### 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
|
|
@lock: the lock for this caps structure
|
|
@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_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_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:
|
|
<!-- # Unused Parameters # -->
|
|
@Param2:
|
|
@typeid:
|
|
|
|
|
|
<!-- ##### 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_check_compatibility ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@fromcaps:
|
|
@tocaps:
|
|
@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_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
|
|
|
|
|
|
<!-- ##### 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
|
|
|
|
|
|
<!-- ##### 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
|
|
|
|
|
|
<!-- ##### 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
|
|
|
|
|
|
<!-- ##### 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
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_save_thyself ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@caps:
|
|
@parent:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_caps_load_thyself ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@parent:
|
|
@Returns:
|
|
|
|
|