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