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