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