2 * Copyright (C) 2013 Collabora Ltd.
3 * Author: Sebastian Dröge <sebastian.droege@collabora.co.uk>
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.
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.
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.
22 * SECTION:gstcapsfeatures
23 * @short_description: A set of features in caps
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.
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
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".
53 #include "gst_private.h"
54 #include "gstcapsfeatures.h"
57 GST_DEBUG_CATEGORY_STATIC (gst_caps_features_debug);
58 #define GST_CAT_DEFAULT gst_caps_features_debug
60 struct _GstCapsFeatures
63 gint *parent_refcount;
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;
74 G_DEFINE_BOXED_TYPE (GstCapsFeatures, gst_caps_features,
75 gst_caps_features_copy, gst_caps_features_free);
77 #define IS_MUTABLE(features) \
78 (!features->parent_refcount || \
79 g_atomic_int_get (features->parent_refcount) == 1)
82 gst_caps_features_transform_to_string (const GValue * src_value,
86 _priv_gst_caps_features_initialize (void)
88 GST_DEBUG_CATEGORY_INIT (gst_caps_features_debug, "caps-features", 0,
89 "GstCapsFeatures debug");
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);
95 g_value_register_transform_func (_gst_caps_features_type, G_TYPE_STRING,
96 gst_caps_features_transform_to_string);
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);
109 gst_is_caps_features (gconstpointer obj)
111 const GstCapsFeatures *features = obj;
113 return (obj != NULL && features->type == _gst_caps_features_type);
117 gst_caps_feature_name_is_valid (const gchar * feature)
119 #ifndef G_DISABLE_CHECKS
121 if (g_ascii_isalpha (*feature))
123 else if (*feature == ':')
133 if (*feature == '\0' || !g_ascii_isalpha (*feature))
137 if (g_ascii_isalnum (*feature))
139 else if (*feature == '\0')
150 * gst_caps_features_new_empty:
152 * Creates a new, empty #GstCapsFeatures.
154 * Free-function: gst_caps_features_free
156 * Returns: (transfer full): a new, empty #GstCapsFeatures
161 gst_caps_features_new_empty (void)
163 GstCapsFeatures *features;
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;
171 GST_TRACE ("created caps features %p", features);
177 * gst_caps_features_new_any:
179 * Creates a new, ANY #GstCapsFeatures. This will be equal
180 * to any other #GstCapsFeatures but caps with these are
183 * Free-function: gst_caps_features_free
185 * Returns: (transfer full): a new, ANY #GstCapsFeatures
190 gst_caps_features_new_any (void)
192 GstCapsFeatures *features;
194 features = gst_caps_features_new_empty ();
195 features->is_any = TRUE;
201 * gst_caps_features_new:
202 * @feature1: name of first feature to set
203 * @...: additional features
205 * Creates a new #GstCapsFeatures with the given features.
206 * The last argument must be %NULL.
208 * Free-function: gst_caps_features_free
210 * Returns: (transfer full): a new, empty #GstCapsFeatures
215 gst_caps_features_new (const gchar * feature1, ...)
217 GstCapsFeatures *features;
220 g_return_val_if_fail (feature1 != NULL, NULL);
222 va_start (varargs, feature1);
223 features = gst_caps_features_new_valist (feature1, varargs);
230 * gst_caps_features_new_valist:
231 * @feature1: name of first feature to set
232 * @varargs: variable argument list
234 * Creates a new #GstCapsFeatures with the given features.
236 * Free-function: gst_caps_features_free
238 * Returns: (transfer full): a new, empty #GstCapsFeatures
243 gst_caps_features_new_valist (const gchar * feature1, va_list varargs)
245 GstCapsFeatures *features;
247 g_return_val_if_fail (feature1 != NULL, NULL);
249 features = gst_caps_features_new_empty ();
252 gst_caps_features_add (features, feature1);
253 feature1 = va_arg (varargs, const gchar *);
260 * gst_caps_features_new_id:
261 * @feature1: name of first feature to set
262 * @...: additional features
264 * Creates a new #GstCapsFeatures with the given features.
265 * The last argument must be 0.
267 * Free-function: gst_caps_features_free
269 * Returns: (transfer full): a new, empty #GstCapsFeatures
274 gst_caps_features_new_id (GQuark feature1, ...)
276 GstCapsFeatures *features;
279 g_return_val_if_fail (feature1 != 0, NULL);
281 va_start (varargs, feature1);
282 features = gst_caps_features_new_id_valist (feature1, varargs);
289 * gst_caps_features_new_id_valist:
290 * @feature1: name of first feature to set
291 * @varargs: variable argument list
293 * Creates a new #GstCapsFeatures with the given features.
295 * Free-function: gst_caps_features_free
297 * Returns: (transfer full): a new, empty #GstCapsFeatures
302 gst_caps_features_new_id_valist (GQuark feature1, va_list varargs)
304 GstCapsFeatures *features;
306 g_return_val_if_fail (feature1 != 0, NULL);
308 features = gst_caps_features_new_empty ();
311 gst_caps_features_add_id (features, feature1);
312 feature1 = va_arg (varargs, GQuark);
319 * gst_caps_features_set_parent_refcount:
320 * @features: a #GstCapsFeatures
321 * @refcount: (in): a pointer to the parent's refcount
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.
328 * Returns: %TRUE if the parent refcount could be set.
333 gst_caps_features_set_parent_refcount (GstCapsFeatures * features,
336 g_return_val_if_fail (features != NULL, FALSE);
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);
346 if (refcount == NULL) {
347 g_return_val_if_fail (refcount != NULL, FALSE);
352 features->parent_refcount = refcount;
358 * gst_caps_features_copy:
359 * @features: a #GstCapsFeatures to duplicate
361 * Duplicates a #GstCapsFeatures and all its values.
363 * Free-function: gst_caps_features_free
365 * Returns: (transfer full): a new #GstCapsFeatures.
370 gst_caps_features_copy (const GstCapsFeatures * features)
372 GstCapsFeatures *copy;
375 g_return_val_if_fail (features != NULL, NULL);
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;
387 * gst_caps_features_free:
388 * @features: (in) (transfer full): the #GstCapsFeatures to free
390 * Frees a #GstCapsFeatures and all its values. The caps features must not
391 * have a parent when this function is called.
396 gst_caps_features_free (GstCapsFeatures * features)
398 g_return_if_fail (features != NULL);
399 g_return_if_fail (features->parent_refcount == NULL);
401 g_array_free (features->array, TRUE);
403 memset (features, 0xff, sizeof (GstCapsFeatures));
405 GST_TRACE ("free caps features %p", features);
407 g_slice_free (GstCapsFeatures, features);
411 * gst_caps_features_to_string:
412 * @features: a #GstCapsFeatures
414 * Converts @features to a human-readable string representation.
416 * For debugging purposes its easier to do something like this:
418 * GST_LOG ("features is %" GST_PTR_FORMAT, features);
420 * This prints the features in human readable form.
422 * Free-function: g_free
424 * Returns: (transfer full): a pointer to string allocated by g_malloc().
425 * g_free() after usage.
430 gst_caps_features_to_string (const GstCapsFeatures * features)
434 g_return_val_if_fail (features != NULL, NULL);
436 s = g_string_sized_new (FEATURES_ESTIMATED_STRING_LEN (features));
438 priv_gst_caps_features_append_to_gstring (features, s);
440 return g_string_free (s, FALSE);
444 priv_gst_caps_features_append_to_gstring (const GstCapsFeatures * features,
449 g_return_if_fail (features != NULL);
451 if (features->array->len == 0 && features->is_any) {
452 g_string_append (s, "ANY");
456 n = features->array->len;
457 for (i = 0; i < n; i++) {
458 GQuark *quark = &g_array_index (features->array, GQuark, i);
460 g_string_append (s, g_quark_to_string (*quark));
462 g_string_append (s, ", ");
467 * gst_caps_features_from_string:
468 * @features: a string representation of a #GstCapsFeatures.
470 * Creates a #GstCapsFeatures from a string representation.
472 * Free-function: gst_caps_features_free
474 * Returns: (transfer full): a new #GstCapsFeatures or %NULL when the string could
475 * not be parsed. Free with gst_caps_features_free() after use.
480 gst_caps_features_from_string (const gchar * features)
482 GstCapsFeatures *ret;
483 gboolean escape = FALSE;
484 const gchar *features_orig = features;
485 const gchar *feature;
487 ret = gst_caps_features_new_empty ();
489 if (!features || *features == '\0')
492 if (strcmp (features, "ANY") == 0) {
497 /* Skip trailing spaces */
498 while (*features == ' ')
509 } else if ((!escape && c == ',') || c == '\0') {
510 guint len = features - feature + 1;
515 g_warning ("Failed deserialize caps features '%s'", features_orig);
516 gst_caps_features_free (ret);
520 tmp = g_malloc (len);
521 memcpy (tmp, feature, len - 1);
530 if (strstr (tmp, " ") != NULL || *tmp == '\0') {
532 g_warning ("Failed deserialize caps features '%s'", features_orig);
533 gst_caps_features_free (ret);
537 gst_caps_features_add (ret, tmp);
543 /* Skip to the next value */
545 while (*features == ' ')
558 * gst_caps_features_get_size:
559 * @features: a #GstCapsFeatures.
561 * Returns the number of features in @features.
563 * Returns: The number of features in @features.
568 gst_caps_features_get_size (const GstCapsFeatures * features)
570 g_return_val_if_fail (features != NULL, 0);
572 return features->array->len;
576 * gst_caps_features_get_nth:
577 * @features: a #GstCapsFeatures.
578 * @i: index of the feature
580 * Returns the @i-th feature of @features.
582 * Returns: The @i-th feature of @features.
587 gst_caps_features_get_nth (const GstCapsFeatures * features, guint i)
589 const gchar *feature;
592 g_return_val_if_fail (features != NULL, NULL);
594 quark = gst_caps_features_get_nth_id (features, i);
598 feature = g_quark_to_string (quark);
603 * gst_caps_features_get_nth_id:
604 * @features: a #GstCapsFeatures.
605 * @i: index of the feature
607 * Returns the @i-th feature of @features.
609 * Returns: The @i-th feature of @features.
614 gst_caps_features_get_nth_id (const GstCapsFeatures * features, guint i)
618 g_return_val_if_fail (features != NULL, 0);
619 g_return_val_if_fail (i < features->array->len, 0);
621 quark = &g_array_index (features->array, GQuark, i);
627 * gst_caps_features_contains:
628 * @features: a #GstCapsFeatures.
629 * @feature: a feature
631 * Check if @features contains @feature.
633 * Returns: %TRUE if @features contains @feature.
638 gst_caps_features_contains (const GstCapsFeatures * features,
639 const gchar * feature)
641 g_return_val_if_fail (features != NULL, FALSE);
642 g_return_val_if_fail (feature != NULL, FALSE);
644 return gst_caps_features_contains_id (features,
645 g_quark_from_string (feature));
649 * gst_caps_features_contains_id:
650 * @features: a #GstCapsFeatures.
651 * @feature: a feature
653 * Check if @features contains @feature.
655 * Returns: %TRUE if @features contains @feature.
660 gst_caps_features_contains_id (const GstCapsFeatures * features, GQuark feature)
664 g_return_val_if_fail (features != NULL, FALSE);
665 g_return_val_if_fail (feature != 0, FALSE);
667 if (features->is_any)
670 n = features->array->len;
672 return feature == _gst_caps_feature_memory_system_memory;
674 for (i = 0; i < n; i++) {
675 if (gst_caps_features_get_nth_id (features, i) == feature)
683 * gst_caps_features_is_equal:
684 * @features1: a #GstCapsFeatures.
685 * @features2: a #GstCapsFeatures.
687 * Check if @features1 and @features2 are equal.
689 * Returns: %TRUE if @features1 and @features2 are equal.
694 gst_caps_features_is_equal (const GstCapsFeatures * features1,
695 const GstCapsFeatures * features2)
699 g_return_val_if_fail (features1 != NULL, FALSE);
700 g_return_val_if_fail (features2 != NULL, FALSE);
702 if (features1->is_any || features2->is_any)
705 /* Check for the sysmem==empty case */
706 if (features1->array->len == 0 && features2->array->len == 0)
708 if (features1->array->len == 0 && features2->array->len == 1
709 && gst_caps_features_contains_id (features2,
710 _gst_caps_feature_memory_system_memory))
712 if (features2->array->len == 0 && features1->array->len == 1
713 && gst_caps_features_contains_id (features1,
714 _gst_caps_feature_memory_system_memory))
717 if (features1->array->len != features2->array->len)
720 n = features1->array->len;
721 for (i = 0; i < n; i++)
722 if (!gst_caps_features_contains_id (features2,
723 gst_caps_features_get_nth_id (features1, i)))
730 * gst_caps_features_is_any:
731 * @features: a #GstCapsFeatures.
733 * Check if @features is %GST_CAPS_FEATURES_ANY.
735 * Returns: %TRUE if @features is %GST_CAPS_FEATURES_ANY.
740 gst_caps_features_is_any (const GstCapsFeatures * features)
742 g_return_val_if_fail (features != NULL, FALSE);
744 return features->is_any;
748 * gst_caps_features_add:
749 * @features: a #GstCapsFeatures.
750 * @feature: a feature.
752 * Adds @feature to @features.
757 gst_caps_features_add (GstCapsFeatures * features, const gchar * feature)
759 g_return_if_fail (features != NULL);
760 g_return_if_fail (IS_MUTABLE (features));
761 g_return_if_fail (feature != NULL);
762 g_return_if_fail (!features->is_any);
764 gst_caps_features_add_id (features, g_quark_from_string (feature));
768 * gst_caps_features_add_id:
769 * @features: a #GstCapsFeatures.
770 * @feature: a feature.
772 * Adds @feature to @features.
777 gst_caps_features_add_id (GstCapsFeatures * features, GQuark feature)
779 g_return_if_fail (features != NULL);
780 g_return_if_fail (IS_MUTABLE (features));
781 g_return_if_fail (feature != 0);
782 g_return_if_fail (!features->is_any);
784 if (!gst_caps_feature_name_is_valid (g_quark_to_string (feature))) {
785 g_warning ("Invalid caps feature name: %s", g_quark_to_string (feature));
789 /* If features is empty it will contain sysmem, however
790 * we want to add it explicitely if it is tried to be
791 * added as first features
793 if (features->array->len > 0
794 && gst_caps_features_contains_id (features, feature))
797 g_array_append_val (features->array, feature);
801 * gst_caps_features_remove:
802 * @features: a #GstCapsFeatures.
803 * @feature: a feature.
805 * Removes @feature from @features.
810 gst_caps_features_remove (GstCapsFeatures * features, const gchar * feature)
812 g_return_if_fail (features != NULL);
813 g_return_if_fail (IS_MUTABLE (features));
814 g_return_if_fail (feature != NULL);
816 gst_caps_features_remove_id (features, g_quark_from_string (feature));
820 * gst_caps_features_remove_id:
821 * @features: a #GstCapsFeatures.
822 * @feature: a feature.
824 * Removes @feature from @features.
829 gst_caps_features_remove_id (GstCapsFeatures * features, GQuark feature)
833 g_return_if_fail (features != NULL);
834 g_return_if_fail (IS_MUTABLE (features));
835 g_return_if_fail (feature != 0);
837 n = features->array->len;
838 for (i = 0; i < n; i++) {
839 GQuark quark = gst_caps_features_get_nth_id (features, i);
841 if (quark == feature) {
842 g_array_remove_index_fast (features->array, i);
849 gst_caps_features_transform_to_string (const GValue * src_value,
852 g_return_if_fail (src_value != NULL);
853 g_return_if_fail (dest_value != NULL);
855 dest_value->data[0].v_pointer =
856 gst_caps_features_to_string (src_value->data[0].v_pointer);