gst/gstcaps.c

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