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