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 < caps->structs->len, NULL);
 608
 609   return g_ptr_array_index (caps->structs, index);
 610 }
 611
 612 /**
 613  * gst_caps_copy_nth:
 614  * @caps: the #GstCaps to copy
 615  * @nth: the nth structure to copy
 616  *
 617  * Creates a new #GstCaps and appends a copy of the nth structure
 618  * contained in @caps.
 619  *
 620  * Returns: the new #GstCaps
 621  */
 622 GstCaps *
 623 gst_caps_copy_nth (const GstCaps * caps, guint nth)
 624 {
 625   GstCaps *newcaps;
 626   GstStructure *structure;
 627
 628   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 629
 630   newcaps = gst_caps_new_empty ();
 631   newcaps->flags = caps->flags;
 632
 633   if (caps->structs->len > nth) {
 634     structure = gst_caps_get_structure (caps, nth);
 635     gst_caps_append_structure (newcaps, gst_structure_copy (structure));
 636   }
 637
 638   return newcaps;
 639 }
 640
 641 /**
 642  * gst_caps_truncate:
 643  * @caps: the #GstCaps to truncate
 644  *
 645  * Destructively discard all but the first structure from @caps. Useful when
 646  * fixating. @caps must be writable.
 647  */
 648 void
 649 gst_caps_truncate (GstCaps * caps)
 650 {
 651   gint i;
 652
 653   g_return_if_fail (GST_IS_CAPS (caps));
 654   g_return_if_fail (IS_WRITABLE (caps));
 655
 656   i = caps->structs->len - 1;
 657
 658   while (i > 0)
 659     gst_caps_remove_structure (caps, i--);
 660 }
 661
 662 /**
 663  * gst_caps_set_simple:
 664  * @caps: the #GstCaps to set
 665  * @field: first field to set
 666  * @...: additional parameters
 667  *
 668  * Sets fields in a simple #GstCaps.  A simple #GstCaps is one that
 669  * only has one structure.  The arguments must be passed in the same
 670  * manner as gst_structure_set(), and be NULL-terminated.
 671  */
 672 void
 673 gst_caps_set_simple (GstCaps * caps, char *field, ...)
 674 {
 675   GstStructure *structure;
 676   va_list var_args;
 677
 678   g_return_if_fail (GST_IS_CAPS (caps));
 679   g_return_if_fail (caps->structs->len == 1);
 680   g_return_if_fail (IS_WRITABLE (caps));
 681
 682   structure = gst_caps_get_structure (caps, 0);
 683
 684   va_start (var_args, field);
 685   gst_structure_set_valist (structure, field, var_args);
 686   va_end (var_args);
 687 }
 688
 689 /**
 690  * gst_caps_set_simple_valist:
 691  * @caps: the #GstCaps to copy
 692  * @field: first field to set
 693  * @varargs: additional parameters
 694  *
 695  * Sets fields in a simple #GstCaps.  A simple #GstCaps is one that
 696  * only has one structure.  The arguments must be passed in the same
 697  * manner as gst_structure_set(), and be NULL-terminated.
 698  */
 699 void
 700 gst_caps_set_simple_valist (GstCaps * caps, char *field, va_list varargs)
 701 {
 702   GstStructure *structure;
 703
 704   g_return_if_fail (GST_IS_CAPS (caps));
 705   g_return_if_fail (caps->structs->len != 1);
 706   g_return_if_fail (IS_WRITABLE (caps));
 707
 708   structure = gst_caps_get_structure (caps, 0);
 709
 710   gst_structure_set_valist (structure, field, varargs);
 711 }
 712
 713 /* tests */
 714
 715 /**
 716  * gst_caps_is_any:
 717  * @caps: the #GstCaps to test
 718  *
 719  * Determines if @caps represents any media format.
 720  *
 721  * Returns: TRUE if @caps represents any format.
 722  */
 723 gboolean
 724 gst_caps_is_any (const GstCaps * caps)
 725 {
 726   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 727
 728   return (caps->flags & GST_CAPS_FLAGS_ANY);
 729 }
 730
 731 /**
 732  * gst_caps_is_empty:
 733  * @caps: the #GstCaps to test
 734  *
 735  * Determines if @caps represents no media formats.
 736  *
 737  * Returns: TRUE if @caps represents no formats.
 738  */
 739 gboolean
 740 gst_caps_is_empty (const GstCaps * caps)
 741 {
 742   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 743
 744   if (caps->flags & GST_CAPS_FLAGS_ANY)
 745     return FALSE;
 746
 747   return (caps->structs == NULL) || (caps->structs->len == 0);
 748 }
 749
 750 static gboolean
 751 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
 752     gpointer unused)
 753 {
 754   return gst_value_is_fixed (value);
 755 }
 756
 757 /**
 758  * gst_caps_is_fixed:
 759  * @caps: the #GstCaps to test
 760  *
 761  * Fixed #GstCaps describe exactly one format, that is, they have exactly
 762  * one structure, and each field in the structure describes a fixed type.
 763  * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
 764  *
 765  * Returns: TRUE if @caps is fixed
 766  */
 767 gboolean
 768 gst_caps_is_fixed (const GstCaps * caps)
 769 {
 770   GstStructure *structure;
 771
 772   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 773
 774   if (caps->structs->len != 1)
 775     return FALSE;
 776
 777   structure = gst_caps_get_structure (caps, 0);
 778
 779   return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
 780 }
 781
 782 static gboolean
 783 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
 784     gpointer data)
 785 {
 786   GstStructure *struct1 = (GstStructure *) data;
 787   const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
 788
 789   if (val1 == NULL)
 790     return FALSE;
 791   if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
 792     return TRUE;
 793   }
 794
 795   return FALSE;
 796 }
 797
 798 /**
 799  * gst_caps_is_equal_fixed:
 800  * @caps1: the #GstCaps to test
 801  * @caps2: the #GstCaps to test
 802  *
 803  * Tests if two #GstCaps are equal.  This function only works on fixed
 804  * #GstCaps.
 805  *
 806  * Returns: TRUE if the arguments represent the same format
 807  */
 808 gboolean
 809 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
 810 {
 811   GstStructure *struct1, *struct2;
 812
 813   g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
 814   g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
 815
 816   struct1 = gst_caps_get_structure (caps1, 0);
 817   struct2 = gst_caps_get_structure (caps2, 0);
 818
 819   if (struct1->name != struct2->name) {
 820     return FALSE;
 821   }
 822   if (struct1->fields->len != struct2->fields->len) {
 823     return FALSE;
 824   }
 825
 826   return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
 827       struct2);
 828 }
 829
 830 /**
 831  * gst_caps_is_always_compatible:
 832  * @caps1: the #GstCaps to test
 833  * @caps2: the #GstCaps to test
 834  *
 835  * A given #GstCaps structure is always compatible with another if
 836  * every media format that is in the first is also contained in the
 837  * second.  That is, @caps1 is a subset of @caps2.
 838  *
 839  * Returns: TRUE if @caps1 is a subset of @caps2.
 840  */
 841 gboolean
 842 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
 843 {
 844   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
 845   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
 846
 847   return gst_caps_is_subset (caps1, caps2);
 848 }
 849
 850 /**
 851  * gst_caps_is_subset:
 852  * @subset: a #GstCaps
 853  * @superset: a potentially greater #GstCaps
 854  *
 855  * Checks if all caps represented by @subset are also represented by @superset
 856  * <note>This function does not work reliably if optional properties for caps
 857  * are included on one caps and omitted on the other.</note>
 858  *
 859  * Returns: TRUE if @subset is a subset of @superset
 860  */
 861 gboolean
 862 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
 863 {
 864   GstCaps *caps;
 865   gboolean ret;
 866
 867   g_return_val_if_fail (subset != NULL, FALSE);
 868   g_return_val_if_fail (superset != NULL, FALSE);
 869
 870   if (gst_caps_is_empty (subset) || gst_caps_is_any (superset))
 871     return TRUE;
 872   if (gst_caps_is_any (subset) || gst_caps_is_empty (superset))
 873     return FALSE;
 874
 875   caps = gst_caps_subtract (subset, superset);
 876   ret = gst_caps_is_empty (caps);
 877   gst_caps_unref (caps);
 878   return ret;
 879 }
 880
 881 /**
 882  * gst_caps_is_equal:
 883  * @caps1: a #GstCaps
 884  * @caps2: another #GstCaps
 885  *
 886  * Checks if the given caps represent the same set of caps.
 887  * <note>This function does not work reliably if optional properties for caps
 888  * are included on one caps and omitted on the other.</note>
 889  *
 890  * This function deals correctly with passing NULL for any of the caps.
 891  *
 892  * Returns: TRUE if both caps are equal.
 893  */
 894 gboolean
 895 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
 896 {
 897   /* NULL <-> NULL is allowed here */
 898   if (caps1 == caps2)
 899     return TRUE;
 900
 901   /* one of them NULL => they are different (can't be both NULL because
 902    * we checked that above) */
 903   if (caps1 == NULL || caps2 == NULL)
 904     return FALSE;
 905
 906   if (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2))
 907     return gst_caps_is_equal_fixed (caps1, caps2);
 908
 909   return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
 910 }
 911
 912 typedef struct
 913 {
 914   GstStructure *dest;
 915   const GstStructure *intersect;
 916   gboolean first_run;
 917 }
 918 IntersectData;
 919
 920 static gboolean
 921 gst_caps_structure_intersect_field (GQuark id, const GValue * val1,
 922     gpointer data)
 923 {
 924   IntersectData *idata = (IntersectData *) data;
 925   GValue dest_value = { 0 };
 926   const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
 927
 928   if (val2 == NULL) {
 929     gst_structure_id_set_value (idata->dest, id, val1);
 930   } else if (idata->first_run) {
 931     if (gst_value_intersect (&dest_value, val1, val2)) {
 932       gst_structure_id_set_value (idata->dest, id, &dest_value);
 933       g_value_unset (&dest_value);
 934     } else {
 935       return FALSE;
 936     }
 937   }
 938
 939   return TRUE;
 940 }
 941
 942 static GstStructure *
 943 gst_caps_structure_intersect (const GstStructure * struct1,
 944     const GstStructure * struct2)
 945 {
 946   IntersectData data;
 947
 948   g_return_val_if_fail (struct1 != NULL, NULL);
 949   g_return_val_if_fail (struct2 != NULL, NULL);
 950
 951   if (struct1->name != struct2->name)
 952     return NULL;
 953
 954   data.dest = gst_structure_id_empty_new (struct1->name);
 955   data.intersect = struct2;
 956   data.first_run = TRUE;
 957   if (!gst_structure_foreach ((GstStructure *) struct1,
 958           gst_caps_structure_intersect_field, &data))
 959     goto error;
 960
 961   data.intersect = struct1;
 962   data.first_run = FALSE;
 963   if (!gst_structure_foreach ((GstStructure *) struct2,
 964           gst_caps_structure_intersect_field, &data))
 965     goto error;
 966
 967   return data.dest;
 968
 969 error:
 970   gst_structure_free (data.dest);
 971   return NULL;
 972 }
 973
 974 #if 0
 975 static GstStructure *
 976 gst_caps_structure_union (const GstStructure * struct1,
 977     const GstStructure * struct2)
 978 {
 979   int i;
 980   GstStructure *dest;
 981   const GstStructureField *field1;
 982   const GstStructureField *field2;
 983   int ret;
 984
 985   /* FIXME this doesn't actually work */
 986
 987   if (struct1->name != struct2->name)
 988     return NULL;
 989
 990   dest = gst_structure_id_empty_new (struct1->name);
 991
 992   for (i = 0; i < struct1->fields->len; i++) {
 993     GValue dest_value = { 0 };
 994
 995     field1 = GST_STRUCTURE_FIELD (struct1, i);
 996     field2 = gst_structure_id_get_field (struct2, field1->name);
 997
 998     if (field2 == NULL) {
 999       continue;
1000     } else {
1001       if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1002         gst_structure_set_value (dest, g_quark_to_string (field1->name),
1003             &dest_value);
1004       } else {
1005         ret = gst_value_compare (&field1->value, &field2->value);
1006       }
1007     }
1008   }
1009
1010   return dest;
1011 }
1012 #endif
1013
1014 /* operations */
1015
1016 /**
1017  * gst_caps_intersect:
1018  * @caps1: a #GstCaps to intersect
1019  * @caps2: a #GstCaps to intersect
1020  *
1021  * Creates a new #GstCaps that contains all the formats that are common
1022  * to both @caps1 and @caps2.
1023  *
1024  * Returns: the new #GstCaps
1025  */
1026 GstCaps *
1027 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1028 {
1029   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1030   guint j, k;
1031
1032   GstStructure *struct1;
1033   GstStructure *struct2;
1034   GstCaps *dest;
1035   GstStructure *istruct;
1036
1037   g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1038   g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1039
1040   if (gst_caps_is_empty (caps1) || gst_caps_is_empty (caps2)) {
1041     return gst_caps_new_empty ();
1042   }
1043   if (gst_caps_is_any (caps1))
1044     return gst_caps_copy (caps2);
1045   if (gst_caps_is_any (caps2))
1046     return gst_caps_copy (caps1);
1047
1048   dest = gst_caps_new_empty ();
1049
1050   /* run zigzag on top line then right line, this preserves the caps order
1051    * much better than a simple loop.
1052    *
1053    * This algorithm zigzags over the caps structures as demonstrated in
1054    * the folowing matrix:
1055    *
1056    *          caps1
1057    *       +-------------
1058    *       | 1  2  4  7
1059    * caps2 | 3  5  8 10
1060    *       | 6  9 11 12
1061    *
1062    * First we iterate over the caps1 structures (top line) intersecting
1063    * the structures diagonally down, then we iterate over the caps2
1064    * structures.
1065    */
1066   for (i = 0; i < caps1->structs->len + caps2->structs->len - 1; i++) {
1067     /* caps1 index goes from 0 to caps1->structs->len-1 */
1068     j = MIN (i, caps1->structs->len - 1);
1069     /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1070      * up from 1 to caps2->structs->len - 1 */
1071     k = MAX (0, i - j);
1072
1073     /* now run the diagonal line, end condition is the left or bottom
1074      * border */
1075     while (k < caps2->structs->len) {
1076       struct1 = gst_caps_get_structure (caps1, j);
1077       struct2 = gst_caps_get_structure (caps2, k);
1078
1079       istruct = gst_caps_structure_intersect (struct1, struct2);
1080
1081       gst_caps_append_structure (dest, istruct);
1082       /* move down left */
1083       k++;
1084       if (j == 0)
1085         break;                  /* so we don't roll back to G_MAXUINT */
1086       j--;
1087     }
1088   }
1089   return dest;
1090 }
1091
1092 typedef struct
1093 {
1094   const GstStructure *subtract_from;
1095   GSList *put_into;
1096 }
1097 SubtractionEntry;
1098
1099
1100 static gboolean
1101 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1102     gpointer user_data)
1103 {
1104   SubtractionEntry *e = user_data;
1105   GValue subtraction = { 0, };
1106   const GValue *other;
1107   GstStructure *structure;
1108
1109   other = gst_structure_id_get_value (e->subtract_from, field_id);
1110   if (!other) {
1111     return FALSE;
1112   }
1113   if (!gst_value_subtract (&subtraction, other, value))
1114     return TRUE;
1115   if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1116     g_value_unset (&subtraction);
1117     return FALSE;
1118   } else {
1119     structure = gst_structure_copy (e->subtract_from);
1120     gst_structure_id_set_value (structure, field_id, &subtraction);
1121     g_value_unset (&subtraction);
1122     e->put_into = g_slist_prepend (e->put_into, structure);
1123     return TRUE;
1124   }
1125 }
1126
1127 static gboolean
1128 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1129     const GstStructure * subtrahend)
1130 {
1131   SubtractionEntry e;
1132   gboolean ret;
1133
1134   e.subtract_from = minuend;
1135   e.put_into = NULL;
1136
1137   ret = gst_structure_foreach ((GstStructure *) subtrahend,
1138       gst_caps_structure_subtract_field, &e);
1139   if (ret) {
1140     *into = e.put_into;
1141   } else {
1142     GSList *walk;
1143
1144     for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1145       gst_structure_free (walk->data);
1146     }
1147     g_slist_free (e.put_into);
1148   }
1149   return ret;
1150 }
1151
1152 /**
1153  * gst_caps_subtract:
1154  * @minuend: #GstCaps to substract from
1155  * @subtrahend: #GstCaps to substract
1156  *
1157  * Subtracts the @subtrahend from the @minuend.
1158  * <note>This function does not work reliably if optional properties for caps
1159  * are included on one caps and omitted on the other.</note>
1160  *
1161  * Returns: the resulting caps
1162  */
1163 GstCaps *
1164 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1165 {
1166   guint i, j;
1167   GstStructure *min;
1168   GstStructure *sub;
1169   GstCaps *dest = NULL, *src;
1170
1171   g_return_val_if_fail (minuend != NULL, NULL);
1172   g_return_val_if_fail (subtrahend != NULL, NULL);
1173
1174   if (gst_caps_is_empty (minuend) || gst_caps_is_any (subtrahend)) {
1175     return gst_caps_new_empty ();
1176   }
1177   if (gst_caps_is_empty (subtrahend))
1178     return gst_caps_copy (minuend);
1179
1180   /* FIXME: Do we want this here or above?
1181      The reason we need this is that there is no definition about what
1182      ANY means for specific types, so it's not possible to reduce ANY partially
1183      You can only remove everything or nothing and that is done above.
1184      Note: there's a test that checks this behaviour. */
1185   g_return_val_if_fail (!gst_caps_is_any (minuend), NULL);
1186   g_assert (subtrahend->structs->len > 0);
1187
1188   src = gst_caps_copy (minuend);
1189   for (i = 0; i < subtrahend->structs->len; i++) {
1190     sub = gst_caps_get_structure (subtrahend, i);
1191     if (dest) {
1192       gst_caps_unref (src);
1193       src = dest;
1194     }
1195     dest = gst_caps_new_empty ();
1196     for (j = 0; j < src->structs->len; j++) {
1197       min = gst_caps_get_structure (src, j);
1198       if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1199         GSList *list;
1200
1201         if (gst_caps_structure_subtract (&list, min, sub)) {
1202           GSList *walk;
1203
1204           for (walk = list; walk; walk = g_slist_next (walk)) {
1205             gst_caps_append_structure (dest, (GstStructure *) walk->data);
1206           }
1207           g_slist_free (list);
1208         } else {
1209           gst_caps_append_structure (dest, gst_structure_copy (min));
1210         }
1211       } else {
1212         gst_caps_append_structure (dest, gst_structure_copy (min));
1213       }
1214     }
1215     if (gst_caps_is_empty (dest)) {
1216       gst_caps_unref (src);
1217       return dest;
1218     }
1219   }
1220
1221   gst_caps_unref (src);
1222   gst_caps_do_simplify (dest);
1223   return dest;
1224 }
1225
1226 /**
1227  * gst_caps_union:
1228  * @caps1: a #GstCaps to union
1229  * @caps2: a #GstCaps to union
1230  *
1231  * Creates a new #GstCaps that contains all the formats that are in
1232  * either @caps1 and @caps2.
1233  *
1234  * Returns: the new #GstCaps
1235  */
1236 GstCaps *
1237 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1238 {
1239   GstCaps *dest1;
1240   GstCaps *dest2;
1241
1242   if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2))
1243     return gst_caps_new_any ();
1244
1245   dest1 = gst_caps_copy (caps1);
1246   dest2 = gst_caps_copy (caps2);
1247   gst_caps_append (dest1, dest2);
1248
1249   gst_caps_do_simplify (dest1);
1250   return dest1;
1251 }
1252
1253 typedef struct _NormalizeForeach
1254 {
1255   GstCaps *caps;
1256   GstStructure *structure;
1257 }
1258 NormalizeForeach;
1259
1260 static gboolean
1261 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1262 {
1263   NormalizeForeach *nf = (NormalizeForeach *) ptr;
1264   GValue val = { 0 };
1265   guint i;
1266
1267   if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1268     for (i = 1; i < gst_value_list_get_size (value); i++) {
1269       const GValue *v = gst_value_list_get_value (value, i);
1270       GstStructure *structure = gst_structure_copy (nf->structure);
1271
1272       gst_structure_id_set_value (structure, field_id, v);
1273       gst_caps_append_structure (nf->caps, structure);
1274     }
1275
1276     gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1277     gst_structure_id_set_value (nf->structure, field_id, &val);
1278     g_value_unset (&val);
1279
1280     return FALSE;
1281   }
1282   return TRUE;
1283 }
1284
1285 /**
1286  * gst_caps_normalize:
1287  * @caps: a #GstCaps to normalize
1288  *
1289  * Creates a new #GstCaps that represents the same set of formats as
1290  * @caps, but contains no lists.  Each list is expanded into separate
1291  * @GstStructures.
1292  *
1293  * Returns: the new #GstCaps
1294  */
1295 GstCaps *
1296 gst_caps_normalize (const GstCaps * caps)
1297 {
1298   NormalizeForeach nf;
1299   GstCaps *newcaps;
1300   guint i;
1301
1302   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1303
1304   newcaps = gst_caps_copy (caps);
1305   nf.caps = newcaps;
1306
1307   for (i = 0; i < newcaps->structs->len; i++) {
1308     nf.structure = gst_caps_get_structure (newcaps, i);
1309
1310     while (!gst_structure_foreach (nf.structure,
1311             gst_caps_normalize_foreach, &nf));
1312   }
1313
1314   return newcaps;
1315 }
1316
1317 static gint
1318 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1319 {
1320   gint ret;
1321   const GstStructure *struct1 = *((const GstStructure **) one);
1322   const GstStructure *struct2 = *((const GstStructure **) two);
1323
1324   /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1325      So what's the best way? */
1326   ret = strcmp (gst_structure_get_name (struct1),
1327       gst_structure_get_name (struct2));
1328   if (ret)
1329     return ret;
1330
1331   return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1332 }
1333
1334 typedef struct
1335 {
1336   GQuark name;
1337   GValue value;
1338   GstStructure *compare;
1339 }
1340 UnionField;
1341
1342 static gboolean
1343 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1344     gpointer user_data)
1345 {
1346   UnionField *u = user_data;
1347   const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1348
1349   if (!val) {
1350     if (u->name)
1351       g_value_unset (&u->value);
1352     return FALSE;
1353   }
1354   if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1355     return TRUE;
1356   if (u->name) {
1357     g_value_unset (&u->value);
1358     return FALSE;
1359   }
1360   u->name = field_id;
1361   gst_value_union (&u->value, val, value);
1362   return TRUE;
1363 }
1364
1365 static gboolean
1366 gst_caps_structure_simplify (GstStructure ** result,
1367     const GstStructure * simplify, GstStructure * compare)
1368 {
1369   GSList *list;
1370   UnionField field = { 0, {0,}, NULL };
1371
1372   /* try to subtract to get a real subset */
1373   if (gst_caps_structure_subtract (&list, simplify, compare)) {
1374     switch (g_slist_length (list)) {
1375       case 0:
1376         *result = NULL;
1377         return TRUE;
1378       case 1:
1379         *result = list->data;
1380         g_slist_free (list);
1381         return TRUE;
1382       default:
1383       {
1384         GSList *walk;
1385
1386         for (walk = list; walk; walk = g_slist_next (walk)) {
1387           gst_structure_free (walk->data);
1388         }
1389         g_slist_free (list);
1390         break;
1391       }
1392     }
1393   }
1394
1395   /* try to union both structs */
1396   field.compare = compare;
1397   if (gst_structure_foreach ((GstStructure *) simplify,
1398           gst_caps_structure_figure_out_union, &field)) {
1399     gboolean ret = FALSE;
1400
1401     /* now we know all of simplify's fields are the same in compare
1402      * but at most one field: field.name */
1403     if (G_IS_VALUE (&field.value)) {
1404       if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1405         gst_structure_id_set_value (compare, field.name, &field.value);
1406         *result = NULL;
1407         ret = TRUE;
1408       }
1409       g_value_unset (&field.value);
1410     } else if (gst_structure_n_fields (simplify) <=
1411         gst_structure_n_fields (compare)) {
1412       /* compare is just more specific, will be optimized away later */
1413       /* FIXME: do this here? */
1414       GST_LOG ("found a case that will be optimized later.");
1415     } else {
1416       gchar *one = gst_structure_to_string (simplify);
1417       gchar *two = gst_structure_to_string (compare);
1418
1419       GST_ERROR
1420           ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1421           one, two);
1422       g_free (one);
1423       g_free (two);
1424     }
1425     return ret;
1426   }
1427
1428   return FALSE;
1429 }
1430
1431 static void
1432 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1433     GstStructure * new, gint i)
1434 {
1435   gst_structure_set_parent_refcount (old, NULL);
1436   gst_structure_free (old);
1437   gst_structure_set_parent_refcount (new, &caps->refcount);
1438   g_ptr_array_index (caps->structs, i) = new;
1439 }
1440
1441 /**
1442  * gst_caps_do_simplify:
1443  * @caps: a #GstCaps to simplify
1444  *
1445  * Modifies the given @caps inplace into a representation that represents the
1446  * same set of formats, but in a simpler form.  Component structures that are
1447  * identical are merged.  Component structures that have values that can be
1448  * merged are also merged.
1449  *
1450  * Returns: TRUE, if the caps could be simplified
1451  */
1452 gboolean
1453 gst_caps_do_simplify (GstCaps * caps)
1454 {
1455   GstStructure *simplify, *compare, *result = NULL;
1456   gint i, j, start;
1457   gboolean changed = FALSE;
1458
1459   g_return_val_if_fail (caps != NULL, FALSE);
1460   g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1461
1462   if (gst_caps_get_size (caps) < 2)
1463     return FALSE;
1464
1465   g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1466
1467   start = caps->structs->len - 1;
1468   for (i = caps->structs->len - 1; i >= 0; i--) {
1469     simplify = gst_caps_get_structure (caps, i);
1470     if (gst_structure_get_name_id (simplify) !=
1471         gst_structure_get_name_id (gst_caps_get_structure (caps, start)))
1472       start = i;
1473     for (j = start; j >= 0; j--) {
1474       if (j == i)
1475         continue;
1476       compare = gst_caps_get_structure (caps, j);
1477       if (gst_structure_get_name_id (simplify) !=
1478           gst_structure_get_name_id (compare)) {
1479         break;
1480       }
1481       if (gst_caps_structure_simplify (&result, simplify, compare)) {
1482         if (result) {
1483           gst_caps_switch_structures (caps, simplify, result, i);
1484           simplify = result;
1485         } else {
1486           gst_caps_remove_structure (caps, i);
1487           start--;
1488           break;
1489         }
1490         changed = TRUE;
1491       }
1492     }
1493   }
1494
1495   if (!changed)
1496     return FALSE;
1497
1498   /* gst_caps_do_simplify (caps); */
1499   return TRUE;
1500 }
1501
1502 #ifndef GST_DISABLE_LOADSAVE
1503 /**
1504  * gst_caps_save_thyself:
1505  * @caps: a #GstCaps structure
1506  * @parent: a XML parent node
1507  *
1508  * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1509  *
1510  * Returns: a XML node pointer
1511  */
1512 xmlNodePtr
1513 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1514 {
1515   char *s = gst_caps_to_string (caps);
1516
1517   xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1518   g_free (s);
1519   return parent;
1520 }
1521
1522 /**
1523  * gst_caps_load_thyself:
1524  * @parent: a XML node
1525  *
1526  * Creates a #GstCaps from its XML serialization.
1527  *
1528  * Returns: a new #GstCaps structure
1529  */
1530 GstCaps *
1531 gst_caps_load_thyself (xmlNodePtr parent)
1532 {
1533   if (strcmp ("caps", (char *) parent->name) == 0) {
1534     return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1535   }
1536
1537   return NULL;
1538 }
1539 #endif
1540
1541 /* utility */
1542
1543 /**
1544  * gst_caps_replace:
1545  * @caps: a pointer to #GstCaps
1546  * @newcaps: a #GstCaps to replace *caps
1547  *
1548  * Replaces *caps with @newcaps.  Unrefs the #GstCaps in the location
1549  * pointed to by @caps, if applicable, then modifies @caps to point to
1550  * @newcaps. An additional ref on @newcaps is taken.
1551  *
1552  * This function does not take any locks so you might want to lock
1553  * the object owning @caps pointer.
1554  */
1555 void
1556 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1557 {
1558   GstCaps *oldcaps;
1559
1560   g_return_if_fail (caps != NULL);
1561
1562   oldcaps = *caps;
1563
1564   if (newcaps != oldcaps) {
1565     if (newcaps)
1566       gst_caps_ref (newcaps);
1567
1568     *caps = newcaps;
1569
1570     if (oldcaps)
1571       gst_caps_unref (oldcaps);
1572   }
1573 }
1574
1575 /**
1576  * gst_caps_to_string:
1577  * @caps: a #GstCaps
1578  *
1579  * Converts @caps to a string representation.  This string representation
1580  * can be converted back to a #GstCaps by gst_caps_from_string().
1581  *
1582  * For debugging purposes its easier to do something like this:
1583  * <programlisting>
1584  *  GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1585  * </programlisting>
1586  * This prints the caps in human readble form.
1587  *
1588  * Returns: a newly allocated string representing @caps.
1589  */
1590 gchar *
1591 gst_caps_to_string (const GstCaps * caps)
1592 {
1593   guint i;
1594   GString *s;
1595
1596   /* NOTE:  This function is potentially called by the debug system,
1597    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1598    * should be careful to avoid recursion.  This includes any functions
1599    * called by gst_caps_to_string.  In particular, calls should
1600    * not use the GST_PTR_FORMAT extension.  */
1601
1602   if (caps == NULL) {
1603     return g_strdup ("NULL");
1604   }
1605   if (gst_caps_is_any (caps)) {
1606     return g_strdup ("ANY");
1607   }
1608   if (gst_caps_is_empty (caps)) {
1609     return g_strdup ("EMPTY");
1610   }
1611
1612   s = g_string_new ("");
1613   for (i = 0; i < caps->structs->len; i++) {
1614     GstStructure *structure;
1615     char *sstr;
1616
1617     if (i > 0)
1618       g_string_append (s, "; ");
1619
1620     structure = gst_caps_get_structure (caps, i);
1621     sstr = gst_structure_to_string (structure);
1622     g_string_append (s, sstr);
1623     g_free (sstr);
1624   }
1625
1626   return g_string_free (s, FALSE);
1627 }
1628
1629 static gboolean
1630 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1631 {
1632   GstStructure *structure;
1633   gchar *s;
1634
1635   g_return_val_if_fail (string, FALSE);
1636   if (strcmp ("ANY", string) == 0) {
1637     caps->flags = GST_CAPS_FLAGS_ANY;
1638     return TRUE;
1639   }
1640   if (strcmp ("EMPTY", string) == 0) {
1641     return TRUE;
1642   }
1643
1644   structure = gst_structure_from_string (string, &s);
1645   if (structure == NULL) {
1646     return FALSE;
1647   }
1648   gst_caps_append_structure (caps, structure);
1649
1650   while (*s == ';') {
1651     s++;
1652     while (g_ascii_isspace (*s))
1653       s++;
1654     structure = gst_structure_from_string (s, &s);
1655     if (structure == NULL) {
1656       return FALSE;
1657     }
1658     gst_caps_append_structure (caps, structure);
1659     while (g_ascii_isspace (*s))
1660       s++;
1661   }
1662
1663   if (*s != 0) {
1664     return FALSE;
1665   }
1666
1667   return TRUE;
1668 }
1669
1670 /**
1671  * gst_caps_from_string:
1672  * @string: a string to convert to #GstCaps
1673  *
1674  * Converts @caps from a string representation.
1675  *
1676  * Returns: a newly allocated #GstCaps
1677  */
1678 GstCaps *
1679 gst_caps_from_string (const gchar * string)
1680 {
1681   GstCaps *caps;
1682
1683   caps = gst_caps_new_empty ();
1684   if (gst_caps_from_string_inplace (caps, string)) {
1685     return caps;
1686   } else {
1687     gst_caps_unref (caps);
1688     return NULL;
1689   }
1690 }
1691
1692 static void
1693 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1694 {
1695   g_return_if_fail (G_IS_VALUE (src_value));
1696   g_return_if_fail (G_IS_VALUE (dest_value));
1697   g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1698   g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1699       || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1700
1701   dest_value->data[0].v_pointer =
1702       gst_caps_to_string (src_value->data[0].v_pointer);
1703 }
1704
1705 static GstCaps *
1706 gst_caps_copy_conditional (GstCaps * src)
1707 {
1708   if (src) {
1709     return gst_caps_ref (src);
1710   } else {
1711     return NULL;
1712   }
1713 }