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_simpl(), which takes a mime type and
a list of arguments in sets of 3, terminated with NULL.  Each set of 3
arguments is the name of a field, the GType of the field, and the value
of the field.  The following example shows how to create a GstCaps.
<programlisting>
  GstCaps *caps;

  caps = gst_caps_new (
      "audio/x-raw-int",		/* mime type */
      "channels", G_TYPE_INT, 5,
      NULL);
</programlisting>

The following code example is equivalent to the above example:
<programlisting>
  GstCaps *caps;

  caps = gst_caps_from_string ("audio/x-raw-int, channels = (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 fields of the caps structure can be modified with gst_caps_set_simple,
which takes the caps structure to be modified, a list of arguments in
sets of 3, terminated by NULL.  The format of these arguments is the
same as above.

<programlisting>
  GstCaps *caps;
   ....

  gst_caps_set_simple (caps, "channels", G_TYPE_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>
  GstStaticCaps my_caps = GST_STATIC_CAPS (
      "audio/x-raw-float, "
        "channels = (int) 5; "
      "audio/x-raw-int, "
        "channels = (int) 5"
    )
  )

  void
  some_function (void)
  {
    GstCaps *caps = gst_caps_copy (gst_static_caps_get (&amp;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>
#GstStructure, #GstPad
</para>

<!-- ##### MACRO GST_TYPE_CAPS ##### -->
<para>
The GType of the caps boxed type, for use in GValues.
</para>



<!-- ##### STRUCT GstCaps ##### -->
<para>
The gstcaps structure
</para>

@type: 
@flags: 
@structs: 

<!-- ##### FUNCTION gst_caps_copy ##### -->
<para>

</para>

@caps: 
@Returns: 


<!-- ##### FUNCTION gst_caps_copy_1 ##### -->
<para>

</para>

@caps: 
@Returns: 


<!-- ##### FUNCTION gst_caps_append ##### -->
<para>

</para>

@caps1: 
@caps2: 
<!-- # Unused Parameters # -->
@caps: 
@capstoadd: 
@Returns: 


<!-- ##### FUNCTION gst_caps_replace ##### -->
<para>

</para>

@caps: 
@newcaps: 
<!-- # Unused Parameters # -->
@oldcaps: 


<!-- ##### FUNCTION gst_caps_is_always_compatible ##### -->
<para>

</para>

@caps1: 
@caps2: 
@Returns: 
<!-- # Unused Parameters # -->
@fromcaps: 
@tocaps: 


<!-- ##### FUNCTION gst_caps_normalize ##### -->
<para>

</para>

@caps: 
@Returns: 


<!-- ##### FUNCTION gst_caps_intersect ##### -->
<para>

</para>

@caps1: 
@caps2: 
@Returns: 


<!-- ##### FUNCTION gst_caps_save_thyself ##### -->
<para>

</para>

@caps: 
@parent: 
@Returns: 


<!-- ##### FUNCTION gst_caps_load_thyself ##### -->
<para>

</para>

@parent: 
@Returns: 


<!-- ##### FUNCTION gst_caps_union ##### -->
<para>

</para>

@caps1: 
@caps2: 
@Returns: