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