gstreamer/docs/gst/tmpl/gstcaps.sgml
Benjamin Otte 385b9ee5c4 merge in tagging
Original commit message from CVS:
merge in tagging
Includes:
- gsttag.[ch] - The definition of GstTagList and tag registering/querying
- gsttaginterface.[ch] - Interface for elements that can handle setting of tags
- updates and merges to gststructure.[ch] and gstvalue.[ch]
- testsuite/tags - some tests for tagging
- bugfixes
- updates to make make distcheck work
- updates the version number to 0.7.2.1

Does not include:
- including tagging stuff in docs
- extensive tests
2003-11-24 02:09:23 +00:00

611 lines
10 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"),
"channels", 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 &gt;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 link 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 link 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
@...: 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
@...: 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>
The gstcaps structure
</para>
@name: the name of the capability, for the application
@id: the typeid of the capability
@flags:
@refcount: a refcounter for this caps structure
@properties: the properties of the capability
@next: a pointer to the next caps.
<!-- ##### ENUM GstCapsFlags ##### -->
<para>
Flags for this caps.
</para>
@GST_CAPS_UNUSED:
@GST_CAPS_FLOATING: the caps is not owned by anyone
<!-- ##### MACRO GST_CAPS_FLAGS ##### -->
<para>
Get the flags of the caps
</para>
@caps: The caps to get the flags of
<!-- ##### MACRO GST_CAPS_FLAG_IS_SET ##### -->
<para>
Test is a flag is set
</para>
@caps: The caps to test
@flag: The flag to check
<!-- ##### MACRO GST_CAPS_FLAG_SET ##### -->
<para>
Set a flag on the caps
</para>
@caps: The caps to modify
@flag: The flag to set
<!-- ##### MACRO GST_CAPS_FLAG_UNSET ##### -->
<para>
Unset a flag on the caps
</para>
@caps: The caps to modify
@flag: The flag to unset
<!-- ##### MACRO GST_CAPS_IS_FLOATING ##### -->
<para>
Test if a caps is floating
</para>
@caps: The caps to test
<!-- ##### 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
<!-- ##### MACRO GST_CAPS_NEXT ##### -->
<para>
Get a pointer to the next chained caps
</para>
@caps: The caps to query
<!-- ##### MACRO GST_CAPS_PROPERTIES ##### -->
<para>
Get the properties of the caps
</para>
@caps: The caps to query
<!-- ##### MACRO GST_CAPS_REFCOUNT ##### -->
<para>
Get the refcount of the caps.
</para>
@caps: The caps to query
<!-- ##### MACRO GST_CAPS_TRACE_NAME ##### -->
<para>
The name used for tracing
</para>
<!-- ##### FUNCTION gst_caps_new ##### -->
<para>
</para>
@name:
@mime:
@props:
@Returns:
<!-- ##### FUNCTION gst_caps_new_id ##### -->
<para>
</para>
@name:
@id:
@props:
@Returns:
<!-- ##### 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_next ##### -->
<para>
</para>
@caps:
@Returns:
<!-- ##### FUNCTION gst_caps_replace ##### -->
<para>
</para>
@oldcaps:
@newcaps:
<!-- ##### FUNCTION gst_caps_replace_sink ##### -->
<para>
</para>
@oldcaps:
@newcaps:
<!-- ##### FUNCTION gst_caps_sink ##### -->
<para>
</para>
@caps:
<!-- ##### FUNCTION gst_caps_set_name ##### -->
<para>
</para>
@caps:
@name:
<!-- ##### FUNCTION gst_caps_get_name ##### -->
<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:
<!-- ##### FUNCTION 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
@Returns:
<!-- ##### FUNCTION 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
@Returns:
<!-- ##### FUNCTION 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:
@Returns:
<!-- ##### 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
@...: 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
@...: 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: