2 * Copyright (C) <2003> David A. Schleef <ds@schleef.org>
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.
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.
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., 51 Franklin St, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
23 * @short_description: Structure describing sets of media formats
24 * @see_also: #GstStructure, #GstMiniObject
26 * Caps (capabilities) are lightweight refcounted objects describing media types.
27 * They are composed of an array of #GstStructure.
29 * Caps are exposed on #GstPadTemplate to describe all possible types a
30 * given pad can handle. They are also stored in the #GstRegistry along with
31 * a description of the #GstElement.
33 * Caps are exposed on the element pads using the gst_pad_query_caps() pad
34 * function. This function describes the possible types that the pad can
35 * handle or produce at runtime.
37 * A #GstCaps can be constructed with the following code fragment:
40 * GstCaps *caps = gst_caps_new_simple ("video/x-raw",
41 * "format", G_TYPE_STRING, "I420",
42 * "framerate", GST_TYPE_FRACTION, 25, 1,
43 * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
44 * "width", G_TYPE_INT, 320,
45 * "height", G_TYPE_INT, 240,
49 * A #GstCaps is fixed when it has no fields with ranges or lists. Use
50 * gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a
51 * caps event to notify downstream elements of the current media type.
53 * Various methods exist to work with the media types such as subtracting
56 * Be aware that until 1.20 the #GstCaps / #GstStructure serialization into string
57 * had limited support for nested #GstCaps / #GstStructure fields. It could only
58 * support one level of nesting. Using more levels would lead to unexpected
59 * behavior when using serialization features, such as gst_caps_to_string() or
60 * gst_value_serialize() and their counterparts.
69 #define GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
70 #include "gst_private.h"
72 #include <gobject/gvaluecollector.h>
74 #define DEBUG_REFCOUNT
76 typedef struct _GstCapsArrayElement
78 GstStructure *structure;
79 GstCapsFeatures *features;
80 } GstCapsArrayElement;
82 typedef struct _GstCapsImpl
89 #define GST_CAPS_ARRAY(c) (((GstCapsImpl *)(c))->array)
91 #define GST_CAPS_LEN(c) (GST_CAPS_ARRAY(c)->len)
93 #define IS_WRITABLE(caps) \
94 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
96 /* same as gst_caps_is_any () */
97 #define CAPS_IS_ANY(caps) \
98 (!!(GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY))
100 /* same as gst_caps_is_empty () */
101 #define CAPS_IS_EMPTY(caps) \
102 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
104 #define CAPS_IS_EMPTY_SIMPLE(caps) \
105 ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
107 #define gst_caps_features_copy_conditional(f) ((f && (gst_caps_features_is_any (f) || !gst_caps_features_is_equal (f, GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY))) ? gst_caps_features_copy (f) : NULL)
109 /* quick way to get a caps structure at an index without doing a type or array
111 #define gst_caps_get_structure_unchecked(caps, index) \
112 (g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, (index)).structure)
113 #define gst_caps_get_features_storage_unchecked(caps, index) \
114 (&g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, (index)).features)
115 #define gst_caps_get_features_unchecked(caps, index) \
116 (g_atomic_pointer_get (gst_caps_get_features_storage_unchecked (caps, index)))
117 /* quick way to append a structure without checking the args */
118 #define gst_caps_append_structure_unchecked(caps, s, f) G_STMT_START{\
119 GstCapsArrayElement __e={s, f}; \
120 if (gst_structure_set_parent_refcount (__e.structure, &GST_MINI_OBJECT_REFCOUNT(caps)) && \
121 (!__e.features || gst_caps_features_set_parent_refcount (__e.features, &GST_MINI_OBJECT_REFCOUNT(caps)))) \
122 g_array_append_val (GST_CAPS_ARRAY (caps), __e); \
125 /* lock to protect multiple invocations of static caps to caps conversion */
126 G_LOCK_DEFINE_STATIC (static_caps_lock);
128 static void gst_caps_transform_to_string (const GValue * src_value,
129 GValue * dest_value);
130 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
131 const gchar * string);
133 GType _gst_caps_type = 0;
134 GstCaps *_gst_caps_any;
135 GstCaps *_gst_caps_none;
137 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
140 _priv_gst_caps_initialize (void)
142 _gst_caps_type = gst_caps_get_type ();
144 _gst_caps_any = gst_caps_new_any ();
145 _gst_caps_none = gst_caps_new_empty ();
147 g_value_register_transform_func (_gst_caps_type,
148 G_TYPE_STRING, gst_caps_transform_to_string);
152 _priv_gst_caps_cleanup (void)
154 gst_caps_unref (_gst_caps_any);
155 _gst_caps_any = NULL;
156 gst_caps_unref (_gst_caps_none);
157 _gst_caps_none = NULL;
161 __gst_caps_get_features_unchecked (const GstCaps * caps, guint idx)
163 return gst_caps_get_features_unchecked (caps, idx);
167 _gst_caps_copy (const GstCaps * caps)
170 GstStructure *structure;
171 GstCapsFeatures *features;
174 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
176 newcaps = gst_caps_new_empty ();
177 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
178 n = GST_CAPS_LEN (caps);
180 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "doing copy %p -> %p", caps, newcaps);
182 for (i = 0; i < n; i++) {
183 structure = gst_caps_get_structure_unchecked (caps, i);
184 features = gst_caps_get_features_unchecked (caps, i);
185 gst_caps_append_structure_full (newcaps, gst_structure_copy (structure),
186 gst_caps_features_copy_conditional (features));
192 /* creation/deletion */
194 _gst_caps_free (GstCaps * caps)
196 GstStructure *structure;
197 GstCapsFeatures *features;
200 /* The refcount must be 0, but since we're only called by gst_caps_unref,
201 * don't bother testing. */
202 len = GST_CAPS_LEN (caps);
203 /* This can be used to get statistics about caps sizes */
204 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
205 for (i = 0; i < len; i++) {
206 structure = gst_caps_get_structure_unchecked (caps, i);
207 gst_structure_set_parent_refcount (structure, NULL);
208 gst_structure_free (structure);
209 features = gst_caps_get_features_unchecked (caps, i);
211 gst_caps_features_set_parent_refcount (features, NULL);
212 gst_caps_features_free (features);
215 g_array_free (GST_CAPS_ARRAY (caps), TRUE);
217 #ifdef DEBUG_REFCOUNT
218 GST_CAT_TRACE (GST_CAT_CAPS, "freeing caps %p", caps);
222 memset (caps, 0xff, sizeof (GstCapsImpl));
225 g_slice_free1 (sizeof (GstCapsImpl), caps);
229 gst_caps_init (GstCaps * caps)
231 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), 0, _gst_caps_type,
232 (GstMiniObjectCopyFunction) _gst_caps_copy, NULL,
233 (GstMiniObjectFreeFunction) _gst_caps_free);
235 /* the 32 has been determined by logging caps sizes in _gst_caps_free
236 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
238 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
240 GST_CAPS_ARRAY (caps) =
241 g_array_new (FALSE, TRUE, sizeof (GstCapsArrayElement));
245 * gst_caps_new_empty:
247 * Creates a new #GstCaps that is empty. That is, the returned
248 * #GstCaps contains no media formats.
249 * The #GstCaps is guaranteed to be writable.
251 * Returns: (transfer full): the new #GstCaps
254 gst_caps_new_empty (void)
258 caps = (GstCaps *) g_slice_new (GstCapsImpl);
260 gst_caps_init (caps);
262 #ifdef DEBUG_REFCOUNT
263 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
272 * Creates a new #GstCaps that indicates that it is compatible with
275 * Returns: (transfer full): the new #GstCaps
278 gst_caps_new_any (void)
280 GstCaps *caps = gst_caps_new_empty ();
282 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
288 * gst_caps_new_empty_simple:
289 * @media_type: the media type of the structure
291 * Creates a new #GstCaps that contains one #GstStructure with name
294 * Returns: (transfer full): the new #GstCaps
297 gst_caps_new_empty_simple (const char *media_type)
300 GstStructure *structure;
302 caps = gst_caps_new_empty ();
303 if (strcmp ("ANY", media_type) == 0) {
305 ("media_type should not be ANY. Please consider using `gst_caps_new_any` or `gst_caps_from_string`.");
307 if (strcmp ("", media_type) == 0 || strcmp ("EMPTY", media_type) == 0
308 || strcmp ("NONE", media_type) == 0) {
310 ("media_type should not be `%s`. Please consider using `gst_caps_new_empty` or `gst_caps_from_string`.",
313 structure = gst_structure_new_empty (media_type);
315 gst_caps_append_structure_unchecked (caps, structure, NULL);
321 * gst_caps_new_simple:
322 * @media_type: the media type of the structure
323 * @fieldname: first field to set
324 * @...: additional arguments
326 * Creates a new #GstCaps that contains one #GstStructure. The
327 * structure is defined by the arguments, which have the same format
328 * as gst_structure_new().
330 * Returns: (transfer full): the new #GstCaps
333 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
336 GstStructure *structure;
339 caps = gst_caps_new_empty ();
341 va_start (var_args, fieldname);
342 structure = gst_structure_new_valist (media_type, fieldname, var_args);
346 gst_caps_append_structure_unchecked (caps, structure, NULL);
348 gst_caps_replace (&caps, NULL);
355 * @struct1: the first structure to add
356 * @...: additional structures to add
358 * Creates a new #GstCaps and adds all the structures listed as
359 * arguments. The list must be %NULL-terminated. The structures
360 * are not copied; the returned #GstCaps owns the structures.
362 * Returns: (transfer full): the new #GstCaps
365 gst_caps_new_full (GstStructure * struct1, ...)
370 va_start (var_args, struct1);
371 caps = gst_caps_new_full_valist (struct1, var_args);
378 * gst_caps_new_full_valist:
379 * @structure: the first structure to add
380 * @var_args: additional structures to add
382 * Creates a new #GstCaps and adds all the structures listed as
383 * arguments. The list must be %NULL-terminated. The structures
384 * are not copied; the returned #GstCaps owns the structures.
386 * Returns: (transfer full): the new #GstCaps
389 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
393 caps = gst_caps_new_empty ();
396 gst_caps_append_structure_unchecked (caps, structure, NULL);
397 structure = va_arg (var_args, GstStructure *);
403 G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
406 * gst_static_caps_get:
407 * @static_caps: the #GstStaticCaps to convert
409 * Converts a #GstStaticCaps to a #GstCaps.
411 * Returns: (transfer full) (nullable): a pointer to the #GstCaps. Since the
412 * core holds an additional ref to the returned caps, use
413 * gst_caps_make_writable() on the returned caps to modify it.
416 gst_static_caps_get (GstStaticCaps * static_caps)
420 g_return_val_if_fail (static_caps != NULL, NULL);
422 caps = &static_caps->caps;
424 /* refcount is 0 when we need to convert */
425 if (G_UNLIKELY (*caps == NULL)) {
428 G_LOCK (static_caps_lock);
429 /* check if other thread already updated */
430 if (G_UNLIKELY (*caps != NULL))
433 string = static_caps->string;
435 if (G_UNLIKELY (string == NULL))
438 *caps = gst_caps_from_string (string);
440 /* convert to string */
441 if (G_UNLIKELY (*caps == NULL)) {
442 g_critical ("Could not convert static caps \"%s\"", string);
446 /* Caps generated from static caps are usually leaked */
447 GST_MINI_OBJECT_FLAG_SET (*caps, GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED);
449 GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
452 G_UNLOCK (static_caps_lock);
454 /* ref the caps, makes it not writable */
455 if (G_LIKELY (*caps != NULL))
456 gst_caps_ref (*caps);
463 G_UNLOCK (static_caps_lock);
464 g_warning ("static caps %p string is NULL", static_caps);
470 * gst_static_caps_cleanup:
471 * @static_caps: the #GstStaticCaps to clean
473 * Cleans up the cached caps contained in @static_caps.
476 gst_static_caps_cleanup (GstStaticCaps * static_caps)
478 G_LOCK (static_caps_lock);
479 gst_caps_replace (&static_caps->caps, NULL);
480 G_UNLOCK (static_caps_lock);
486 gst_caps_remove_and_get_structure_and_features (GstCaps * caps, guint idx,
487 GstStructure ** s, GstCapsFeatures ** f)
492 s_ = gst_caps_get_structure_unchecked (caps, idx);
493 f_ = gst_caps_get_features_unchecked (caps, idx);
495 /* don't use index_fast, gst_caps_simplify relies on the order */
496 g_array_remove_index (GST_CAPS_ARRAY (caps), idx);
498 gst_structure_set_parent_refcount (s_, NULL);
500 gst_caps_features_set_parent_refcount (f_, NULL);
507 static GstStructure *
508 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
513 gst_caps_remove_and_get_structure_and_features (caps, idx, &s, &f);
516 gst_caps_features_free (f);
522 gst_caps_make_any (GstCaps * caps)
527 /* empty out residual structures */
528 for (i = GST_CAPS_LEN (caps); i; i--) {
529 s = gst_caps_remove_and_get_structure (caps, 0);
530 gst_structure_free (s);
532 GST_CAPS_FLAGS (caps) |= GST_CAPS_FLAG_ANY;
536 * gst_caps_steal_structure:
537 * @caps: the #GstCaps to retrieve from
538 * @index: Index of the structure to retrieve
540 * Retrieves the structure with the given index from the list of structures
541 * contained in @caps. The caller becomes the owner of the returned structure.
543 * Returns: (transfer full) (nullable): a pointer to the #GstStructure
544 * corresponding to @index.
547 gst_caps_steal_structure (GstCaps * caps, guint index)
549 g_return_val_if_fail (caps != NULL, NULL);
550 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
552 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
555 return gst_caps_remove_and_get_structure (caps, index);
560 * @caps1: the #GstCaps that will be appended to
561 * @caps2: (transfer full): the #GstCaps to append
563 * Appends the structures contained in @caps2 to @caps1. The structures in
564 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
565 * freed. If either caps is ANY, the resulting caps will be ANY.
568 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
570 GstStructure *structure;
571 GstCapsFeatures *features;
574 g_return_if_fail (GST_IS_CAPS (caps1));
575 g_return_if_fail (GST_IS_CAPS (caps2));
576 g_return_if_fail (IS_WRITABLE (caps1));
578 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
579 gst_caps_make_any (caps1);
580 gst_caps_unref (caps2);
582 caps2 = gst_caps_make_writable (caps2);
584 for (i = GST_CAPS_LEN (caps2); i; i--) {
585 gst_caps_remove_and_get_structure_and_features (caps2, 0, &structure,
587 gst_caps_append_structure_unchecked (caps1, structure, features);
589 gst_caps_unref (caps2); /* guaranteed to free it */
595 * @caps1: (transfer full): the #GstCaps that will take the new entries
596 * @caps2: (transfer full): the #GstCaps to merge in
598 * Appends the structures contained in @caps2 to @caps1 if they are not yet
599 * expressed by @caps1. The structures in @caps2 are not copied -- they are
600 * transferred to a writable copy of @caps1, and then @caps2 is freed.
601 * If either caps is ANY, the resulting caps will be ANY.
603 * Returns: (transfer full): the merged caps.
606 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
608 GstStructure *structure;
609 GstCapsFeatures *features;
613 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
614 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
616 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
617 gst_caps_unref (caps2);
619 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
620 gst_caps_unref (caps1);
623 caps2 = gst_caps_make_writable (caps2);
625 for (i = GST_CAPS_LEN (caps2); i; i--) {
626 gst_caps_remove_and_get_structure_and_features (caps2, 0, &structure,
628 caps1 = gst_caps_merge_structure_full (caps1, structure, features);
630 gst_caps_unref (caps2);
634 GstCaps *com = gst_caps_intersect (caps1, caps2);
635 GstCaps *add = gst_caps_subtract (caps2, com);
637 GST_DEBUG ("common : %d", gst_caps_get_size (com));
638 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
639 gst_caps_append (caps1, add);
640 gst_caps_unref (com);
648 * gst_caps_append_structure:
649 * @caps: the #GstCaps that will be appended to
650 * @structure: (transfer full): the #GstStructure to append
652 * Appends @structure to @caps. The structure is not copied; @caps
653 * becomes the owner of @structure.
656 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
658 g_return_if_fail (GST_IS_CAPS (caps));
659 g_return_if_fail (IS_WRITABLE (caps));
661 if (CAPS_IS_ANY (caps)) {
662 /* ANY caps will stay as ANY caps */
664 gst_structure_free (structure);
668 if (G_LIKELY (structure)) {
669 gst_caps_append_structure_unchecked (caps, structure, NULL);
674 * gst_caps_append_structure_full:
675 * @caps: the #GstCaps that will be appended to
676 * @structure: (transfer full): the #GstStructure to append
677 * @features: (transfer full) (allow-none): the #GstCapsFeatures to append
679 * Appends @structure with @features to @caps. The structure is not copied; @caps
680 * becomes the owner of @structure.
685 gst_caps_append_structure_full (GstCaps * caps, GstStructure * structure,
686 GstCapsFeatures * features)
688 g_return_if_fail (GST_IS_CAPS (caps));
689 g_return_if_fail (IS_WRITABLE (caps));
691 if (CAPS_IS_ANY (caps)) {
692 /* ANY caps will stay as ANY caps */
694 gst_structure_free (structure);
696 gst_caps_features_free (features);
700 if (G_LIKELY (structure)) {
701 gst_caps_append_structure_unchecked (caps, structure, features);
706 * gst_caps_remove_structure:
707 * @caps: the #GstCaps to remove from
708 * @idx: Index of the structure to remove
710 * Removes the structure with the given index from the list of structures
711 * contained in @caps.
714 gst_caps_remove_structure (GstCaps * caps, guint idx)
716 GstStructure *structure;
718 g_return_if_fail (caps != NULL);
719 g_return_if_fail (idx < gst_caps_get_size (caps));
720 g_return_if_fail (IS_WRITABLE (caps));
722 structure = gst_caps_remove_and_get_structure (caps, idx);
723 gst_structure_free (structure);
727 * gst_caps_merge_structure:
728 * @caps: (transfer full): the #GstCaps to merge into
729 * @structure: (transfer full): the #GstStructure to merge
731 * Appends @structure to @caps if it is not already expressed by @caps.
733 * Returns: (transfer full): the merged caps.
736 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
738 GstStructure *structure1;
739 GstCapsFeatures *features1;
741 gboolean unique = TRUE;
743 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
745 if (G_UNLIKELY (structure == NULL))
748 if (CAPS_IS_ANY (caps)) {
749 /* ANY caps will stay as ANY caps */
750 gst_structure_free (structure);
754 /* check each structure */
755 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
756 structure1 = gst_caps_get_structure_unchecked (caps, i);
757 features1 = gst_caps_get_features_unchecked (caps, i);
759 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
761 /* if structure is a subset of structure1 and the
762 * there are no existing features, then skip it */
763 if (gst_caps_features_is_equal (features1,
764 GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY)
765 && gst_structure_is_subset (structure, structure1)) {
771 caps = gst_caps_make_writable (caps);
772 gst_caps_append_structure_unchecked (caps, structure, NULL);
774 gst_structure_free (structure);
780 * gst_caps_merge_structure_full:
781 * @caps: (transfer full): the #GstCaps to merge into
782 * @structure: (transfer full): the #GstStructure to merge
783 * @features: (transfer full) (allow-none): the #GstCapsFeatures to merge
785 * Appends @structure with @features to @caps if its not already expressed by @caps.
787 * Returns: (transfer full): the merged caps.
792 gst_caps_merge_structure_full (GstCaps * caps, GstStructure * structure,
793 GstCapsFeatures * features)
795 GstStructure *structure1;
796 GstCapsFeatures *features1, *features_tmp;
798 gboolean unique = TRUE;
800 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
802 if (G_UNLIKELY (structure == NULL))
805 if (CAPS_IS_ANY (caps)) {
806 /* ANY caps will stay as ANY caps */
807 gst_structure_free (structure);
809 gst_caps_features_free (features);
813 /* To make comparisons easier below */
814 features_tmp = features ? features : GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
816 /* check each structure */
817 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
818 structure1 = gst_caps_get_structure_unchecked (caps, i);
819 features1 = gst_caps_get_features_unchecked (caps, i);
821 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
822 /* if structure is a subset of structure1 and the
823 * the features are a subset, then skip it */
824 /* FIXME: We only skip if none of the features are
825 * ANY and are still equal. That way all ANY structures
826 * show up in the caps and no non-ANY structures are
827 * swallowed by ANY structures
829 if (((!gst_caps_features_is_any (features_tmp)
830 || gst_caps_features_is_any (features1))
831 && gst_caps_features_is_equal (features_tmp, features1))
832 && gst_structure_is_subset (structure, structure1)) {
838 caps = gst_caps_make_writable (caps);
839 gst_caps_append_structure_unchecked (caps, structure, features);
841 gst_structure_free (structure);
843 gst_caps_features_free (features);
852 * Gets the number of structures contained in @caps.
854 * Returns: the number of structures that @caps contains
857 gst_caps_get_size (const GstCaps * caps)
859 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
861 return GST_CAPS_LEN (caps);
865 * gst_caps_get_structure:
867 * @index: the index of the structure
869 * Finds the structure in @caps at @index, and returns it.
871 * WARNING: This function takes a `const GstCaps *`, but returns a
872 * non-const `GstStructure *`. This is for programming convenience --
873 * the caller should be aware that structures inside a constant
874 * #GstCaps should not be modified. However, if you know the caps
875 * are writable, either because you have just copied them or made
876 * them writable with gst_caps_make_writable(), you may modify the
877 * structure returned in the usual way, e.g. with functions like
878 * gst_structure_set().
880 * Returns: (transfer none): a pointer to the #GstStructure corresponding
884 gst_caps_get_structure (const GstCaps * caps, guint index)
886 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
887 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
889 return gst_caps_get_structure_unchecked (caps, index);
893 * gst_caps_get_features:
895 * @index: the index of the structure
897 * Finds the features in @caps at @index, and returns it.
899 * WARNING: This function takes a `const GstCaps *`, but returns a
900 * non-const `GstCapsFeatures *`. This is for programming convenience --
901 * the caller should be aware that features inside a constant
902 * #GstCaps should not be modified. However, if you know the caps
903 * are writable, either because you have just copied them or made
904 * them writable with gst_caps_make_writable(), you may modify the
905 * features returned in the usual way, e.g. with functions like
906 * gst_caps_features_add().
908 * Returns: (transfer none) (nullable): a pointer to the #GstCapsFeatures
909 * corresponding to @index
914 gst_caps_get_features (const GstCaps * caps, guint index)
916 GstCapsFeatures *features;
918 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
919 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
921 features = gst_caps_get_features_unchecked (caps, index);
923 GstCapsFeatures **storage;
925 /* We have to do some atomic pointer magic here as the caps
926 * might not be writable and someone else calls this function
927 * at the very same time */
928 features = gst_caps_features_copy (GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY);
929 gst_caps_features_set_parent_refcount (features, &GST_CAPS_REFCOUNT (caps));
931 storage = gst_caps_get_features_storage_unchecked (caps, index);
932 if (!g_atomic_pointer_compare_and_exchange (storage,
933 (GstCapsFeatures *) NULL, features)) {
934 /* Someone did the same we just tried in the meantime */
935 gst_caps_features_set_parent_refcount (features, NULL);
936 gst_caps_features_free (features);
938 features = gst_caps_get_features_unchecked (caps, index);
939 g_assert (features != NULL);
947 * gst_caps_set_features:
949 * @index: the index of the structure
950 * @features: (allow-none) (transfer full): the #GstCapsFeatures to set
952 * Sets the @features for the structure at @index.
957 gst_caps_set_features (GstCaps * caps, guint index, GstCapsFeatures * features)
959 GstCapsFeatures **storage, *old;
961 g_return_if_fail (caps != NULL);
962 g_return_if_fail (index < gst_caps_get_size (caps));
963 g_return_if_fail (IS_WRITABLE (caps));
965 storage = gst_caps_get_features_storage_unchecked (caps, index);
966 /* Not much problem here as caps are writable */
967 old = g_atomic_pointer_get (storage);
968 g_atomic_pointer_set (storage, features);
971 gst_caps_features_set_parent_refcount (features, &GST_CAPS_REFCOUNT (caps));
974 gst_caps_features_set_parent_refcount (old, NULL);
975 gst_caps_features_free (old);
980 * gst_caps_set_features_simple:
982 * @features: (allow-none) (transfer full): the #GstCapsFeatures to set
984 * Sets the @features for all the structures of @caps.
989 gst_caps_set_features_simple (GstCaps * caps, GstCapsFeatures * features)
994 g_return_if_fail (caps != NULL);
995 g_return_if_fail (IS_WRITABLE (caps));
997 n = gst_caps_get_size (caps);
1000 /* features will not be set on any structure */
1002 gst_caps_features_free (features);
1006 for (i = 0; i < n; i++) {
1009 /* Transfer ownership of @features to the last structure */
1010 if (features && i < n - 1)
1011 f = gst_caps_features_copy (features);
1015 gst_caps_set_features (caps, i, f);
1020 * gst_caps_copy_nth:
1021 * @caps: the #GstCaps to copy
1022 * @nth: the nth structure to copy
1024 * Creates a new #GstCaps and appends a copy of the nth structure
1025 * contained in @caps.
1027 * Returns: (transfer full): the new #GstCaps
1032 gst_caps_copy_nth (const GstCaps * caps, guint nth)
1035 GstStructure *structure;
1036 GstCapsFeatures *features;
1038 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1040 newcaps = gst_caps_new_empty ();
1041 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
1043 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
1044 structure = gst_caps_get_structure_unchecked (caps, nth);
1045 features = gst_caps_get_features_unchecked (caps, nth);
1046 gst_caps_append_structure_unchecked (newcaps,
1047 gst_structure_copy (structure),
1048 gst_caps_features_copy_conditional (features));
1055 * gst_caps_truncate:
1056 * @caps: (transfer full): the #GstCaps to truncate
1058 * Discards all but the first structure from @caps. Useful when
1061 * This function takes ownership of @caps and will call gst_caps_make_writable()
1062 * on it if necessary, so you must not use @caps afterwards unless you keep an
1063 * additional reference to it with gst_caps_ref().
1065 * Note that it is not guaranteed that the returned caps have exactly one
1066 * structure. If @caps is any or empty caps then the returned caps will be
1067 * the same and contain no structure at all.
1069 * Returns: (transfer full): truncated caps
1072 gst_caps_truncate (GstCaps * caps)
1076 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1078 /* Nothing to truncate here */
1079 if (GST_CAPS_LEN (caps) == 0)
1082 i = GST_CAPS_LEN (caps) - 1;
1084 /* Already truncated */
1088 caps = gst_caps_make_writable (caps);
1090 gst_caps_remove_structure (caps, i--);
1096 * gst_caps_set_value:
1097 * @caps: a writable caps
1098 * @field: name of the field to set
1099 * @value: value to set the field to
1101 * Sets the given @field on all structures of @caps to the given @value.
1102 * This is a convenience function for calling gst_structure_set_value() on
1103 * all structures of @caps.
1106 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
1110 g_return_if_fail (GST_IS_CAPS (caps));
1111 g_return_if_fail (IS_WRITABLE (caps));
1112 g_return_if_fail (field != NULL);
1113 g_return_if_fail (G_IS_VALUE (value));
1115 len = GST_CAPS_LEN (caps);
1116 for (i = 0; i < len; i++) {
1117 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
1118 gst_structure_set_value (structure, field, value);
1123 * gst_caps_set_simple_valist:
1124 * @caps: the #GstCaps to set
1125 * @field: first field to set
1126 * @varargs: additional parameters
1128 * Sets fields in a #GstCaps. The arguments must be passed in the same
1129 * manner as gst_structure_set(), and be %NULL-terminated.
1132 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
1134 GValue value = { 0, };
1136 g_return_if_fail (GST_IS_CAPS (caps));
1137 g_return_if_fail (IS_WRITABLE (caps));
1143 type = va_arg (varargs, GType);
1145 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
1146 if (G_UNLIKELY (err)) {
1147 g_critical ("%s", err);
1152 gst_caps_set_value (caps, field, &value);
1154 g_value_unset (&value);
1156 field = va_arg (varargs, const gchar *);
1161 * gst_caps_set_simple:
1162 * @caps: the #GstCaps to set
1163 * @field: first field to set
1164 * @...: additional parameters
1166 * Sets fields in a #GstCaps. The arguments must be passed in the same
1167 * manner as gst_structure_set(), and be %NULL-terminated.
1170 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
1174 g_return_if_fail (GST_IS_CAPS (caps));
1175 g_return_if_fail (IS_WRITABLE (caps));
1177 va_start (var_args, field);
1178 gst_caps_set_simple_valist (caps, field, var_args);
1186 * @caps: the #GstCaps to test
1188 * Determines if @caps represents any media format.
1190 * Returns: %TRUE if @caps represents any format.
1193 gst_caps_is_any (const GstCaps * caps)
1195 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1197 return (CAPS_IS_ANY (caps));
1201 * gst_caps_is_empty:
1202 * @caps: the #GstCaps to test
1204 * Determines if @caps represents no media formats.
1206 * Returns: %TRUE if @caps represents no formats.
1209 gst_caps_is_empty (const GstCaps * caps)
1211 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1213 if (CAPS_IS_ANY (caps))
1216 return CAPS_IS_EMPTY_SIMPLE (caps);
1220 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
1223 return gst_value_is_fixed (value);
1227 * gst_caps_is_fixed:
1228 * @caps: the #GstCaps to test
1230 * Fixed #GstCaps describe exactly one format, that is, they have exactly
1231 * one structure, and each field in the structure describes a fixed type.
1232 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
1234 * Returns: %TRUE if @caps is fixed
1237 gst_caps_is_fixed (const GstCaps * caps)
1239 GstStructure *structure;
1240 GstCapsFeatures *features;
1242 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1244 if (GST_CAPS_LEN (caps) != 1)
1247 /* double check not ANY, even though ANY caps should have 0 length */
1248 if (CAPS_IS_ANY (caps))
1251 features = gst_caps_get_features_unchecked (caps, 0);
1252 if (features && gst_caps_features_is_any (features))
1255 structure = gst_caps_get_structure_unchecked (caps, 0);
1257 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
1261 * gst_caps_is_equal_fixed:
1262 * @caps1: the #GstCaps to test
1263 * @caps2: the #GstCaps to test
1265 * Tests if two #GstCaps are equal. This function only works on fixed
1268 * Returns: %TRUE if the arguments represent the same format
1271 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
1273 GstStructure *struct1, *struct2;
1274 GstCapsFeatures *features1, *features2;
1276 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1277 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1279 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1280 features1 = gst_caps_get_features_unchecked (caps1, 0);
1282 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1283 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1284 features2 = gst_caps_get_features_unchecked (caps2, 0);
1286 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1288 return gst_structure_is_equal (struct1, struct2) &&
1289 gst_caps_features_is_equal (features1, features2);
1293 * gst_caps_is_always_compatible:
1294 * @caps1: the #GstCaps to test
1295 * @caps2: the #GstCaps to test
1297 * A given #GstCaps structure is always compatible with another if
1298 * every media format that is in the first is also contained in the
1299 * second. That is, @caps1 is a subset of @caps2.
1301 * Returns: %TRUE if @caps1 is a subset of @caps2.
1304 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1306 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1307 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1309 return gst_caps_is_subset (caps1, caps2);
1313 * gst_caps_is_subset:
1314 * @subset: a #GstCaps
1315 * @superset: a potentially greater #GstCaps
1317 * Checks if all caps represented by @subset are also represented by @superset.
1319 * Returns: %TRUE if @subset is a subset of @superset
1322 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1324 GstStructure *s1, *s2;
1325 GstCapsFeatures *f1, *f2;
1326 gboolean ret = TRUE;
1329 g_return_val_if_fail (subset != NULL, FALSE);
1330 g_return_val_if_fail (superset != NULL, FALSE);
1332 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1334 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1337 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
1338 s1 = gst_caps_get_structure_unchecked (subset, i);
1339 f1 = gst_caps_get_features_unchecked (subset, i);
1341 f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1343 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
1344 s2 = gst_caps_get_structure_unchecked (superset, j);
1345 f2 = gst_caps_get_features_unchecked (superset, j);
1347 f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1348 if ((!gst_caps_features_is_any (f1) || gst_caps_features_is_any (f2)) &&
1349 gst_caps_features_is_equal (f1, f2)
1350 && gst_structure_is_subset (s1, s2)) {
1351 /* If we found a superset, continue with the next
1352 * subset structure */
1357 /* If we found no superset for this subset structure
1358 * we return FALSE immediately */
1369 * gst_caps_is_subset_structure:
1371 * @structure: a potential #GstStructure subset of @caps
1373 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1374 * for more information.
1376 * Returns: %TRUE if @structure is a subset of @caps
1379 gst_caps_is_subset_structure (const GstCaps * caps,
1380 const GstStructure * structure)
1385 g_return_val_if_fail (caps != NULL, FALSE);
1386 g_return_val_if_fail (structure != NULL, FALSE);
1388 if (CAPS_IS_ANY (caps))
1390 if (CAPS_IS_EMPTY (caps))
1393 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1394 s = gst_caps_get_structure_unchecked (caps, i);
1395 if (gst_structure_is_subset (structure, s)) {
1396 /* If we found a superset return TRUE */
1405 * gst_caps_is_subset_structure_full:
1407 * @structure: a potential #GstStructure subset of @caps
1408 * @features: (allow-none): a #GstCapsFeatures for @structure
1410 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1411 * for more information.
1413 * Returns: %TRUE if @structure is a subset of @caps
1418 gst_caps_is_subset_structure_full (const GstCaps * caps,
1419 const GstStructure * structure, const GstCapsFeatures * features)
1425 g_return_val_if_fail (caps != NULL, FALSE);
1426 g_return_val_if_fail (structure != NULL, FALSE);
1428 if (CAPS_IS_ANY (caps))
1430 if (CAPS_IS_EMPTY (caps))
1434 features = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1436 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1437 s = gst_caps_get_structure_unchecked (caps, i);
1438 f = gst_caps_get_features_unchecked (caps, i);
1440 f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1441 if ((!gst_caps_features_is_any (features) || gst_caps_features_is_any (f))
1442 && gst_caps_features_is_equal (features, f)
1443 && gst_structure_is_subset (structure, s)) {
1444 /* If we found a superset return TRUE */
1453 * gst_caps_is_equal:
1454 * @caps1: a #GstCaps
1455 * @caps2: another #GstCaps
1457 * Checks if the given caps represent the same set of caps.
1459 * Returns: %TRUE if both caps are equal.
1462 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1464 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1465 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1467 if (G_UNLIKELY (caps1 == caps2))
1470 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1471 return gst_caps_is_equal_fixed (caps1, caps2);
1473 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1477 * gst_caps_is_strictly_equal:
1478 * @caps1: a #GstCaps
1479 * @caps2: another #GstCaps
1481 * Checks if the given caps are exactly the same set of caps.
1483 * Returns: %TRUE if both caps are strictly equal.
1486 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1489 GstStructure *s1, *s2;
1490 GstCapsFeatures *f1, *f2;
1492 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1493 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1495 if (G_UNLIKELY (caps1 == caps2))
1498 /* if both are ANY caps, consider them strictly equal */
1499 if (CAPS_IS_ANY (caps1))
1500 return (CAPS_IS_ANY (caps2));
1501 else if (CAPS_IS_ANY (caps2))
1504 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1507 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1508 s1 = gst_caps_get_structure_unchecked (caps1, i);
1509 f1 = gst_caps_get_features_unchecked (caps1, i);
1511 f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1512 s2 = gst_caps_get_structure_unchecked (caps2, i);
1513 f2 = gst_caps_get_features_unchecked (caps2, i);
1515 f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1517 if (gst_caps_features_is_any (f1) != gst_caps_features_is_any (f2) ||
1518 !gst_caps_features_is_equal (f1, f2) ||
1519 !gst_structure_is_equal (s1, s2))
1526 /* intersect operation */
1529 * gst_caps_can_intersect:
1530 * @caps1: a #GstCaps to intersect
1531 * @caps2: a #GstCaps to intersect
1533 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1536 * Returns: %TRUE if intersection would be not empty
1539 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1541 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1542 guint j, k, len1, len2;
1543 GstStructure *struct1;
1544 GstStructure *struct2;
1545 GstCapsFeatures *features1;
1546 GstCapsFeatures *features2;
1548 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1549 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1551 /* caps are exactly the same pointers */
1552 if (G_UNLIKELY (caps1 == caps2))
1555 /* empty caps on either side, return empty */
1556 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1559 /* one of the caps is any */
1560 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1563 /* run zigzag on top line then right line, this preserves the caps order
1564 * much better than a simple loop.
1566 * This algorithm zigzags over the caps structures as demonstrated in
1567 * the following matrix:
1570 * +------------- total distance: +-------------
1571 * | 1 2 4 7 0 | 0 1 2 3
1572 * caps2 | 3 5 8 10 1 | 1 2 3 4
1573 * | 6 9 11 12 2 | 2 3 4 5
1575 * First we iterate over the caps1 structures (top line) intersecting
1576 * the structures diagonally down, then we iterate over the caps2
1577 * structures. The result is that the intersections are ordered based on the
1578 * sum of the indexes in the list.
1580 len1 = GST_CAPS_LEN (caps1);
1581 len2 = GST_CAPS_LEN (caps2);
1582 for (i = 0; i < len1 + len2 - 1; i++) {
1583 /* superset index goes from 0 to superset->structs->len-1 */
1584 j = MIN (i, len1 - 1);
1585 /* subset index stays 0 until i reaches superset->structs->len, then it
1586 * counts up from 1 to subset->structs->len - 1 */
1587 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1588 /* now run the diagonal line, end condition is the left or bottom
1591 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1592 features1 = gst_caps_get_features_unchecked (caps1, j);
1594 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1595 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1596 features2 = gst_caps_get_features_unchecked (caps2, k);
1598 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1599 if (gst_caps_features_is_equal (features1, features2) &&
1600 gst_structure_can_intersect (struct1, struct2)) {
1603 /* move down left */
1605 if (G_UNLIKELY (j == 0))
1606 break; /* so we don't roll back to G_MAXUINT */
1615 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1617 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1618 guint j, k, len1, len2;
1619 GstStructure *struct1;
1620 GstStructure *struct2;
1621 GstCapsFeatures *features1;
1622 GstCapsFeatures *features2;
1624 GstStructure *istruct;
1626 dest = gst_caps_new_empty ();
1627 /* run zigzag on top line then right line, this preserves the caps order
1628 * much better than a simple loop.
1630 * This algorithm zigzags over the caps structures as demonstrated in
1631 * the following matrix:
1639 * First we iterate over the caps1 structures (top line) intersecting
1640 * the structures diagonally down, then we iterate over the caps2
1643 len1 = GST_CAPS_LEN (caps1);
1644 len2 = GST_CAPS_LEN (caps2);
1645 for (i = 0; i < len1 + len2 - 1; i++) {
1646 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1647 j = MIN (i, len1 - 1);
1648 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1649 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1650 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1651 /* now run the diagonal line, end condition is the left or bottom
1654 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1655 features1 = gst_caps_get_features_unchecked (caps1, j);
1657 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1658 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1659 features2 = gst_caps_get_features_unchecked (caps2, k);
1661 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1662 if (gst_caps_features_is_equal (features1, features2)) {
1663 istruct = gst_structure_intersect (struct1, struct2);
1665 if (gst_caps_features_is_any (features1))
1667 gst_caps_merge_structure_full (dest, istruct,
1668 gst_caps_features_copy_conditional (features2));
1671 gst_caps_merge_structure_full (dest, istruct,
1672 gst_caps_features_copy_conditional (features1));
1675 /* move down left */
1677 if (G_UNLIKELY (j == 0))
1678 break; /* so we don't roll back to G_MAXUINT */
1686 * gst_caps_intersect_first:
1687 * @caps1: a #GstCaps to intersect
1688 * @caps2: a #GstCaps to intersect
1690 * Creates a new #GstCaps that contains all the formats that are common
1691 * to both @caps1 and @caps2.
1693 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1694 * fashion as @caps1.
1696 * Returns: (transfer full): the new #GstCaps
1699 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1702 guint j, len1, len2;
1703 GstStructure *struct1;
1704 GstStructure *struct2;
1705 GstCapsFeatures *features1;
1706 GstCapsFeatures *features2;
1708 GstStructure *istruct;
1710 dest = gst_caps_new_empty ();
1711 len1 = GST_CAPS_LEN (caps1);
1712 len2 = GST_CAPS_LEN (caps2);
1713 for (i = 0; i < len1; i++) {
1714 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1715 features1 = gst_caps_get_features_unchecked (caps1, i);
1717 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1718 for (j = 0; j < len2; j++) {
1719 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1720 features2 = gst_caps_get_features_unchecked (caps2, j);
1722 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1723 if (gst_caps_features_is_equal (features1, features2)) {
1724 istruct = gst_structure_intersect (struct1, struct2);
1726 if (gst_caps_features_is_any (features1))
1728 gst_caps_merge_structure_full (dest, istruct,
1729 gst_caps_features_copy_conditional (features2));
1732 gst_caps_merge_structure_full (dest, istruct,
1733 gst_caps_features_copy_conditional (features1));
1743 * gst_caps_intersect_full:
1744 * @caps1: a #GstCaps to intersect
1745 * @caps2: a #GstCaps to intersect
1746 * @mode: The intersection algorithm/mode to use
1748 * Creates a new #GstCaps that contains all the formats that are common
1749 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1752 * Returns: (transfer full): the new #GstCaps
1755 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1756 GstCapsIntersectMode mode)
1758 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1759 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1761 /* Common fast-path */
1762 /* caps are exactly the same pointers, just copy one caps */
1763 if (G_UNLIKELY (caps1 == caps2))
1764 return gst_caps_ref (caps1);
1766 /* empty caps on either side, return empty */
1767 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1768 return gst_caps_ref (GST_CAPS_NONE);
1770 /* one of the caps is any, just copy the other caps */
1771 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1772 return gst_caps_ref (caps2);
1774 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1775 return gst_caps_ref (caps1);
1778 case GST_CAPS_INTERSECT_FIRST:
1779 return gst_caps_intersect_first (caps1, caps2);
1781 g_warning ("Unknown caps intersect mode: %d", mode);
1783 case GST_CAPS_INTERSECT_ZIG_ZAG:
1784 return gst_caps_intersect_zig_zag (caps1, caps2);
1789 * gst_caps_intersect:
1790 * @caps1: a #GstCaps to intersect
1791 * @caps2: a #GstCaps to intersect
1793 * Creates a new #GstCaps that contains all the formats that are common
1794 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1796 * Returns: (transfer full): the new #GstCaps
1799 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1801 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1804 /* subtract operation */
1808 const GstStructure *subtract_from;
1813 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1816 SubtractionEntry *e = user_data;
1817 GValue subtraction = { 0, };
1818 const GValue *other;
1819 GstStructure *structure;
1821 other = gst_structure_id_get_value (e->subtract_from, field_id);
1827 if (!gst_value_subtract (&subtraction, other, value))
1830 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1831 g_value_unset (&subtraction);
1834 structure = gst_structure_copy (e->subtract_from);
1835 gst_structure_id_take_value (structure, field_id, &subtraction);
1836 e->put_into = g_slist_prepend (e->put_into, structure);
1842 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1843 const GstStructure * subtrahend)
1848 e.subtract_from = minuend;
1850 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1851 gst_caps_structure_subtract_field, &e);
1858 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1859 gst_structure_free (walk->data);
1861 g_slist_free (e.put_into);
1868 * gst_caps_subtract:
1869 * @minuend: #GstCaps to subtract from
1870 * @subtrahend: #GstCaps to subtract
1872 * Subtracts the @subtrahend from the @minuend.
1873 * > This function does not work reliably if optional properties for caps
1874 * > are included on one caps and omitted on the other.
1876 * Returns: (transfer full): the resulting caps
1879 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1884 GstCapsFeatures *min_f, *sub_f;
1885 GstCaps *dest = NULL, *src;
1887 g_return_val_if_fail (minuend != NULL, NULL);
1888 g_return_val_if_fail (subtrahend != NULL, NULL);
1890 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1891 return gst_caps_new_empty ();
1894 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1895 return gst_caps_ref (minuend);
1897 /* FIXME: Do we want this here or above?
1898 The reason we need this is that there is no definition about what
1899 ANY means for specific types, so it's not possible to reduce ANY partially
1900 You can only remove everything or nothing and that is done above.
1901 Note: there's a test that checks this behaviour. */
1903 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1904 sublen = GST_CAPS_LEN (subtrahend);
1905 g_assert (sublen > 0);
1907 src = _gst_caps_copy (minuend);
1908 for (i = 0; i < sublen; i++) {
1911 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1912 sub_f = gst_caps_get_features_unchecked (subtrahend, i);
1914 sub_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1916 gst_caps_unref (src);
1919 dest = gst_caps_new_empty ();
1920 srclen = GST_CAPS_LEN (src);
1921 for (j = 0; j < srclen; j++) {
1922 min = gst_caps_get_structure_unchecked (src, j);
1923 min_f = gst_caps_get_features_unchecked (src, j);
1925 min_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1927 /* Same reason as above for ANY caps */
1928 g_return_val_if_fail (!gst_caps_features_is_any (min_f), NULL);
1930 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub) &&
1931 gst_caps_features_is_equal (min_f, sub_f)) {
1934 if (gst_caps_structure_subtract (&list, min, sub)) {
1937 for (walk = list; walk; walk = g_slist_next (walk)) {
1938 gst_caps_append_structure_unchecked (dest,
1939 (GstStructure *) walk->data,
1940 gst_caps_features_copy_conditional (min_f));
1942 g_slist_free (list);
1944 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1945 gst_caps_features_copy_conditional (min_f));
1948 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1949 gst_caps_features_copy_conditional (min_f));
1953 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1954 gst_caps_unref (src);
1959 gst_caps_unref (src);
1960 dest = gst_caps_simplify (dest);
1965 /* normalize/simplify operations */
1967 typedef struct _NormalizeForeach
1970 GstStructure *structure;
1971 GstCapsFeatures *features;
1975 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1977 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1981 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1982 guint len = gst_value_list_get_size (value);
1984 for (i = 1; i < len; i++) {
1985 const GValue *v = gst_value_list_get_value (value, i);
1986 GstStructure *structure = gst_structure_copy (nf->structure);
1988 gst_structure_id_set_value (structure, field_id, v);
1989 gst_caps_append_structure_unchecked (nf->caps, structure,
1990 gst_caps_features_copy_conditional (nf->features));
1993 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1994 gst_structure_id_take_value (nf->structure, field_id, &val);
2002 * gst_caps_normalize:
2003 * @caps: (transfer full): a #GstCaps to normalize
2005 * Returns a #GstCaps that represents the same set of formats as
2006 * @caps, but contains no lists. Each list is expanded into separate
2009 * This function takes ownership of @caps and will call gst_caps_make_writable()
2010 * on it so you must not use @caps afterwards unless you keep an additional
2011 * reference to it with gst_caps_ref().
2013 * Returns: (transfer full): the normalized #GstCaps
2016 gst_caps_normalize (GstCaps * caps)
2018 NormalizeForeach nf;
2021 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2023 caps = gst_caps_make_writable (caps);
2026 for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
2027 nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
2028 nf.features = gst_caps_get_features_unchecked (nf.caps, i);
2029 while (!gst_structure_foreach (nf.structure,
2030 gst_caps_normalize_foreach, &nf));
2037 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
2040 const GstStructure *struct1 = ((const GstCapsArrayElement *) one)->structure;
2041 const GstStructure *struct2 = ((const GstCapsArrayElement *) two)->structure;
2043 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
2044 So what's the best way? */
2045 ret = strcmp (gst_structure_get_name (struct1),
2046 gst_structure_get_name (struct2));
2051 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
2058 GstStructure *compare;
2062 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
2065 UnionField *u = user_data;
2066 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
2070 g_value_unset (&u->value);
2074 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
2078 g_value_unset (&u->value);
2083 gst_value_union (&u->value, val, value);
2089 gst_caps_structure_simplify (GstStructure ** result,
2090 GstStructure * simplify, GstStructure * compare)
2093 UnionField field = { 0, {0,}, NULL };
2095 /* try to subtract to get a real subset */
2096 if (gst_caps_structure_subtract (&list, simplify, compare)) {
2097 if (list == NULL) { /* no result */
2100 } else if (list->next == NULL) { /* one result */
2101 *result = list->data;
2102 g_slist_free (list);
2104 } else { /* multiple results */
2105 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
2106 g_slist_free (list);
2111 /* try to union both structs */
2112 field.compare = compare;
2113 if (gst_structure_foreach (simplify,
2114 gst_caps_structure_figure_out_union, &field)) {
2115 gboolean ret = FALSE;
2117 /* now we know all of simplify's fields are the same in compare
2118 * but at most one field: field.name */
2119 if (G_IS_VALUE (&field.value)) {
2120 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
2121 gst_structure_id_take_value (compare, field.name, &field.value);
2125 g_value_unset (&field.value);
2128 if (gst_structure_n_fields (simplify) <=
2129 gst_structure_n_fields (compare)) {
2130 /* compare is just more specific, will be optimized away later */
2131 /* FIXME: do this here? */
2132 GST_LOG ("found a case that will be optimized later.");
2134 gchar *one = gst_structure_to_string (simplify);
2135 gchar *two = gst_structure_to_string (compare);
2138 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
2150 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
2151 GstStructure * new, gint i)
2153 gst_structure_set_parent_refcount (old, NULL);
2154 gst_structure_free (old);
2155 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
2156 g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, i).structure = new;
2160 * gst_caps_simplify:
2161 * @caps: (transfer full): a #GstCaps to simplify
2163 * Converts the given @caps into a representation that represents the
2164 * same set of formats, but in a simpler form. Component structures that are
2165 * identical are merged. Component structures that have values that can be
2166 * merged are also merged.
2168 * This function takes ownership of @caps and will call gst_caps_make_writable()
2169 * on it if necessary, so you must not use @caps afterwards unless you keep an
2170 * additional reference to it with gst_caps_ref().
2172 * This method does not preserve the original order of @caps.
2174 * Returns: (transfer full): The simplified caps.
2177 gst_caps_simplify (GstCaps * caps)
2179 GstStructure *simplify, *compare, *result = NULL;
2180 GstCapsFeatures *simplify_f, *compare_f;
2183 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2185 /* empty/any caps are as simple as can be */
2186 if (GST_CAPS_LEN (caps) == 0)
2189 start = GST_CAPS_LEN (caps) - 1;
2190 /* one caps, already as simple as can be */
2194 caps = gst_caps_make_writable (caps);
2196 g_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
2198 for (i = start; i >= 0; i--) {
2199 simplify = gst_caps_get_structure_unchecked (caps, i);
2200 simplify_f = gst_caps_get_features_unchecked (caps, i);
2202 simplify_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2203 compare = gst_caps_get_structure_unchecked (caps, start);
2204 compare_f = gst_caps_get_features_unchecked (caps, start);
2206 compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2207 if (gst_structure_get_name_id (simplify) !=
2208 gst_structure_get_name_id (compare) ||
2209 !gst_caps_features_is_equal (simplify_f, compare_f))
2211 for (j = start; j >= 0; j--) {
2214 compare = gst_caps_get_structure_unchecked (caps, j);
2215 compare_f = gst_caps_get_features_unchecked (caps, j);
2217 compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2218 if (gst_structure_get_name_id (simplify) !=
2219 gst_structure_get_name_id (compare) ||
2220 !gst_caps_features_is_equal (simplify_f, compare_f)) {
2223 if (gst_caps_structure_simplify (&result, simplify, compare)) {
2225 gst_caps_switch_structures (caps, simplify, result, i);
2228 gst_caps_remove_structure (caps, i);
2240 * @caps: (transfer full): a #GstCaps to fixate
2242 * Modifies the given @caps into a representation with only fixed
2243 * values. First the caps will be truncated and then the first structure will be
2244 * fixated with gst_structure_fixate().
2246 * This function takes ownership of @caps and will call gst_caps_make_writable()
2247 * on it so you must not use @caps afterwards unless you keep an additional
2248 * reference to it with gst_caps_ref().
2250 * Note that it is not guaranteed that the returned caps have exactly one
2251 * structure. If @caps are empty caps then the returned caps will be
2252 * the empty too and contain no structure at all.
2254 * Calling this function with ANY caps is not allowed.
2256 * Returns: (transfer full): the fixated caps
2259 gst_caps_fixate (GstCaps * caps)
2264 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2265 g_return_val_if_fail (!CAPS_IS_ANY (caps), NULL);
2267 /* default fixation */
2268 caps = gst_caps_truncate (caps);
2269 caps = gst_caps_make_writable (caps);
2271 /* need to return early here because empty caps have no structure
2272 * but must return after make_writable() because the documentation
2273 * specifies that it will call make_writable() on the return value
2274 * and callers might assume writable caps.
2276 if (CAPS_IS_EMPTY (caps))
2279 s = gst_caps_get_structure (caps, 0);
2280 gst_structure_fixate (s);
2282 /* Set features to sysmem if they're still ANY */
2283 f = gst_caps_get_features_unchecked (caps, 0);
2284 if (f && gst_caps_features_is_any (f)) {
2285 f = gst_caps_features_new_empty ();
2286 gst_caps_set_features (caps, 0, f);
2295 caps_serialize (const GstCaps * caps, GstSerializeFlags flags)
2297 guint i, slen, clen;
2299 gboolean nested_structs_brackets =
2300 !(flags & GST_SERIALIZE_FLAG_BACKWARD_COMPAT);
2302 /* NOTE: This function is potentially called by the debug system,
2303 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2304 * should be careful to avoid recursion. This includes any functions
2305 * called by gst_caps_to_string. In particular, calls should
2306 * not use the GST_PTR_FORMAT extension. */
2309 return g_strdup ("NULL");
2311 if (CAPS_IS_ANY (caps)) {
2312 return g_strdup ("ANY");
2314 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2315 return g_strdup ("EMPTY");
2318 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2320 clen = GST_CAPS_LEN (caps);
2321 for (i = 0; i < clen; i++) {
2325 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked
2327 f = gst_caps_get_features_unchecked (caps, i);
2329 slen += FEATURES_ESTIMATED_STRING_LEN (f);
2332 s = g_string_sized_new (slen);
2333 for (i = 0; i < clen; i++) {
2334 GstStructure *structure;
2335 GstCapsFeatures *features;
2338 /* ';' is now added by gst_structure_to_string */
2339 g_string_append_c (s, ' ');
2342 structure = gst_caps_get_structure_unchecked (caps, i);
2343 features = gst_caps_get_features_unchecked (caps, i);
2345 g_string_append (s, gst_structure_get_name (structure));
2346 if (features && (gst_caps_features_is_any (features)
2347 || !gst_caps_features_is_equal (features,
2348 GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY))) {
2349 g_string_append_c (s, '(');
2350 priv_gst_caps_features_append_to_gstring (features, s);
2351 g_string_append_c (s, ')');
2353 priv_gst_structure_append_to_gstring (structure, s,
2354 nested_structs_brackets);
2356 if (s->len && s->str[s->len - 1] == ';') {
2357 /* remove latest ';' */
2358 s->str[--s->len] = '\0';
2360 return g_string_free (s, FALSE);
2364 * gst_caps_to_string:
2367 * Converts @caps to a string representation. This string representation
2368 * can be converted back to a #GstCaps by gst_caps_from_string().
2370 * For debugging purposes its easier to do something like this:
2373 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2376 * This prints the caps in human readable form.
2378 * The implementation of serialization up to 1.20 would lead to unexpected results
2379 * when there were nested #GstCaps / #GstStructure deeper than one level.
2381 * Returns: (transfer full): a newly allocated string representing @caps.
2384 gst_caps_to_string (const GstCaps * caps)
2386 return caps_serialize (caps, GST_SERIALIZE_FLAG_BACKWARD_COMPAT);
2390 * gst_caps_serialize:
2392 * @flags: a #GstSerializeFlags
2394 * Converts @caps to a string representation. This string representation can be
2395 * converted back to a #GstCaps by gst_caps_from_string().
2397 * This prints the caps in human readable form.
2399 * This version of the caps serialization function introduces support for nested
2400 * structures and caps but the resulting strings won't be parsable with
2401 * GStreamer prior to 1.20 unless #GST_SERIALIZE_FLAG_BACKWARD_COMPAT is passed
2404 * Returns: (transfer full): a newly allocated string representing @caps.
2409 gst_caps_serialize (const GstCaps * caps, GstSerializeFlags flags)
2411 return caps_serialize (caps, flags);
2415 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2417 GstStructure *structure;
2418 gchar *s, *copy, *end, *next, save;
2420 if (strcmp ("ANY", string) == 0) {
2421 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
2425 if (strcmp ("EMPTY", string) == 0 || strcmp ("NONE", string) == 0) {
2429 copy = s = g_strdup (string);
2431 GstCapsFeatures *features = NULL;
2433 while (g_ascii_isspace (*s))
2439 if (!priv_gst_structure_parse_name (s, &s, &end, &next, FALSE)) {
2446 structure = gst_structure_new_empty (s);
2449 if (structure == NULL) {
2467 } else if (*end == ')') {
2476 features = gst_caps_features_from_string (s);
2478 gst_structure_free (structure);
2492 if (!priv_gst_structure_parse_fields (s, &s, structure)) {
2493 gst_structure_free (structure);
2495 gst_caps_features_free (features);
2501 gst_caps_append_structure_unchecked (caps, structure, features);
2513 * gst_caps_from_string:
2514 * @string: a string to convert to #GstCaps
2516 * Converts @caps from a string representation.
2518 * The implementation of serialization up to 1.20 would lead to unexpected results
2519 * when there were nested #GstCaps / #GstStructure deeper than one level.
2521 * Returns: (transfer full) (nullable): a newly allocated #GstCaps
2524 gst_caps_from_string (const gchar * string)
2528 g_return_val_if_fail (string, NULL);
2530 caps = gst_caps_new_empty ();
2531 if (gst_caps_from_string_inplace (caps, string)) {
2534 gst_caps_unref (caps);
2540 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2542 g_return_if_fail (G_IS_VALUE (src_value));
2543 g_return_if_fail (G_IS_VALUE (dest_value));
2544 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2545 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2546 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2548 g_value_take_string (dest_value,
2549 gst_caps_to_string (gst_value_get_caps (src_value)));
2555 * @func: (scope call): a function to call for each field
2556 * @user_data: (closure): private data
2558 * Calls the provided function once for each structure and caps feature in the
2559 * #GstCaps. The function must not modify the fields.
2560 * Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place().
2562 * Returns: %TRUE if the supplied function returns %TRUE for each call,
2568 gst_caps_foreach (const GstCaps * caps, GstCapsForeachFunc func,
2572 GstCapsFeatures *features;
2573 GstStructure *structure;
2576 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
2577 g_return_val_if_fail (func != NULL, FALSE);
2579 n = GST_CAPS_LEN (caps);
2581 for (i = 0; i < n; i++) {
2582 features = gst_caps_get_features_unchecked (caps, i);
2583 structure = gst_caps_get_structure_unchecked (caps, i);
2585 ret = func (features, structure, user_data);
2586 if (G_UNLIKELY (!ret))
2594 * gst_caps_map_in_place:
2596 * @func: (scope call): a function to call for each field
2597 * @user_data: (closure): private data
2599 * Calls the provided function once for each structure and caps feature in the
2600 * #GstCaps. In contrast to gst_caps_foreach(), the function may modify but not
2601 * delete the structures and features. The caps must be mutable.
2603 * Returns: %TRUE if the supplied function returns %TRUE for each call,
2609 gst_caps_map_in_place (GstCaps * caps, GstCapsMapFunc func, gpointer user_data)
2612 GstCapsFeatures *features;
2613 GstStructure *structure;
2616 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
2617 g_return_val_if_fail (gst_caps_is_writable (caps), FALSE);
2618 g_return_val_if_fail (func != NULL, FALSE);
2620 n = GST_CAPS_LEN (caps);
2622 for (i = 0; i < n; i++) {
2623 features = gst_caps_get_features_unchecked (caps, i);
2624 structure = gst_caps_get_structure_unchecked (caps, i);
2626 /* Provide sysmem features if there are none yet */
2629 gst_caps_features_copy (GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY);
2630 gst_caps_set_features (caps, i, features);
2633 ret = func (features, structure, user_data);
2634 if (G_UNLIKELY (!ret))
2642 * gst_caps_filter_and_map_in_place:
2644 * @func: (scope call): a function to call for each field
2645 * @user_data: (closure): private data
2647 * Calls the provided function once for each structure and caps feature in the
2648 * #GstCaps. In contrast to gst_caps_foreach(), the function may modify the
2649 * structure and features. In contrast to gst_caps_filter_and_map_in_place(),
2650 * the structure and features are removed from the caps if %FALSE is returned
2651 * from the function.
2652 * The caps must be mutable.
2657 gst_caps_filter_and_map_in_place (GstCaps * caps, GstCapsFilterMapFunc func,
2661 GstCapsFeatures *features;
2662 GstStructure *structure;
2665 g_return_if_fail (GST_IS_CAPS (caps));
2666 g_return_if_fail (gst_caps_is_writable (caps));
2667 g_return_if_fail (func != NULL);
2669 n = GST_CAPS_LEN (caps);
2671 for (i = 0; i < n;) {
2672 features = gst_caps_get_features_unchecked (caps, i);
2673 structure = gst_caps_get_structure_unchecked (caps, i);
2675 /* Provide sysmem features if there are none yet */
2678 gst_caps_features_copy (GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY);
2679 gst_caps_set_features (caps, i, features);
2682 ret = func (features, structure, user_data);
2684 GST_CAPS_ARRAY (caps) = g_array_remove_index (GST_CAPS_ARRAY (caps), i);
2686 gst_structure_set_parent_refcount (structure, NULL);
2687 gst_structure_free (structure);
2689 gst_caps_features_set_parent_refcount (features, NULL);
2690 gst_caps_features_free (features);
2693 n = GST_CAPS_LEN (caps);
2702 * @caps: a #GstCaps.
2704 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
2705 * refcount of 1, owned by the caller. The structures are copied as well.
2707 * Note that this function is the semantic equivalent of a gst_caps_ref()
2708 * followed by a gst_caps_make_writable(). If you only want to hold on to a
2709 * reference to the data, you should use gst_caps_ref().
2711 * Returns: (transfer full): the new #GstCaps
2713 GstCaps *(gst_caps_copy) (const GstCaps * caps)
2715 return GST_CAPS (gst_mini_object_copy (GST_MINI_OBJECT_CAST (caps)));
2719 * gst_caps_ref: (skip)
2720 * @caps: the #GstCaps to reference
2722 * Adds a reference to a #GstCaps object.
2724 * From this point on, until the caller calls gst_caps_unref() or
2725 * gst_caps_make_writable(), it is guaranteed that the caps object will not
2726 * change. This means its structures won't change, etc. To use a #GstCaps
2727 * object, you must always have a refcount on it -- either the one made
2728 * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
2731 * Returns: the same #GstCaps object.
2734 gst_caps_ref (GstCaps * caps)
2736 return (GstCaps *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (caps));
2740 * gst_caps_unref: (skip)
2741 * @caps: a #GstCaps.
2743 * Unrefs a #GstCaps and frees all its structures and the
2744 * structures' values when the refcount reaches 0.
2747 gst_caps_unref (GstCaps * caps)
2749 gst_mini_object_unref (GST_MINI_OBJECT_CAST (caps));
2753 * gst_clear_caps: (skip)
2754 * @caps_ptr: a pointer to a #GstCaps reference
2756 * Clears a reference to a #GstCaps.
2758 * @caps_ptr must not be %NULL.
2760 * If the reference is %NULL then this function does nothing. Otherwise, the
2761 * reference count of the caps is decreased and the pointer is set to %NULL.
2766 gst_clear_caps (GstCaps ** caps_ptr)
2768 gst_clear_mini_object ((GstMiniObject **) caps_ptr);
2772 * gst_caps_replace: (skip)
2773 * @old_caps: (inout) (transfer full) (nullable): pointer to a pointer
2774 * to a #GstCaps to be replaced.
2775 * @new_caps: (transfer none) (allow-none): pointer to a #GstCaps that will
2776 * replace the caps pointed to by @old_caps.
2778 * Modifies a pointer to a #GstCaps to point to a different #GstCaps. The
2779 * modification is done atomically (so this is useful for ensuring thread safety
2780 * in some cases), and the reference counts are updated appropriately (the old
2781 * caps is unreffed, the new is reffed).
2783 * Either @new_caps or the #GstCaps pointed to by @old_caps may be %NULL.
2785 * Returns: %TRUE if @new_caps was different from @old_caps
2788 gst_caps_replace (GstCaps ** old_caps, GstCaps * new_caps)
2790 return gst_mini_object_replace ((GstMiniObject **) old_caps,
2791 (GstMiniObject *) new_caps);
2795 * gst_caps_take: (skip)
2796 * @old_caps: (inout) (transfer full): pointer to a pointer to a #GstCaps to be
2798 * @new_caps: (transfer full) (allow-none): pointer to a #GstCaps that will
2799 * replace the caps pointed to by @old_caps.
2801 * Modifies a pointer to a #GstCaps to point to a different #GstCaps. This
2802 * function is similar to gst_caps_replace() except that it takes ownership
2805 * Returns: %TRUE if @new_caps was different from @old_caps
2808 gst_caps_take (GstCaps ** old_caps, GstCaps * new_caps)
2810 return gst_mini_object_take ((GstMiniObject **) old_caps,
2811 (GstMiniObject *) new_caps);