gst/gstcaps.c

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