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