gst/gstcaps.c

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