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