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 #GstRegistry along with
  30  * a description of the #GstElement.
  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",
  47  *       "format", G_TYPE_STRING, "I420"),
  48  *       "framerate", GST_TYPE_FRACTION, 25, 1,
  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 2007-02-13 (0.10.10)
  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 #include <gobject/gvaluecollector.h>
  75
  76 #define DEBUG_REFCOUNT
  77
  78
  79 #define GST_CAPS_ARRAY(c) ((GPtrArray *)((c)->priv))
  80
  81 #define GST_CAPS_LEN(c)   (GST_CAPS_ARRAY(c)->len)
  82
  83 #define IS_WRITABLE(caps) \
  84   (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
  85
  86 /* same as gst_caps_is_any () */
  87 #define CAPS_IS_ANY(caps)                               \
  88   (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAGS_ANY)
  89
  90 /* same as gst_caps_is_empty () */
  91 #define CAPS_IS_EMPTY(caps)                             \
  92   (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
  93
  94 #define CAPS_IS_EMPTY_SIMPLE(caps)                                      \
  95   ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
  96
  97 /* quick way to get a caps structure at an index without doing a type or array
  98  * length check */
  99 #define gst_caps_get_structure_unchecked(caps, index) \
 100      ((GstStructure *)g_ptr_array_index (GST_CAPS_ARRAY (caps), (index)))
 101 /* quick way to append a structure without checking the args */
 102 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
 103   GstStructure *__s=structure;                                      \
 104   if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps)))         \
 105     g_ptr_array_add (GST_CAPS_ARRAY (caps), __s);                             \
 106 }G_STMT_END
 107
 108 /* lock to protect multiple invocations of static caps to caps conversion */
 109 G_LOCK_DEFINE_STATIC (static_caps_lock);
 110
 111 static void gst_caps_transform_to_string (const GValue * src_value,
 112     GValue * dest_value);
 113 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
 114     const gchar * string);
 115
 116 GType _gst_caps_type = 0;
 117
 118 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
 119
 120 void
 121 _priv_gst_caps_initialize (void)
 122 {
 123   _gst_caps_type = gst_caps_get_type ();
 124
 125   g_value_register_transform_func (_gst_caps_type,
 126       G_TYPE_STRING, gst_caps_transform_to_string);
 127 }
 128
 129 static GstCaps *
 130 _gst_caps_copy (const GstCaps * caps)
 131 {
 132   GstCaps *newcaps;
 133   GstStructure *structure;
 134   guint i, n;
 135
 136   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 137
 138   newcaps = gst_caps_new_empty ();
 139   GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
 140   n = GST_CAPS_LEN (caps);
 141
 142   for (i = 0; i < n; i++) {
 143     structure = gst_caps_get_structure_unchecked (caps, i);
 144     gst_caps_append_structure (newcaps, gst_structure_copy (structure));
 145   }
 146
 147   return newcaps;
 148 }
 149
 150 /* creation/deletion */
 151 static void
 152 _gst_caps_free (GstCaps * caps)
 153 {
 154   GstStructure *structure;
 155   guint i, len;
 156
 157   /* The refcount must be 0, but since we're only called by gst_caps_unref,
 158    * don't bother testing. */
 159   len = GST_CAPS_LEN (caps);
 160   /* This can be used to get statistics about caps sizes */
 161   /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
 162   for (i = 0; i < len; i++) {
 163     structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
 164     gst_structure_set_parent_refcount (structure, NULL);
 165     gst_structure_free (structure);
 166   }
 167   g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
 168
 169 #ifdef DEBUG_REFCOUNT
 170   GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
 171 #endif
 172   g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
 173 }
 174
 175 static void
 176 gst_caps_init (GstCaps * caps, gsize size)
 177 {
 178   gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
 179
 180   caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
 181   caps->mini_object.dispose = NULL;
 182   caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
 183
 184   /* the 32 has been determined by logging caps sizes in _gst_caps_free
 185    * but g_ptr_array uses 16 anyway if it expands once, so this does not help
 186    * in practise
 187    * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
 188    */
 189   caps->priv = g_ptr_array_new ();
 190 }
 191
 192 /**
 193  * gst_caps_new_empty:
 194  *
 195  * Creates a new #GstCaps that is empty.  That is, the returned
 196  * #GstCaps contains no media formats.
 197  * Caller is responsible for unreffing the returned caps.
 198  *
 199  * Returns: (transfer full): the new #GstCaps
 200  */
 201 GstCaps *
 202 gst_caps_new_empty (void)
 203 {
 204   GstCaps *caps;
 205
 206   caps = g_slice_new (GstCaps);
 207
 208   gst_caps_init (caps, sizeof (GstCaps));
 209
 210 #ifdef DEBUG_REFCOUNT
 211   GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
 212 #endif
 213
 214   return caps;
 215 }
 216
 217 /**
 218  * gst_caps_new_any:
 219  *
 220  * Creates a new #GstCaps that indicates that it is compatible with
 221  * any media format.
 222  *
 223  * Returns: (transfer full): the new #GstCaps
 224  */
 225 GstCaps *
 226 gst_caps_new_any (void)
 227 {
 228   GstCaps *caps = gst_caps_new_empty ();
 229
 230   GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAGS_ANY);
 231
 232   return caps;
 233 }
 234
 235 /**
 236  * gst_caps_new_simple:
 237  * @media_type: the media type of the structure
 238  * @fieldname: first field to set
 239  * @...: additional arguments
 240  *
 241  * Creates a new #GstCaps that contains one #GstStructure.  The
 242  * structure is defined by the arguments, which have the same format
 243  * as gst_structure_new().
 244  * Caller is responsible for unreffing the returned caps.
 245  *
 246  * Returns: (transfer full): the new #GstCaps
 247  */
 248 GstCaps *
 249 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
 250 {
 251   GstCaps *caps;
 252   GstStructure *structure;
 253   va_list var_args;
 254
 255   caps = gst_caps_new_empty ();
 256
 257   va_start (var_args, fieldname);
 258   structure = gst_structure_new_valist (media_type, fieldname, var_args);
 259   va_end (var_args);
 260
 261   if (structure)
 262     gst_caps_append_structure_unchecked (caps, structure);
 263   else
 264     gst_caps_replace (&caps, NULL);
 265
 266   return caps;
 267 }
 268
 269 /**
 270  * gst_caps_new_full:
 271  * @struct1: the first structure to add
 272  * @...: additional structures to add
 273  *
 274  * Creates a new #GstCaps and adds all the structures listed as
 275  * arguments.  The list must be NULL-terminated.  The structures
 276  * are not copied; the returned #GstCaps owns the structures.
 277  *
 278  * Returns: (transfer full): the new #GstCaps
 279  */
 280 GstCaps *
 281 gst_caps_new_full (GstStructure * struct1, ...)
 282 {
 283   GstCaps *caps;
 284   va_list var_args;
 285
 286   va_start (var_args, struct1);
 287   caps = gst_caps_new_full_valist (struct1, var_args);
 288   va_end (var_args);
 289
 290   return caps;
 291 }
 292
 293 /**
 294  * gst_caps_new_full_valist:
 295  * @structure: the first structure to add
 296  * @var_args: additional structures to add
 297  *
 298  * Creates a new #GstCaps and adds all the structures listed as
 299  * arguments.  The list must be NULL-terminated.  The structures
 300  * are not copied; the returned #GstCaps owns the structures.
 301  *
 302  * Returns: (transfer full): the new #GstCaps
 303  */
 304 GstCaps *
 305 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
 306 {
 307   GstCaps *caps;
 308
 309   caps = gst_caps_new_empty ();
 310
 311   while (structure) {
 312     gst_caps_append_structure_unchecked (caps, structure);
 313     structure = va_arg (var_args, GstStructure *);
 314   }
 315
 316   return caps;
 317 }
 318
 319 GType
 320 gst_static_caps_get_type (void)
 321 {
 322   static GType staticcaps_type = 0;
 323
 324   if (G_UNLIKELY (staticcaps_type == 0)) {
 325     staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
 326   }
 327   return staticcaps_type;
 328 }
 329
 330
 331 /**
 332  * gst_static_caps_get:
 333  * @static_caps: the #GstStaticCaps to convert
 334  *
 335  * Converts a #GstStaticCaps to a #GstCaps.
 336  *
 337  * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
 338  *     Since the core holds an additional ref to the returned caps,
 339  *     use gst_caps_make_writable() on the returned caps to modify it.
 340  */
 341 GstCaps *
 342 gst_static_caps_get (GstStaticCaps * static_caps)
 343 {
 344   GstCaps *caps;
 345
 346   g_return_val_if_fail (static_caps != NULL, NULL);
 347
 348   caps = (GstCaps *) static_caps;
 349
 350   /* refcount is 0 when we need to convert */
 351   if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) == 0)) {
 352     const char *string;
 353     GstCaps temp;
 354
 355     G_LOCK (static_caps_lock);
 356     /* check if other thread already updated */
 357     if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) > 0))
 358       goto done;
 359
 360     string = static_caps->string;
 361
 362     if (G_UNLIKELY (string == NULL))
 363       goto no_string;
 364
 365     GST_CAT_TRACE (GST_CAT_CAPS, "creating %p", static_caps);
 366
 367     /* we construct the caps on the stack, then copy over the struct into our
 368      * real caps, refcount last. We do this because we must leave the refcount
 369      * of the result caps to 0 so that other threads don't run away with the
 370      * caps while we are constructing it. */
 371     gst_caps_init (&temp, sizeof (GstCaps));
 372
 373     /* convert to string */
 374     if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
 375       g_critical ("Could not convert static caps \"%s\"", string);
 376
 377     GST_MINI_OBJECT_REFCOUNT (&temp) = 0;
 378     memcpy (caps, &temp, sizeof (GstCaps));
 379     gst_caps_ref (caps);
 380
 381     GST_CAT_TRACE (GST_CAT_CAPS, "created %p", static_caps);
 382   done:
 383     G_UNLOCK (static_caps_lock);
 384   }
 385   /* ref the caps, makes it not writable */
 386   gst_caps_ref (caps);
 387
 388   return caps;
 389
 390   /* ERRORS */
 391 no_string:
 392   {
 393     G_UNLOCK (static_caps_lock);
 394     g_warning ("static caps %p string is NULL", static_caps);
 395     return NULL;
 396   }
 397 }
 398
 399 /**
 400  * gst_static_caps_cleanup:
 401  * @static_caps: the #GstStaticCaps to convert
 402  *
 403  * Clean up the caps contained in @static_caps when the refcount is 0.
 404  */
 405 void
 406 gst_static_caps_cleanup (GstStaticCaps * static_caps)
 407 {
 408   GstCaps *caps = (GstCaps *) static_caps;
 409
 410   /* FIXME: this is not threadsafe */
 411   if (GST_CAPS_REFCOUNT_VALUE (caps) == 1) {
 412     GstStructure *structure;
 413     guint i, clen;
 414
 415     clen = GST_CAPS_LEN (caps);
 416
 417     for (i = 0; i < clen; i++) {
 418       structure = (GstStructure *) gst_caps_get_structure (caps, i);
 419       gst_structure_set_parent_refcount (structure, NULL);
 420       gst_structure_free (structure);
 421     }
 422     g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
 423     GST_CAPS_REFCOUNT (caps) = 0;
 424   }
 425 }
 426
 427 /* manipulation */
 428
 429 static GstStructure *
 430 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
 431 {
 432   /* don't use index_fast, gst_caps_do_simplify relies on the order */
 433   GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
 434
 435   gst_structure_set_parent_refcount (s, NULL);
 436   return s;
 437 }
 438
 439 /**
 440  * gst_caps_steal_structure:
 441  * @caps: the #GstCaps to retrieve from
 442  * @index: Index of the structure to retrieve
 443  *
 444  * Retrieves the stucture with the given index from the list of structures
 445  * contained in @caps. The caller becomes the owner of the returned structure.
 446  *
 447  * Returns: (transfer full): a pointer to the #GstStructure corresponding
 448  *     to @index.
 449  *
 450  * Since: 0.10.30
 451  */
 452 GstStructure *
 453 gst_caps_steal_structure (GstCaps * caps, guint index)
 454 {
 455   g_return_val_if_fail (caps != NULL, NULL);
 456   g_return_val_if_fail (IS_WRITABLE (caps), NULL);
 457
 458   if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
 459     return NULL;
 460
 461   return gst_caps_remove_and_get_structure (caps, index);
 462 }
 463
 464 /**
 465  * gst_caps_append:
 466  * @caps1: the #GstCaps that will be appended to
 467  * @caps2: (transfer full): the #GstCaps to append
 468  *
 469  * Appends the structures contained in @caps2 to @caps1. The structures in
 470  * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
 471  * freed. If either caps is ANY, the resulting caps will be ANY.
 472  */
 473 void
 474 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
 475 {
 476   GstStructure *structure;
 477   int i;
 478
 479   g_return_if_fail (GST_IS_CAPS (caps1));
 480   g_return_if_fail (GST_IS_CAPS (caps2));
 481   g_return_if_fail (IS_WRITABLE (caps1));
 482   g_return_if_fail (IS_WRITABLE (caps2));
 483
 484   if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
 485     /* FIXME: this leaks */
 486     GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
 487     for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
 488       structure = gst_caps_remove_and_get_structure (caps2, i);
 489       gst_structure_free (structure);
 490     }
 491   } else {
 492     for (i = GST_CAPS_LEN (caps2); i; i--) {
 493       structure = gst_caps_remove_and_get_structure (caps2, 0);
 494       gst_caps_append_structure_unchecked (caps1, structure);
 495     }
 496   }
 497   gst_caps_unref (caps2);       /* guaranteed to free it */
 498 }
 499
 500 /**
 501  * gst_caps_merge:
 502  * @caps1: the #GstCaps that will take the new entries
 503  * @caps2: (transfer full): the #GstCaps to merge in
 504  *
 505  * Appends the structures contained in @caps2 to @caps1 if they are not yet
 506  * expressed by @caps1. The structures in @caps2 are not copied -- they are
 507  * transferred to @caps1, and then @caps2 is freed.
 508  * If either caps is ANY, the resulting caps will be ANY.
 509  *
 510  * Since: 0.10.10
 511  */
 512 void
 513 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
 514 {
 515   GstStructure *structure;
 516   int i;
 517
 518   g_return_if_fail (GST_IS_CAPS (caps1));
 519   g_return_if_fail (GST_IS_CAPS (caps2));
 520   g_return_if_fail (IS_WRITABLE (caps1));
 521   g_return_if_fail (IS_WRITABLE (caps2));
 522
 523   if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
 524     for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
 525       structure = gst_caps_remove_and_get_structure (caps2, i);
 526       gst_structure_free (structure);
 527     }
 528   } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
 529     GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
 530     for (i = GST_CAPS_LEN (caps1) - 1; i >= 0; i--) {
 531       structure = gst_caps_remove_and_get_structure (caps1, i);
 532       gst_structure_free (structure);
 533     }
 534   } else {
 535     for (i = GST_CAPS_LEN (caps2); i; i--) {
 536       structure = gst_caps_remove_and_get_structure (caps2, 0);
 537       gst_caps_merge_structure (caps1, structure);
 538     }
 539     /* this is too naive
 540        GstCaps *com = gst_caps_intersect (caps1, caps2);
 541        GstCaps *add = gst_caps_subtract (caps2, com);
 542
 543        GST_DEBUG ("common : %d", gst_caps_get_size (com));
 544        GST_DEBUG ("adding : %d", gst_caps_get_size (add));
 545        gst_caps_append (caps1, add);
 546        gst_caps_unref (com);
 547      */
 548   }
 549   gst_caps_unref (caps2);       /* guaranteed to free it */
 550 }
 551
 552 /**
 553  * gst_caps_append_structure:
 554  * @caps: the #GstCaps that will be appended to
 555  * @structure: (transfer full): the #GstStructure to append
 556  *
 557  * Appends @structure to @caps.  The structure is not copied; @caps
 558  * becomes the owner of @structure.
 559  */
 560 void
 561 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
 562 {
 563   g_return_if_fail (GST_IS_CAPS (caps));
 564   g_return_if_fail (IS_WRITABLE (caps));
 565
 566   if (G_LIKELY (structure)) {
 567     gst_caps_append_structure_unchecked (caps, structure);
 568   }
 569 }
 570
 571 /**
 572  * gst_caps_remove_structure:
 573  * @caps: the #GstCaps to remove from
 574  * @idx: Index of the structure to remove
 575  *
 576  * removes the stucture with the given index from the list of structures
 577  * contained in @caps.
 578  */
 579 void
 580 gst_caps_remove_structure (GstCaps * caps, guint idx)
 581 {
 582   GstStructure *structure;
 583
 584   g_return_if_fail (caps != NULL);
 585   g_return_if_fail (idx <= gst_caps_get_size (caps));
 586   g_return_if_fail (IS_WRITABLE (caps));
 587
 588   structure = gst_caps_remove_and_get_structure (caps, idx);
 589   gst_structure_free (structure);
 590 }
 591
 592 /**
 593  * gst_caps_merge_structure:
 594  * @caps: the #GstCaps that will the new structure
 595  * @structure: (transfer full): the #GstStructure to merge
 596  *
 597  * Appends @structure to @caps if its not already expressed by @caps.  The
 598  * structure is not copied; @caps becomes the owner of @structure.
 599  */
 600 void
 601 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
 602 {
 603   g_return_if_fail (GST_IS_CAPS (caps));
 604   g_return_if_fail (IS_WRITABLE (caps));
 605
 606   if (G_LIKELY (structure)) {
 607     GstStructure *structure1;
 608     int i;
 609     gboolean unique = TRUE;
 610
 611     /* check each structure */
 612     for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
 613       structure1 = gst_caps_get_structure_unchecked (caps, i);
 614       /* if structure is a subset of structure1, then skip it */
 615       if (gst_structure_is_subset (structure, structure1)) {
 616         unique = FALSE;
 617         break;
 618       }
 619     }
 620     if (unique) {
 621       gst_caps_append_structure_unchecked (caps, structure);
 622     } else {
 623       gst_structure_free (structure);
 624     }
 625   }
 626 }
 627
 628 /**
 629  * gst_caps_get_size:
 630  * @caps: a #GstCaps
 631  *
 632  * Gets the number of structures contained in @caps.
 633  *
 634  * Returns: the number of structures that @caps contains
 635  */
 636 guint
 637 gst_caps_get_size (const GstCaps * caps)
 638 {
 639   g_return_val_if_fail (GST_IS_CAPS (caps), 0);
 640
 641   return GST_CAPS_LEN (caps);
 642 }
 643
 644 /**
 645  * gst_caps_get_structure:
 646  * @caps: a #GstCaps
 647  * @index: the index of the structure
 648  *
 649  * Finds the structure in @caps that has the index @index, and
 650  * returns it.
 651  *
 652  * WARNING: This function takes a const GstCaps *, but returns a
 653  * non-const GstStructure *.  This is for programming convenience --
 654  * the caller should be aware that structures inside a constant
 655  * #GstCaps should not be modified. However, if you know the caps
 656  * are writable, either because you have just copied them or made
 657  * them writable with gst_caps_make_writable(), you may modify the
 658  * structure returned in the usual way, e.g. with functions like
 659  * gst_structure_set().
 660  *
 661  * You do not need to free or unref the structure returned, it
 662  * belongs to the #GstCaps.
 663  *
 664  * Returns: (transfer none): a pointer to the #GstStructure corresponding
 665  *     to @index
 666  */
 667 GstStructure *
 668 gst_caps_get_structure (const GstCaps * caps, guint index)
 669 {
 670   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 671   g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
 672
 673   return gst_caps_get_structure_unchecked (caps, index);
 674 }
 675
 676 /**
 677  * gst_caps_copy_nth:
 678  * @caps: the #GstCaps to copy
 679  * @nth: the nth structure to copy
 680  *
 681  * Creates a new #GstCaps and appends a copy of the nth structure
 682  * contained in @caps.
 683  *
 684  * Returns: (transfer full): the new #GstCaps
 685  */
 686 GstCaps *
 687 gst_caps_copy_nth (const GstCaps * caps, guint nth)
 688 {
 689   GstCaps *newcaps;
 690   GstStructure *structure;
 691
 692   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
 693
 694   newcaps = gst_caps_new_empty ();
 695   GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
 696
 697   if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
 698     structure = gst_caps_get_structure_unchecked (caps, nth);
 699     gst_caps_append_structure_unchecked (newcaps,
 700         gst_structure_copy (structure));
 701   }
 702
 703   return newcaps;
 704 }
 705
 706 /**
 707  * gst_caps_truncate:
 708  * @caps: the #GstCaps to truncate
 709  *
 710  * Destructively discard all but the first structure from @caps. Useful when
 711  * fixating. @caps must be writable.
 712  */
 713 void
 714 gst_caps_truncate (GstCaps * caps)
 715 {
 716   gint i;
 717
 718   g_return_if_fail (GST_IS_CAPS (caps));
 719   g_return_if_fail (IS_WRITABLE (caps));
 720
 721   i = GST_CAPS_LEN (caps) - 1;
 722
 723   while (i > 0)
 724     gst_caps_remove_structure (caps, i--);
 725 }
 726
 727 /**
 728  * gst_caps_set_value:
 729  * @caps: a writable caps
 730  * @field: name of the field to set
 731  * @value: value to set the field to
 732  *
 733  * Sets the given @field on all structures of @caps to the given @value.
 734  * This is a convenience function for calling gst_structure_set_value() on
 735  * all structures of @caps.
 736  *
 737  * Since: 0.10.26
 738  **/
 739 void
 740 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
 741 {
 742   guint i, len;
 743
 744   g_return_if_fail (GST_IS_CAPS (caps));
 745   g_return_if_fail (IS_WRITABLE (caps));
 746   g_return_if_fail (field != NULL);
 747   g_return_if_fail (G_IS_VALUE (value));
 748
 749   len = GST_CAPS_LEN (caps);
 750   for (i = 0; i < len; i++) {
 751     GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
 752     gst_structure_set_value (structure, field, value);
 753   }
 754 }
 755
 756 /**
 757  * gst_caps_set_simple_valist:
 758  * @caps: the #GstCaps to set
 759  * @field: first field to set
 760  * @varargs: additional parameters
 761  *
 762  * Sets fields in a #GstCaps.  The arguments must be passed in the same
 763  * manner as gst_structure_set(), and be NULL-terminated.
 764  * <note>Prior to GStreamer version 0.10.26, this function failed when
 765  * @caps was not simple. If your code needs to work with those versions
 766  * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
 767  * is %TRUE for @caps.</note>
 768  */
 769 void
 770 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
 771 {
 772   GValue value = { 0, };
 773
 774   g_return_if_fail (GST_IS_CAPS (caps));
 775   g_return_if_fail (IS_WRITABLE (caps));
 776
 777   while (field) {
 778     GType type;
 779     char *err;
 780
 781     type = va_arg (varargs, GType);
 782
 783     if (G_UNLIKELY (type == G_TYPE_DATE)) {
 784       g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
 785       type = GST_TYPE_DATE;
 786     }
 787     G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
 788     if (G_UNLIKELY (err)) {
 789       g_critical ("%s", err);
 790       return;
 791     }
 792
 793     gst_caps_set_value (caps, field, &value);
 794
 795     g_value_unset (&value);
 796
 797     field = va_arg (varargs, const gchar *);
 798   }
 799 }
 800
 801 /**
 802  * gst_caps_set_simple:
 803  * @caps: the #GstCaps to set
 804  * @field: first field to set
 805  * @...: additional parameters
 806  *
 807  * Sets fields in a #GstCaps.  The arguments must be passed in the same
 808  * manner as gst_structure_set(), and be NULL-terminated.
 809  * <note>Prior to GStreamer version 0.10.26, this function failed when
 810  * @caps was not simple. If your code needs to work with those versions
 811  * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
 812  * is %TRUE for @caps.</note>
 813  */
 814 void
 815 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
 816 {
 817   va_list var_args;
 818
 819   g_return_if_fail (GST_IS_CAPS (caps));
 820   g_return_if_fail (IS_WRITABLE (caps));
 821
 822   va_start (var_args, field);
 823   gst_caps_set_simple_valist (caps, field, var_args);
 824   va_end (var_args);
 825 }
 826
 827 /* tests */
 828
 829 /**
 830  * gst_caps_is_any:
 831  * @caps: the #GstCaps to test
 832  *
 833  * Determines if @caps represents any media format.
 834  *
 835  * Returns: TRUE if @caps represents any format.
 836  */
 837 gboolean
 838 gst_caps_is_any (const GstCaps * caps)
 839 {
 840   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 841
 842   return (CAPS_IS_ANY (caps));
 843 }
 844
 845 /**
 846  * gst_caps_is_empty:
 847  * @caps: the #GstCaps to test
 848  *
 849  * Determines if @caps represents no media formats.
 850  *
 851  * Returns: TRUE if @caps represents no formats.
 852  */
 853 gboolean
 854 gst_caps_is_empty (const GstCaps * caps)
 855 {
 856   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 857
 858   if (CAPS_IS_ANY (caps))
 859     return FALSE;
 860
 861   return CAPS_IS_EMPTY_SIMPLE (caps);
 862 }
 863
 864 static gboolean
 865 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
 866     gpointer unused)
 867 {
 868   return gst_value_is_fixed (value);
 869 }
 870
 871 /**
 872  * gst_caps_is_fixed:
 873  * @caps: the #GstCaps to test
 874  *
 875  * Fixed #GstCaps describe exactly one format, that is, they have exactly
 876  * one structure, and each field in the structure describes a fixed type.
 877  * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
 878  *
 879  * Returns: TRUE if @caps is fixed
 880  */
 881 gboolean
 882 gst_caps_is_fixed (const GstCaps * caps)
 883 {
 884   GstStructure *structure;
 885
 886   g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
 887
 888   if (GST_CAPS_LEN (caps) != 1)
 889     return FALSE;
 890
 891   structure = gst_caps_get_structure_unchecked (caps, 0);
 892
 893   return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
 894 }
 895
 896 /**
 897  * gst_caps_is_equal_fixed:
 898  * @caps1: the #GstCaps to test
 899  * @caps2: the #GstCaps to test
 900  *
 901  * Tests if two #GstCaps are equal.  This function only works on fixed
 902  * #GstCaps.
 903  *
 904  * Returns: TRUE if the arguments represent the same format
 905  */
 906 gboolean
 907 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
 908 {
 909   GstStructure *struct1, *struct2;
 910
 911   g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
 912   g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
 913
 914   struct1 = gst_caps_get_structure_unchecked (caps1, 0);
 915   struct2 = gst_caps_get_structure_unchecked (caps2, 0);
 916
 917   return gst_structure_is_equal (struct1, struct2);
 918 }
 919
 920 /**
 921  * gst_caps_is_always_compatible:
 922  * @caps1: the #GstCaps to test
 923  * @caps2: the #GstCaps to test
 924  *
 925  * A given #GstCaps structure is always compatible with another if
 926  * every media format that is in the first is also contained in the
 927  * second.  That is, @caps1 is a subset of @caps2.
 928  *
 929  * Returns: TRUE if @caps1 is a subset of @caps2.
 930  */
 931 gboolean
 932 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
 933 {
 934   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
 935   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
 936
 937   return gst_caps_is_subset (caps1, caps2);
 938 }
 939
 940 /**
 941  * gst_caps_is_subset:
 942  * @subset: a #GstCaps
 943  * @superset: a potentially greater #GstCaps
 944  *
 945  * Checks if all caps represented by @subset are also represented by @superset.
 946  * <note>This function does not work reliably if optional properties for caps
 947  * are included on one caps and omitted on the other.</note>
 948  *
 949  * Returns: %TRUE if @subset is a subset of @superset
 950  */
 951 gboolean
 952 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
 953 {
 954   GstStructure *s1, *s2;
 955   gboolean ret = TRUE;
 956   gint i, j;
 957
 958   g_return_val_if_fail (subset != NULL, FALSE);
 959   g_return_val_if_fail (superset != NULL, FALSE);
 960
 961   if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
 962     return TRUE;
 963   if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
 964     return FALSE;
 965
 966   for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
 967     for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
 968       s1 = gst_caps_get_structure_unchecked (subset, i);
 969       s2 = gst_caps_get_structure_unchecked (superset, j);
 970       if (gst_structure_is_subset (s1, s2)) {
 971         /* If we found a superset, continue with the next
 972          * subset structure */
 973         break;
 974       }
 975     }
 976     /* If we found no superset for this subset structure
 977      * we return FALSE immediately */
 978     if (j == -1) {
 979       ret = FALSE;
 980       break;
 981     }
 982   }
 983
 984   return ret;
 985 }
 986
 987 /**
 988  * gst_caps_is_subset_structure:
 989  * @caps: a #GstCaps
 990  * @structure: a potential #GstStructure subset of @caps
 991  *
 992  * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
 993  * for more information.
 994  *
 995  * Returns: %TRUE if @structure is a subset of @caps
 996  *
 997  * Since: 0.10.35
 998  */
 999 gboolean
