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             "layout",   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(), 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
  73 <!-- ##### SECTION See_Also ##### -->
  74 <para>
  75 #GstProps, #GstPad
  76 </para>
  77
  78 <!-- ##### MACRO GST_CAPS_LOCK ##### -->
  79 <para>
  80 Lock the caps structure
  81 </para>
  82
  83 @caps: The caps structure to lock
  84
  85
  86 <!-- ##### MACRO GST_CAPS_TRYLOCK ##### -->
  87 <para>
  88 Try to lock the caps structure
  89 </para>
  90
  91 @caps: The caps structure to try to lock
  92
  93
  94 <!-- ##### MACRO GST_CAPS_UNLOCK ##### -->
  95 <para>
  96 Unlock the caps structure
  97 </para>
  98
  99 @caps: The caps structure to unlock
 100
 101
 102 <!-- ##### MACRO GST_CAPS_NEW ##### -->
 103 <para>
 104 A convenience macro to create a new GstCaps structure.
 105 </para>
 106
 107 @name: the name of the caps structure
 108 @type: the mime type of the caps structure
 109 @a...: the properties of this caps stucture.
 110
 111
 112 <!-- ##### MACRO GST_CAPS_FACTORY ##### -->
 113 <para>
 114 A convenience macro to create a GstCaps factory.
 115 </para>
 116
 117 @factoryname: the name of the factory
 118 @a...: the caps to create with this factory, usualy specified
 119 with GST_CAPS_NEW()
 120
 121
 122 <!-- ##### MACRO GST_CAPS_GET ##### -->
 123 <para>
 124 A convenience macro to get a GstCaps from the given capsfactory.
 125 </para>
 126
 127 @fact: the factory to use.
 128
 129
 130 <!-- ##### STRUCT GstCaps ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @name: the name of the capability, for the application
 136 @id: the typeid of the capability
 137 @refcount: a refcounter for this caps structure
 138 @lock: the lock for this caps structure
 139 @properties: the properties of the capability
 140 @next: a pointer to the next caps.
 141
 142 <!-- ##### FUNCTION gst_caps_new ##### -->
 143 <para>
 144
 145 </para>
 146
 147 @name:
 148 @mime:
 149 @props:
 150 @Returns:
 151
 152
 153 <!-- ##### FUNCTION gst_caps_destroy ##### -->
 154 <para>
 155
 156 </para>
 157
 158 @caps:
 159
 160
 161 <!-- ##### FUNCTION gst_caps_ref ##### -->
 162 <para>
 163
 164 </para>
 165
 166 @caps:
 167 @Returns:
 168
 169
 170 <!-- ##### FUNCTION gst_caps_unref ##### -->
 171 <para>
 172
 173 </para>
 174
 175 @caps:
 176 @Returns:
 177
 178
 179 <!-- ##### FUNCTION gst_caps_copy ##### -->
 180 <para>
 181
 182 </para>
 183
 184 @caps:
 185 @Returns:
 186
 187
 188 <!-- ##### FUNCTION gst_caps_copy_on_write ##### -->
 189 <para>
 190
 191 </para>
 192
 193 @caps:
 194 @Returns:
 195
 196
 197 <!-- ##### FUNCTION gst_caps_chain ##### -->
 198 <para>
 199
 200 </para>
 201
 202 @caps:
 203 @Varargs:
 204 @Returns:
 205
 206
 207 <!-- ##### FUNCTION gst_caps_append ##### -->
 208 <para>
 209
 210 </para>
 211
 212 @caps:
 213 @capstoadd:
 214 @Returns:
 215
 216
 217 <!-- ##### FUNCTION gst_caps_prepend ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @caps:
 223 @capstoadd:
 224 @Returns:
 225
 226
 227 <!-- ##### FUNCTION gst_caps_set_name ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @caps:
 233 @name:
 234
 235
 236 <!-- ##### FUNCTION gst_caps_get_name ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @caps:
 242 @Returns:
 243
 244
 245 <!-- ##### FUNCTION gst_caps_set_type_id ##### -->
 246 <para>
 247
 248 </para>
 249
 250 @caps:
 251 @type_id:
 252 <!-- # Unused Parameters # -->
 253 @Param2:
 254 @typeid:
 255
 256
 257 <!-- ##### FUNCTION gst_caps_get_type_id ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @caps:
 263 @Returns:
 264
 265
 266 <!-- ##### FUNCTION gst_caps_set_mime ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @caps:
 272 @mime:
 273
 274
 275 <!-- ##### FUNCTION gst_caps_get_mime ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @caps:
 281 @Returns:
 282
 283
 284 <!-- ##### FUNCTION gst_caps_set_props ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @caps:
 290 @props:
 291 @Returns:
 292
 293
 294 <!-- ##### FUNCTION gst_caps_get_props ##### -->
 295 <para>
 296
 297 </para>
 298
 299 @caps:
 300 @Returns:
 301
 302
 303 <!-- ##### FUNCTION gst_caps_check_compatibility ##### -->
 304 <para>
 305
 306 </para>
 307
 308 @fromcaps:
 309 @tocaps:
 310 @Returns:
 311
 312
 313 <!-- ##### MACRO gst_caps_set ##### -->
 314 <para>
 315 Set a property of a caps structure.
 316 </para>
 317
 318 @caps: the caps structure to modify
 319 @name: the name of the property to change
 320 @args...: the new value of the property
 321
 322
 323 <!-- ##### MACRO gst_caps_get_boolean ##### -->
 324 <para>
 325 Get the value of the named property as a boolean.
 326 </para>
 327
 328 @caps: the caps to query
 329 @name: the name of the property to get
 330
 331
 332 <!-- ##### FUNCTION gst_caps_get_by_name ##### -->
 333 <para>
 334
 335 </para>
 336
 337 @caps:
 338 @name:
 339 @Returns:
 340
 341
 342 <!-- ##### MACRO gst_caps_get_fourcc_int ##### -->
 343 <para>
 344 Get the value of the named property as a fourcc.
 345 </para>
 346
 347 @caps: the caps to query
 348 @name: the name of the property to get
 349
 350
 351 <!-- ##### MACRO gst_caps_get_int ##### -->
 352 <para>
 353 Get the value of the named property as an int.
 354 </para>
 355
 356 @caps: the caps to query
 357 @name: the name of the property to get
 358
 359
 360 <!-- ##### MACRO gst_caps_get_string ##### -->
 361 <para>
 362 Get the value of the named property as a string.
 363 </para>
 364
 365 @caps: the caps to query
 366 @name: the name of the property to get
 367
 368
 369 <!-- ##### MACRO gst_caps_get_float ##### -->
 370 <para>
 371 Get the value of the named property as a float.
 372 </para>
 373
 374 @caps: the caps to query
 375 @name: the name of the property to get
 376
 377
 378 <!-- ##### FUNCTION gst_caps_save_thyself ##### -->
 379 <para>
 380
 381 </para>
 382
 383 @caps:
 384 @parent:
 385 @Returns:
 386
 387
 388 <!-- ##### FUNCTION gst_caps_load_thyself ##### -->
 389 <para>
 390
 391 </para>
 392
 393 @parent:
 394 @Returns:
 395
 396