gst/gstcaps.c

   1 /* GStreamer
   2  * Copyright (C) <2003> David A. Schleef <ds@schleef.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /**
  21  * SECTION:gstcaps
  22  * @short_description: Structure describing sets of media formats
  23  * @see_also: #GstStructure
  24  *
  25  * Caps (capabilities) are lighweight refcounted objects describing media types.
  26  * They are composed of an array of #GstStructure.
  27  *
  28  * Caps are exposed on #GstPadTemplate to describe all possible types a
  29  * given pad can handle. They are also stored in the #GstRegistry along with
  30  * a description of the #GstElement.
  31  *
  32  * Caps are exposed on the element pads using the gst_pad_get_caps() pad
  33  * function. This function describes the possible types that the pad can
  34  * handle or produce at runtime.
  35  *
  36  * Caps are also attached to buffers to describe to content of the data
  37  * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
  38  * a #GstBuffer allow for format negotiation upstream and downstream.
  39  *
  40  * A #GstCaps can be constructed with the following code fragment:
  41  *
  42  * <example>
  43  *  <title>Creating caps</title>
  44  *  <programlisting>
  45  *  GstCaps *caps;
  46  *  caps = gst_caps_new_simple ("video/x-raw",
  47  *       "format", G_TYPE_STRING, "I420",
  48  *       "framerate", GST_TYPE_FRACTION, 25, 1,
  49  *       "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
  50  *       "width", G_TYPE_INT, 320,
  51  *       "height", G_TYPE_INT, 240,
  52  *       NULL);
  53  *  </programlisting>
  54  * </example>
  55  *
  56  * A #GstCaps is fixed when it has no properties with ranges or lists. Use
  57  * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
  58  * set on a #GstPad or #GstBuffer.
  59  *
  60  * Various methods exist to work with the media types such as subtracting
  61  * or intersecting.
  62  *
  63  * Last reviewed on 2007-02-13 (0.10.10)
  64  */
  65
  66 #ifdef HAVE_CONFIG_H
  67 #include "config.h"
  68 #endif
  69 #include <string.h>
  70 #include <signal.h>
  71
  72 #include "gst_private.h"
  73 #include <gst/gst.h>
  74 #include <gobject/gvaluecollector.h>
  75
  76 #define DEBUG_REFCOUNT
  77
  78 typedef struct _GstCapsImpl
  79 {
  80   GstCaps caps;
  81
  82   GPtrArray *array;
  83 } GstCapsImpl;
  84
  85 #define GST_CAPS_ARRAY(c) (((GstCapsImpl *)(c))->array)
  86
  87 #define GST_CAPS_LEN(c)   (GST_CAPS_ARRAY(c)->len)
  88
  89 #define IS_WRITABLE(caps) \
  90   (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
  91
  92 /* same as gst_caps_is_any () */
  93 #define CAPS_IS_ANY(caps)                               \
  94   (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY)
  95
  96 /* same as gst_caps_is_empty () */
  97 #define CAPS_IS_EMPTY(caps)                             \
  98   (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
  99
 100 #define CAPS_IS_EMPTY_SIMPLE(caps)                                      \
 101   ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
 102
 103 /* quick way to get a caps structure at an index without doing a type or array
 104  * length check */
 105 #define gst_caps_get_structure_unchecked(caps, index) \
 106      ((GstStructure *)g_ptr_array_index (GST_CAPS_ARRAY (caps), (index)))
 107 /* quick way to append a structure without checking the args */
 108 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
 109   GstStructure *__s=structure;                                      \
 110   if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps)))         \
 111     g_ptr_array_add (GST_CAPS_ARRAY (caps), __s);                             \
 112 }G_STMT_END
 113
 114 /* lock to protect multiple invocations of static caps to caps conversion */
 115 G_LOCK_DEFINE_STATIC (static_caps_lock);
 116
 117 static void gst_caps_transform_to_string (const GValue * src_value,
 118     GValue * dest_value);
 119 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
 120     const gchar * string);
 121
 122 GType _gst_caps_type = 0;
 123 GstCaps *_gst_caps_any;
 124 GstCaps *_gst_caps_none;
 125
 126 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
 127
 128 void
 129 _priv_gst_caps_initialize (void)
 130 {
 131   _gst_caps_type = gst_caps_get_type ();
 132
 133   _gst_caps_any = gst_caps_new_any ();
 134   _gst_caps_none = gst_caps_new_empty ();
 135
 136   g_value_register_transform_func (_gst_caps_type,
 137       G_TYPE_STRING, gst_caps_transform_to_string);
 138 }
 139
 140 static GstCaps *
 141 _gst_caps_copy (const GstCaps * caps)
 142 {
 143   GstCaps *newcaps;
 144   GstStructure *structure;
 145   guint i, n;
 146
 147   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 148
 149   newcaps = gst_caps_new_empty ();
 150   GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
 151   n = GST_CAPS_LEN (caps);
 152
 153   GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, caps, "doing copy %p -> %p",
 154       caps, newcaps);
 155
 156   for (i = 0; i < n; i++) {
 157     structure = gst_caps_get_structure_unchecked (caps, i);
 158     gst_caps_append_structure (newcaps, gst_structure_copy (structure));
 159   }
 160
 161   return newcaps;
 162 }
 163
 164 /* creation/deletion */
 165 static void
 166 _gst_caps_free (GstCaps * caps)
 167 {
 168   GstStructure *structure;
 169   guint i, len;
 170
 171   /* The refcount must be 0, but since we're only called by gst_caps_unref,
 172    * don't bother testing. */
 173   len = GST_CAPS_LEN (caps);
 174   /* This can be used to get statistics about caps sizes */
 175   /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
 176   for (i = 0; i < len; i++) {
 177     structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
 178     gst_structure_set_parent_refcount (structure, NULL);
 179     gst_structure_free (structure);
 180   }
 181   g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
 182
 183 #ifdef DEBUG_REFCOUNT
 184   GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
 185 #endif
 186   g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
 187 }
 188
 189 static void
 190 gst_caps_init (GstCaps * caps, gsize size)
 191 {
 192   gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
 193
 194   caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
 195   caps->mini_object.dispose = NULL;
 196   caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
 197
 198   /* the 32 has been determined by logging caps sizes in _gst_caps_free
 199    * but g_ptr_array uses 16 anyway if it expands once, so this does not help
 200    * in practise
 201    * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
 202    */
 203   GST_CAPS_ARRAY (caps) = g_ptr_array_new ();
 204 }
 205
 206 /**
 207  * gst_caps_new_empty:
 208  *
 209  * Creates a new #GstCaps that is empty.  That is, the returned
 210  * #GstCaps contains no media formats.
 211  * The #GstCaps is guaranteed to be writable.
 212  * Caller is responsible for unreffing the returned caps.
 213  *
 214  * Returns: (transfer full): the new #GstCaps
 215  */
 216 GstCaps *
 217 gst_caps_new_empty (void)
 218 {
 219   GstCaps *caps;
 220
 221   caps = (GstCaps *) g_slice_new (GstCapsImpl);
 222
 223   gst_caps_init (caps, sizeof (GstCapsImpl));
 224
 225 #ifdef DEBUG_REFCOUNT
 226   GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
 227 #endif
 228
 229   return caps;
 230 }
 231
 232 /**
 233  * gst_caps_new_any:
 234  *
 235  * Creates a new #GstCaps that indicates that it is compatible with
 236  * any media format.
 237  *
 238  * Returns: (transfer full): the new #GstCaps
 239  */
 240 GstCaps *
 241 gst_caps_new_any (void)
 242 {
 243   GstCaps *caps = gst_caps_new_empty ();
 244
 245   GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
 246
 247   return caps;
 248 }
 249
 250 /**
 251  * gst_caps_new_empty_simple:
 252  * @media_type: the media type of the structure
 253  *
 254  * Creates a new #GstCaps that contains one #GstStructure with name
 255  * @media_type.
 256  * Caller is responsible for unreffing the returned caps.
 257  *
 258  * Returns: (transfer full): the new #GstCaps
 259  */
 260 GstCaps *
 261 gst_caps_new_empty_simple (const char *media_type)
 262 {
 263   GstCaps *caps;
 264   GstStructure *structure;
 265
 266   caps = gst_caps_new_empty ();
 267   structure = gst_structure_new_empty (media_type);
 268   if (structure)
 269     gst_caps_append_structure_unchecked (caps, structure);
 270
 271   return caps;
 272 }
 273
 274 /**
 275  * gst_caps_new_simple:
 276  * @media_type: the media type of the structure
 277  * @fieldname: first field to set
 278  * @...: additional arguments
 279  *
 280  * Creates a new #GstCaps that contains one #GstStructure.  The
 281  * structure is defined by the arguments, which have the same format
 282  * as gst_structure_new().
 283  * Caller is responsible for unreffing the returned caps.
 284  *
 285  * Returns: (transfer full): the new #GstCaps
 286  */
 287 GstCaps *
 288 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
 289 {
 290   GstCaps *caps;
 291   GstStructure *structure;
 292   va_list var_args;
 293
 294   caps = gst_caps_new_empty ();
 295
 296   va_start (var_args, fieldname);
 297   structure = gst_structure_new_valist (media_type, fieldname, var_args);
 298   va_end (var_args);
 299
 300   if (structure)
 301     gst_caps_append_structure_unchecked (caps, structure);
 302   else
 303     gst_caps_replace (&caps, NULL);
 304
 305   return caps;
 306 }
 307
 308 /**
 309  * gst_caps_new_full:
 310  * @struct1: the first structure to add
 311  * @...: additional structures to add
 312  *
 313  * Creates a new #GstCaps and adds all the structures listed as
 314  * arguments.  The list must be NULL-terminated.  The structures
 315  * are not copied; the returned #GstCaps owns the structures.
 316  *
 317  * Returns: (transfer full): the new #GstCaps
 318  */
 319 GstCaps *
 320 gst_caps_new_full (GstStructure * struct1, ...)
 321 {
 322   GstCaps *caps;
 323   va_list var_args;
 324
 325   va_start (var_args, struct1);
 326   caps = gst_caps_new_full_valist (struct1, var_args);
 327   va_end (var_args);
 328
 329   return caps;
 330 }
 331
 332 /**
 333  * gst_caps_new_full_valist:
 334  * @structure: the first structure to add
 335  * @var_args: additional structures to add
 336  *
 337  * Creates a new #GstCaps and adds all the structures listed as
 338  * arguments.  The list must be NULL-terminated.  The structures
 339  * are not copied; the returned #GstCaps owns the structures.
 340  *
 341  * Returns: (transfer full): the new #GstCaps
 342  */
 343 GstCaps *
 344 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
 345 {
 346   GstCaps *caps;
 347
 348   caps = gst_caps_new_empty ();
 349
 350   while (structure) {
 351     gst_caps_append_structure_unchecked (caps, structure);
 352     structure = va_arg (var_args, GstStructure *);
 353   }
 354
 355   return caps;
 356 }
 357
 358 G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
 359
 360 /**
 361  * gst_static_caps_get:
 362  * @static_caps: the #GstStaticCaps to convert
 363  *
 364  * Converts a #GstStaticCaps to a #GstCaps.
 365  *
 366  * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
 367  *     Since the core holds an additional ref to the returned caps,
 368  *     use gst_caps_make_writable() on the returned caps to modify it.
 369  */
 370 GstCaps *
 371 gst_static_caps_get (GstStaticCaps * static_caps)
 372 {
 373   GstCaps **caps;
 374
 375   g_return_val_if_fail (static_caps != NULL, NULL);
 376
 377   caps = &static_caps->caps;
 378
 379   /* refcount is 0 when we need to convert */
 380   if (G_UNLIKELY (*caps == NULL)) {
 381     const char *string;
 382
 383     G_LOCK (static_caps_lock);
 384     /* check if other thread already updated */
 385     if (G_UNLIKELY (*caps != NULL))
 386       goto done;
 387
 388     string = static_caps->string;
 389
 390     if (G_UNLIKELY (string == NULL))
 391       goto no_string;
 392
 393     *caps = gst_caps_from_string (string);
 394
 395     /* convert to string */
 396     if (G_UNLIKELY (*caps == NULL))
 397       g_critical ("Could not convert static caps \"%s\"", string);
 398
 399     GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
 400         string);
 401   done:
 402     G_UNLOCK (static_caps_lock);
 403   }
 404   /* ref the caps, makes it not writable */
 405   if (G_LIKELY (*caps != NULL))
 406     gst_caps_ref (*caps);
 407
 408   return *caps;
 409
 410   /* ERRORS */
 411 no_string:
 412   {
 413     G_UNLOCK (static_caps_lock);
 414     g_warning ("static caps %p string is NULL", static_caps);
 415     return NULL;
 416   }
 417 }
 418
 419 /**
 420  * gst_static_caps_cleanup:
 421  * @static_caps: the #GstStaticCaps to clean
 422  *
 423  * Clean up the cached caps contained in @static_caps.
 424  */
 425 void
 426 gst_static_caps_cleanup (GstStaticCaps * static_caps)
 427 {
 428   G_LOCK (static_caps_lock);
 429   gst_caps_replace (&static_caps->caps, NULL);
 430   G_UNLOCK (static_caps_lock);
 431 }
 432
 433 /* manipulation */
 434
 435 static GstStructure *
 436 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
 437 {
 438   /* don't use index_fast, gst_caps_simplify relies on the order */
 439   GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
 440
 441   gst_structure_set_parent_refcount (s, NULL);
 442   return s;
 443 }
 444
 445 /**
 446  * gst_caps_steal_structure:
 447  * @caps: the #GstCaps to retrieve from
 448  * @index: Index of the structure to retrieve
 449  *
 450  * Retrieves the stucture with the given index from the list of structures
 451  * contained in @caps. The caller becomes the owner of the returned structure.
 452  *
 453  * Returns: (transfer full): a pointer to the #GstStructure corresponding
 454  *     to @index.
 455  *
 456  * Since: 0.10.30
 457  */
 458 GstStructure *
 459 gst_caps_steal_structure (GstCaps * caps, guint index)
 460 {
 461   g_return_val_if_fail (caps != NULL, NULL);
 462   g_return_val_if_fail (IS_WRITABLE (caps), NULL);
 463
 464   if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
 465     return NULL;
 466
 467   return gst_caps_remove_and_get_structure (caps, index);
 468 }
 469
 470 /**
 471  * gst_caps_append:
 472  * @caps1: the #GstCaps that will be appended to
 473  * @caps2: (transfer full): the #GstCaps to append
 474  *
 475  * Appends the structures contained in @caps2 to @caps1. The structures in
 476  * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
 477  * freed. If either caps is ANY, the resulting caps will be ANY.
 478  */
 479 void
 480 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
 481 {
 482   GstStructure *structure;
 483   int i;
 484
 485   g_return_if_fail (GST_IS_CAPS (caps1));
 486   g_return_if_fail (GST_IS_CAPS (caps2));
 487   g_return_if_fail (IS_WRITABLE (caps1));
 488
 489   if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
 490     GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
 491     gst_caps_unref (caps2);
 492   } else {
 493     caps2 = gst_caps_make_writable (caps2);
 494
 495     for (i = GST_CAPS_LEN (caps2); i; i--) {
 496       structure = gst_caps_remove_and_get_structure (caps2, 0);
 497       gst_caps_append_structure_unchecked (caps1, structure);
 498     }
 499     gst_caps_unref (caps2);     /* guaranteed to free it */
 500   }
 501 }
 502
 503 /**
 504  * gst_caps_merge:
 505  * @caps1: (transfer full): the #GstCaps that will take the new entries
 506  * @caps2: (transfer full): the #GstCaps to merge in
 507  *
 508  * Appends the structures contained in @caps2 to @caps1 if they are not yet
 509  * expressed by @caps1. The structures in @caps2 are not copied -- they are
 510  * transferred to a writable copy of @caps1, and then @caps2 is freed.
 511  * If either caps is ANY, the resulting caps will be ANY.
 512  *
 513  * Returns: (transfer full): the merged caps.
 514  *
 515  * Since: 0.10.10
 516  */
 517 GstCaps *
 518 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
 519 {
 520   GstStructure *structure;
 521   int i;
 522   GstCaps *result;
 523
 524   g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
 525   g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
 526
 527   if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
 528     gst_caps_unref (caps2);
 529     result = caps1;
 530   } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
 531     gst_caps_unref (caps1);
 532     result = caps2;
 533   } else {
 534     caps2 = gst_caps_make_writable (caps2);
 535
 536     for (i = GST_CAPS_LEN (caps2); i; i--) {
 537       structure = gst_caps_remove_and_get_structure (caps2, 0);
 538       caps1 = gst_caps_merge_structure (caps1, structure);
 539     }
 540     gst_caps_unref (caps2);
 541     result = caps1;
 542
 543     /* this is too naive
 544        GstCaps *com = gst_caps_intersect (caps1, caps2);
 545        GstCaps *add = gst_caps_subtract (caps2, com);
 546
 547        GST_DEBUG ("common : %d", gst_caps_get_size (com));
 548        GST_DEBUG ("adding : %d", gst_caps_get_size (add));
 549        gst_caps_append (caps1, add);
 550        gst_caps_unref (com);
 551      */
 552   }
 553
 554   return result;
 555 }
 556
 557 /**
 558  * gst_caps_append_structure:
 559  * @caps: the #GstCaps that will be appended to
 560  * @structure: (transfer full): the #GstStructure to append
 561  *
 562  * Appends @structure to @caps.  The structure is not copied; @caps
 563  * becomes the owner of @structure.
 564  */
 565 void
 566 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
 567 {
 568   g_return_if_fail (GST_IS_CAPS (caps));
 569   g_return_if_fail (IS_WRITABLE (caps));
 570
 571   if (G_LIKELY (structure)) {
 572     gst_caps_append_structure_unchecked (caps, structure);
 573   }
 574 }
 575
 576 /**
 577  * gst_caps_remove_structure:
 578  * @caps: the #GstCaps to remove from
 579  * @idx: Index of the structure to remove
 580  *
 581  * removes the stucture with the given index from the list of structures
 582  * contained in @caps.
 583  */
 584 void
 585 gst_caps_remove_structure (GstCaps * caps, guint idx)
 586 {
 587   GstStructure *structure;
 588
 589   g_return_if_fail (caps != NULL);
 590   g_return_if_fail (idx <= gst_caps_get_size (caps));
 591   g_return_if_fail (IS_WRITABLE (caps));
 592
 593   structure = gst_caps_remove_and_get_structure (caps, idx);
 594   gst_structure_free (structure);
 595 }
 596
 597 /**
 598  * gst_caps_merge_structure:
 599  * @caps: (transfer full): the #GstCaps to merge into
 600  * @structure: (transfer full): the #GstStructure to merge
 601  *
 602  * Appends @structure to @caps if its not already expressed by @caps.
 603  *
 604  * Returns: (transfer full): the merged caps.
 605  */
 606 GstCaps *
 607 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
 608 {
 609   GstStructure *structure1;
 610   int i;
 611   gboolean unique = TRUE;
 612
 613   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 614
 615   if (G_UNLIKELY (structure == NULL))
 616     return caps;
 617
 618   /* check each structure */
 619   for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
 620     structure1 = gst_caps_get_structure_unchecked (caps, i);
 621     /* if structure is a subset of structure1, then skip it */
 622     if (gst_structure_is_subset (structure, structure1)) {
 623       unique = FALSE;
 624       break;
 625     }
 626   }
 627   if (unique) {
 628     caps = gst_caps_make_writable (caps);
 629     gst_caps_append_structure_unchecked (caps, structure);
 630   } else {
 631     gst_structure_free (structure);
 632   }
 633   return caps;
 634 }
 635
 636 /**
 637  * gst_caps_get_size:
 638  * @caps: a #GstCaps
 639  *
 640  * Gets the number of structures contained in @caps.
 641  *
 642  * Returns: the number of structures that @caps contains
 643  */
 644 guint
 645 gst_caps_get_size (const GstCaps * caps)
 646 {
 647   g_return_val_if_fail (GST_IS_CAPS (caps), 0);
 648
 649   return GST_CAPS_LEN (caps);
 650 }
 651
 652 /**
 653  * gst_caps_get_structure:
 654  * @caps: a #GstCaps
 655  * @index: the index of the structure
 656  *
 657  * Finds the structure in @caps that has the index @index, and
 658  * returns it.
 659  *
 660  * WARNING: This function takes a const GstCaps *, but returns a
 661  * non-const GstStructure *.  This is for programming convenience --
 662  * the caller should be aware that structures inside a constant
 663  * #GstCaps should not be modified. However, if you know the caps
 664  * are writable, either because you have just copied them or made
 665  * them writable with gst_caps_make_writable(), you may modify the
 666  * structure returned in the usual way, e.g. with functions like
 667  * gst_structure_set().
 668  *
 669  * You do not need to free or unref the structure returned, it
 670  * belongs to the #GstCaps.
 671  *
 672  * Returns: (transfer none): a pointer to the #GstStructure corresponding
 673  *     to @index
 674  */
 675 GstStructure *
 676 gst_caps_get_structure (const GstCaps * caps, guint index)
 677 {
 678   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 679   g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
 680
 681   return gst_caps_get_structure_unchecked (caps, index);
 682 }
 683
 684 /**
 685  * gst_caps_copy_nth:
 686  * @caps: the #GstCaps to copy
 687  * @nth: the nth structure to copy
 688  *
 689  * Creates a new #GstCaps and appends a copy of the nth structure
 690  * contained in @caps.
 691  *
 692  * Returns: (transfer full): the new #GstCaps
 693  */
 694 GstCaps *
 695 gst_caps_copy_nth (const GstCaps * caps, guint nth)
 696 {
 697   GstCaps *newcaps;
 698   GstStructure *structure;
 699
 700   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 701
 702   newcaps = gst_caps_new_empty ();
 703   GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
 704
 705   if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
 706     structure = gst_caps_get_structure_unchecked (caps, nth);
 707     gst_caps_append_structure_unchecked (newcaps,
 708         gst_structure_copy (structure));
 709   }
 710
 711   return newcaps;
 712 }
 713
 714 /**
 715  * gst_caps_truncate:
 716  * @caps: (transfer full): the #GstCaps to truncate
 717  *
 718  * Discard all but the first structure from @caps. Useful when
 719  * fixating.
 720  *
 721  * Returns: (transfer full): truncated caps
 722  */
 723 GstCaps *
 724 gst_caps_truncate (GstCaps * caps)
 725 {
 726   gint i;
 727
 728   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 729
 730   i = GST_CAPS_LEN (caps) - 1;
 731   if (i == 0)
 732     return caps;
 733
 734   caps = gst_caps_make_writable (caps);
 735   while (i > 0)
 736     gst_caps_remove_structure (caps, i--);
 737
 738   return caps;
 739 }
 740
 741 /**
 742  * gst_caps_set_value:
 743  * @caps: a writable caps
 744  * @field: name of the field to set
 745  * @value: value to set the field to
 746  *
 747  * Sets the given @field on all structures of @caps to the given @value.
 748  * This is a convenience function for calling gst_structure_set_value() on
 749  * all structures of @caps.
 750  *
 751  * Since: 0.10.26
 752  **/
 753 void
 754 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
 755 {
 756   guint i, len;
 757
 758   g_return_if_fail (GST_IS_CAPS (caps));
 759   g_return_if_fail (IS_WRITABLE (caps));
 760   g_return_if_fail (field != NULL);
 761   g_return_if_fail (G_IS_VALUE (value));
 762
 763   len = GST_CAPS_LEN (caps);
 764   for (i = 0; i < len; i++) {
 765     GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
 766     gst_structure_set_value (structure, field, value);
 767   }
 768 }
 769
 770 /**
 771  * gst_caps_set_simple_valist:
 772  * @caps: the #GstCaps to set
 773  * @field: first field to set
 774  * @varargs: additional parameters
 775  *
 776  * Sets fields in a #GstCaps.  The arguments must be passed in the same
 777  * manner as gst_structure_set(), and be NULL-terminated.
 778  * <note>Prior to GStreamer version 0.10.26, this function failed when
 779  * @caps was not simple. If your code needs to work with those versions
 780  * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
 781  * is %TRUE for @caps.</note>
 782  */
 783 void
 784 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
 785 {
 786   GValue value = { 0, };
 787
 788   g_return_if_fail (GST_IS_CAPS (caps));
 789   g_return_if_fail (IS_WRITABLE (caps));
 790
 791   while (field) {
 792     GType type;
 793     char *err;
 794
 795     type = va_arg (varargs, GType);
 796
 797     G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
 798     if (G_UNLIKELY (err)) {
 799       g_critical ("%s", err);
 800       return;
 801     }
 802
 803     gst_caps_set_value (caps, field, &value);
 804
 805     g_value_unset (&value);
 806
 807     field = va_arg (varargs, const gchar *);
 808   }
 809 }
 810
 811 /**
 812  * gst_caps_set_simple:
 813  * @caps: the #GstCaps to set
 814  * @field: first field to set
 815  * @...: additional parameters
 816  *
 817  * Sets fields in a #GstCaps.  The arguments must be passed in the same
 818  * manner as gst_structure_set(), and be NULL-terminated.
 819  * <note>Prior to GStreamer version 0.10.26, this function failed when
 820  * @caps was not simple. If your code needs to work with those versions
 821  * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
 822  * is %TRUE for @caps.</note>
 823  */
 824 void
 825 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
 826 {
 827   va_list var_args;
 828
 829   g_return_if_fail (GST_IS_CAPS (caps));
 830   g_return_if_fail (IS_WRITABLE (caps));
 831
 832   va_start (var_args, field);
 833   gst_caps_set_simple_valist (caps, field, var_args);
 834   va_end (var_args);
 835 }
 836
 837 /* tests */
 838
 839 /**
 840  * gst_caps_is_any:
 841  * @caps: the #GstCaps to test
 842  *
 843  * Determines if @caps represents any media format.
 844  *
 845  * Returns: TRUE if @caps represents any format.
 846  */
 847 gboolean
 848 gst_caps_is_any (const GstCaps * caps)
 849 {
 850   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 851
 852   return (CAPS_IS_ANY (caps));
 853 }
 854
 855 /**
 856  * gst_caps_is_empty:
 857  * @caps: the #GstCaps to test
 858  *
 859  * Determines if @caps represents no media formats.
 860  *
 861  * Returns: TRUE if @caps represents no formats.
 862  */
 863 gboolean
 864 gst_caps_is_empty (const GstCaps * caps)
 865 {
 866   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 867
 868   if (CAPS_IS_ANY (caps))
 869     return FALSE;
 870
 871   return CAPS_IS_EMPTY_SIMPLE (caps);
 872 }
 873
 874 static gboolean
 875 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
 876     gpointer unused)
 877 {
 878   return gst_value_is_fixed (value);
 879 }
 880
 881 /**
 882  * gst_caps_is_fixed:
 883  * @caps: the #GstCaps to test
 884  *
 885  * Fixed #GstCaps describe exactly one format, that is, they have exactly
 886  * one structure, and each field in the structure describes a fixed type.
 887  * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
 888  *
 889  * Returns: TRUE if @caps is fixed
 890  */
 891 gboolean
 892 gst_caps_is_fixed (const GstCaps * caps)
 893 {
 894   GstStructure *structure;
 895
 896   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 897
 898   if (GST_CAPS_LEN (caps) != 1)
 899     return FALSE;
 900
 901   structure = gst_caps_get_structure_unchecked (caps, 0);
 902
 903   return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
 904 }
 905
 906 /**
 907  * gst_caps_is_equal_fixed:
 908  * @caps1: the #GstCaps to test
 909  * @caps2: the #GstCaps to test
 910  *
 911  * Tests if two #GstCaps are equal.  This function only works on fixed
 912  * #GstCaps.
 913  *
 914  * Returns: TRUE if the arguments represent the same format
 915  */
 916 gboolean
 917 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
 918 {
 919   GstStructure *struct1, *struct2;
 920
 921   g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
 922   g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
 923
 924   struct1 = gst_caps_get_structure_unchecked (caps1, 0);
 925   struct2 = gst_caps_get_structure_unchecked (caps2, 0);
 926
 927   return gst_structure_is_equal (struct1, struct2);
 928 }
 929
 930 /**
 931  * gst_caps_is_always_compatible:
 932  * @caps1: the #GstCaps to test
 933  * @caps2: the #GstCaps to test
 934  *
 935  * A given #GstCaps structure is always compatible with another if
 936  * every media format that is in the first is also contained in the
 937  * second.  That is, @caps1 is a subset of @caps2.
 938  *
 939  * Returns: TRUE if @caps1 is a subset of @caps2.
 940  */
 941 gboolean
 942 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
 943 {
 944   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
 945   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
 946
 947   return gst_caps_is_subset (caps1, caps2);
 948 }
 949
 950 /**
 951  * gst_caps_is_subset:
 952  * @subset: a #GstCaps
 953  * @superset: a potentially greater #GstCaps
 954  *
 955  * Checks if all caps represented by @subset are also represented by @superset.
 956  * <note>This function does not work reliably if optional properties for caps
 957  * are included on one caps and omitted on the other.</note>
 958  *
 959  * Returns: %TRUE if @subset is a subset of @superset
 960  */
 961 gboolean
 962 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
 963 {
 964   GstStructure *s1, *s2;
 965   gboolean ret = TRUE;
 966   gint i, j;
 967
 968   g_return_val_if_fail (subset != NULL, FALSE);
 969   g_return_val_if_fail (superset != NULL, FALSE);
 970
 971   if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
 972     return TRUE;
 973   if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
 974     return FALSE;
 975
 976   for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
 977     for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
 978       s1 = gst_caps_get_structure_unchecked (subset, i);
 979       s2 = gst_caps_get_structure_unchecked (superset, j);
 980       if (gst_structure_is_subset (s1, s2)) {
 981         /* If we found a superset, continue with the next
 982          * subset structure */
 983         break;
 984       }
 985     }
 986     /* If we found no superset for this subset structure
 987      * we return FALSE immediately */
 988     if (j == -1) {
 989       ret = FALSE;
 990       break;
 991     }
 992   }
 993
 994   return ret;
 995 }
 996
 997 /**
 998  * gst_caps_is_subset_structure:
 999  * @caps: a #GstCaps
1000  * @structure: a potential #GstStructure subset of @caps
1001  *
1002  * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1003  * for more information.
1004  *
1005  * Returns: %TRUE if @structure is a subset of @caps
1006  *
1007  * Since: 0.10.36
1008  */
1009 gboolean
1010 gst_caps_is_subset_structure (const GstCaps * caps,
1011     const GstStructure * structure)
1012 {
1013   GstStructure *s;
1014   gint i;
1015
1016   g_return_val_if_fail (caps != NULL, FALSE);
1017   g_return_val_if_fail (structure != NULL, FALSE);
1018
1019   if (CAPS_IS_ANY (caps))
1020     return TRUE;
1021   if (CAPS_IS_EMPTY (caps))
1022     return FALSE;
1023
1024   for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1025     s = gst_caps_get_structure_unchecked (caps, i);
1026     if (gst_structure_is_subset (structure, s)) {
1027       /* If we found a superset return TRUE */
1028       return TRUE;
1029     }
1030   }
1031
1032   return FALSE;
1033 }
1034
1035 /**
1036  * gst_caps_is_equal:
1037  * @caps1: a #GstCaps
1038  * @caps2: another #GstCaps
1039  *
1040  * Checks if the given caps represent the same set of caps.
1041  * <note>This function does not work reliably if optional properties for caps
1042  * are included on one caps and omitted on the other.</note>
1043  *
1044  * This function deals correctly with passing NULL for any of the caps.
1045  *
1046  * Returns: TRUE if both caps are equal.
1047  */
1048 gboolean
1049 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1050 {
1051   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1052   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1053
1054   if (G_UNLIKELY (caps1 == caps2))
1055     return TRUE;
1056
1057   if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1058     return gst_caps_is_equal_fixed (caps1, caps2);
1059
1060   return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1061 }
1062
1063 /**
1064  * gst_caps_is_strictly_equal:
1065  * @caps1: a #GstCaps
1066  * @caps2: another #GstCaps
1067  *
1068  * Checks if the given caps are exactly the same set of caps.
1069  *
1070  * This function deals correctly with passing NULL for any of the caps.
1071  *
1072  * Returns: TRUE if both caps are strictly equal.
1073  *
1074  * Since: 0.10.36
1075  */
1076 gboolean
1077 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1078 {
1079   int i;
1080
1081   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1082   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1083
1084   if (G_UNLIKELY (caps1 == caps2))
1085     return TRUE;
1086
1087   if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1088     return FALSE;
1089
1090   for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1091     if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1092             gst_caps_get_structure_unchecked (caps2, i)))
1093       return FALSE;
1094   }
1095
1096   return TRUE;
1097 }
1098
1099 /* intersect operation */
1100
1101 /**
1102  * gst_caps_can_intersect:
1103  * @caps1: a #GstCaps to intersect
1104  * @caps2: a #GstCaps to intersect
1105  *
1106  * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1107  * be empty
1108  *
1109  * Returns: %TRUE if intersection would be not empty
1110  *
1111  * Since: 0.10.25
1112  */
1113 gboolean
1114 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1115 {
1116   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1117   guint j, k, len1, len2;
1118   GstStructure *struct1;
1119   GstStructure *struct2;
1120
1121   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1122   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1123
1124   /* caps are exactly the same pointers */
1125   if (G_UNLIKELY (caps1 == caps2))
1126     return TRUE;
1127
1128   /* empty caps on either side, return empty */
1129   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1130     return FALSE;
1131
1132   /* one of the caps is any */
1133   if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1134     return TRUE;
1135
1136   /* run zigzag on top line then right line, this preserves the caps order
1137    * much better than a simple loop.
1138    *
1139    * This algorithm zigzags over the caps structures as demonstrated in
1140    * the folowing matrix:
1141    *
1142    *          caps1                              0  1  2  3
1143    *       +-------------     total distance:  +-------------
1144    *       | 1  2  4  7                      0 | 0  1  2  3
1145    * caps2 | 3  5  8 10                      1 | 1  2  3  4
1146    *       | 6  9 11 12                      2 | 2  3  4  5
1147    *
1148    * First we iterate over the caps1 structures (top line) intersecting
1149    * the structures diagonally down, then we iterate over the caps2
1150    * structures. The result is that the intersections are ordered based on the
1151    * sum of the indexes in the list.
1152    */
1153   len1 = GST_CAPS_LEN (caps1);
1154   len2 = GST_CAPS_LEN (caps2);
1155   for (i = 0; i < len1 + len2 - 1; i++) {
1156     /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1157     j = MIN (i, len1 - 1);
1158     /* subset index stays 0 until i reaches superset->structs->len, then it
1159      * counts up from 1 to subset->structs->len - 1 */
1160     k = (i > j) ? (i - j) : 0;  /* MAX (0, i - j) */
1161
1162     /* now run the diagonal line, end condition is the left or bottom
1163      * border */
1164     while (k < len2) {
1165       struct1 = gst_caps_get_structure_unchecked (caps1, j);
1166       struct2 = gst_caps_get_structure_unchecked (caps2, k);
1167
1168       if (gst_structure_can_intersect (struct1, struct2)) {
1169         return TRUE;
1170       }
1171       /* move down left */
1172       k++;
1173       if (G_UNLIKELY (j == 0))
1174         break;                  /* so we don't roll back to G_MAXUINT */
1175       j--;
1176     }
1177   }
1178   return FALSE;
1179 }
1180
1181 static GstCaps *
1182 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1183 {
1184   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1185   guint j, k, len1, len2;
1186
1187   GstStructure *struct1;
1188   GstStructure *struct2;
1189   GstCaps *dest;
1190   GstStructure *istruct;
1191
1192   /* caps are exactly the same pointers, just copy one caps */
1193   if (G_UNLIKELY (caps1 == caps2))
1194     return gst_caps_ref (caps1);
1195
1196   /* empty caps on either side, return empty */
1197   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1198     return gst_caps_ref (GST_CAPS_NONE);
1199
1200   /* one of the caps is any, just copy the other caps */
1201   if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1202     return gst_caps_ref (caps2);
1203   if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1204     return gst_caps_ref (caps1);
1205
1206   dest = gst_caps_new_empty ();
1207
1208   /* run zigzag on top line then right line, this preserves the caps order
1209    * much better than a simple loop.
1210    *
1211    * This algorithm zigzags over the caps structures as demonstrated in
1212    * the folowing matrix:
1213    *
1214    *          caps1
1215    *       +-------------
1216    *       | 1  2  4  7
1217    * caps2 | 3  5  8 10
1218    *       | 6  9 11 12
1219    *
1220    * First we iterate over the caps1 structures (top line) intersecting
1221    * the structures diagonally down, then we iterate over the caps2
1222    * structures.
1223    */
1224   len1 = GST_CAPS_LEN (caps1);
1225   len2 = GST_CAPS_LEN (caps2);
1226   for (i = 0; i < len1 + len2 - 1; i++) {
1227     /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1228     j = MIN (i, len1 - 1);
1229     /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1230      * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1231     k = (i > j) ? (i - j) : 0;  /* MAX (0, i - j) */
1232
1233     /* now run the diagonal line, end condition is the left or bottom
1234      * border */
1235     while (k < len2) {
1236       struct1 = gst_caps_get_structure_unchecked (caps1, j);
1237       struct2 = gst_caps_get_structure_unchecked (caps2, k);
1238
1239       istruct = gst_structure_intersect (struct1, struct2);
1240
1241       dest = gst_caps_merge_structure (dest, istruct);
1242       /* move down left */
1243       k++;
1244       if (G_UNLIKELY (j == 0))
1245         break;                  /* so we don't roll back to G_MAXUINT */
1246       j--;
1247     }
1248   }
1249   return dest;
1250 }
1251
1252 /**
1253  * gst_caps_intersect_first:
1254  * @caps1: a #GstCaps to intersect
1255  * @caps2: a #GstCaps to intersect
1256  *
1257  * Creates a new #GstCaps that contains all the formats that are common
1258  * to both @caps1 and @caps2.
1259  *
1260  * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1261  * fashion as @caps1.
1262  *
1263  * Returns: the new #GstCaps
1264  */
1265 static GstCaps *
1266 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1267 {
1268   guint i;
1269   guint j, len1, len2;
1270
1271   GstStructure *struct1;
1272   GstStructure *struct2;
1273   GstCaps *dest;
1274   GstStructure *istruct;
1275
1276   /* caps are exactly the same pointers, just copy one caps */
1277   if (G_UNLIKELY (caps1 == caps2))
1278     return gst_caps_ref (caps1);
1279
1280   /* empty caps on either side, return empty */
1281   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1282     return gst_caps_ref (GST_CAPS_NONE);
1283
1284   /* one of the caps is any, just copy the other caps */
1285   if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1286     return gst_caps_ref (caps2);
1287   if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1288     return gst_caps_ref (caps1);
1289
1290   dest = gst_caps_new_empty ();
1291
1292   len1 = GST_CAPS_LEN (caps1);
1293   len2 = GST_CAPS_LEN (caps2);
1294   for (i = 0; i < len1; i++) {
1295     struct1 = gst_caps_get_structure_unchecked (caps1, i);
1296     for (j = 0; j < len2; j++) {
1297       struct2 = gst_caps_get_structure_unchecked (caps2, j);
1298       istruct = gst_structure_intersect (struct1, struct2);
1299       if (istruct)
1300         dest = gst_caps_merge_structure (dest, istruct);
1301     }
1302   }
1303
1304   return dest;
1305 }
1306
1307 /**
1308  * gst_caps_intersect_full:
1309  * @caps1: a #GstCaps to intersect
1310  * @caps2: a #GstCaps to intersect
1311  * @mode: The intersection algorithm/mode to use
1312  *
1313  * Creates a new #GstCaps that contains all the formats that are common
1314  * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1315  * used.
1316  *
1317  * Returns: the new #GstCaps
1318  * Since: 0.10.33
1319  */
1320 GstCaps *
1321 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1322     GstCapsIntersectMode mode)
1323 {
1324   g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1325   g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1326
1327   switch (mode) {
1328     case GST_CAPS_INTERSECT_FIRST:
1329       return gst_caps_intersect_first (caps1, caps2);
1330     default:
1331       g_warning ("Unknown caps intersect mode: %d", mode);
1332       /* fallthrough */
1333     case GST_CAPS_INTERSECT_ZIG_ZAG:
1334       return gst_caps_intersect_zig_zag (caps1, caps2);
1335   }
1336 }
1337
1338 /**
1339  * gst_caps_intersect:
1340  * @caps1: a #GstCaps to intersect
1341  * @caps2: a #GstCaps to intersect
1342  *
1343  * Creates a new #GstCaps that contains all the formats that are common
1344  * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1345  *
1346  * Returns: the new #GstCaps
1347  */
1348 GstCaps *
1349 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1350 {
1351   return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1352 }
1353
1354
1355 /* subtract operation */
1356
1357 typedef struct
1358 {
1359   const GstStructure *subtract_from;
1360   GSList *put_into;
1361 }
1362 SubtractionEntry;
1363
1364 static gboolean
1365 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1366     gpointer user_data)
1367 {
1368   SubtractionEntry *e = user_data;
1369   GValue subtraction = { 0, };
1370   const GValue *other;
1371   GstStructure *structure;
1372
1373   other = gst_structure_id_get_value (e->subtract_from, field_id);
1374   if (!other) {
1375     return FALSE;
1376   }
1377   if (!gst_value_subtract (&subtraction, other, value))
1378     return TRUE;
1379   if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1380     g_value_unset (&subtraction);
1381     return FALSE;
1382   } else {
1383     structure = gst_structure_copy (e->subtract_from);
1384     gst_structure_id_set_value (structure, field_id, &subtraction);
1385     g_value_unset (&subtraction);
1386     e->put_into = g_slist_prepend (e->put_into, structure);
1387     return TRUE;
1388   }
1389 }
1390
1391 static gboolean
1392 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1393     const GstStructure * subtrahend)
1394 {
1395   SubtractionEntry e;
1396   gboolean ret;
1397
1398   e.subtract_from = minuend;
1399   e.put_into = NULL;
1400
1401   ret = gst_structure_foreach ((GstStructure *) subtrahend,
1402       gst_caps_structure_subtract_field, &e);
1403   if (ret) {
1404     *into = e.put_into;
1405   } else {
1406     GSList *walk;
1407
1408     for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1409       gst_structure_free (walk->data);
1410     }
1411     g_slist_free (e.put_into);
1412   }
1413   return ret;
1414 }
1415
1416 /**
1417  * gst_caps_subtract:
1418  * @minuend: #GstCaps to subtract from
1419  * @subtrahend: #GstCaps to subtract
1420  *
1421  * Subtracts the @subtrahend from the @minuend.
1422  * <note>This function does not work reliably if optional properties for caps
1423  * are included on one caps and omitted on the other.</note>
1424  *
1425  * Returns: the resulting caps
1426  */
1427 GstCaps *
1428 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1429 {
1430   guint i, j, sublen;
1431   GstStructure *min;
1432   GstStructure *sub;
1433   GstCaps *dest = NULL, *src;
1434
1435   g_return_val_if_fail (minuend != NULL, NULL);
1436   g_return_val_if_fail (subtrahend != NULL, NULL);
1437
1438   if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1439     return gst_caps_new_empty ();
1440   }
1441   if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1442     return gst_caps_ref (minuend);
1443
1444   /* FIXME: Do we want this here or above?
1445      The reason we need this is that there is no definition about what
1446      ANY means for specific types, so it's not possible to reduce ANY partially
1447      You can only remove everything or nothing and that is done above.
1448      Note: there's a test that checks this behaviour. */
1449   g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1450   sublen = GST_CAPS_LEN (subtrahend);
1451   g_assert (sublen > 0);
1452
1453   src = _gst_caps_copy (minuend);
1454   for (i = 0; i < sublen; i++) {
1455     guint srclen;
1456
1457     sub = gst_caps_get_structure_unchecked (subtrahend, i);
1458     if (dest) {
1459       gst_caps_unref (src);
1460       src = dest;
1461     }
1462     dest = gst_caps_new_empty ();
1463     srclen = GST_CAPS_LEN (src);
1464     for (j = 0; j < srclen; j++) {
1465       min = gst_caps_get_structure_unchecked (src, j);
1466       if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1467         GSList *list;
1468
1469         if (gst_caps_structure_subtract (&list, min, sub)) {
1470           GSList *walk;
1471
1472           for (walk = list; walk; walk = g_slist_next (walk)) {
1473             gst_caps_append_structure_unchecked (dest,
1474                 (GstStructure *) walk->data);
1475           }
1476           g_slist_free (list);
1477         } else {
1478           gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1479         }
1480       } else {
1481         gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1482       }
1483     }
1484     if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1485       gst_caps_unref (src);
1486       return dest;
1487     }
1488   }
1489
1490   gst_caps_unref (src);
1491   dest = gst_caps_simplify (dest);
1492   return dest;
1493 }
1494
1495 /* normalize/simplify operations */
1496
1497 typedef struct _NormalizeForeach
1498 {
1499   GstCaps *caps;
1500   GstStructure *structure;
1501   gboolean writable;
1502 }
1503 NormalizeForeach;
1504
1505 static gboolean
1506 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1507 {
1508   NormalizeForeach *nf = (NormalizeForeach *) ptr;
1509   GValue val = { 0 };
1510   guint i;
1511
1512   if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1513     guint len = gst_value_list_get_size (value);
1514     for (i = 1; i < len; i++) {
1515       const GValue *v = gst_value_list_get_value (value, i);
1516       GstStructure *structure = gst_structure_copy (nf->structure);
1517
1518       gst_structure_id_set_value (structure, field_id, v);
1519       if (G_UNLIKELY (!nf->writable)) {
1520         nf->caps = gst_caps_make_writable (nf->caps);
1521         nf->writable = TRUE;
1522       }
1523       gst_caps_append_structure_unchecked (nf->caps, structure);
1524     }
1525
1526     gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1527     gst_structure_id_set_value (nf->structure, field_id, &val);
1528     g_value_unset (&val);
1529
1530     return FALSE;
1531   }
1532   return TRUE;
1533 }
1534
1535 /**
1536  * gst_caps_normalize:
1537  * @caps: (transfer full): a #GstCaps to normalize
1538  *
1539  * Returns a #GstCaps that represents the same set of formats as
1540  * @caps, but contains no lists.  Each list is expanded into separate
1541  * @GstStructures.
1542  *
1543  * This function takes ownership of @caps.
1544  *
1545  * Returns: (transfer full): the normalized #GstCaps
1546  */
1547 GstCaps *
1548 gst_caps_normalize (GstCaps * caps)
1549 {
1550   NormalizeForeach nf;
1551   guint i;
1552
1553   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1554
1555   nf.caps = caps;
1556   nf.writable = FALSE;
1557
1558   for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1559     nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1560
1561     while (!gst_structure_foreach (nf.structure,
1562             gst_caps_normalize_foreach, &nf));
1563   }
1564
1565   return nf.caps;
1566 }
1567
1568 static gint
1569 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1570 {
1571   gint ret;
1572   const GstStructure *struct1 = *((const GstStructure **) one);
1573   const GstStructure *struct2 = *((const GstStructure **) two);
1574
1575   /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1576      So what's the best way? */
1577   ret = strcmp (gst_structure_get_name (struct1),
1578       gst_structure_get_name (struct2));
1579   if (ret)
1580     return ret;
1581
1582   return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1583 }
1584
1585 typedef struct
1586 {
1587   GQuark name;
1588   GValue value;
1589   GstStructure *compare;
1590 }
1591 UnionField;
1592
1593 static gboolean
1594 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1595     gpointer user_data)
1596 {
1597   UnionField *u = user_data;
1598   const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1599
1600   if (!val) {
1601     if (u->name)
1602       g_value_unset (&u->value);
1603     return FALSE;
1604   }
1605   if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1606     return TRUE;
1607   if (u->name) {
1608     g_value_unset (&u->value);
1609     return FALSE;
1610   }
1611   u->name = field_id;
1612   gst_value_union (&u->value, val, value);
1613   return TRUE;
1614 }
1615
1616 static gboolean
1617 gst_caps_structure_simplify (GstStructure ** result,
1618     GstStructure * simplify, GstStructure * compare)
1619 {
1620   GSList *list;
1621   UnionField field = { 0, {0,}, NULL };
1622
1623   /* try to subtract to get a real subset */
1624   if (gst_caps_structure_subtract (&list, simplify, compare)) {
1625     if (list == NULL) {         /* no result */
1626       *result = NULL;
1627       return TRUE;
1628     } else if (list->next == NULL) {    /* one result */
1629       *result = list->data;
1630       g_slist_free (list);
1631       return TRUE;
1632     } else {                    /* multiple results */
1633       g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1634       g_slist_free (list);
1635       list = NULL;
1636     }
1637   }
1638
1639   /* try to union both structs */
1640   field.compare = compare;
1641   if (gst_structure_foreach (simplify,
1642           gst_caps_structure_figure_out_union, &field)) {
1643     gboolean ret = FALSE;
1644
1645     /* now we know all of simplify's fields are the same in compare
1646      * but at most one field: field.name */
1647     if (G_IS_VALUE (&field.value)) {
1648       if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1649         gst_structure_id_set_value (compare, field.name, &field.value);
1650         *result = NULL;
1651         ret = TRUE;
1652       }
1653       g_value_unset (&field.value);
1654     } else if (gst_structure_n_fields (simplify) <=
1655         gst_structure_n_fields (compare)) {
1656       /* compare is just more specific, will be optimized away later */
1657       /* FIXME: do this here? */
1658       GST_LOG ("found a case that will be optimized later.");
1659     } else {
1660       gchar *one = gst_structure_to_string (simplify);
1661       gchar *two = gst_structure_to_string (compare);
1662
1663       GST_ERROR
1664           ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1665           one, two);
1666       g_free (one);
1667       g_free (two);
1668     }
1669     return ret;
1670   }
1671
1672   return FALSE;
1673 }
1674
1675 static void
1676 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1677     GstStructure * new, gint i)
1678 {
1679   gst_structure_set_parent_refcount (old, NULL);
1680   gst_structure_free (old);
1681   gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1682   g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1683 }
1684
1685 /**
1686  * gst_caps_simplify:
1687  * @caps: (transfer full): a #GstCaps to simplify
1688  *
1689  * Converts the given @caps into a representation that represents the
1690  * same set of formats, but in a simpler form.  Component structures that are
1691  * identical are merged.  Component structures that have values that can be
1692  * merged are also merged.
1693  *
1694  * This method does not preserve the original order of @caps.
1695  *
1696  * Returns: The simplified caps.
1697  */
1698 GstCaps *
1699 gst_caps_simplify (GstCaps * caps)
1700 {
1701   GstStructure *simplify, *compare, *result = NULL;
1702   gint i, j, start;
1703
1704   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1705
1706   start = GST_CAPS_LEN (caps) - 1;
1707   /* one caps, already as simple as can be */
1708   if (start == 0)
1709     return caps;
1710
1711   caps = gst_caps_make_writable (caps);
1712
1713   g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1714
1715   for (i = start; i >= 0; i--) {
1716     simplify = gst_caps_get_structure_unchecked (caps, i);
1717     compare = gst_caps_get_structure_unchecked (caps, start);
1718     if (gst_structure_get_name_id (simplify) !=
1719         gst_structure_get_name_id (compare))
1720       start = i;
1721     for (j = start; j >= 0; j--) {
1722       if (j == i)
1723         continue;
1724       compare = gst_caps_get_structure_unchecked (caps, j);
1725       if (gst_structure_get_name_id (simplify) !=
1726           gst_structure_get_name_id (compare)) {
1727         break;
1728       }
1729       if (gst_caps_structure_simplify (&result, simplify, compare)) {
1730         if (result) {
1731           gst_caps_switch_structures (caps, simplify, result, i);
1732           simplify = result;
1733         } else {
1734           gst_caps_remove_structure (caps, i);
1735           start--;
1736           break;
1737         }
1738       }
1739     }
1740   }
1741   return caps;
1742 }
1743
1744 /**
1745  * gst_caps_fixate:
1746  * @caps: (transfer full): a #GstCaps to fixate
1747  *
1748  * Modifies the given @caps into a representation with only fixed
1749  * values. First the caps will be truncated and then the first structure will be
1750  * fixated with gst_structure_fixate().
1751  *
1752  * Returns: (transfer full): the fixated caps
1753  */
1754 GstCaps *
1755 gst_caps_fixate (GstCaps * caps)
1756 {
1757   GstStructure *s;
1758
1759   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1760
1761   /* default fixation */
1762   caps = gst_caps_truncate (caps);
1763   caps = gst_caps_make_writable (caps);
1764   s = gst_caps_get_structure (caps, 0);
1765   gst_structure_fixate (s);
1766
1767   return caps;
1768 }
1769
1770 /* utility */
1771
1772 /**
1773  * gst_caps_to_string:
1774  * @caps: a #GstCaps
1775  *
1776  * Converts @caps to a string representation.  This string representation
1777  * can be converted back to a #GstCaps by gst_caps_from_string().
1778  *
1779  * For debugging purposes its easier to do something like this:
1780  * |[
1781  * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1782  * ]|
1783  * This prints the caps in human readble form.
1784  *
1785  * Returns: (transfer full): a newly allocated string representing @caps.
1786  */
1787 gchar *
1788 gst_caps_to_string (const GstCaps * caps)
1789 {
1790   guint i, slen, clen;
1791   GString *s;
1792
1793   /* NOTE:  This function is potentially called by the debug system,
1794    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1795    * should be careful to avoid recursion.  This includes any functions
1796    * called by gst_caps_to_string.  In particular, calls should
1797    * not use the GST_PTR_FORMAT extension.  */
1798
1799   if (caps == NULL) {
1800     return g_strdup ("NULL");
1801   }
1802   if (CAPS_IS_ANY (caps)) {
1803     return g_strdup ("ANY");
1804   }
1805   if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1806     return g_strdup ("EMPTY");
1807   }
1808
1809   /* estimate a rough string length to avoid unnecessary reallocs in GString */
1810   slen = 0;
1811   clen = GST_CAPS_LEN (caps);
1812   for (i = 0; i < clen; i++) {
1813     slen +=
1814         STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1815             i));
1816   }
1817
1818   s = g_string_sized_new (slen);
1819   for (i = 0; i < clen; i++) {
1820     GstStructure *structure;
1821
1822     if (i > 0) {
1823       /* ';' is now added by gst_structure_to_string */
1824       g_string_append_c (s, ' ');
1825     }
1826
1827     structure = gst_caps_get_structure_unchecked (caps, i);
1828     priv_gst_structure_append_to_gstring (structure, s);
1829   }
1830   if (s->len && s->str[s->len - 1] == ';') {
1831     /* remove latest ';' */
1832     s->str[--s->len] = '\0';
1833   }
1834   return g_string_free (s, FALSE);
1835 }
1836
1837 static gboolean
1838 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1839 {
1840   GstStructure *structure;
1841   gchar *s;
1842
1843   if (strcmp ("ANY", string) == 0) {
1844     GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1845     return TRUE;
1846   }
1847   if (strcmp ("EMPTY", string) == 0) {
1848     return TRUE;
1849   }
1850
1851   structure = gst_structure_from_string (string, &s);
1852   if (structure == NULL) {
1853     return FALSE;
1854   }
1855   gst_caps_append_structure_unchecked (caps, structure);
1856
1857   do {
1858
1859     while (g_ascii_isspace (*s))
1860       s++;
1861     if (*s == '\0') {
1862       break;
1863     }
1864     structure = gst_structure_from_string (s, &s);
1865     if (structure == NULL) {
1866       return FALSE;
1867     }
1868     gst_caps_append_structure_unchecked (caps, structure);
1869
1870   } while (TRUE);
1871
1872   return TRUE;
1873 }
1874
1875 /**
1876  * gst_caps_from_string:
1877  * @string: a string to convert to #GstCaps
1878  *
1879  * Converts @caps from a string representation.
1880  *
1881  * Returns: (transfer full): a newly allocated #GstCaps
1882  */
1883 GstCaps *
1884 gst_caps_from_string (const gchar * string)
1885 {
1886   GstCaps *caps;
1887
1888   g_return_val_if_fail (string, FALSE);
1889
1890   caps = gst_caps_new_empty ();
1891   if (gst_caps_from_string_inplace (caps, string)) {
1892     return caps;
1893   } else {
1894     gst_caps_unref (caps);
1895     return NULL;
1896   }
1897 }
1898
1899 static void
1900 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1901 {
1902   g_return_if_fail (G_IS_VALUE (src_value));
1903   g_return_if_fail (G_IS_VALUE (dest_value));
1904   g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1905   g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1906       || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1907
1908   g_value_take_string (dest_value,
1909       gst_caps_to_string (gst_value_get_caps (src_value)));
1910 }