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