gst/gstcapsfeatures.c

   1 /* GStreamer
   2  * Copyright (C) 2013 Collabora Ltd.
   3  *   Author: Sebastian Dröge <sebastian.droege@collabora.co.uk>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  18  * Boston, MA 02110-1301, USA.
  19  */
  20
  21 /**
  22  * SECTION:gstcapsfeatures
  23  * @short_description: A set of features in caps
  24  * @see_also: #GstCaps
  25  *
  26  * #GstCapsFeatures can optionally be set on a #GstCaps to add requirements
  27  * for additional features for a specific #GstStructure. Caps structures with
  28  * the same name but with a non-equal set of caps features are not compatible.
  29  * If a pad supports multiple sets of features it has to add multiple equal
  30  * structures with different feature sets to the caps.
  31  *
  32  * Empty #GstCapsFeatures are equivalent with the #GstCapsFeatures that only
  33  * contain #GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY. ANY #GstCapsFeatures as
  34  * created by gst_caps_features_new_any() are equal to any other #GstCapsFeatures
  35  * and can be used to specify that any #GstCapsFeatures would be supported, e.g.
  36  * for elements that don't touch buffer memory. #GstCaps with ANY #GstCapsFeatures
  37  * are considered non-fixed and during negotiation some #GstCapsFeatures have
  38  * to be selected.
  39  *
  40  * Examples for caps features would be the requirement of a specific #GstMemory
  41  * types or the requirement of having a specific #GstMeta on the buffer. Features
  42  * are given as a string of the format "memory:GstMemoryTypeName" or
  43  * "meta:GstMetaAPIName".
  44  *
  45  * Since: 1.2
  46  */
  47
  48 #ifdef HAVE_CONFIG_H
  49 #include "config.h"
  50 #endif
  51
  52 #include <string.h>
  53 #include "gst_private.h"
  54 #include "gstcapsfeatures.h"
  55 #include <gst/gst.h>
  56
  57 GST_DEBUG_CATEGORY_STATIC (gst_caps_features_debug);
  58 #define GST_CAT_DEFAULT gst_caps_features_debug
  59
  60 struct _GstCapsFeatures
  61 {
  62   GType type;
  63   gint *parent_refcount;
  64   GArray *array;
  65   gboolean is_any;
  66 };
  67
  68 GType _gst_caps_features_type = 0;
  69 static gint static_caps_features_parent_refcount = G_MAXINT;
  70 GstCapsFeatures *_gst_caps_features_any = NULL;
  71 GstCapsFeatures *_gst_caps_features_memory_system_memory = NULL;
  72 static GQuark _gst_caps_feature_memory_system_memory = 0;
  73
  74 G_DEFINE_BOXED_TYPE (GstCapsFeatures, gst_caps_features,
  75     gst_caps_features_copy, gst_caps_features_free);
  76
  77 #define IS_MUTABLE(features) \
  78     (!features->parent_refcount || \
  79      g_atomic_int_get (features->parent_refcount) == 1)
  80
  81 static void
  82 gst_caps_features_transform_to_string (const GValue * src_value,
  83     GValue * dest_value);
  84
  85 void
  86 _priv_gst_caps_features_initialize (void)
  87 {
  88   GST_DEBUG_CATEGORY_INIT (gst_caps_features_debug, "caps-features", 0,
  89       "GstCapsFeatures debug");
  90
  91   _gst_caps_features_type = gst_caps_features_get_type ();
  92   _gst_caps_feature_memory_system_memory =
  93       g_quark_from_static_string (GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY);
  94
  95   g_value_register_transform_func (_gst_caps_features_type, G_TYPE_STRING,
  96       gst_caps_features_transform_to_string);
  97
  98   _gst_caps_features_any = gst_caps_features_new_any ();
  99   gst_caps_features_set_parent_refcount (_gst_caps_features_any,
 100       &static_caps_features_parent_refcount);
 101   _gst_caps_features_memory_system_memory =
 102       gst_caps_features_new_id (_gst_caps_feature_memory_system_memory, 0);
 103   gst_caps_features_set_parent_refcount
 104       (_gst_caps_features_memory_system_memory,
 105       &static_caps_features_parent_refcount);
 106 }
 107
 108 gboolean
 109 gst_is_caps_features (gconstpointer obj)
 110 {
 111   const GstCapsFeatures *features = obj;
 112
 113   return (obj != NULL && features->type == _gst_caps_features_type);
 114 }
 115
 116 static gboolean
 117 gst_caps_feature_name_is_valid (const gchar * feature)
 118 {
 119 #ifndef G_DISABLE_CHECKS
 120   while (TRUE) {
 121     if (g_ascii_isalpha (*feature))
 122       feature++;
 123     else if (*feature == ':')
 124       break;
 125     else
 126       return FALSE;
 127   }
 128
 129   if (*feature != ':')
 130     return FALSE;
 131
 132   feature++;
 133   if (*feature == '\0' || !g_ascii_isalpha (*feature))
 134     return FALSE;
 135
 136   while (TRUE) {
 137     if (g_ascii_isalnum (*feature))
 138       feature++;
 139     else if (*feature == '\0')
 140       break;
 141     else
 142       return FALSE;
 143   }
 144 #endif
 145
 146   return TRUE;
 147 }
 148
 149 /**
 150  * gst_caps_features_new_empty:
 151  *
 152  * Creates a new, empty #GstCapsFeatures.
 153  *
 154  * Free-function: gst_caps_features_free
 155  *
 156  * Returns: (transfer full): a new, empty #GstCapsFeatures
 157  *
 158  * Since: 1.2
 159  */
 160 GstCapsFeatures *
 161 gst_caps_features_new_empty (void)
 162 {
 163   GstCapsFeatures *features;
 164
 165   features = g_slice_new (GstCapsFeatures);
 166   features->type = _gst_caps_features_type;
 167   features->parent_refcount = NULL;
 168   features->array = g_array_new (FALSE, FALSE, sizeof (GQuark));
 169   features->is_any = FALSE;
 170
 171   GST_TRACE ("created caps features %p", features);
 172
 173   return features;
 174 }
 175
 176 /**
 177  * gst_caps_features_new_any:
 178  *
 179  * Creates a new, ANY #GstCapsFeatures. This will be equal
 180  * to any other #GstCapsFeatures but caps with these are
 181  * unfixed.
 182  *
 183  * Free-function: gst_caps_features_free
 184  *
 185  * Returns: (transfer full): a new, ANY #GstCapsFeatures
 186  *
 187  * Since: 1.2
 188  */
 189 GstCapsFeatures *
 190 gst_caps_features_new_any (void)
 191 {
 192   GstCapsFeatures *features;
 193
 194   features = gst_caps_features_new_empty ();
 195   features->is_any = TRUE;
 196
 197   return features;
 198 }
 199
 200 /**
 201  * gst_caps_features_new:
 202  * @feature1: name of first feature to set
 203  * @...: additional features
 204  *
 205  * Creates a new #GstCapsFeatures with the given features.
 206  * The last argument must be %NULL.
 207  *
 208  * Free-function: gst_caps_features_free
 209  *
 210  * Returns: (transfer full): a new, empty #GstCapsFeatures
 211  *
 212  * Since: 1.2
 213  */
 214 GstCapsFeatures *
 215 gst_caps_features_new (const gchar * feature1, ...)
 216 {
 217   GstCapsFeatures *features;
 218   va_list varargs;
 219
 220   g_return_val_if_fail (feature1 != NULL, NULL);
 221
 222   va_start (varargs, feature1);
 223   features = gst_caps_features_new_valist (feature1, varargs);
 224   va_end (varargs);
 225
 226   return features;
 227 }
 228
 229 /**
 230  * gst_caps_features_new_valist:
 231  * @feature1: name of first feature to set
 232  * @varargs: variable argument list
 233  *
 234  * Creates a new #GstCapsFeatures with the given features.
 235  *
 236  * Free-function: gst_caps_features_free
 237  *
 238  * Returns: (transfer full): a new, empty #GstCapsFeatures
 239  *
 240  * Since: 1.2
 241  */
 242 GstCapsFeatures *
 243 gst_caps_features_new_valist (const gchar * feature1, va_list varargs)
 244 {
 245   GstCapsFeatures *features;
 246
 247   g_return_val_if_fail (feature1 != NULL, NULL);
 248
 249   features = gst_caps_features_new_empty ();
 250
 251   while (feature1) {
 252     gst_caps_features_add (features, feature1);
 253     feature1 = va_arg (varargs, const gchar *);
 254   }
 255
 256   return features;
 257 }
 258
 259 /**
 260  * gst_caps_features_new_id:
 261  * @feature1: name of first feature to set
 262  * @...: additional features
 263  *
 264  * Creates a new #GstCapsFeatures with the given features.
 265  * The last argument must be 0.
 266  *
 267  * Free-function: gst_caps_features_free
 268  *
 269  * Returns: (transfer full): a new, empty #GstCapsFeatures
 270  *
 271  * Since: 1.2
 272  */
 273 GstCapsFeatures *
 274 gst_caps_features_new_id (GQuark feature1, ...)
 275 {
 276   GstCapsFeatures *features;
 277   va_list varargs;
 278
 279   g_return_val_if_fail (feature1 != 0, NULL);
 280
 281   va_start (varargs, feature1);
 282   features = gst_caps_features_new_id_valist (feature1, varargs);
 283   va_end (varargs);
 284
 285   return features;
 286 }
 287
 288 /**
 289  * gst_caps_features_new_id_valist:
 290  * @feature1: name of first feature to set
 291  * @varargs: variable argument list
 292  *
 293  * Creates a new #GstCapsFeatures with the given features.
 294  *
 295  * Free-function: gst_caps_features_free
 296  *
 297  * Returns: (transfer full): a new, empty #GstCapsFeatures
 298  *
 299  * Since: 1.2
 300  */
 301 GstCapsFeatures *
 302 gst_caps_features_new_id_valist (GQuark feature1, va_list varargs)
 303 {
 304   GstCapsFeatures *features;
 305
 306   g_return_val_if_fail (feature1 != 0, NULL);
 307
 308   features = gst_caps_features_new_empty ();
 309
 310   while (feature1) {
 311     gst_caps_features_add_id (features, feature1);
 312     feature1 = va_arg (varargs, GQuark);
 313   }
 314
 315   return features;
 316 }
 317
 318 /**
 319  * gst_caps_features_set_parent_refcount:
 320  * @features: a #GstCapsFeatures
 321  * @refcount: (in): a pointer to the parent's refcount
 322  *
 323  * Sets the parent_refcount field of #GstCapsFeatures. This field is used to
 324  * determine whether a caps features is mutable or not. This function should only be
 325  * called by code implementing parent objects of #GstCapsFeatures, as described in
 326  * the MT Refcounting section of the design documents.
 327  *
 328  * Returns: %TRUE if the parent refcount could be set.
 329  *
 330  * Since: 1.2
 331  */
 332 gboolean
 333 gst_caps_features_set_parent_refcount (GstCapsFeatures * features,
 334     gint * refcount)
 335 {
 336   g_return_val_if_fail (features != NULL, FALSE);
 337
 338   /* if we have a parent_refcount already, we can only clear
 339    * if with a NULL refcount */
 340   if (features->parent_refcount) {
 341     if (refcount != NULL) {
 342       g_return_val_if_fail (refcount == NULL, FALSE);
 343       return FALSE;
 344     }
 345   } else {
 346     if (refcount == NULL) {
 347       g_return_val_if_fail (refcount != NULL, FALSE);
 348       return FALSE;
 349     }
 350   }
 351
 352   features->parent_refcount = refcount;
 353
 354   return TRUE;
 355 }
 356
 357 /**
 358  * gst_caps_features_copy:
 359  * @features: a #GstCapsFeatures to duplicate
 360  *
 361  * Duplicates a #GstCapsFeatures and all its values.
 362  *
 363  * Free-function: gst_caps_features_free
 364  *
 365  * Returns: (transfer full): a new #GstCapsFeatures.
 366  *
 367  * Since: 1.2
 368  */
 369 GstCapsFeatures *
 370 gst_caps_features_copy (const GstCapsFeatures * features)
 371 {
 372   GstCapsFeatures *copy;
 373   guint i, n;
 374
 375   g_return_val_if_fail (features != NULL, NULL);
 376
 377   copy = gst_caps_features_new_empty ();
 378   n = gst_caps_features_get_size (features);
 379   for (i = 0; i < n; i++)
 380     gst_caps_features_add_id (copy, gst_caps_features_get_nth_id (features, i));
 381   copy->is_any = features->is_any;
 382
 383   return copy;
 384 }
 385
 386 /**
 387  * gst_caps_features_free:
 388  * @features: (in) (transfer full): the #GstCapsFeatures to free
 389  *
 390  * Frees a #GstCapsFeatures and all its values. The caps features must not
 391  * have a parent when this function is called.
 392  *
 393  * Since: 1.2
 394  */
 395 void
 396 gst_caps_features_free (GstCapsFeatures * features)
 397 {
 398   g_return_if_fail (features != NULL);
 399   g_return_if_fail (features->parent_refcount == NULL);
 400
 401   g_array_free (features->array, TRUE);
 402 #ifdef USE_POISONING
 403   memset (features, 0xff, sizeof (GstCapsFeatures));
 404 #endif
 405   GST_TRACE ("free caps features %p", features);
 406
 407   g_slice_free (GstCapsFeatures, features);
 408 }
 409
 410 /**
 411  * gst_caps_features_to_string:
 412  * @features: a #GstCapsFeatures
 413  *
 414  * Converts @features to a human-readable string representation.
 415  *
 416  * For debugging purposes its easier to do something like this:
 417  * |[
 418  * GST_LOG ("features is %" GST_PTR_FORMAT, features);
 419  * ]|
 420  * This prints the features in human readable form.
 421  *
 422  * Free-function: g_free
 423  *
 424  * Returns: (transfer full): a pointer to string allocated by g_malloc().
 425  *     g_free() after usage.
 426  *
 427  * Since: 1.2
 428  */
 429 gchar *
 430 gst_caps_features_to_string (const GstCapsFeatures * features)
 431 {
 432   GString *s;
 433
 434   g_return_val_if_fail (features != NULL, NULL);
 435
 436   s = g_string_sized_new (FEATURES_ESTIMATED_STRING_LEN (features));
 437
 438   priv_gst_caps_features_append_to_gstring (features, s);
 439
 440   return g_string_free (s, FALSE);
 441 }
 442
 443 void
 444 priv_gst_caps_features_append_to_gstring (const GstCapsFeatures * features,
 445     GString * s)
 446 {
 447   guint i, n;
 448
 449   g_return_if_fail (features != NULL);
 450
 451   if (features->array->len == 0 && features->is_any) {
 452     g_string_append (s, "ANY");
 453     return;
 454   }
 455
 456   n = features->array->len;
 457   for (i = 0; i < n; i++) {
 458     GQuark *quark = &g_array_index (features->array, GQuark, i);
 459
 460     g_string_append (s, g_quark_to_string (*quark));
 461     if (i + 1 < n)
 462       g_string_append (s, ", ");
 463   }
 464 }
 465
 466 /**
 467  * gst_caps_features_from_string:
 468  * @features: a string representation of a #GstCapsFeatures.
 469  *
 470  * Creates a #GstCapsFeatures from a string representation.
 471  *
 472  * Free-function: gst_caps_features_free
 473  *
 474  * Returns: (transfer full) (nullable): a new #GstCapsFeatures or
 475  *     %NULL when the string could not be parsed. Free with
 476  *     gst_caps_features_free() after use.
 477  *
 478  * Since: 1.2
 479  */
 480 GstCapsFeatures *
 481 gst_caps_features_from_string (const gchar * features)
 482 {
 483   GstCapsFeatures *ret;
 484   gboolean escape = FALSE;
 485   const gchar *features_orig = features;
 486   const gchar *feature;
 487
 488   ret = gst_caps_features_new_empty ();
 489
 490   if (!features || *features == '\0')
 491     return ret;
 492
 493   if (strcmp (features, "ANY") == 0) {
 494     ret->is_any = TRUE;
 495     return ret;
 496   }
 497
 498   /* Skip trailing spaces */
 499   while (*features == ' ')
 500     features++;
 501
 502   feature = features;
 503   while (TRUE) {
 504     gchar c = *features;
 505
 506     if (c == '\\') {
 507       escape = TRUE;
 508       features++;
 509       continue;
 510     } else if ((!escape && c == ',') || c == '\0') {
 511       guint len = features - feature + 1;
 512       gchar *tmp;
 513       gchar *p;
 514
 515       if (len == 1) {
 516         g_warning ("Failed deserialize caps features '%s'", features_orig);
 517         gst_caps_features_free (ret);
 518         return NULL;
 519       }
 520
 521       tmp = g_malloc (len);
 522       memcpy (tmp, feature, len - 1);
 523       tmp[len - 1] = '\0';
 524
 525       p = tmp + len - 1;
 526       while (*p == ' ') {
 527         *p = '\0';
 528         p--;
 529       }
 530
 531       if (strstr (tmp, " ") != NULL || *tmp == '\0') {
 532         g_free (tmp);
 533         g_warning ("Failed deserialize caps features '%s'", features_orig);
 534         gst_caps_features_free (ret);
 535         return NULL;
 536       }
 537
 538       gst_caps_features_add (ret, tmp);
 539       g_free (tmp);
 540
 541       if (c == '\0')
 542         break;
 543
 544       /* Skip to the next value */
 545       features++;
 546       while (*features == ' ')
 547         features++;
 548       feature = features;
 549     } else {
 550       escape = FALSE;
 551       features++;
 552     }
 553   }
 554
 555   return ret;
 556 }
 557
 558 /**
 559  * gst_caps_features_get_size:
 560  * @features: a #GstCapsFeatures.
 561  *
 562  * Returns the number of features in @features.
 563  *
 564  * Returns: The number of features in @features.
 565  *
 566  * Since: 1.2
 567  */
 568 guint
 569 gst_caps_features_get_size (const GstCapsFeatures * features)
 570 {
 571   g_return_val_if_fail (features != NULL, 0);
 572
 573   return features->array->len;
 574 }
 575
 576 /**
 577  * gst_caps_features_get_nth:
 578  * @features: a #GstCapsFeatures.
 579  * @i: index of the feature
 580  *
 581  * Returns the @i-th feature of @features.
 582  *
 583  * Returns: The @i-th feature of @features.
 584  *
 585  * Since: 1.2
 586  */
 587 const gchar *
 588 gst_caps_features_get_nth (const GstCapsFeatures * features, guint i)
 589 {
 590   const gchar *feature;
 591   GQuark quark;
 592
 593   g_return_val_if_fail (features != NULL, NULL);
 594
 595   quark = gst_caps_features_get_nth_id (features, i);
 596   if (!quark)
 597     return NULL;
 598
 599   feature = g_quark_to_string (quark);
 600   return feature;
 601 }
 602
 603 /**
 604  * gst_caps_features_get_nth_id:
 605  * @features: a #GstCapsFeatures.
 606  * @i: index of the feature
 607  *
 608  * Returns the @i-th feature of @features.
 609  *
 610  * Returns: The @i-th feature of @features.
 611  *
 612  * Since: 1.2
 613  */
 614 GQuark
 615 gst_caps_features_get_nth_id (const GstCapsFeatures * features, guint i)
 616 {
 617   GQuark *quark;
 618
 619   g_return_val_if_fail (features != NULL, 0);
 620   g_return_val_if_fail (i < features->array->len, 0);
 621
 622   quark = &g_array_index (features->array, GQuark, i);
 623
 624   return *quark;
 625 }
 626
 627 /**
 628  * gst_caps_features_contains:
 629  * @features: a #GstCapsFeatures.
 630  * @feature: a feature
 631  *
 632  * Check if @features contains @feature.
 633  *
 634  * Returns: %TRUE if @features contains @feature.
 635  *
 636  * Since: 1.2
 637  */
 638 gboolean
 639 gst_caps_features_contains (const GstCapsFeatures * features,
 640     const gchar * feature)
 641 {
 642   g_return_val_if_fail (features != NULL, FALSE);
 643   g_return_val_if_fail (feature != NULL, FALSE);
 644
 645   return gst_caps_features_contains_id (features,
 646       g_quark_from_string (feature));
 647 }
 648
 649 /**
 650  * gst_caps_features_contains_id:
 651  * @features: a #GstCapsFeatures.
 652  * @feature: a feature
 653  *
 654  * Check if @features contains @feature.
 655  *
 656  * Returns: %TRUE if @features contains @feature.
 657  *
 658  * Since: 1.2
 659  */
 660 gboolean
 661 gst_caps_features_contains_id (const GstCapsFeatures * features, GQuark feature)
 662 {
 663   guint i, n;
 664
 665   g_return_val_if_fail (features != NULL, FALSE);
 666   g_return_val_if_fail (feature != 0, FALSE);
 667
 668   if (features->is_any)
 669     return TRUE;
 670
 671   n = features->array->len;
 672   if (n == 0)
 673     return feature == _gst_caps_feature_memory_system_memory;
 674
 675   for (i = 0; i < n; i++) {
 676     if (gst_caps_features_get_nth_id (features, i) == feature)
 677       return TRUE;
 678   }
 679
 680   return FALSE;
 681 }
 682
 683 /**
 684  * gst_caps_features_is_equal:
 685  * @features1: a #GstCapsFeatures.
 686  * @features2: a #GstCapsFeatures.
 687  *
 688  * Check if @features1 and @features2 are equal.
 689  *
 690  * Returns: %TRUE if @features1 and @features2 are equal.
 691  *
 692  * Since: 1.2
 693  */
 694 gboolean
 695 gst_caps_features_is_equal (const GstCapsFeatures * features1,
 696     const GstCapsFeatures * features2)
 697 {
 698   guint i, n;
 699
 700   g_return_val_if_fail (features1 != NULL, FALSE);
 701   g_return_val_if_fail (features2 != NULL, FALSE);
 702
 703   if (features1->is_any || features2->is_any)
 704     return TRUE;
 705
 706   /* Check for the sysmem==empty case */
 707   if (features1->array->len == 0 && features2->array->len == 0)
 708     return TRUE;
 709   if (features1->array->len == 0 && features2->array->len == 1
 710       && gst_caps_features_contains_id (features2,
 711           _gst_caps_feature_memory_system_memory))
 712     return TRUE;
 713   if (features2->array->len == 0 && features1->array->len == 1
 714       && gst_caps_features_contains_id (features1,
 715           _gst_caps_feature_memory_system_memory))
 716     return TRUE;
 717
 718   if (features1->array->len != features2->array->len)
 719     return FALSE;
 720
 721   n = features1->array->len;
 722   for (i = 0; i < n; i++)
 723     if (!gst_caps_features_contains_id (features2,
 724             gst_caps_features_get_nth_id (features1, i)))
 725       return FALSE;
 726
 727   return TRUE;
 728 }
 729
 730 /**
 731  * gst_caps_features_is_any:
 732  * @features: a #GstCapsFeatures.
 733  *
 734  * Check if @features is %GST_CAPS_FEATURES_ANY.
 735  *
 736  * Returns: %TRUE if @features is %GST_CAPS_FEATURES_ANY.
 737  *
 738  * Since: 1.2
 739  */
 740 gboolean
 741 gst_caps_features_is_any (const GstCapsFeatures * features)
 742 {
 743   g_return_val_if_fail (features != NULL, FALSE);
 744
 745   return features->is_any;
 746 }
 747
 748 /**
 749  * gst_caps_features_add:
 750  * @features: a #GstCapsFeatures.
 751  * @feature: a feature.
 752  *
 753  * Adds @feature to @features.
 754  *
 755  * Since: 1.2
 756  */
 757 void
 758 gst_caps_features_add (GstCapsFeatures * features, const gchar * feature)
 759 {
 760   g_return_if_fail (features != NULL);
 761   g_return_if_fail (IS_MUTABLE (features));
 762   g_return_if_fail (feature != NULL);
 763   g_return_if_fail (!features->is_any);
 764
 765   gst_caps_features_add_id (features, g_quark_from_string (feature));
 766 }
 767
 768 /**
 769  * gst_caps_features_add_id:
 770  * @features: a #GstCapsFeatures.
 771  * @feature: a feature.
 772  *
 773  * Adds @feature to @features.
 774  *
 775  * Since: 1.2
 776  */
 777 void
 778 gst_caps_features_add_id (GstCapsFeatures * features, GQuark feature)
 779 {
 780   g_return_if_fail (features != NULL);
 781   g_return_if_fail (IS_MUTABLE (features));
 782   g_return_if_fail (feature != 0);
 783   g_return_if_fail (!features->is_any);
 784
 785   if (!gst_caps_feature_name_is_valid (g_quark_to_string (feature))) {
 786     g_warning ("Invalid caps feature name: %s", g_quark_to_string (feature));
 787     return;
 788   }
 789
 790   /* If features is empty it will contain sysmem, however
 791    * we want to add it explicitely if it is tried to be
 792    * added as first features
 793    */
 794   if (features->array->len > 0
 795       && gst_caps_features_contains_id (features, feature))
 796     return;
 797
 798   g_array_append_val (features->array, feature);
 799 }
 800
 801 /**
 802  * gst_caps_features_remove:
 803  * @features: a #GstCapsFeatures.
 804  * @feature: a feature.
 805  *
 806  * Removes @feature from @features.
 807  *
 808  * Since: 1.2
 809  */
 810 void
 811 gst_caps_features_remove (GstCapsFeatures * features, const gchar * feature)
 812 {
 813   g_return_if_fail (features != NULL);
 814   g_return_if_fail (IS_MUTABLE (features));
 815   g_return_if_fail (feature != NULL);
 816
 817   gst_caps_features_remove_id (features, g_quark_from_string (feature));
 818 }
 819
 820 /**
 821  * gst_caps_features_remove_id:
 822  * @features: a #GstCapsFeatures.
 823  * @feature: a feature.
 824  *
 825  * Removes @feature from @features.
 826  *
 827  * Since: 1.2
 828  */
 829 void
 830 gst_caps_features_remove_id (GstCapsFeatures * features, GQuark feature)
 831 {
 832   guint i, n;
 833
 834   g_return_if_fail (features != NULL);
 835   g_return_if_fail (IS_MUTABLE (features));
 836   g_return_if_fail (feature != 0);
 837
 838   n = features->array->len;
 839   for (i = 0; i < n; i++) {
 840     GQuark quark = gst_caps_features_get_nth_id (features, i);
 841
 842     if (quark == feature) {
 843       g_array_remove_index_fast (features->array, i);
 844       return;
 845     }
 846   }
 847 }
 848
 849 static void
 850 gst_caps_features_transform_to_string (const GValue * src_value,
 851     GValue * dest_value)
 852 {
 853   g_return_if_fail (src_value != NULL);
 854   g_return_if_fail (dest_value != NULL);
 855
 856   dest_value->data[0].v_pointer =
 857       gst_caps_features_to_string (src_value->data[0].v_pointer);
 858 }