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