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