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