gst/gstcaps.c

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