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