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  * <note>This function does not work reliably if optional properties for caps
1153  * are included on one caps and omitted on the other.</note>
1154  *
1155  * Returns: %TRUE if @subset is a subset of @superset
1156  */
1157 gboolean
1158 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1159 {
1160   GstStructure *s1, *s2;
1161   GstCapsFeatures *f1, *f2;
1162   gboolean ret = TRUE;
1163   gint i, j;
1164
1165   g_return_val_if_fail (subset != NULL, FALSE);
1166   g_return_val_if_fail (superset != NULL, FALSE);
1167
1168   if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1169     return TRUE;
1170   if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1171     return FALSE;
1172
1173   for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
1174     for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
1175       s1 = gst_caps_get_structure_unchecked (subset, i);
1176       f1 = gst_caps_get_features_unchecked (subset, i);
1177       if (!f1)
1178         f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1179       s2 = gst_caps_get_structure_unchecked (superset, j);
1180       f2 = gst_caps_get_features_unchecked (superset, j);
1181       if (!f2)
1182         f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1183       if (gst_structure_is_subset (s1, s2) &&
1184           gst_caps_features_is_equal (f1, f2)) {
1185         /* If we found a superset, continue with the next
1186          * subset structure */
1187         break;
1188       }
1189     }
1190     /* If we found no superset for this subset structure
1191      * we return FALSE immediately */
1192     if (j == -1) {
1193       ret = FALSE;
1194       break;
1195     }
1196   }
1197
1198   return ret;
1199 }
1200
1201 /**
1202  * gst_caps_is_subset_structure:
1203  * @caps: a #GstCaps
1204  * @structure: a potential #GstStructure subset of @caps
1205  *
1206  * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1207  * for more information.
1208  *
1209  * Returns: %TRUE if @structure is a subset of @caps
1210  */
1211 gboolean
1212 gst_caps_is_subset_structure (const GstCaps * caps,
1213     const GstStructure * structure)
1214 {
1215   GstStructure *s;
1216   gint i;
1217
1218   g_return_val_if_fail (caps != NULL, FALSE);
1219   g_return_val_if_fail (structure != NULL, FALSE);
1220
1221   if (CAPS_IS_ANY (caps))
1222     return TRUE;
1223   if (CAPS_IS_EMPTY (caps))
1224     return FALSE;
1225
1226   for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1227     s = gst_caps_get_structure_unchecked (caps, i);
1228     if (gst_structure_is_subset (structure, s)) {
1229       /* If we found a superset return TRUE */
1230       return TRUE;
1231     }
1232   }
1233
1234   return FALSE;
1235 }
1236
1237 /**
1238  * gst_caps_is_subset_structure_full:
1239  * @caps: a #GstCaps
1240  * @structure: a potential #GstStructure subset of @caps
1241  * @features: (allow-none): a #GstCapsFeatures for @structure
1242  *
1243  * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1244  * for more information.
1245  *
1246  * Returns: %TRUE if @structure is a subset of @caps
1247  */
1248 gboolean
1249 gst_caps_is_subset_structure_full (const GstCaps * caps,
1250     const GstStructure * structure, const GstCapsFeatures * features)
1251 {
1252   GstStructure *s;
1253   GstCapsFeatures *f;
1254   gint i;
1255
1256   g_return_val_if_fail (caps != NULL, FALSE);
1257   g_return_val_if_fail (structure != NULL, FALSE);
1258
1259   if (CAPS_IS_ANY (caps))
1260     return TRUE;
1261   if (CAPS_IS_EMPTY (caps))
1262     return FALSE;
1263
1264   if (!features)
1265     features = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1266
1267   for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1268     s = gst_caps_get_structure_unchecked (caps, i);
1269     f = gst_caps_get_features_unchecked (caps, i);
1270     if (!f)
1271       f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1272     if (gst_structure_is_subset (structure, s) &&
1273         gst_caps_features_is_equal (features, f)) {
1274       /* If we found a superset return TRUE */
1275       return TRUE;
1276     }
1277   }
1278
1279   return FALSE;
1280 }
1281
1282 /**
1283  * gst_caps_is_equal:
1284  * @caps1: a #GstCaps
1285  * @caps2: another #GstCaps
1286  *
1287  * Checks if the given caps represent the same set of caps.
1288  * <note>This function does not work reliably if optional properties for caps
1289  * are included on one caps and omitted on the other.</note>
1290  *
1291  * Returns: TRUE if both caps are equal.
1292  */
1293 gboolean
1294 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1295 {
1296   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1297   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1298
1299   if (G_UNLIKELY (caps1 == caps2))
1300     return TRUE;
1301
1302   if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1303     return gst_caps_is_equal_fixed (caps1, caps2);
1304
1305   return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1306 }
1307
1308 /**
1309  * gst_caps_is_strictly_equal:
1310  * @caps1: a #GstCaps
1311  * @caps2: another #GstCaps
1312  *
1313  * Checks if the given caps are exactly the same set of caps.
1314  *
1315  * Returns: TRUE if both caps are strictly equal.
1316  */
1317 gboolean
1318 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1319 {
1320   int i;
1321   GstStructure *s1, *s2;
1322   GstCapsFeatures *f1, *f2;
1323
1324   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1325   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1326
1327   if (G_UNLIKELY (caps1 == caps2))
1328     return TRUE;
1329
1330   if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1331     return FALSE;
1332
1333   for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1334     s1 = gst_caps_get_structure_unchecked (caps1, i);
1335     f1 = gst_caps_get_features_unchecked (caps1, i);
1336     if (!f1)
1337       f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1338     s2 = gst_caps_get_structure_unchecked (caps2, i);
1339     f2 = gst_caps_get_features_unchecked (caps2, i);
1340     if (!f2)
1341       f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1342
1343     if (!gst_structure_is_equal (s1, s2)
1344         || !gst_caps_features_is_equal (f1, f2))
1345       return FALSE;
1346   }
1347
1348   return TRUE;
1349 }
1350
1351 /* intersect operation */
1352
1353 /**
1354  * gst_caps_can_intersect:
1355  * @caps1: a #GstCaps to intersect
1356  * @caps2: a #GstCaps to intersect
1357  *
1358  * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1359  * be empty
1360  *
1361  * Returns: %TRUE if intersection would be not empty
1362  */
1363 gboolean
1364 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1365 {
1366   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1367   guint j, k, len1, len2;
1368   GstStructure *struct1;
1369   GstStructure *struct2;
1370   GstCapsFeatures *features1;
1371   GstCapsFeatures *features2;
1372
1373   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1374   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1375
1376   /* caps are exactly the same pointers */
1377   if (G_UNLIKELY (caps1 == caps2))
1378     return TRUE;
1379
1380   /* empty caps on either side, return empty */
1381   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1382     return FALSE;
1383
1384   /* one of the caps is any */
1385   if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1386     return TRUE;
1387
1388   /* run zigzag on top line then right line, this preserves the caps order
1389    * much better than a simple loop.
1390    *
1391    * This algorithm zigzags over the caps structures as demonstrated in
1392    * the following matrix:
1393    *
1394    *          caps1                              0  1  2  3
1395    *       +-------------     total distance:  +-------------
1396    *       | 1  2  4  7                      0 | 0  1  2  3
1397    * caps2 | 3  5  8 10                      1 | 1  2  3  4
1398    *       | 6  9 11 12                      2 | 2  3  4  5
1399    *
1400    * First we iterate over the caps1 structures (top line) intersecting
1401    * the structures diagonally down, then we iterate over the caps2
1402    * structures. The result is that the intersections are ordered based on the
1403    * sum of the indexes in the list.
1404    */
1405   len1 = GST_CAPS_LEN (caps1);
1406   len2 = GST_CAPS_LEN (caps2);
1407   for (i = 0; i < len1 + len2 - 1; i++) {
1408     /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1409     j = MIN (i, len1 - 1);
1410     /* subset index stays 0 until i reaches superset->structs->len, then it
1411      * counts up from 1 to subset->structs->len - 1 */
1412     k = (i > j) ? (i - j) : 0;  /* MAX (0, i - j) */
1413     /* now run the diagonal line, end condition is the left or bottom
1414      * border */
1415     while (k < len2) {
1416       struct1 = gst_caps_get_structure_unchecked (caps1, j);
1417       features1 = gst_caps_get_features_unchecked (caps1, j);
1418       if (!features1)
1419         features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1420       struct2 = gst_caps_get_structure_unchecked (caps2, k);
1421       features2 = gst_caps_get_features_unchecked (caps2, k);
1422       if (!features2)
1423         features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1424       if (gst_structure_can_intersect (struct1, struct2) &&
1425           gst_caps_features_is_equal (features1, features2)) {
1426         return TRUE;
1427       }
1428       /* move down left */
1429       k++;
1430       if (G_UNLIKELY (j == 0))
1431         break;                  /* so we don't roll back to G_MAXUINT */
1432       j--;
1433     }
1434   }
1435
1436   return FALSE;
1437 }
1438
1439 static GstCaps *
1440 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1441 {
1442   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1443   guint j, k, len1, len2;
1444   GstStructure *struct1;
1445   GstStructure *struct2;
1446   GstCapsFeatures *features1;
1447   GstCapsFeatures *features2;
1448   GstCaps *dest;
1449   GstStructure *istruct;
1450
1451   /* caps are exactly the same pointers, just copy one caps */
1452   if (G_UNLIKELY (caps1 == caps2))
1453     return gst_caps_ref (caps1);
1454
1455   /* empty caps on either side, return empty */
1456   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1457     return gst_caps_ref (GST_CAPS_NONE);
1458
1459   /* one of the caps is any, just copy the other caps */
1460   if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1461     return gst_caps_ref (caps2);
1462
1463   if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1464     return gst_caps_ref (caps1);
1465
1466   dest = gst_caps_new_empty ();
1467   /* run zigzag on top line then right line, this preserves the caps order
1468    * much better than a simple loop.
1469    *
1470    * This algorithm zigzags over the caps structures as demonstrated in
1471    * the following matrix:
1472    *
1473    *          caps1
1474    *       +-------------
1475    *       | 1  2  4  7
1476    * caps2 | 3  5  8 10
1477    *       | 6  9 11 12
1478    *
1479    * First we iterate over the caps1 structures (top line) intersecting
1480    * the structures diagonally down, then we iterate over the caps2
1481    * structures.
1482    */
1483   len1 = GST_CAPS_LEN (caps1);
1484   len2 = GST_CAPS_LEN (caps2);
1485   for (i = 0; i < len1 + len2 - 1; i++) {
1486     /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1487     j = MIN (i, len1 - 1);
1488     /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1489      * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1490     k = (i > j) ? (i - j) : 0;  /* MAX (0, i - j) */
1491     /* now run the diagonal line, end condition is the left or bottom
1492      * border */
1493     while (k < len2) {
1494       struct1 = gst_caps_get_structure_unchecked (caps1, j);
1495       features1 = gst_caps_get_features_unchecked (caps1, j);
1496       if (!features1)
1497         features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1498       struct2 = gst_caps_get_structure_unchecked (caps2, k);
1499       features2 = gst_caps_get_features_unchecked (caps2, k);
1500       if (!features2)
1501         features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1502       istruct = gst_structure_intersect (struct1, struct2);
1503       if (istruct && gst_caps_features_is_equal (features1, features2))
1504         dest =
1505             gst_caps_merge_structure_full (dest, istruct,
1506             gst_caps_features_copy_conditional (features1));
1507       /* move down left */
1508       k++;
1509       if (G_UNLIKELY (j == 0))
1510         break;                  /* so we don't roll back to G_MAXUINT */
1511       j--;
1512     }
1513   }
1514   return dest;
1515 }
1516
1517 /**
1518  * gst_caps_intersect_first:
1519  * @caps1: a #GstCaps to intersect
1520  * @caps2: a #GstCaps to intersect
1521  *
1522  * Creates a new #GstCaps that contains all the formats that are common
1523  * to both @caps1 and @caps2.
1524  *
1525  * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1526  * fashion as @caps1.
1527  *
1528  * Returns: the new #GstCaps
1529  */
1530 static GstCaps *
1531 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1532 {
1533   guint i;
1534   guint j, len1, len2;
1535   GstStructure *struct1;
1536   GstStructure *struct2;
1537   GstCapsFeatures *features1;
1538   GstCapsFeatures *features2;
1539   GstCaps *dest;
1540   GstStructure *istruct;
1541
1542   /* caps are exactly the same pointers, just copy one caps */
1543   if (G_UNLIKELY (caps1 == caps2))
1544     return gst_caps_ref (caps1);
1545
1546   /* empty caps on either side, return empty */
1547   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1548     return gst_caps_ref (GST_CAPS_NONE);
1549
1550   /* one of the caps is any, just copy the other caps */
1551   if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1552     return gst_caps_ref (caps2);
1553
1554   if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1555     return gst_caps_ref (caps1);
1556
1557   dest = gst_caps_new_empty ();
1558   len1 = GST_CAPS_LEN (caps1);
1559   len2 = GST_CAPS_LEN (caps2);
1560   for (i = 0; i < len1; i++) {
1561     struct1 = gst_caps_get_structure_unchecked (caps1, i);
1562     features1 = gst_caps_get_features_unchecked (caps1, i);
1563     if (!features1)
1564       features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1565     for (j = 0; j < len2; j++) {
1566       struct2 = gst_caps_get_structure_unchecked (caps2, j);
1567       features2 = gst_caps_get_features_unchecked (caps2, j);
1568       if (!features2)
1569         features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1570       istruct = gst_structure_intersect (struct1, struct2);
1571       if (istruct && gst_caps_features_is_equal (features1, features2))
1572         dest = gst_caps_merge_structure (dest, istruct);
1573     }
1574   }
1575
1576   return dest;
1577 }
1578
1579 /**
1580  * gst_caps_intersect_full:
1581  * @caps1: a #GstCaps to intersect
1582  * @caps2: a #GstCaps to intersect
1583  * @mode: The intersection algorithm/mode to use
1584  *
1585  * Creates a new #GstCaps that contains all the formats that are common
1586  * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1587  * used.
1588  *
1589  * Returns: the new #GstCaps
1590  */
1591 GstCaps *
1592 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1593     GstCapsIntersectMode mode)
1594 {
1595   g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1596   g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1597
1598   switch (mode) {
1599     case GST_CAPS_INTERSECT_FIRST:
1600       return gst_caps_intersect_first (caps1, caps2);
1601     default:
1602       g_warning ("Unknown caps intersect mode: %d", mode);
1603       /* fallthrough */
1604     case GST_CAPS_INTERSECT_ZIG_ZAG:
1605       return gst_caps_intersect_zig_zag (caps1, caps2);
1606   }
1607 }
1608
1609 /**
1610  * gst_caps_intersect:
1611  * @caps1: a #GstCaps to intersect
1612  * @caps2: a #GstCaps to intersect
1613  *
1614  * Creates a new #GstCaps that contains all the formats that are common
1615  * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1616  *
1617  * Returns: the new #GstCaps
1618  */
1619 GstCaps *
1620 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1621 {
1622   return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1623 }
1624
1625 /* subtract operation */
1626
1627 typedef struct
1628 {
1629   const GstStructure *subtract_from;
1630   GSList *put_into;
1631 } SubtractionEntry;
1632
1633 static gboolean
1634 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1635     gpointer user_data)
1636 {
1637   SubtractionEntry *e = user_data;
1638   GValue subtraction = { 0, };
1639   const GValue *other;
1640   GstStructure *structure;
1641
1642   other = gst_structure_id_get_value (e->subtract_from, field_id);
1643
1644   if (!other) {
1645     return FALSE;
1646   }
1647
1648   if (!gst_value_subtract (&subtraction, other, value))
1649     return TRUE;
1650
1651   if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1652     g_value_unset (&subtraction);
1653     return FALSE;
1654   } else {
1655     structure = gst_structure_copy (e->subtract_from);
1656     gst_structure_id_take_value (structure, field_id, &subtraction);
1657     e->put_into = g_slist_prepend (e->put_into, structure);
1658     return TRUE;
1659   }
1660 }
1661
1662 static gboolean
1663 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1664     const GstStructure * subtrahend)
1665 {
1666   SubtractionEntry e;
1667   gboolean ret;
1668
1669   e.subtract_from = minuend;
1670   e.put_into = NULL;
1671   ret = gst_structure_foreach ((GstStructure *) subtrahend,
1672       gst_caps_structure_subtract_field, &e);
1673
1674   if (ret) {
1675     *into = e.put_into;
1676   } else {
1677     GSList *walk;
1678
1679     for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1680       gst_structure_free (walk->data);
1681     }
1682     g_slist_free (e.put_into);
1683   }
1684
1685   return ret;
1686 }
1687
1688 /**
1689  * gst_caps_subtract:
1690  * @minuend: #GstCaps to subtract from
1691  * @subtrahend: #GstCaps to subtract
1692  *
1693  * Subtracts the @subtrahend from the @minuend.
1694  * <note>This function does not work reliably if optional properties for caps
1695  * are included on one caps and omitted on the other.</note>
1696  *
1697  * Returns: the resulting caps
1698  */
1699 GstCaps *
1700 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1701 {
1702   guint i, j, sublen;
1703   GstStructure *min;
1704   GstStructure *sub;
1705   GstCapsFeatures *min_f, *sub_f;
1706   GstCaps *dest = NULL, *src;
1707
1708   g_return_val_if_fail (minuend != NULL, NULL);
1709   g_return_val_if_fail (subtrahend != NULL, NULL);
1710
1711   if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1712     return gst_caps_new_empty ();
1713   }
1714
1715   if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1716     return gst_caps_ref (minuend);
1717
1718   /* FIXME: Do we want this here or above?
1719      The reason we need this is that there is no definition about what
1720      ANY means for specific types, so it's not possible to reduce ANY partially
1721      You can only remove everything or nothing and that is done above.
1722      Note: there's a test that checks this behaviour. */
1723
1724   g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1725   sublen = GST_CAPS_LEN (subtrahend);
1726   g_assert (sublen > 0);
1727
1728   src = _gst_caps_copy (minuend);
1729   for (i = 0; i < sublen; i++) {
1730     guint srclen;
1731
1732     sub = gst_caps_get_structure_unchecked (subtrahend, i);
1733     sub_f = gst_caps_get_features_unchecked (subtrahend, i);
1734     if (!sub_f)
1735       sub_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1736     if (dest) {
1737       gst_caps_unref (src);
1738       src = dest;
1739     }
1740     dest = gst_caps_new_empty ();
1741     srclen = GST_CAPS_LEN (src);
1742     for (j = 0; j < srclen; j++) {
1743       min = gst_caps_get_structure_unchecked (src, j);
1744       min_f = gst_caps_get_features_unchecked (src, j);
1745       if (!min_f)
1746         min_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1747       if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub) &&
1748           gst_caps_features_is_equal (min_f, sub_f)) {
1749         GSList *list;
1750
1751         if (gst_caps_structure_subtract (&list, min, sub)) {
1752           GSList *walk;
1753
1754           for (walk = list; walk; walk = g_slist_next (walk)) {
1755             gst_caps_append_structure_unchecked (dest,
1756                 (GstStructure *) walk->data,
1757                 gst_caps_features_copy_conditional (min_f));
1758           }
1759           g_slist_free (list);
1760         } else {
1761           gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1762               gst_caps_features_copy_conditional (min_f));
1763         }
1764       } else {
1765         gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1766             gst_caps_features_copy_conditional (min_f));
1767       }
1768     }
1769
1770     if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1771       gst_caps_unref (src);
1772       return dest;
1773     }
1774   }
1775
1776   gst_caps_unref (src);
1777   dest = gst_caps_simplify (dest);
1778
1779   return dest;
1780 }
1781
1782 /* normalize/simplify operations */
1783
1784 typedef struct _NormalizeForeach
1785 {
1786   GstCaps *caps;
1787   GstStructure *structure;
1788   GstCapsFeatures *features;
1789 } NormalizeForeach;
1790
1791 static gboolean
1792 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1793 {
1794   NormalizeForeach *nf = (NormalizeForeach *) ptr;
1795   GValue val = { 0 };
1796   guint i;
1797
1798   if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1799     guint len = gst_value_list_get_size (value);
1800
1801     for (i = 1; i < len; i++) {
1802       const GValue *v = gst_value_list_get_value (value, i);
1803       GstStructure *structure = gst_structure_copy (nf->structure);
1804
1805       gst_structure_id_set_value (structure, field_id, v);
1806       gst_caps_append_structure_unchecked (nf->caps, structure,
1807           gst_caps_features_copy_conditional (nf->features));
1808     }
1809
1810     gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1811     gst_structure_id_take_value (nf->structure, field_id, &val);
1812     return FALSE;
1813   }
1814
1815   return TRUE;
1816 }
1817
1818 /**
1819  * gst_caps_normalize:
1820  * @caps: (transfer full): a #GstCaps to normalize
1821  *
1822  * Returns a #GstCaps that represents the same set of formats as
1823  * @caps, but contains no lists.  Each list is expanded into separate
1824  * @GstStructures.
1825  *
1826  * This function takes ownership of @caps.
1827  *
1828  * Returns: (transfer full): the normalized #GstCaps
1829  */
1830 GstCaps *
1831 gst_caps_normalize (GstCaps * caps)
1832 {
1833   NormalizeForeach nf;
1834   guint i;
1835
1836   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1837
1838   caps = gst_caps_make_writable (caps);
1839   nf.caps = caps;
1840
1841   for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1842     nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1843     nf.features = gst_caps_get_features_unchecked (nf.caps, i);
1844     while (!gst_structure_foreach (nf.structure,
1845             gst_caps_normalize_foreach, &nf));
1846   }
1847
1848   return nf.caps;
1849 }
1850
1851 static gint
1852 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1853 {
1854   gint ret;
1855   const GstStructure *struct1 = ((const GstCapsArrayElement *) one)->structure;
1856   const GstStructure *struct2 = ((const GstCapsArrayElement *) two)->structure;
1857
1858   /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1859      So what's the best way? */
1860   ret = strcmp (gst_structure_get_name (struct1),
1861       gst_structure_get_name (struct2));
1862
1863   if (ret)
1864     return ret;
1865
1866   return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1867 }
1868
1869 typedef struct
1870 {
1871   GQuark name;
1872   GValue value;
1873   GstStructure *compare;
1874 } UnionField;
1875
1876 static gboolean
1877 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1878     gpointer user_data)
1879 {
1880   UnionField *u = user_data;
1881   const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1882
1883   if (!val) {
1884     if (u->name)
1885       g_value_unset (&u->value);
1886     return FALSE;
1887   }
1888
1889   if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1890     return TRUE;
1891
1892   if (u->name) {
1893     g_value_unset (&u->value);
1894     return FALSE;
1895   }
1896
1897   u->name = field_id;
1898   gst_value_union (&u->value, val, value);
1899
1900   return TRUE;
1901 }
1902
1903 static gboolean
1904 gst_caps_structure_simplify (GstStructure ** result,
1905     GstStructure * simplify, GstStructure * compare)
1906 {
1907   GSList *list;
1908   UnionField field = { 0, {0,}, NULL };
1909
1910   /* try to subtract to get a real subset */
1911   if (gst_caps_structure_subtract (&list, simplify, compare)) {
1912     if (list == NULL) {         /* no result */
1913       *result = NULL;
1914       return TRUE;
1915     } else if (list->next == NULL) {    /* one result */
1916       *result = list->data;
1917       g_slist_free (list);
1918       return TRUE;
1919     } else {                    /* multiple results */
1920       g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1921       g_slist_free (list);
1922       list = NULL;
1923     }
1924   }
1925
1926   /* try to union both structs */
1927   field.compare = compare;
1928   if (gst_structure_foreach (simplify,
1929           gst_caps_structure_figure_out_union, &field)) {
1930     gboolean ret = FALSE;
1931
1932     /* now we know all of simplify's fields are the same in compare
1933      * but at most one field: field.name */
1934     if (G_IS_VALUE (&field.value)) {
1935       if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1936         gst_structure_id_take_value (compare, field.name, &field.value);
1937         *result = NULL;
1938         ret = TRUE;
1939       } else {
1940         g_value_unset (&field.value);
1941       }
1942     } else
1943         if (gst_structure_n_fields (simplify) <=
1944         gst_structure_n_fields (compare)) {
1945       /* compare is just more specific, will be optimized away later */
1946       /* FIXME: do this here? */
1947       GST_LOG ("found a case that will be optimized later.");
1948     } else {
1949       gchar *one = gst_structure_to_string (simplify);
1950       gchar *two = gst_structure_to_string (compare);
1951
1952       GST_ERROR
1953           ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1954           one, two);
1955       g_free (one);
1956       g_free (two);
1957     }
1958     return ret;
1959   }
1960
1961   return FALSE;
1962 }
1963
1964 static void
1965 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1966     GstStructure * new, gint i)
1967 {
1968   gst_structure_set_parent_refcount (old, NULL);
1969   gst_structure_free (old);
1970   gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1971   g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, i).structure = new;
1972 }
1973
1974 /**
1975  * gst_caps_simplify:
1976  * @caps: (transfer full): a #GstCaps to simplify
1977  *
1978  * Converts the given @caps into a representation that represents the
1979  * same set of formats, but in a simpler form.  Component structures that are
1980  * identical are merged.  Component structures that have values that can be
1981  * merged are also merged.
1982  *
1983  * This method does not preserve the original order of @caps.
1984  *
1985  * Returns: The simplified caps.
1986  */
1987 GstCaps *
1988 gst_caps_simplify (GstCaps * caps)
1989 {
1990   GstStructure *simplify, *compare, *result = NULL;
1991   GstCapsFeatures *simplify_f, *compare_f;
1992   gint i, j, start;
1993
1994   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1995
1996   start = GST_CAPS_LEN (caps) - 1;
1997   /* one caps, already as simple as can be */
1998   if (start == 0)
1999     return caps;
2000
2001   caps = gst_caps_make_writable (caps);
2002
2003   g_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
2004
2005   for (i = start; i >= 0; i--) {
2006     simplify = gst_caps_get_structure_unchecked (caps, i);
2007     simplify_f = gst_caps_get_features_unchecked (caps, i);
2008     if (!simplify_f)
2009       simplify_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2010     compare = gst_caps_get_structure_unchecked (caps, start);
2011     compare_f = gst_caps_get_features_unchecked (caps, start);
2012     if (!compare_f)
2013       compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2014     if (gst_structure_get_name_id (simplify) !=
2015         gst_structure_get_name_id (compare) ||
2016         !gst_caps_features_is_equal (simplify_f, compare_f))
2017       start = i;
2018     for (j = start; j >= 0; j--) {
2019       if (j == i)
2020         continue;
2021       compare = gst_caps_get_structure_unchecked (caps, j);
2022       compare_f = gst_caps_get_features_unchecked (caps, j);
2023       if (!compare_f)
2024         compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2025       if (gst_structure_get_name_id (simplify) !=
2026           gst_structure_get_name_id (compare) ||
2027           !gst_caps_features_is_equal (simplify_f, compare_f)) {
2028         break;
2029       }
2030       if (gst_caps_structure_simplify (&result, simplify, compare)) {
2031         if (result) {
2032           gst_caps_switch_structures (caps, simplify, result, i);
2033           simplify = result;
2034         } else {
2035           gst_caps_remove_structure (caps, i);
2036           start--;
2037           break;
2038         }
2039       }
2040     }
2041   }
2042   return caps;
2043 }
2044
2045 /**
2046  * gst_caps_fixate:
2047  * @caps: (transfer full): a #GstCaps to fixate
2048  *
2049  * Modifies the given @caps into a representation with only fixed
2050  * values. First the caps will be truncated and then the first structure will be
2051  * fixated with gst_structure_fixate().
2052  *
2053  * Returns: (transfer full): the fixated caps
2054  */
2055 GstCaps *
2056 gst_caps_fixate (GstCaps * caps)
2057 {
2058   GstStructure *s;
2059
2060   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2061
2062   /* default fixation */
2063   caps = gst_caps_truncate (caps);
2064   caps = gst_caps_make_writable (caps);
2065   s = gst_caps_get_structure (caps, 0);
2066   gst_structure_fixate (s);
2067
2068   return caps;
2069 }
2070
2071 /* utility */
2072
2073 /**
2074  * gst_caps_to_string:
2075  * @caps: a #GstCaps
2076  *
2077  * Converts @caps to a string representation.  This string representation
2078  * can be converted back to a #GstCaps by gst_caps_from_string().
2079  *
2080  * For debugging purposes its easier to do something like this:
2081  * |[
2082  * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2083  * ]|
2084  * This prints the caps in human readable form.
2085  *
2086  * Returns: (transfer full): a newly allocated string representing @caps.
2087  */
2088 gchar *
2089 gst_caps_to_string (const GstCaps * caps)
2090 {
2091   guint i, slen, clen;
2092   GString *s;
2093
2094   /* NOTE:  This function is potentially called by the debug system,
2095    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2096    * should be careful to avoid recursion.  This includes any functions
2097    * called by gst_caps_to_string.  In particular, calls should
2098    * not use the GST_PTR_FORMAT extension.  */
2099
2100   if (caps == NULL) {
2101     return g_strdup ("NULL");
2102   }
2103   if (CAPS_IS_ANY (caps)) {
2104     return g_strdup ("ANY");
2105   }
2106   if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2107     return g_strdup ("EMPTY");
2108   }
2109
2110   /* estimate a rough string length to avoid unnecessary reallocs in GString */
2111   slen = 0;
2112   clen = GST_CAPS_LEN (caps);
2113   for (i = 0; i < clen; i++) {
2114     GstCapsFeatures *f;
2115
2116     slen +=
2117         STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked
2118         (caps, i));
2119     f = gst_caps_get_features_unchecked (caps, i);
2120     if (f)
2121       slen += FEATURES_ESTIMATED_STRING_LEN (f);
2122   }
2123
2124   s = g_string_sized_new (slen);
2125   for (i = 0; i < clen; i++) {
2126     GstStructure *structure;
2127     GstCapsFeatures *features;
2128
2129     if (i > 0) {
2130       /* ';' is now added by gst_structure_to_string */
2131       g_string_append_c (s, ' ');
2132     }
2133
2134     structure = gst_caps_get_structure_unchecked (caps, i);
2135     features = gst_caps_get_features_unchecked (caps, i);
2136
2137     g_string_append (s, gst_structure_get_name (structure));
2138     if (features
2139         && !gst_caps_features_is_equal (features,
2140             GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY)) {
2141       g_string_append_c (s, '(');
2142       priv_gst_caps_features_append_to_gstring (features, s);
2143       g_string_append_c (s, ')');
2144     }
2145     priv_gst_structure_append_to_gstring (structure, s);
2146   }
2147   if (s->len && s->str[s->len - 1] == ';') {
2148     /* remove latest ';' */
2149     s->str[--s->len] = '\0';
2150   }
2151   return g_string_free (s, FALSE);
2152 }
2153
2154 static gboolean
2155 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2156 {
2157   GstStructure *structure;
2158   gchar *s, *copy, *end, *next, save;
2159
2160   if (strcmp ("ANY", string) == 0) {
2161     GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
2162     return TRUE;
2163   }
2164
2165   if (strcmp ("EMPTY", string) == 0 || strcmp ("NONE", string) == 0) {
2166     return TRUE;
2167   }
2168
2169   copy = s = g_strdup (string);
2170   do {
2171     GstCapsFeatures *features = NULL;
2172
2173     while (g_ascii_isspace (*s))
2174       s++;
2175     if (*s == '\0') {
2176       break;
2177     }
2178
2179     if (!priv_gst_structure_parse_name (s, &s, &end, &next)) {
2180       g_free (copy);
2181       return FALSE;
2182     }
2183
2184     save = *end;
2185     *end = '\0';
2186     structure = gst_structure_new_empty (s);
2187     *end = save;
2188
2189     if (structure == NULL) {
2190       g_free (copy);
2191       return FALSE;
2192     }
2193
2194     s = next;
2195
2196     if (*s == '\0') {
2197       goto append;
2198     }
2199
2200     if (*s == '(') {
2201       s++;
2202       end = s;
2203
2204       while (TRUE) {
2205         if (*end == '\0') {
2206           break;
2207         } else if (*end == ')') {
2208           break;
2209         } else {
2210           end++;
2211         }
2212       }
2213
2214       save = *end;
2215       *end = '\0';
2216       features = gst_caps_features_from_string (s);
2217       if (!features) {
2218         gst_structure_free (structure);
2219         g_free (copy);
2220         return FALSE;
2221       }
2222       *end = save;
2223       s = end;
2224       if (save == ')')
2225         s++;
2226     }
2227
2228     if (*s == '\0') {
2229       goto append;
2230     }
2231
2232     if (!priv_gst_structure_parse_fields (s, &s, structure)) {
2233       gst_structure_free (structure);
2234       g_free (copy);
2235       return FALSE;
2236     }
2237
2238   append:
2239     gst_caps_append_structure_unchecked (caps, structure, features);
2240     if (*s == '\0')
2241       break;
2242   } while (TRUE);
2243
2244   g_free (copy);
2245
2246   return TRUE;
2247 }
2248
2249 /**
2250  * gst_caps_from_string:
2251  * @string: a string to convert to #GstCaps
2252  *
2253  * Converts @caps from a string representation.
2254  *
2255  * Returns: (transfer full): a newly allocated #GstCaps
2256  */
2257 GstCaps *
2258 gst_caps_from_string (const gchar * string)
2259 {
2260   GstCaps *caps;
2261
2262   g_return_val_if_fail (string, FALSE);
2263
2264   caps = gst_caps_new_empty ();
2265   if (gst_caps_from_string_inplace (caps, string)) {
2266     return caps;
2267   } else {
2268     gst_caps_unref (caps);
2269     return NULL;
2270   }
2271 }
2272
2273 static void
2274 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2275 {
2276   g_return_if_fail (G_IS_VALUE (src_value));
2277   g_return_if_fail (G_IS_VALUE (dest_value));
2278   g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2279   g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2280       || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2281
2282   g_value_take_string (dest_value,
2283       gst_caps_to_string (gst_value_get_caps (src_value)));
2284 }