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