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