1000 gst_caps_is_subset_structure (const GstCaps * caps,
1001     const GstStructure * structure)
1002 {
1003   GstStructure *s;
1004   gint i;
1005
1006   g_return_val_if_fail (caps != NULL, FALSE);
1007   g_return_val_if_fail (structure != NULL, FALSE);
1008
1009   if (CAPS_IS_ANY (caps))
1010     return TRUE;
1011   if (CAPS_IS_EMPTY (caps))
1012     return FALSE;
1013
1014   for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1015     s = gst_caps_get_structure_unchecked (caps, i);
1016     if (gst_structure_is_subset (structure, s)) {
1017       /* If we found a superset return TRUE */
1018       return TRUE;
1019     }
1020   }
1021
1022   return FALSE;
1023 }
1024
1025 /**
1026  * gst_caps_is_equal:
1027  * @caps1: a #GstCaps
1028  * @caps2: another #GstCaps
1029  *
1030  * Checks if the given caps represent the same set of caps.
1031  * <note>This function does not work reliably if optional properties for caps
1032  * are included on one caps and omitted on the other.</note>
1033  *
1034  * This function deals correctly with passing NULL for any of the caps.
1035  *
1036  * Returns: TRUE if both caps are equal.
1037  */
1038 gboolean
1039 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1040 {
1041   /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1042    * So there should be an assertion that caps1 and caps2 != NULL */
1043
1044   /* NULL <-> NULL is allowed here */
1045   if (G_UNLIKELY (caps1 == caps2))
1046     return TRUE;
1047
1048   /* one of them NULL => they are different (can't be both NULL because
1049    * we checked that above) */
1050   if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1051     return FALSE;
1052
1053   if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1054     return gst_caps_is_equal_fixed (caps1, caps2);
1055
1056   return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1057 }
1058
1059 /* intersect operation */
1060
1061 /**
1062  * gst_caps_can_intersect:
1063  * @caps1: a #GstCaps to intersect
1064  * @caps2: a #GstCaps to intersect
1065  *
1066  * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1067  * be empty
1068  *
1069  * Returns: %TRUE if intersection would be not empty
1070  *
1071  * Since: 0.10.25
1072  */
1073 gboolean
1074 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1075 {
1076   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1077   guint j, k, len1, len2;
1078   GstStructure *struct1;
1079   GstStructure *struct2;
1080
1081   g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1082   g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1083
1084   /* caps are exactly the same pointers */
1085   if (G_UNLIKELY (caps1 == caps2))
1086     return TRUE;
1087
1088   /* empty caps on either side, return empty */
1089   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1090     return FALSE;
1091
1092   /* one of the caps is any */
1093   if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1094     return TRUE;
1095
1096   /* run zigzag on top line then right line, this preserves the caps order
1097    * much better than a simple loop.
1098    *
1099    * This algorithm zigzags over the caps structures as demonstrated in
1100    * the folowing matrix:
1101    *
1102    *          caps1                              0  1  2  3
1103    *       +-------------     total distance:  +-------------
1104    *       | 1  2  4  7                      0 | 0  1  2  3
1105    * caps2 | 3  5  8 10                      1 | 1  2  3  4
1106    *       | 6  9 11 12                      2 | 2  3  4  5
1107    *
1108    * First we iterate over the caps1 structures (top line) intersecting
1109    * the structures diagonally down, then we iterate over the caps2
1110    * structures. The result is that the intersections are ordered based on the
1111    * sum of the indexes in the list.
1112    */
1113   len1 = GST_CAPS_LEN (caps1);
1114   len2 = GST_CAPS_LEN (caps2);
1115   for (i = 0; i < len1 + len2 - 1; i++) {
1116     /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1117     j = MIN (i, len1 - 1);
1118     /* subset index stays 0 until i reaches superset->structs->len, then it
1119      * counts up from 1 to subset->structs->len - 1 */
1120     k = (i > j) ? (i - j) : 0;  /* MAX (0, i - j) */
1121
1122     /* now run the diagonal line, end condition is the left or bottom
1123      * border */
1124     while (k < len2) {
1125       struct1 = gst_caps_get_structure_unchecked (caps1, j);
1126       struct2 = gst_caps_get_structure_unchecked (caps2, k);
1127
1128       if (gst_structure_can_intersect (struct1, struct2)) {
1129         return TRUE;
1130       }
1131       /* move down left */
1132       k++;
1133       if (G_UNLIKELY (j == 0))
1134         break;                  /* so we don't roll back to G_MAXUINT */
1135       j--;
1136     }
1137   }
1138   return FALSE;
1139 }
1140
1141 static GstCaps *
1142 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1143 {
1144   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1145   guint j, k, len1, len2;
1146
1147   GstStructure *struct1;
1148   GstStructure *struct2;
1149   GstCaps *dest;
1150   GstStructure *istruct;
1151
1152   /* caps are exactly the same pointers, just copy one caps */
1153   if (G_UNLIKELY (caps1 == caps2))
1154     return _gst_caps_copy (caps1);
1155
1156   /* empty caps on either side, return empty */
1157   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1158     return gst_caps_new_empty ();
1159
1160   /* one of the caps is any, just copy the other caps */
1161   if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1162     return _gst_caps_copy (caps2);
1163   if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1164     return _gst_caps_copy (caps1);
1165
1166   dest = gst_caps_new_empty ();
1167
1168   /* run zigzag on top line then right line, this preserves the caps order
1169    * much better than a simple loop.
1170    *
1171    * This algorithm zigzags over the caps structures as demonstrated in
1172    * the folowing matrix:
1173    *
1174    *          caps1
1175    *       +-------------
1176    *       | 1  2  4  7
1177    * caps2 | 3  5  8 10
1178    *       | 6  9 11 12
1179    *
1180    * First we iterate over the caps1 structures (top line) intersecting
1181    * the structures diagonally down, then we iterate over the caps2
1182    * structures.
1183    */
1184   len1 = GST_CAPS_LEN (caps1);
1185   len2 = GST_CAPS_LEN (caps2);
1186   for (i = 0; i < len1 + len2 - 1; i++) {
1187     /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1188     j = MIN (i, len1 - 1);
1189     /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1190      * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1191     k = (i > j) ? (i - j) : 0;  /* MAX (0, i - j) */
1192
1193     /* now run the diagonal line, end condition is the left or bottom
1194      * border */
1195     while (k < len2) {
1196       struct1 = gst_caps_get_structure_unchecked (caps1, j);
1197       struct2 = gst_caps_get_structure_unchecked (caps2, k);
1198
1199       istruct = gst_structure_intersect (struct1, struct2);
1200
1201       gst_caps_merge_structure (dest, istruct);
1202       /* move down left */
1203       k++;
1204       if (G_UNLIKELY (j == 0))
1205         break;                  /* so we don't roll back to G_MAXUINT */
1206       j--;
1207     }
1208   }
1209   return dest;
1210 }
1211
1212 /**
1213  * gst_caps_intersect_first:
1214  * @caps1: a #GstCaps to intersect
1215  * @caps2: a #GstCaps to intersect
1216  *
1217  * Creates a new #GstCaps that contains all the formats that are common
1218  * to both @caps1 and @caps2.
1219  *
1220  * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1221  * fashion as @caps1.
1222  *
1223  * Returns: the new #GstCaps
1224  */
1225 static GstCaps *
1226 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1227 {
1228   guint64 i;                    /* index can be up to 2 * G_MAX_UINT */
1229   guint j, len1, len2;
1230
1231   GstStructure *struct1;
1232   GstStructure *struct2;
1233   GstCaps *dest;
1234   GstStructure *istruct;
1235
1236   /* caps are exactly the same pointers, just copy one caps */
1237   if (G_UNLIKELY (caps1 == caps2))
1238     return gst_caps_copy (caps1);
1239
1240   /* empty caps on either side, return empty */
1241   if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1242     return gst_caps_new_empty ();
1243
1244   /* one of the caps is any, just copy the other caps */
1245   if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1246     return gst_caps_copy (caps2);
1247   if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1248     return gst_caps_copy (caps1);
1249
1250   dest = gst_caps_new_empty ();
1251
1252   len1 = GST_CAPS_LEN (caps1);
1253   len2 = GST_CAPS_LEN (caps2);
1254   for (i = 0; i < len1; i++) {
1255     struct1 = gst_caps_get_structure_unchecked (caps1, i);
1256     for (j = 0; j < len2; j++) {
1257       struct2 = gst_caps_get_structure_unchecked (caps2, j);
1258       istruct = gst_structure_intersect (struct1, struct2);
1259       if (istruct)
1260         gst_caps_merge_structure (dest, istruct);
1261     }
1262   }
1263
1264   return dest;
1265 }
1266
1267 /**
1268  * gst_caps_intersect_full:
1269  * @caps1: a #GstCaps to intersect
1270  * @caps2: a #GstCaps to intersect
1271  * @mode: The intersection algorithm/mode to use
1272  *
1273  * Creates a new #GstCaps that contains all the formats that are common
1274  * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1275  * used.
1276  *
1277  * Returns: the new #GstCaps
1278  * Since: 0.10.33
1279  */
1280 GstCaps *
1281 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1282     GstCapsIntersectMode mode)
1283 {
1284   g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1285   g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1286
1287   switch (mode) {
1288     case GST_CAPS_INTERSECT_FIRST:
1289       return gst_caps_intersect_first (caps1, caps2);
1290     default:
1291       g_warning ("Unknown caps intersect mode: %d", mode);
1292       /* fallthrough */
1293     case GST_CAPS_INTERSECT_ZIG_ZAG:
1294       return gst_caps_intersect_zig_zag (caps1, caps2);
1295   }
1296 }
1297
1298 /**
1299  * gst_caps_intersect:
1300  * @caps1: a #GstCaps to intersect
1301  * @caps2: a #GstCaps to intersect
1302  *
1303  * Creates a new #GstCaps that contains all the formats that are common
1304  * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1305  *
1306  * Returns: the new #GstCaps
1307  */
1308 GstCaps *
1309 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1310 {
1311   return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1312 }
1313
1314
1315 /* subtract operation */
1316
1317 typedef struct
1318 {
1319   const GstStructure *subtract_from;
1320   GSList *put_into;
1321 }
1322 SubtractionEntry;
1323
1324 static gboolean
1325 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1326     gpointer user_data)
1327 {
1328   SubtractionEntry *e = user_data;
1329   GValue subtraction = { 0, };
1330   const GValue *other;
1331   GstStructure *structure;
1332
1333   other = gst_structure_id_get_value (e->subtract_from, field_id);
1334   if (!other) {
1335     return FALSE;
1336   }
1337   if (!gst_value_subtract (&subtraction, other, value))
1338     return TRUE;
1339   if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1340     g_value_unset (&subtraction);
1341     return FALSE;
1342   } else {
1343     structure = gst_structure_copy (e->subtract_from);
1344     gst_structure_id_set_value (structure, field_id, &subtraction);
1345     g_value_unset (&subtraction);
1346     e->put_into = g_slist_prepend (e->put_into, structure);
1347     return TRUE;
1348   }
1349 }
1350
1351 static gboolean
1352 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1353     const GstStructure * subtrahend)
1354 {
1355   SubtractionEntry e;
1356   gboolean ret;
1357
1358   e.subtract_from = minuend;
1359   e.put_into = NULL;
1360
1361   ret = gst_structure_foreach ((GstStructure *) subtrahend,
1362       gst_caps_structure_subtract_field, &e);
1363   if (ret) {
1364     *into = e.put_into;
1365   } else {
1366     GSList *walk;
1367
1368     for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1369       gst_structure_free (walk->data);
1370     }
1371     g_slist_free (e.put_into);
1372   }
1373   return ret;
1374 }
1375
1376 /**
1377  * gst_caps_subtract:
1378  * @minuend: #GstCaps to subtract from
1379  * @subtrahend: #GstCaps to subtract
1380  *
1381  * Subtracts the @subtrahend from the @minuend.
1382  * <note>This function does not work reliably if optional properties for caps
1383  * are included on one caps and omitted on the other.</note>
1384  *
1385  * Returns: the resulting caps
1386  */
1387 GstCaps *
1388 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1389 {
1390   guint i, j, sublen;
1391   GstStructure *min;
1392   GstStructure *sub;
1393   GstCaps *dest = NULL, *src;
1394
1395   g_return_val_if_fail (minuend != NULL, NULL);
1396   g_return_val_if_fail (subtrahend != NULL, NULL);
1397
1398   if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1399     return gst_caps_new_empty ();
1400   }
1401   if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1402     return _gst_caps_copy (minuend);
1403
1404   /* FIXME: Do we want this here or above?
1405      The reason we need this is that there is no definition about what
1406      ANY means for specific types, so it's not possible to reduce ANY partially
1407      You can only remove everything or nothing and that is done above.
1408      Note: there's a test that checks this behaviour. */
1409   g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1410   sublen = GST_CAPS_LEN (subtrahend);
1411   g_assert (sublen > 0);
1412
1413   src = _gst_caps_copy (minuend);
1414   for (i = 0; i < sublen; i++) {
1415     guint srclen;
1416
1417     sub = gst_caps_get_structure_unchecked (subtrahend, i);
1418     if (dest) {
1419       gst_caps_unref (src);
1420       src = dest;
1421     }
1422     dest = gst_caps_new_empty ();
1423     srclen = GST_CAPS_LEN (src);
1424     for (j = 0; j < srclen; j++) {
1425       min = gst_caps_get_structure_unchecked (src, j);
1426       if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1427         GSList *list;
1428
1429         if (gst_caps_structure_subtract (&list, min, sub)) {
1430           GSList *walk;
1431
1432           for (walk = list; walk; walk = g_slist_next (walk)) {
1433             gst_caps_append_structure_unchecked (dest,
1434                 (GstStructure *) walk->data);
1435           }
1436           g_slist_free (list);
1437         } else {
1438           gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1439         }
1440       } else {
1441         gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1442       }
1443     }
1444     if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1445       gst_caps_unref (src);
1446       return dest;
1447     }
1448   }
1449
1450   gst_caps_unref (src);
1451   gst_caps_do_simplify (dest);
1452   return dest;
1453 }
1454
1455 /* union operation */
1456
1457 #if 0
1458 static GstStructure *
1459 gst_caps_structure_union (const GstStructure * struct1,
1460     const GstStructure * struct2)
1461 {
1462   int i;
1463   GstStructure *dest;
1464   const GstStructureField *field1;
1465   const GstStructureField *field2;
1466   int ret;
1467
1468   /* FIXME this doesn't actually work */
1469
1470   if (struct1->name != struct2->name)
1471     return NULL;
1472
1473   dest = gst_structure_id_empty_new (struct1->name);
1474
1475   for (i = 0; i < struct1->fields->len; i++) {
1476     GValue dest_value = { 0 };
1477
1478     field1 = GST_STRUCTURE_FIELD (struct1, i);
1479     field2 = gst_structure_id_get_field (struct2, field1->name);
1480
1481     if (field2 == NULL) {
1482       continue;
1483     } else {
1484       if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1485         gst_structure_set_value (dest, g_quark_to_string (field1->name),
1486             &dest_value);
1487       } else {
1488         ret = gst_value_compare (&field1->value, &field2->value);
1489       }
1490     }
1491   }
1492
1493   return dest;
1494 }
1495 #endif
1496
1497 /**
1498  * gst_caps_union:
1499  * @caps1: a #GstCaps to union
1500  * @caps2: a #GstCaps to union
1501  *
1502  * Creates a new #GstCaps that contains all the formats that are in
1503  * either @caps1 and @caps2.
1504  *
1505  * Returns: the new #GstCaps
1506  */
1507 GstCaps *
1508 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1509 {
1510   GstCaps *dest1;
1511   GstCaps *dest2;
1512
1513   /* NULL pointers are no correct GstCaps */
1514   g_return_val_if_fail (caps1 != NULL, NULL);
1515   g_return_val_if_fail (caps2 != NULL, NULL);
1516
1517   if (CAPS_IS_EMPTY (caps1))
1518     return _gst_caps_copy (caps2);
1519
1520   if (CAPS_IS_EMPTY (caps2))
1521     return _gst_caps_copy (caps1);
1522
1523   if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1524     return gst_caps_new_any ();
1525
1526   dest1 = _gst_caps_copy (caps1);
1527   dest2 = _gst_caps_copy (caps2);
1528   gst_caps_append (dest1, dest2);
1529
1530   gst_caps_do_simplify (dest1);
1531   return dest1;
1532 }
1533
1534 /* normalize/simplify operations */
1535
1536 typedef struct _NormalizeForeach
1537 {
1538   GstCaps *caps;
1539   GstStructure *structure;
1540 }
1541 NormalizeForeach;
1542
1543 static gboolean
1544 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1545 {
1546   NormalizeForeach *nf = (NormalizeForeach *) ptr;
1547   GValue val = { 0 };
1548   guint i;
1549
1550   if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1551     guint len = gst_value_list_get_size (value);
1552     for (i = 1; i < len; i++) {
1553       const GValue *v = gst_value_list_get_value (value, i);
1554       GstStructure *structure = gst_structure_copy (nf->structure);
1555
1556       gst_structure_id_set_value (structure, field_id, v);
1557       gst_caps_append_structure_unchecked (nf->caps, structure);
1558     }
1559
1560     gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1561     gst_structure_id_set_value (nf->structure, field_id, &val);
1562     g_value_unset (&val);
1563
1564     return FALSE;
1565   }
1566   return TRUE;
1567 }
1568
1569 /**
1570  * gst_caps_normalize:
1571  * @caps: a #GstCaps to normalize
1572  *
1573  * Creates a new #GstCaps that represents the same set of formats as
1574  * @caps, but contains no lists.  Each list is expanded into separate
1575  * @GstStructures.
1576  *
1577  * Returns: the new #GstCaps
1578  */
1579 GstCaps *
1580 gst_caps_normalize (const GstCaps * caps)
1581 {
1582   NormalizeForeach nf;
1583   GstCaps *newcaps;
1584   guint i;
1585
1586   g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1587
1588   newcaps = _gst_caps_copy (caps);
1589   nf.caps = newcaps;
1590
1591   for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1592     nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1593
1594     while (!gst_structure_foreach (nf.structure,
1595             gst_caps_normalize_foreach, &nf));
1596   }
1597
1598   return newcaps;
1599 }
1600
1601 static gint
1602 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1603 {
1604   gint ret;
1605   const GstStructure *struct1 = *((const GstStructure **) one);
1606   const GstStructure *struct2 = *((const GstStructure **) two);
1607
1608   /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1609      So what's the best way? */
1610   ret = strcmp (gst_structure_get_name (struct1),
1611       gst_structure_get_name (struct2));
1612   if (ret)
1613     return ret;
1614
1615   return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1616 }
1617
1618 typedef struct
1619 {
1620   GQuark name;
1621   GValue value;
1622   GstStructure *compare;
1623 }
1624 UnionField;
1625
1626 static gboolean
1627 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1628     gpointer user_data)
1629 {
1630   UnionField *u = user_data;
1631   const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1632
1633   if (!val) {
1634     if (u->name)
1635       g_value_unset (&u->value);
1636     return FALSE;
1637   }
1638   if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1639     return TRUE;
1640   if (u->name) {
1641     g_value_unset (&u->value);
1642     return FALSE;
1643   }
1644   u->name = field_id;
1645   gst_value_union (&u->value, val, value);
1646   return TRUE;
1647 }
1648
1649 static gboolean
1650 gst_caps_structure_simplify (GstStructure ** result,
1651     const GstStructure * simplify, GstStructure * compare)
1652 {
1653   GSList *list;
1654   UnionField field = { 0, {0,}, NULL };
1655
1656   /* try to subtract to get a real subset */
1657   if (gst_caps_structure_subtract (&list, simplify, compare)) {
1658     if (list == NULL) {         /* no result */
1659       *result = NULL;
1660       return TRUE;
1661     } else if (list->next == NULL) {    /* one result */
1662       *result = list->data;
1663       g_slist_free (list);
1664       return TRUE;
1665     } else {                    /* multiple results */
1666       g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1667       g_slist_free (list);
1668       list = NULL;
1669     }
1670   }
1671
1672   /* try to union both structs */
1673   field.compare = compare;
1674   if (gst_structure_foreach ((GstStructure *) simplify,
1675           gst_caps_structure_figure_out_union, &field)) {
1676     gboolean ret = FALSE;
1677
1678     /* now we know all of simplify's fields are the same in compare
1679      * but at most one field: field.name */
1680     if (G_IS_VALUE (&field.value)) {
1681       if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1682         gst_structure_id_set_value (compare, field.name, &field.value);
1683         *result = NULL;
1684         ret = TRUE;
1685       }
1686       g_value_unset (&field.value);
1687     } else if (gst_structure_n_fields (simplify) <=
1688         gst_structure_n_fields (compare)) {
1689       /* compare is just more specific, will be optimized away later */
1690       /* FIXME: do this here? */
1691       GST_LOG ("found a case that will be optimized later.");
1692     } else {
1693       gchar *one = gst_structure_to_string (simplify);
1694       gchar *two = gst_structure_to_string (compare);
1695
1696       GST_ERROR
1697           ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1698           one, two);
1699       g_free (one);
1700       g_free (two);
1701     }
1702     return ret;
1703   }
1704
1705   return FALSE;
1706 }
1707
1708 static void
1709 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1710     GstStructure * new, gint i)
1711 {
1712   gst_structure_set_parent_refcount (old, NULL);
1713   gst_structure_free (old);
1714   gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1715   g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1716 }
1717
1718 /**
1719  * gst_caps_do_simplify:
1720  * @caps: a #GstCaps to simplify
1721  *
1722  * Modifies the given @caps inplace into a representation that represents the
1723  * same set of formats, but in a simpler form.  Component structures that are
1724  * identical are merged.  Component structures that have values that can be
1725  * merged are also merged.
1726  *
1727  * Returns: TRUE, if the caps could be simplified
1728  */
1729 gboolean
1730 gst_caps_do_simplify (GstCaps * caps)
1731 {
1732   GstStructure *simplify, *compare, *result = NULL;
1733   gint i, j, start;
1734   gboolean changed = FALSE;
1735
1736   g_return_val_if_fail (caps != NULL, FALSE);
1737   g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1738
1739   if (gst_caps_get_size (caps) < 2)
1740     return FALSE;
1741
1742   g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1743
1744   start = GST_CAPS_LEN (caps) - 1;
1745   for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1746     simplify = gst_caps_get_structure_unchecked (caps, i);
1747     if (gst_structure_get_name_id (simplify) !=
1748         gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1749                 start)))
1750       start = i;
1751     for (j = start; j >= 0; j--) {
1752       if (j == i)
1753         continue;
1754       compare = gst_caps_get_structure_unchecked (caps, j);
1755       if (gst_structure_get_name_id (simplify) !=
1756           gst_structure_get_name_id (compare)) {
1757         break;
1758       }
1759       if (gst_caps_structure_simplify (&result, simplify, compare)) {
1760         if (result) {
1761           gst_caps_switch_structures (caps, simplify, result, i);
1762           simplify = result;
1763         } else {
1764           gst_caps_remove_structure (caps, i);
1765           start--;
1766           break;
1767         }
1768         changed = TRUE;
1769       }
1770     }
1771   }
1772
1773   if (!changed)
1774     return FALSE;
1775
1776   /* gst_caps_do_simplify (caps); */
1777   return TRUE;
1778 }
1779
1780 /**
1781  * gst_caps_fixate:
1782  * @caps: a #GstCaps to fixate
1783  *
1784  * Modifies the given @caps inplace into a representation with only fixed
1785  * values. First the caps will be truncated and then the first structure will be
1786  * fixated with gst_structure_fixate(). @caps should be writable.
1787  */
1788 void
1789 gst_caps_fixate (GstCaps * caps)
1790 {
1791   GstStructure *s;
1792
1793   g_return_if_fail (GST_IS_CAPS (caps));
1794   g_return_if_fail (IS_WRITABLE (caps));
1795
1796   /* default fixation */
1797   gst_caps_truncate (caps);
1798   s = gst_caps_get_structure (caps, 0);
1799   gst_structure_fixate (s);
1800 }
1801
1802 /* utility */
1803
1804 /**
1805  * gst_caps_to_string:
1806  * @caps: a #GstCaps
1807  *
1808  * Converts @caps to a string representation.  This string representation
1809  * can be converted back to a #GstCaps by gst_caps_from_string().
1810  *
1811  * For debugging purposes its easier to do something like this:
1812  * |[
1813  * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1814  * ]|
1815  * This prints the caps in human readble form.
1816  *
1817  * Returns: (transfer full): a newly allocated string representing @caps.
1818  */
1819 gchar *
1820 gst_caps_to_string (const GstCaps * caps)
1821 {
1822   guint i, slen, clen;
1823   GString *s;
1824
1825   /* NOTE:  This function is potentially called by the debug system,
1826    * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1827    * should be careful to avoid recursion.  This includes any functions
1828    * called by gst_caps_to_string.  In particular, calls should
1829    * not use the GST_PTR_FORMAT extension.  */
1830
1831   if (caps == NULL) {
1832     return g_strdup ("NULL");
1833   }
1834   if (CAPS_IS_ANY (caps)) {
1835     return g_strdup ("ANY");
1836   }
1837   if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1838     return g_strdup ("EMPTY");
1839   }
1840
1841   /* estimate a rough string length to avoid unnecessary reallocs in GString */
1842   slen = 0;
1843   clen = GST_CAPS_LEN (caps);
1844   for (i = 0; i < clen; i++) {
1845     slen +=
1846         STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1847             i));
1848   }
1849
1850   s = g_string_sized_new (slen);
1851   for (i = 0; i < clen; i++) {
1852     GstStructure *structure;
1853
1854     if (i > 0) {
1855       /* ';' is now added by gst_structure_to_string */
1856       g_string_append_c (s, ' ');
1857     }
1858
1859     structure = gst_caps_get_structure_unchecked (caps, i);
1860     priv_gst_structure_append_to_gstring (structure, s);
1861   }
1862   if (s->len && s->str[s->len - 1] == ';') {
1863     /* remove latest ';' */
1864     s->str[--s->len] = '\0';
1865   }
1866   return g_string_free (s, FALSE);
1867 }
1868
1869 static gboolean
1870 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1871 {
1872   GstStructure *structure;
1873   gchar *s;
1874
1875   if (strcmp ("ANY", string) == 0) {
1876     GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
1877     return TRUE;
1878   }
1879   if (strcmp ("EMPTY", string) == 0) {
1880     return TRUE;
1881   }
1882
1883   structure = gst_structure_from_string (string, &s);
1884   if (structure == NULL) {
1885     return FALSE;
1886   }
1887   gst_caps_append_structure_unchecked (caps, structure);
1888
1889   do {
1890
1891     while (g_ascii_isspace (*s))
1892       s++;
1893     if (*s == '\0') {
1894       break;
1895     }
1896     structure = gst_structure_from_string (s, &s);
1897     if (structure == NULL) {
1898       return FALSE;
1899     }
1900     gst_caps_append_structure_unchecked (caps, structure);
1901
1902   } while (TRUE);
1903
1904   return TRUE;
1905 }
1906
1907 /**
1908  * gst_caps_from_string:
1909  * @string: a string to convert to #GstCaps
1910  *
1911  * Converts @caps from a string representation.
1912  *
1913  * Returns: (transfer full): a newly allocated #GstCaps
1914  */
1915 GstCaps *
1916 gst_caps_from_string (const gchar * string)
1917 {
1918   GstCaps *caps;
1919
1920   g_return_val_if_fail (string, FALSE);
1921
1922   caps = gst_caps_new_empty ();
1923   if (gst_caps_from_string_inplace (caps, string)) {
1924     return caps;
1925   } else {
1926     gst_caps_unref (caps);
1927     return NULL;
1928   }
1929 }
1930
1931 static void
1932 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1933 {
1934   g_return_if_fail (G_IS_VALUE (src_value));
1935   g_return_if_fail (G_IS_VALUE (dest_value));
1936   g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1937   g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1938       || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1939
1940   g_value_take_string (dest_value,
1941       gst_caps_to_string (gst_value_get_caps (src_value)));
1942 }