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-09 (0.9.4)
  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   g_return_val_if_fail (caps1 != NULL, FALSE);
 876   g_return_val_if_fail (caps2 != NULL, FALSE);
 877
 878   if (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2))
 879     return gst_caps_is_equal_fixed (caps1, caps2);
 880
 881   return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
 882 }
 883
 884 typedef struct
 885 {
 886   GstStructure *dest;
 887   const GstStructure *intersect;
 888   gboolean first_run;
 889 }
 890 IntersectData;
 891
 892 static gboolean
 893 gst_caps_structure_intersect_field (GQuark id, const GValue * val1,
 894     gpointer data)
 895 {
 896   IntersectData *idata = (IntersectData *) data;
 897   GValue dest_value = { 0 };
 898   const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
 899
 900   if (val2 == NULL) {
 901     gst_structure_id_set_value (idata->dest, id, val1);
 902   } else if (idata->first_run) {
 903     if (gst_value_intersect (&dest_value, val1, val2)) {
 904       gst_structure_id_set_value (idata->dest, id, &dest_value);
 905       g_value_unset (&dest_value);
 906     } else {
 907       return FALSE;
 908     }
 909   }
 910
 911   return TRUE;
 912 }
 913
 914 static GstStructure *
 915 gst_caps_structure_intersect (const GstStructure * struct1,
 916     const GstStructure * struct2)
 917 {
 918   IntersectData data;
 919
 920   g_return_val_if_fail (struct1 != NULL, NULL);
 921   g_return_val_if_fail (struct2 != NULL, NULL);
 922
 923   if (struct1->name != struct2->name)
 924     return NULL;
 925
 926   data.dest = gst_structure_id_empty_new (struct1->name);
 927   data.intersect = struct2;
 928   data.first_run = TRUE;
 929   if (!gst_structure_foreach ((GstStructure *) struct1,
 930           gst_caps_structure_intersect_field, &data))
 931     goto error;
 932
 933   data.intersect = struct1;
 934   data.first_run = FALSE;
 935   if (!gst_structure_foreach ((GstStructure *) struct2,
 936           gst_caps_structure_intersect_field, &data))
 937     goto error;
 938
 939   return data.dest;
 940
 941 error:
 942   gst_structure_free (data.dest);
 943   return NULL;
 944 }
 945
 946 #if 0
 947 static GstStructure *
 948 gst_caps_structure_union (const GstStructure * struct1,
 949     const GstStructure * struct2)
 950 {
 951   int i;
 952   GstStructure *dest;
 953   const GstStructureField *field1;
 954   const GstStructureField *field2;
 955   int ret;
 956
 957   /* FIXME this doesn't actually work */
 958
 959   if (struct1->name != struct2->name)
 960     return NULL;
 961
 962   dest = gst_structure_id_empty_new (struct1->name);
 963
 964   for (i = 0; i < struct1->fields->len; i++) {
 965     GValue dest_value = { 0 };
 966
 967     field1 = GST_STRUCTURE_FIELD (struct1, i);
 968     field2 = gst_structure_id_get_field (struct2, field1->name);
 969
 970     if (field2 == NULL) {
 971       continue;
 972     } else {
 973       if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
 974         gst_structure_set_value (dest, g_quark_to_string (field1->name),
 975             &dest_value);
 976       } else {
 977         ret = gst_value_compare (&field1->value, &field2->value);
 978       }
 979     }
 980   }
 981
 982   return dest;
 983 }
 984 #endif
 985
 986 /* operations */
 987
 988 /**
 989  * gst_caps_intersect:
 990  * @caps1: a #GstCaps to intersect
 991  * @caps2: a #GstCaps to intersect
 992  *
 993  * Creates a new #GstCaps that contains all the formats that are common
 994  * to both @caps1 and @caps2.
 995  *
 996  * Returns: the new #GstCaps
 997  */
 998 GstCaps *
 999 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1000 {
1001   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1002   guint j, k;
1003
1004   GstStructure *struct1;
1005   GstStructure *struct2;
1006   GstCaps *dest;
1007   GstStructure *istruct;
1008
1009   g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1010   g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1011
1012   if (gst_caps_is_empty (caps1) || gst_caps_is_empty (caps2)) {
1013     return gst_caps_new_empty ();
1014   }
1015   if (gst_caps_is_any (caps1))
1016     return gst_caps_copy (caps2);
1017   if (gst_caps_is_any (caps2))
1018     return gst_caps_copy (caps1);
1019
1020   dest = gst_caps_new_empty ();
1021
1022   /* run zigzag on top line then right line, this preserves the caps order
1023    * much better than a simple loop.
1024    *
1025    * This algorithm zigzags over the caps structures as demonstrated in
1026    * the folowing matrix:
1027    *
1028    *          caps1
1029    *       +-------------
1030    *       | 1  2  4  7
1031    * caps2 | 3  5  8 10
1032    *       | 6  9 11 12
1033    *
1034    * First we iterate over the caps1 structures (top line) intersecting
1035    * the structures diagonally down, then we iterate over the caps2
1036    * structures.
1037    */
1038   for (i = 0; i < caps1->structs->len + caps2->structs->len - 1; i++) {
1039     /* caps1 index goes from 0 to caps1->structs->len-1 */
1040     j = MIN (i, caps1->structs->len - 1);
1041     /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1042      * up from 1 to caps2->structs->len - 1 */
1043     k = MAX (0, i - j);
1044
1045     /* now run the diagonal line, end condition is the left or bottom
1046      * border */
1047     while (k < caps2->structs->len) {
1048       struct1 = gst_caps_get_structure (caps1, j);
1049       struct2 = gst_caps_get_structure (caps2, k);
1050
1051       istruct = gst_caps_structure_intersect (struct1, struct2);
1052
1053       gst_caps_append_structure (dest, istruct);
1054       /* move down left */
1055       k++;
1056       if (j == 0)
1057         break;                  /* so we don't roll back to G_MAXUINT */
1058       j--;
1059     }
1060   }
1061   return dest;
1062 }
1063
1064 typedef struct
1065 {
1066   const GstStructure *subtract_from;
1067   GSList *put_into;
1068 }
1069 SubtractionEntry;
1070
1071
1072 static gboolean
1073 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1074     gpointer user_data)
1075 {
1076   SubtractionEntry *e = user_data;
1077   GValue subtraction = { 0, };
1078   const GValue *other;
1079   GstStructure *structure;
1080
1081   other = gst_structure_id_get_value (e->subtract_from, field_id);
1082   if (!other) {
1083     return FALSE;
1084   }
1085   if (!gst_value_subtract (&subtraction, other, value))
1086     return TRUE;
1087   if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1088     g_value_unset (&subtraction);
1089     return FALSE;
1090   } else {
1091     structure = gst_structure_copy (e->subtract_from);
1092     gst_structure_id_set_value (structure, field_id, &subtraction);
1093     g_value_unset (&subtraction);
1094     e->put_into = g_slist_prepend (e->put_into, structure);
1095     return TRUE;
1096   }
1097 }
1098
1099 static gboolean
1100 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1101     const GstStructure * subtrahend)
1102 {
1103   SubtractionEntry e;
1104   gboolean ret;
1105
1106   e.subtract_from = minuend;
1107   e.put_into = NULL;
1108
1109   ret = gst_structure_foreach ((GstStructure *) subtrahend,
1110       gst_caps_structure_subtract_field, &e);
1111   if (ret) {
1112     *into = e.put_into;
1113   } else {
1114     GSList *walk;
1115
1116     for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1117       gst_structure_free (walk->data);
1118     }
1119     g_slist_free (e.put_into);
1120   }
1121   return ret;
1122 }
1123
1124 /**
1125  * gst_caps_subtract:
1126  * @minuend: #GstCaps to substract from
1127  * @subtrahend: #GstCaps to substract
1128  *
1129  * Subtracts the @subtrahend from the @minuend.
1130  * <note>This function does not work reliably if optional properties for caps
1131  * are included on one caps and omitted on the other.</note>
1132  *
1133  * Returns: the resulting caps
1134  */
1135 GstCaps *
1136 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1137 {
1138   guint i, j;
1139   GstStructure *min;
1140   GstStructure *sub;
1141   GstCaps *dest = NULL, *src;
1142
1143   g_return_val_if_fail (minuend != NULL, NULL);
1144   g_return_val_if_fail (subtrahend != NULL, NULL);
1145
1146   if (gst_caps_is_empty (minuend) || gst_caps_is_any (subtrahend)) {
1147     return gst_caps_new_empty ();
1148   }
1149   if (gst_caps_is_empty (subtrahend))
1150     return gst_caps_copy (minuend);
1151
1152   /* FIXME: Do we want this here or above?
1153      The reason we need this is that there is no definition about what
1154      ANY means for specific types, so it's not possible to reduce ANY partially
1155      You can only remove everything or nothing and that is done above.
1156      Note: there's a test that checks this behaviour. */
1157   g_return_val_if_fail (!gst_caps_is_any (minuend), NULL);
1158   g_assert (subtrahend->structs->len > 0);
1159
1160   src = gst_caps_copy (minuend);
1161   for (i = 0; i < subtrahend->structs->len; i++) {
1162     sub = gst_caps_get_structure (subtrahend, i);
1163     if (dest) {
1164       gst_caps_unref (src);
1165       src = dest;
1166     }
1167     dest = gst_caps_new_empty ();
1168     for (j = 0; j < src->structs->len; j++) {
1169       min = gst_caps_get_structure (src, j);
1170       if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1171         GSList *list;
1172
1173         if (gst_caps_structure_subtract (&list, min, sub)) {
1174           GSList *walk;
1175
1176           for (walk = list; walk; walk = g_slist_next (walk)) {
1177             gst_caps_append_structure (dest, (GstStructure *) walk->data);
1178           }
1179           g_slist_free (list);
1180         } else {
1181           gst_caps_append_structure (dest, gst_structure_copy (min));
1182         }
1183       } else {
1184         gst_caps_append_structure (dest, gst_structure_copy (min));
1185       }
1186     }
1187     if (gst_caps_is_empty (dest)) {
1188       gst_caps_unref (src);
1189       return dest;
1190     }
1191   }
1192
1193   gst_caps_unref (src);
1194   gst_caps_do_simplify (dest);
1195   return dest;
1196 }
1197
1198 /**
1199  * gst_caps_union:
1200  * @caps1: a #GstCaps to union
1201  * @caps2: a #GstCaps to union
1202  *
1203  * Creates a new #GstCaps that contains all the formats that are in
1204  * either @caps1 and @caps2.
1205  *
1206  * Returns: the new #GstCaps
1207  */
1208 GstCaps *
1209 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1210 {
1211   GstCaps *dest1;
1212   GstCaps *dest2;
1213
1214   if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2))
1215     return gst_caps_new_any ();
1216
1217   dest1 = gst_caps_copy (caps1);
1218   dest2 = gst_caps_copy (caps2);
1219   gst_caps_append (dest1, dest2);
1220
1221   gst_caps_do_simplify (dest1);
1222   return dest1;
1223 }
1224
1225 typedef struct _NormalizeForeach
1226 {
1227   GstCaps *caps;
1228   GstStructure *structure;
1229 }
1230 NormalizeForeach;
1231
1232 static gboolean
1233 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1234 {
1235   NormalizeForeach *nf = (NormalizeForeach *) ptr;
1236   GValue val = { 0 };
1237   guint i;
1238
1239   if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1240     for (i = 1; i < gst_value_list_get_size (value); i++) {
1241       const GValue *v = gst_value_list_get_value (value, i);
1242       GstStructure *structure = gst_structure_copy (nf->structure);
1243
1244       gst_structure_id_set_value (structure, field_id, v);
1245       gst_caps_append_structure (nf->caps, structure);
1246     }
1247
1248     gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1249     gst_structure_id_set_value (nf->structure, field_id, &val);
1250     g_value_unset (&val);
1251
1252     return FALSE;
1253   }
1254   return TRUE;
1255 }
1256
1257 /**
1258  * gst_caps_normalize:
1259  * @caps: a #GstCaps to normalize
1260  *
1261  * Creates a new #GstCaps that represents the same set of formats as
1262  * @caps, but contains no lists.  Each list is expanded into separate
1263  * @GstStructures.
1264  *
1265  * Returns: the new #GstCaps
1266  */
1267 GstCaps *
1268 gst_caps_normalize (const GstCaps * caps)
1269 {
1270   NormalizeForeach nf;
1271   GstCaps *newcaps;
1272   guint i;
1273
1274   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1275
1276   newcaps = gst_caps_copy (caps);
1277   nf.caps = newcaps;
1278
1279   for (i = 0; i < newcaps->structs->len; i++) {
1280     nf.structure = gst_caps_get_structure (newcaps, i);
1281
1282     while (!gst_structure_foreach (nf.structure,
1283             gst_caps_normalize_foreach, &nf));
1284   }
1285
1286   return newcaps;
1287 }
1288
1289 static gint
1290 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1291 {
1292   gint ret;
1293   const GstStructure *struct1 = *((const GstStructure **) one);
1294   const GstStructure *struct2 = *((const GstStructure **) two);
1295
1296   /* FIXME: this orders aphabetically, but ordering the quarks might be faster
1297      So what's the best way? */
1298   ret = strcmp (gst_structure_get_name (struct1),
1299       gst_structure_get_name (struct2));
1300   if (ret)
1301     return ret;
1302
1303   return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1304 }
1305
1306 /**
1307  * gst_caps_simplify:
1308  * @caps: a #GstCaps to simplify
1309  *
1310  * Creates a new #GstCaps that represents the same set of formats as
1311  * @caps, but simpler.  Component structures that are identical are
1312  * merged.  Component structures that have ranges or lists that can
1313  * be merged are also merged.
1314  *
1315  * Returns: the new #GstCaps
1316  */
1317 GstCaps *
1318 gst_caps_simplify (const GstCaps * caps)
1319 {
1320   GstCaps *ret;
1321
1322   g_return_val_if_fail (caps != NULL, NULL);
1323
1324   ret = gst_caps_copy (caps);
1325   gst_caps_do_simplify (ret);
1326
1327   return ret;
1328 }
1329
1330 typedef struct
1331 {
1332   GQuark name;
1333   GValue value;
1334   GstStructure *compare;
1335 }
1336 UnionField;
1337
1338 static gboolean
1339 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1340     gpointer user_data)
1341 {
1342   UnionField *u = user_data;
1343   const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1344
1345   if (!val) {
1346     if (u->name)
1347       g_value_unset (&u->value);
1348     return FALSE;
1349   }
1350   if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1351     return TRUE;
1352   if (u->name) {
1353     g_value_unset (&u->value);
1354     return FALSE;
1355   }
1356   u->name = field_id;
1357   gst_value_union (&u->value, val, value);
1358   return TRUE;
1359 }
1360
1361 static gboolean
1362 gst_caps_structure_simplify (GstStructure ** result,
1363     const GstStructure * simplify, GstStructure * compare)
1364 {
1365   GSList *list;
1366   UnionField field = { 0, {0,}, NULL };
1367
1368   /* try to subtract to get a real subset */
1369   if (gst_caps_structure_subtract (&list, simplify, compare)) {
1370     switch (g_slist_length (list)) {
1371       case 0:
1372         *result = NULL;
1373         return TRUE;
1374       case 1:
1375         *result = list->data;
1376         g_slist_free (list);
1377         return TRUE;
1378       default:
1379       {
1380         GSList *walk;
1381
1382         for (walk = list; walk; walk = g_slist_next (walk)) {
1383           gst_structure_free (walk->data);
1384         }
1385         g_slist_free (list);
1386         break;
1387       }
1388     }
1389   }
1390
1391   /* try to union both structs */
1392   field.compare = compare;
1393   if (gst_structure_foreach ((GstStructure *) simplify,
1394           gst_caps_structure_figure_out_union, &field)) {
1395     gboolean ret = FALSE;
1396
1397     /* now we know all of simplify's fields are the same in compare
1398      * but at most one field: field.name */
1399     if (G_IS_VALUE (&field.value)) {
1400       if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1401         gst_structure_id_set_value (compare, field.name, &field.value);
1402         *result = NULL;
1403         ret = TRUE;
1404       }
1405       g_value_unset (&field.value);
1406     } else if (gst_structure_n_fields (simplify) <=
1407         gst_structure_n_fields (compare)) {
1408       /* compare is just more specific, will be optimized away later */
1409       /* FIXME: do this here? */
1410       GST_LOG ("found a case that will be optimized later.");
1411     } else {
1412       gchar *one = gst_structure_to_string (simplify);
1413       gchar *two = gst_structure_to_string (compare);
1414
1415       GST_ERROR
1416           ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1417           one, two);
1418       g_free (one);
1419       g_free (two);
1420     }
1421     return ret;
1422   }
1423
1424   return FALSE;
1425 }
1426
1427 static void
1428 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1429     GstStructure * new, gint i)
1430 {
1431   gst_structure_set_parent_refcount (old, NULL);
1432   gst_structure_free (old);
1433   gst_structure_set_parent_refcount (new, &caps->refcount);
1434   g_ptr_array_index (caps->structs, i) = new;
1435 }
1436
1437 /**
1438  * gst_caps_do_simplify:
1439  * @caps: a #GstCaps to simplify
1440  *
1441  * Modifies the given @caps inplace into a representation that represents the
1442  * same set of formats, but in a simpler form.  Component structures that are
1443  * identical are merged.  Component structures that have values that can be
1444  * merged are also merged.
1445  *
1446  * Returns: TRUE, if the caps could be simplified
1447  */
1448 gboolean
1449 gst_caps_do_simplify (GstCaps * caps)
1450 {
1451   GstStructure *simplify, *compare, *result = NULL;
1452   gint i, j, start;
1453   gboolean changed = FALSE;
1454
1455   g_return_val_if_fail (caps != NULL, FALSE);
1456   g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1457
1458   if (gst_caps_get_size (caps) < 2)
1459     return FALSE;
1460
1461   g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1462
1463   start = caps->structs->len - 1;
1464   for (i = caps->structs->len - 1; i >= 0; i--) {
1465     simplify = gst_caps_get_structure (caps, i);
1466     if (gst_structure_get_name_id (simplify) !=
1467         gst_structure_get_name_id (gst_caps_get_structure (caps, start)))
1468       start = i;
1469     for (j = start; j >= 0; j--) {
1470       if (j == i)
1471         continue;
1472       compare = gst_caps_get_structure (caps, j);
1473       if (gst_structure_get_name_id (simplify) !=
1474           gst_structure_get_name_id (compare)) {
1475         break;
1476       }
1477       if (gst_caps_structure_simplify (&result, simplify, compare)) {
1478         if (result) {
1479           gst_caps_switch_structures (caps, simplify, result, i);
1480           simplify = result;
1481         } else {
1482           gst_caps_remove_structure (caps, i);
1483           start--;
1484           break;
1485         }
1486         changed = TRUE;
1487       }
1488     }
1489   }
1490
1491   if (!changed)
1492     return FALSE;
1493
1494   /* gst_caps_do_simplify (caps); */
1495   return TRUE;
1496 }
1497
1498 #ifndef GST_DISABLE_LOADSAVE
1499 /**
1500  * gst_caps_save_thyself:
1501  * @caps: a #GstCaps structure
1502  * @parent: a XML parent node
1503  *
1504  * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1505  *
1506  * Returns: a XML node pointer
1507  */
1508 xmlNodePtr
1509 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1510 {
1511   char *s = gst_caps_to_string (caps);
1512
1513   xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1514   g_free (s);
1515   return parent;
1516 }
1517
1518 /**
1519  * gst_caps_load_thyself:
1520  * @parent: a XML node
1521  *
1522  * Creates a #GstCaps from its XML serialization.
1523  *
1524  * Returns: a new #GstCaps structure
1525  */
1526 GstCaps *
1527 gst_caps_load_thyself (xmlNodePtr parent)
1528 {
1529   if (strcmp ("caps", (char *) parent->name) == 0) {
1530     return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1531   }
1532
1533   return NULL;
1534 }
1535 #endif
1536
1537 /* utility */
1538
1539 /**
1540  * gst_caps_replace:
1541  * @caps: a pointer to #GstCaps
1542  * @newcaps: a #GstCaps to replace *caps
1543  *
1544  * Replaces *caps with @newcaps.  Unrefs the #GstCaps in the location
1545  * pointed to by @caps, if applicable, then modifies @caps to point to
1546  * @newcaps. An additional ref on @newcaps is taken.
1547  */
1548 void
1549 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1550 {
1551   GstCaps *oldcaps;
1552
1553 #if 0                           /* disable this, since too many plugins rely on undefined behavior */
1554 #ifdef USE_POISONING
1555   //if (newcaps) CAPS_POISON (newcaps);
1556 #endif
1557 #endif
1558   oldcaps = *caps;
1559
1560   if (newcaps)
1561     gst_caps_ref (newcaps);
1562
1563   *caps = newcaps;
1564
1565   if (oldcaps)
1566     gst_caps_unref (oldcaps);
1567 }
1568
1569 /**
1570  * gst_caps_to_string:
1571  * @caps: a #GstCaps
1572  *
1573  * Converts @caps to a string representation.  This string representation
1574  * can be converted back to a #GstCaps by #gst_caps_from_string.
1575  *
1576  * Returns: a newly allocated string representing @caps.
1577  */
1578 gchar *
1579 gst_caps_to_string (const GstCaps * caps)
1580 {
1581   guint i;
1582   GString *s;
1583
1584   /* NOTE:  This function is potentially called by the debug system,
1585    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1586    * should be careful to avoid recursion.  This includes any functions
1587    * called by gst_caps_to_string.  In particular, calls should
1588    * not use the GST_PTR_FORMAT extension.  */
1589
1590   if (caps == NULL) {
1591     return g_strdup ("NULL");
1592   }
1593   if (gst_caps_is_any (caps)) {
1594     return g_strdup ("ANY");
1595   }
1596   if (gst_caps_is_empty (caps)) {
1597     return g_strdup ("EMPTY");
1598   }
1599
1600   s = g_string_new ("");
1601   for (i = 0; i < caps->structs->len; i++) {
1602     GstStructure *structure;
1603     char *sstr;
1604
1605     if (i > 0)
1606       g_string_append (s, "; ");
1607
1608     structure = gst_caps_get_structure (caps, i);
1609     sstr = gst_structure_to_string (structure);
1610     g_string_append (s, sstr);
1611     g_free (sstr);
1612   }
1613
1614   return g_string_free (s, FALSE);
1615 }
1616
1617 static gboolean
1618 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1619 {
1620   GstStructure *structure;
1621   gchar *s;
1622
1623   g_return_val_if_fail (string, FALSE);
1624   if (strcmp ("ANY", string) == 0) {
1625     caps->flags = GST_CAPS_FLAGS_ANY;
1626     return TRUE;
1627   }
1628   if (strcmp ("EMPTY", string) == 0) {
1629     return TRUE;
1630   }
1631
1632   structure = gst_structure_from_string (string, &s);
1633   if (structure == NULL) {
1634     return FALSE;
1635   }
1636   gst_caps_append_structure (caps, structure);
1637
1638   while (*s == ';') {
1639     s++;
1640     while (g_ascii_isspace (*s))
1641       s++;
1642     structure = gst_structure_from_string (s, &s);
1643     if (structure == NULL) {
1644       return FALSE;
1645     }
1646     gst_caps_append_structure (caps, structure);
1647     while (g_ascii_isspace (*s))
1648       s++;
1649   }
1650
1651   if (*s != 0) {
1652     return FALSE;
1653   }
1654
1655   return TRUE;
1656 }
1657
1658 /**
1659  * gst_caps_from_string:
1660  * @string: a string to convert to #GstCaps
1661  *
1662  * Converts @caps from a string representation.
1663  *
1664  * Returns: a newly allocated #GstCaps
1665  */
1666 GstCaps *
1667 gst_caps_from_string (const gchar * string)
1668 {
1669   GstCaps *caps;
1670
1671   caps = gst_caps_new_empty ();
1672   if (gst_caps_from_string_inplace (caps, string)) {
1673     return caps;
1674   } else {
1675     gst_caps_unref (caps);
1676     return NULL;
1677   }
1678 }
1679
1680 static void
1681 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1682 {
1683   g_return_if_fail (G_IS_VALUE (src_value));
1684   g_return_if_fail (G_IS_VALUE (dest_value));
1685   g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1686   g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1687       || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1688
1689   dest_value->data[0].v_pointer =
1690       gst_caps_to_string (src_value->data[0].v_pointer);
1691 }
1692
1693 static GstCaps *
1694 gst_caps_copy_conditional (GstCaps * src)
1695 {
1696   if (src) {
1697     return gst_caps_ref (src);
1698   } else {
1699     return NULL;
1700   }
1701 }