docs/gst/tmpl/gstcaps.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstCaps
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Capabilities of pads
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GstCaps is used to attach capabilities to a pad. Capabilities are made of
  10 a mime-type and a set of properties. GstCaps can be named and chained into
  11 a list, which is then a GstCaps on its own.
  12 </para>
  13 <para>
  14 GstCaps are created with gst_caps_new(), which takes a name, a mime type and
  15 a pointer to a #GstProps. A convenience macro with a cleaner syntax is
  16 available to create a caps with GST_CAPS_NEW(). The following example shows how
  17 to create a GstCaps.
  18 <programlisting>
  19   GstCaps *caps;
  20
  21   caps = gst_caps_new (
  22           "my_caps",            /* capability name */
  23           "audio/raw",          /* mime type */
  24           gst_props_new (       /* properties */
  25             "format",   GST_PROPS_STRING ("float"),
  26             "channels",   GST_PROPS_INT (5),
  27             NULL));
  28 </programlisting>
  29
  30 The following code example is equivalent to the above example:
  31 <programlisting>
  32   GstCaps *caps;
  33
  34   caps = GST_CAPS_NEW (
  35           "my_caps",            /* capability name */
  36           "audio/raw",          /* mime type */
  37             "format",   GST_PROPS_STRING ("float"),
  38             "channels", GST_PROPS_INT (5)
  39           );
  40 </programlisting>
  41 </para>
  42 <para>
  43 GstCaps are refcounted with gst_caps_ref() and gst_caps_unref().
  44 </para>
  45 <para>
  46 GstCaps can be chained with the gst_caps_append(), gst_caps_prepend() and
  47 gst_caps_chain() functions. Use gst_caps_get_by_name() to get a named caps
  48 structure from a chained list.
  49 </para>
  50 <para>
  51 To get the properties of a caps structure the functions
  52 gst_caps_get_boolean(), gst_caps_get_fourcc_int(), gst_caps_get_int(),
  53 gst_caps_get_string(), gst_caps_get_float(), which all take a property name as an argument.
  54 </para>
  55 <para>
  56 The properties of the caps structure can be modified with gst_caps_set, which
  57 takes a list of key value pairs in the #GstProps syntax as shown by this example:
  58
  59 <programlisting>
  60   GstCaps *caps;
  61    ....
  62
  63   gst_caps_set (caps, "format", GST_PROPS_STRING ("int"), NULL);
  64   gst_caps_set (caps, "channels", GST_PROPS_INT (20), NULL);
  65
  66 </programlisting>
  67 </para>
  68 <para>
  69 before modifying a GstCaps, it is a good idea to make a copy if it first with
  70 gst_caps_copy_on_write(). This will copy the GstCaps if the refcount is &gt;1.
  71 </para>
  72 <para>
  73 If you need a unique instance of a GstCaps you can use the convenient
  74 GST_CAPS_FACTORY() macro as shown below.
  75 <programlisting>
  76   GST_CAPS_FACTORY (my_caps,
  77     GST_CAPS_NEW (
  78       "caps1",
  79       "audio/raw",
  80         "format",   GST_PROPS_STRING ("float"),
  81         "channels", GST_PROPS_INT (5)
  82     ),
  83     GST_CAPS_NEW (
  84       "caps2",
  85       "audio/raw",
  86         "format",   GST_PROPS_STRING ("int"),
  87         "channels", GST_PROPS_INT (5)
  88     )
  89   )
  90
  91   void
  92   some_function (void)
  93   {
  94     GstCaps *caps = GST_CAPS_GET (my_caps);
  95
  96     ...
  97   }
  98 </programlisting>
  99 </para>
 100 <para>
 101 If you want to check if a link between source and destination caps
 102 is always possible, use gst_caps_is_always_compatible(), which returns
 103 a boolean.
 104 If you want to check if a link between source and destination caps
 105 might be possible, use gst_caps_intersect(), which returns an intersection
 106 of the capabilities.
 107 </para>
 108
 109 <!-- ##### SECTION See_Also ##### -->
 110 <para>
 111 #GstProps, #GstPad
 112 </para>
 113
 114 <!-- ##### MACRO GST_TYPE_CAPS ##### -->
 115 <para>
 116 The GType of the caps boxed type, for use in GValues.
 117 </para>
 118
 119
 120
 121 <!-- ##### STRUCT GstCaps ##### -->
 122 <para>
 123 The gstcaps structure
 124 </para>
 125
 126 @type:
 127 @flags:
 128 @structs:
 129
 130 <!-- ##### FUNCTION gst_caps_copy ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @caps:
 136 @Returns:
 137
 138
 139 <!-- ##### FUNCTION gst_caps_copy_1 ##### -->
 140 <para>
 141
 142 </para>
 143
 144 @caps:
 145 @Returns:
 146
 147
 148 <!-- ##### FUNCTION gst_caps_append ##### -->
 149 <para>
 150
 151 </para>
 152
 153 @caps1:
 154 @caps2:
 155 <!-- # Unused Parameters # -->
 156 @caps:
 157 @capstoadd:
 158 @Returns:
 159
 160
 161 <!-- ##### FUNCTION gst_caps_replace ##### -->
 162 <para>
 163
 164 </para>
 165
 166 @caps:
 167 @newcaps:
 168 <!-- # Unused Parameters # -->
 169 @oldcaps:
 170
 171
 172 <!-- ##### FUNCTION gst_caps_is_always_compatible ##### -->
 173 <para>
 174
 175 </para>
 176
 177 @caps1:
 178 @caps2:
 179 @Returns:
 180 <!-- # Unused Parameters # -->
 181 @fromcaps:
 182 @tocaps:
 183
 184
 185 <!-- ##### FUNCTION gst_caps_normalize ##### -->
 186 <para>
 187
 188 </para>
 189
 190 @caps:
 191 @Returns:
 192
 193
 194 <!-- ##### FUNCTION gst_caps_intersect ##### -->
 195 <para>
 196
 197 </para>
 198
 199 @caps1:
 200 @caps2:
 201 @Returns:
 202
 203
 204 <!-- ##### FUNCTION gst_caps_save_thyself ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @caps:
 210 @parent:
 211 @Returns:
 212
 213
 214 <!-- ##### FUNCTION gst_caps_load_thyself ##### -->
 215 <para>
 216
 217 </para>
 218
 219 @parent:
 220 @Returns:
 221
 222
 223 <!-- ##### FUNCTION gst_caps_union ##### -->
 224 <para>
 225
 226 </para>
 227
 228 @caps1:
 229 @caps2:
 230 @Returns:
 231
 232