gstreamer/docs/gst/tmpl/gstcaps.sgml

<!-- ##### 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 &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>

<!-- ##### 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: