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