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.
22 * @short_description: Structure describing sets of media formats
23 * @see_also: #GstStructure, #GstMiniObject
25 * Caps (capabilities) are lightweight refcounted objects describing media types.
26 * They are composed of an array of #GstStructure.
28 * Caps are exposed on #GstPadTemplate to describe all possible types a
29 * given pad can handle. They are also stored in the #GstRegistry along with
30 * a description of the #GstElement.
32 * Caps are exposed on the element pads using the gst_pad_query_caps() pad
33 * function. This function describes the possible types that the pad can
34 * handle or produce at runtime.
36 * A #GstCaps can be constructed with the following code fragment:
38 * GstCaps *caps = gst_caps_new_simple ("video/x-raw",
39 * "format", G_TYPE_STRING, "I420",
40 * "framerate", GST_TYPE_FRACTION, 25, 1,
41 * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
42 * "width", G_TYPE_INT, 320,
43 * "height", G_TYPE_INT, 240,
47 * A #GstCaps is fixed when it has no properties with ranges or lists. Use
48 * gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a
49 * caps event to notify downstream elements of the current media type.
51 * Various methods exist to work with the media types such as subtracting
54 * Be aware that the current #GstCaps / #GstStructure serialization into string
55 * has limited support for nested #GstCaps / #GstStructure fields. It can only
56 * support one level of nesting. Using more levels will lead to unexpected
57 * behavior when using serialization features, such as gst_caps_to_string() or
58 * gst_value_serialize() and their counterparts.
67 #include "gst_private.h"
69 #include <gobject/gvaluecollector.h>
71 #define DEBUG_REFCOUNT
73 typedef struct _GstCapsArrayElement
75 GstStructure *structure;
76 GstCapsFeatures *features;
77 } GstCapsArrayElement;
79 typedef struct _GstCapsImpl
86 #define GST_CAPS_ARRAY(c) (((GstCapsImpl *)(c))->array)
88 #define GST_CAPS_LEN(c) (GST_CAPS_ARRAY(c)->len)
90 #define IS_WRITABLE(caps) \
91 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
93 /* same as gst_caps_is_any () */
94 #define CAPS_IS_ANY(caps) \
95 (!!(GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY))
97 /* same as gst_caps_is_empty () */
98 #define CAPS_IS_EMPTY(caps) \
99 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
101 #define CAPS_IS_EMPTY_SIMPLE(caps) \
102 ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
104 #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)
106 /* quick way to get a caps structure at an index without doing a type or array
108 #define gst_caps_get_structure_unchecked(caps, index) \
109 (g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, (index)).structure)
110 #define gst_caps_get_features_storage_unchecked(caps, index) \
111 (&g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, (index)).features)
112 #define gst_caps_get_features_unchecked(caps, index) \
113 (g_atomic_pointer_get (gst_caps_get_features_storage_unchecked (caps, index)))
114 /* quick way to append a structure without checking the args */
115 #define gst_caps_append_structure_unchecked(caps, s, f) G_STMT_START{\
116 GstCapsArrayElement __e={s, f}; \
117 if (gst_structure_set_parent_refcount (__e.structure, &GST_MINI_OBJECT_REFCOUNT(caps)) && \
118 (!__e.features || gst_caps_features_set_parent_refcount (__e.features, &GST_MINI_OBJECT_REFCOUNT(caps)))) \
119 g_array_append_val (GST_CAPS_ARRAY (caps), __e); \
122 /* lock to protect multiple invocations of static caps to caps conversion */
123 G_LOCK_DEFINE_STATIC (static_caps_lock);
125 static void gst_caps_transform_to_string (const GValue * src_value,
126 GValue * dest_value);
127 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
128 const gchar * string);
130 GType _gst_caps_type = 0;
131 GstCaps *_gst_caps_any;
132 GstCaps *_gst_caps_none;
134 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
137 _priv_gst_caps_initialize (void)
139 _gst_caps_type = gst_caps_get_type ();
141 _gst_caps_any = gst_caps_new_any ();
142 _gst_caps_none = gst_caps_new_empty ();
144 g_value_register_transform_func (_gst_caps_type,
145 G_TYPE_STRING, gst_caps_transform_to_string);
149 _gst_caps_copy (const GstCaps * caps)
152 GstStructure *structure;
153 GstCapsFeatures *features;
156 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
158 newcaps = gst_caps_new_empty ();
159 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
160 n = GST_CAPS_LEN (caps);
162 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, caps, "doing copy %p -> %p",
165 for (i = 0; i < n; i++) {
166 structure = gst_caps_get_structure_unchecked (caps, i);
167 features = gst_caps_get_features_unchecked (caps, i);
168 gst_caps_append_structure_full (newcaps, gst_structure_copy (structure),
169 gst_caps_features_copy_conditional (features));
175 /* creation/deletion */
177 _gst_caps_free (GstCaps * caps)
179 GstStructure *structure;
180 GstCapsFeatures *features;
183 /* The refcount must be 0, but since we're only called by gst_caps_unref,
184 * don't bother testing. */
185 len = GST_CAPS_LEN (caps);
186 /* This can be used to get statistics about caps sizes */
187 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
188 for (i = 0; i < len; i++) {
189 structure = gst_caps_get_structure_unchecked (caps, i);
190 gst_structure_set_parent_refcount (structure, NULL);
191 gst_structure_free (structure);
192 features = gst_caps_get_features_unchecked (caps, i);
194 gst_caps_features_set_parent_refcount (features, NULL);
195 gst_caps_features_free (features);
198 g_array_free (GST_CAPS_ARRAY (caps), TRUE);
200 #ifdef DEBUG_REFCOUNT
201 GST_CAT_TRACE (GST_CAT_CAPS, "freeing caps %p", caps);
203 g_slice_free1 (sizeof (GstCapsImpl), caps);
207 gst_caps_init (GstCaps * caps)
209 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), 0, _gst_caps_type,
210 (GstMiniObjectCopyFunction) _gst_caps_copy, NULL,
211 (GstMiniObjectFreeFunction) _gst_caps_free);
213 /* the 32 has been determined by logging caps sizes in _gst_caps_free
214 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
216 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
218 GST_CAPS_ARRAY (caps) =
219 g_array_new (FALSE, TRUE, sizeof (GstCapsArrayElement));
223 * gst_caps_new_empty:
225 * Creates a new #GstCaps that is empty. That is, the returned
226 * #GstCaps contains no media formats.
227 * The #GstCaps is guaranteed to be writable.
228 * Caller is responsible for unreffing the returned caps.
230 * Returns: (transfer full): the new #GstCaps
233 gst_caps_new_empty (void)
237 caps = (GstCaps *) g_slice_new (GstCapsImpl);
239 gst_caps_init (caps);
241 #ifdef DEBUG_REFCOUNT
242 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
251 * Creates a new #GstCaps that indicates that it is compatible with
254 * Returns: (transfer full): the new #GstCaps
257 gst_caps_new_any (void)
259 GstCaps *caps = gst_caps_new_empty ();
261 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
267 * gst_caps_new_empty_simple:
268 * @media_type: the media type of the structure
270 * Creates a new #GstCaps that contains one #GstStructure with name
272 * Caller is responsible for unreffing the returned caps.
274 * Returns: (transfer full): the new #GstCaps
277 gst_caps_new_empty_simple (const char *media_type)
280 GstStructure *structure;
282 caps = gst_caps_new_empty ();
283 structure = gst_structure_new_empty (media_type);
285 gst_caps_append_structure_unchecked (caps, structure, NULL);
291 * gst_caps_new_simple:
292 * @media_type: the media type of the structure
293 * @fieldname: first field to set
294 * @...: additional arguments
296 * Creates a new #GstCaps that contains one #GstStructure. The
297 * structure is defined by the arguments, which have the same format
298 * as gst_structure_new().
299 * Caller is responsible for unreffing the returned caps.
301 * Returns: (transfer full): the new #GstCaps
304 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
307 GstStructure *structure;
310 caps = gst_caps_new_empty ();
312 va_start (var_args, fieldname);
313 structure = gst_structure_new_valist (media_type, fieldname, var_args);
317 gst_caps_append_structure_unchecked (caps, structure, NULL);
319 gst_caps_replace (&caps, NULL);
326 * @struct1: the first structure to add
327 * @...: additional structures to add
329 * Creates a new #GstCaps and adds all the structures listed as
330 * arguments. The list must be %NULL-terminated. The structures
331 * are not copied; the returned #GstCaps owns the structures.
333 * Returns: (transfer full): the new #GstCaps
336 gst_caps_new_full (GstStructure * struct1, ...)
341 va_start (var_args, struct1);
342 caps = gst_caps_new_full_valist (struct1, var_args);
349 * gst_caps_new_full_valist:
350 * @structure: the first structure to add
351 * @var_args: additional structures to add
353 * Creates a new #GstCaps and adds all the structures listed as
354 * arguments. The list must be %NULL-terminated. The structures
355 * are not copied; the returned #GstCaps owns the structures.
357 * Returns: (transfer full): the new #GstCaps
360 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
364 caps = gst_caps_new_empty ();
367 gst_caps_append_structure_unchecked (caps, structure, NULL);
368 structure = va_arg (var_args, GstStructure *);
374 G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
377 * gst_static_caps_get:
378 * @static_caps: the #GstStaticCaps to convert
380 * Converts a #GstStaticCaps to a #GstCaps.
382 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
383 * Since the core holds an additional ref to the returned caps,
384 * use gst_caps_make_writable() on the returned caps to modify it.
387 gst_static_caps_get (GstStaticCaps * static_caps)
391 g_return_val_if_fail (static_caps != NULL, NULL);
393 caps = &static_caps->caps;
395 /* refcount is 0 when we need to convert */
396 if (G_UNLIKELY (*caps == NULL)) {
399 G_LOCK (static_caps_lock);
400 /* check if other thread already updated */
401 if (G_UNLIKELY (*caps != NULL))
404 string = static_caps->string;
406 if (G_UNLIKELY (string == NULL))
409 *caps = gst_caps_from_string (string);
411 /* convert to string */
412 if (G_UNLIKELY (*caps == NULL))
413 g_critical ("Could not convert static caps \"%s\"", string);
415 GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
418 G_UNLOCK (static_caps_lock);
420 /* ref the caps, makes it not writable */
421 if (G_LIKELY (*caps != NULL))
422 gst_caps_ref (*caps);
429 G_UNLOCK (static_caps_lock);
430 g_warning ("static caps %p string is NULL", static_caps);
436 * gst_static_caps_cleanup:
437 * @static_caps: the #GstStaticCaps to clean
439 * Clean up the cached caps contained in @static_caps.
442 gst_static_caps_cleanup (GstStaticCaps * static_caps)
444 G_LOCK (static_caps_lock);
445 gst_caps_replace (&static_caps->caps, NULL);
446 G_UNLOCK (static_caps_lock);
452 gst_caps_remove_and_get_structure_and_features (GstCaps * caps, guint idx,
453 GstStructure ** s, GstCapsFeatures ** f)
458 s_ = gst_caps_get_structure_unchecked (caps, idx);
459 f_ = gst_caps_get_features_unchecked (caps, idx);
461 /* don't use index_fast, gst_caps_simplify relies on the order */
462 g_array_remove_index (GST_CAPS_ARRAY (caps), idx);
464 gst_structure_set_parent_refcount (s_, NULL);
466 gst_caps_features_set_parent_refcount (f_, NULL);
473 static GstStructure *
474 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
479 gst_caps_remove_and_get_structure_and_features (caps, idx, &s, &f);
482 gst_caps_features_free (f);
490 * gst_caps_steal_structure:
491 * @caps: the #GstCaps to retrieve from
492 * @index: Index of the structure to retrieve
494 * Retrieves the structure with the given index from the list of structures
495 * contained in @caps. The caller becomes the owner of the returned structure.
497 * Returns: (transfer full): a pointer to the #GstStructure corresponding
501 gst_caps_steal_structure (GstCaps * caps, guint index)
503 g_return_val_if_fail (caps != NULL, NULL);
504 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
506 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
509 return gst_caps_remove_and_get_structure (caps, index);
514 * @caps1: the #GstCaps that will be appended to
515 * @caps2: (transfer full): the #GstCaps to append
517 * Appends the structures contained in @caps2 to @caps1. The structures in
518 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
519 * freed. If either caps is ANY, the resulting caps will be ANY.
522 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
524 GstStructure *structure;
525 GstCapsFeatures *features;
528 g_return_if_fail (GST_IS_CAPS (caps1));
529 g_return_if_fail (GST_IS_CAPS (caps2));
530 g_return_if_fail (IS_WRITABLE (caps1));
532 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
533 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
534 gst_caps_unref (caps2);
536 caps2 = gst_caps_make_writable (caps2);
538 for (i = GST_CAPS_LEN (caps2); i; i--) {
539 gst_caps_remove_and_get_structure_and_features (caps2, 0, &structure,
541 gst_caps_append_structure_unchecked (caps1, structure, features);
543 gst_caps_unref (caps2); /* guaranteed to free it */
549 * @caps1: (transfer full): the #GstCaps that will take the new entries
550 * @caps2: (transfer full): the #GstCaps to merge in
552 * Appends the structures contained in @caps2 to @caps1 if they are not yet
553 * expressed by @caps1. The structures in @caps2 are not copied -- they are
554 * transferred to a writable copy of @caps1, and then @caps2 is freed.
555 * If either caps is ANY, the resulting caps will be ANY.
557 * Returns: (transfer full): the merged caps.
560 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
562 GstStructure *structure;
563 GstCapsFeatures *features;
567 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
568 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
570 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
571 gst_caps_unref (caps2);
573 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
574 gst_caps_unref (caps1);
577 caps2 = gst_caps_make_writable (caps2);
579 for (i = GST_CAPS_LEN (caps2); i; i--) {
580 gst_caps_remove_and_get_structure_and_features (caps2, 0, &structure,
582 caps1 = gst_caps_merge_structure_full (caps1, structure, features);
584 gst_caps_unref (caps2);
588 GstCaps *com = gst_caps_intersect (caps1, caps2);
589 GstCaps *add = gst_caps_subtract (caps2, com);
591 GST_DEBUG ("common : %d", gst_caps_get_size (com));
592 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
593 gst_caps_append (caps1, add);
594 gst_caps_unref (com);
602 * gst_caps_append_structure:
603 * @caps: the #GstCaps that will be appended to
604 * @structure: (transfer full): the #GstStructure to append
606 * Appends @structure to @caps. The structure is not copied; @caps
607 * becomes the owner of @structure.
610 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
612 g_return_if_fail (GST_IS_CAPS (caps));
613 g_return_if_fail (IS_WRITABLE (caps));
615 if (G_LIKELY (structure)) {
616 gst_caps_append_structure_unchecked (caps, structure, NULL);
621 * gst_caps_append_structure_full:
622 * @caps: the #GstCaps that will be appended to
623 * @structure: (transfer full): the #GstStructure to append
624 * @features: (transfer full) (allow-none): the #GstCapsFeatures to append
626 * Appends @structure with @features to @caps. The structure is not copied; @caps
627 * becomes the owner of @structure.
632 gst_caps_append_structure_full (GstCaps * caps, GstStructure * structure,
633 GstCapsFeatures * features)
635 g_return_if_fail (GST_IS_CAPS (caps));
636 g_return_if_fail (IS_WRITABLE (caps));
638 if (G_LIKELY (structure)) {
639 gst_caps_append_structure_unchecked (caps, structure, features);
644 * gst_caps_remove_structure:
645 * @caps: the #GstCaps to remove from
646 * @idx: Index of the structure to remove
648 * removes the structure with the given index from the list of structures
649 * contained in @caps.
652 gst_caps_remove_structure (GstCaps * caps, guint idx)
654 GstStructure *structure;
656 g_return_if_fail (caps != NULL);
657 g_return_if_fail (idx <= gst_caps_get_size (caps));
658 g_return_if_fail (IS_WRITABLE (caps));
660 structure = gst_caps_remove_and_get_structure (caps, idx);
661 gst_structure_free (structure);
665 * gst_caps_merge_structure:
666 * @caps: (transfer full): the #GstCaps to merge into
667 * @structure: (transfer full): the #GstStructure to merge
669 * Appends @structure to @caps if its not already expressed by @caps.
671 * Returns: (transfer full): the merged caps.
674 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
676 GstStructure *structure1;
677 GstCapsFeatures *features1;
679 gboolean unique = TRUE;
681 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
683 if (G_UNLIKELY (structure == NULL))
686 /* check each structure */
687 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
688 structure1 = gst_caps_get_structure_unchecked (caps, i);
689 features1 = gst_caps_get_features_unchecked (caps, i);
691 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
693 /* if structure is a subset of structure1 and the
694 * there are no existing features, then skip it */
695 if (gst_caps_features_is_equal (features1,
696 GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY)
697 && gst_structure_is_subset (structure, structure1)) {
703 caps = gst_caps_make_writable (caps);
704 gst_caps_append_structure_unchecked (caps, structure, NULL);
706 gst_structure_free (structure);
712 * gst_caps_merge_structure_full:
713 * @caps: (transfer full): the #GstCaps to merge into
714 * @structure: (transfer full): the #GstStructure to merge
715 * @features: (transfer full) (allow-none): the #GstCapsFeatures to merge
717 * Appends @structure with @features to @caps if its not already expressed by @caps.
719 * Returns: (transfer full): the merged caps.
724 gst_caps_merge_structure_full (GstCaps * caps, GstStructure * structure,
725 GstCapsFeatures * features)
727 GstStructure *structure1;
728 GstCapsFeatures *features1, *features_tmp;
730 gboolean unique = TRUE;
732 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
734 if (G_UNLIKELY (structure == NULL))
737 /* To make comparisons easier below */
738 features_tmp = features ? features : GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
740 /* check each structure */
741 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
742 structure1 = gst_caps_get_structure_unchecked (caps, i);
743 features1 = gst_caps_get_features_unchecked (caps, i);
745 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
746 /* if structure is a subset of structure1 and the
747 * the features are a subset, then skip it */
748 /* FIXME: We only skip if none of the features are
749 * ANY and are still equal. That way all ANY structures
750 * show up in the caps and no non-ANY structures are
751 * swallowed by ANY structures
753 if (((!gst_caps_features_is_any (features_tmp)
754 || gst_caps_features_is_any (features1))
755 && gst_caps_features_is_equal (features_tmp, features1))
756 && gst_structure_is_subset (structure, structure1)) {
762 caps = gst_caps_make_writable (caps);
763 gst_caps_append_structure_unchecked (caps, structure, features);
765 gst_structure_free (structure);
767 gst_caps_features_free (features);
776 * Gets the number of structures contained in @caps.
778 * Returns: the number of structures that @caps contains
781 gst_caps_get_size (const GstCaps * caps)
783 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
785 return GST_CAPS_LEN (caps);
789 * gst_caps_get_structure:
791 * @index: the index of the structure
793 * Finds the structure in @caps that has the index @index, and
796 * WARNING: This function takes a const GstCaps *, but returns a
797 * non-const GstStructure *. This is for programming convenience --
798 * the caller should be aware that structures inside a constant
799 * #GstCaps should not be modified. However, if you know the caps
800 * are writable, either because you have just copied them or made
801 * them writable with gst_caps_make_writable(), you may modify the
802 * structure returned in the usual way, e.g. with functions like
803 * gst_structure_set().
805 * You do not need to free or unref the structure returned, it
806 * belongs to the #GstCaps.
808 * Returns: (transfer none): a pointer to the #GstStructure corresponding
812 gst_caps_get_structure (const GstCaps * caps, guint index)
814 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
815 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
817 return gst_caps_get_structure_unchecked (caps, index);
821 * gst_caps_get_features:
823 * @index: the index of the structure
825 * Finds the features in @caps that has the index @index, and
828 * WARNING: This function takes a const GstCaps *, but returns a
829 * non-const GstCapsFeatures *. This is for programming convenience --
830 * the caller should be aware that structures inside a constant
831 * #GstCaps should not be modified. However, if you know the caps
832 * are writable, either because you have just copied them or made
833 * them writable with gst_caps_make_writable(), you may modify the
834 * features returned in the usual way, e.g. with functions like
835 * gst_caps_features_add().
837 * You do not need to free or unref the structure returned, it
838 * belongs to the #GstCaps.
840 * Returns: (transfer none): a pointer to the #GstCapsFeatures corresponding
846 gst_caps_get_features (const GstCaps * caps, guint index)
848 GstCapsFeatures *features;
850 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
851 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
853 features = gst_caps_get_features_unchecked (caps, index);
855 GstCapsFeatures **storage;
857 /* We have to do some atomic pointer magic here as the caps
858 * might not be writable and someone else calls this function
859 * at the very same time */
860 features = gst_caps_features_copy (GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY);
861 gst_caps_features_set_parent_refcount (features, &GST_CAPS_REFCOUNT (caps));
863 storage = gst_caps_get_features_storage_unchecked (caps, index);
864 if (!g_atomic_pointer_compare_and_exchange (storage, NULL, features)) {
865 /* Someone did the same we just tried in the meantime */
866 gst_caps_features_set_parent_refcount (features, NULL);
867 gst_caps_features_free (features);
869 features = gst_caps_get_features_unchecked (caps, index);
870 g_assert (features != NULL);
878 * gst_caps_set_features:
880 * @index: the index of the structure
881 * @features: (allow-none) (transfer full): the #GstCapsFeatures to set
883 * Sets the #GstCapsFeatures @features for the structure at @index.
888 gst_caps_set_features (GstCaps * caps, guint index, GstCapsFeatures * features)
890 GstCapsFeatures **storage, *old;
892 g_return_if_fail (caps != NULL);
893 g_return_if_fail (index <= gst_caps_get_size (caps));
894 g_return_if_fail (IS_WRITABLE (caps));
896 storage = gst_caps_get_features_storage_unchecked (caps, index);
897 /* Not much problem here as caps are writable */
898 old = g_atomic_pointer_get (storage);
899 g_atomic_pointer_set (storage, features);
902 gst_caps_features_set_parent_refcount (features, &GST_CAPS_REFCOUNT (caps));
905 gst_caps_features_set_parent_refcount (old, NULL);
906 gst_caps_features_free (old);
912 * @caps: the #GstCaps to copy
913 * @nth: the nth structure to copy
915 * Creates a new #GstCaps and appends a copy of the nth structure
916 * contained in @caps.
918 * Returns: (transfer full): the new #GstCaps
921 gst_caps_copy_nth (const GstCaps * caps, guint nth)
924 GstStructure *structure;
925 GstCapsFeatures *features;
927 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
929 newcaps = gst_caps_new_empty ();
930 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
932 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
933 structure = gst_caps_get_structure_unchecked (caps, nth);
934 features = gst_caps_get_features_unchecked (caps, nth);
935 gst_caps_append_structure_unchecked (newcaps,
936 gst_structure_copy (structure),
937 gst_caps_features_copy_conditional (features));
945 * @caps: (transfer full): the #GstCaps to truncate
947 * Discard all but the first structure from @caps. Useful when
950 * Returns: (transfer full): truncated caps
953 gst_caps_truncate (GstCaps * caps)
957 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
959 i = GST_CAPS_LEN (caps) - 1;
963 caps = gst_caps_make_writable (caps);
965 gst_caps_remove_structure (caps, i--);
971 * gst_caps_set_value:
972 * @caps: a writable caps
973 * @field: name of the field to set
974 * @value: value to set the field to
976 * Sets the given @field on all structures of @caps to the given @value.
977 * This is a convenience function for calling gst_structure_set_value() on
978 * all structures of @caps.
981 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
985 g_return_if_fail (GST_IS_CAPS (caps));
986 g_return_if_fail (IS_WRITABLE (caps));
987 g_return_if_fail (field != NULL);
988 g_return_if_fail (G_IS_VALUE (value));
990 len = GST_CAPS_LEN (caps);
991 for (i = 0; i < len; i++) {
992 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
993 gst_structure_set_value (structure, field, value);
998 * gst_caps_set_simple_valist:
999 * @caps: the #GstCaps to set
1000 * @field: first field to set
1001 * @varargs: additional parameters
1003 * Sets fields in a #GstCaps. The arguments must be passed in the same
1004 * manner as gst_structure_set(), and be %NULL-terminated.
1007 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
1009 GValue value = { 0, };
1011 g_return_if_fail (GST_IS_CAPS (caps));
1012 g_return_if_fail (IS_WRITABLE (caps));
1018 type = va_arg (varargs, GType);
1020 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
1021 if (G_UNLIKELY (err)) {
1022 g_critical ("%s", err);
1026 gst_caps_set_value (caps, field, &value);
1028 g_value_unset (&value);
1030 field = va_arg (varargs, const gchar *);
1035 * gst_caps_set_simple:
1036 * @caps: the #GstCaps to set
1037 * @field: first field to set
1038 * @...: additional parameters
1040 * Sets fields in a #GstCaps. The arguments must be passed in the same
1041 * manner as gst_structure_set(), and be %NULL-terminated.
1044 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
1048 g_return_if_fail (GST_IS_CAPS (caps));
1049 g_return_if_fail (IS_WRITABLE (caps));
1051 va_start (var_args, field);
1052 gst_caps_set_simple_valist (caps, field, var_args);
1060 * @caps: the #GstCaps to test
1062 * Determines if @caps represents any media format.
1064 * Returns: %TRUE if @caps represents any format.
1067 gst_caps_is_any (const GstCaps * caps)
1069 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1071 return (CAPS_IS_ANY (caps));
1075 * gst_caps_is_empty:
1076 * @caps: the #GstCaps to test
1078 * Determines if @caps represents no media formats.
1080 * Returns: %TRUE if @caps represents no formats.
1083 gst_caps_is_empty (const GstCaps * caps)
1085 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1087 if (CAPS_IS_ANY (caps))
1090 return CAPS_IS_EMPTY_SIMPLE (caps);
1094 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
1097 return gst_value_is_fixed (value);
1101 * gst_caps_is_fixed:
1102 * @caps: the #GstCaps to test
1104 * Fixed #GstCaps describe exactly one format, that is, they have exactly
1105 * one structure, and each field in the structure describes a fixed type.
1106 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
1108 * Returns: %TRUE if @caps is fixed
1111 gst_caps_is_fixed (const GstCaps * caps)
1113 GstStructure *structure;
1114 GstCapsFeatures *features;
1116 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1118 if (GST_CAPS_LEN (caps) != 1)
1121 features = gst_caps_get_features_unchecked (caps, 0);
1122 if (features && gst_caps_features_is_any (features))
1125 structure = gst_caps_get_structure_unchecked (caps, 0);
1127 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
1131 * gst_caps_is_equal_fixed:
1132 * @caps1: the #GstCaps to test
1133 * @caps2: the #GstCaps to test
1135 * Tests if two #GstCaps are equal. This function only works on fixed
1138 * Returns: %TRUE if the arguments represent the same format
1141 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
1143 GstStructure *struct1, *struct2;
1144 GstCapsFeatures *features1, *features2;
1146 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1147 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1149 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1150 features1 = gst_caps_get_features_unchecked (caps1, 0);
1152 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1153 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1154 features2 = gst_caps_get_features_unchecked (caps2, 0);
1156 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1158 return gst_structure_is_equal (struct1, struct2) &&
1159 gst_caps_features_is_equal (features1, features2);
1163 * gst_caps_is_always_compatible:
1164 * @caps1: the #GstCaps to test
1165 * @caps2: the #GstCaps to test
1167 * A given #GstCaps structure is always compatible with another if
1168 * every media format that is in the first is also contained in the
1169 * second. That is, @caps1 is a subset of @caps2.
1171 * Returns: %TRUE if @caps1 is a subset of @caps2.
1174 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1176 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1177 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1179 return gst_caps_is_subset (caps1, caps2);
1183 * gst_caps_is_subset:
1184 * @subset: a #GstCaps
1185 * @superset: a potentially greater #GstCaps
1187 * Checks if all caps represented by @subset are also represented by @superset.
1189 * Returns: %TRUE if @subset is a subset of @superset
1192 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1194 GstStructure *s1, *s2;
1195 GstCapsFeatures *f1, *f2;
1196 gboolean ret = TRUE;
1199 g_return_val_if_fail (subset != NULL, FALSE);
1200 g_return_val_if_fail (superset != NULL, FALSE);
1202 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1204 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1207 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
1208 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
1209 s1 = gst_caps_get_structure_unchecked (subset, i);
1210 f1 = gst_caps_get_features_unchecked (subset, i);
1212 f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1213 s2 = gst_caps_get_structure_unchecked (superset, j);
1214 f2 = gst_caps_get_features_unchecked (superset, j);
1216 f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1217 if ((!gst_caps_features_is_any (f1) || gst_caps_features_is_any (f2)) &&
1218 gst_caps_features_is_equal (f1, f2)
1219 && gst_structure_is_subset (s1, s2)) {
1220 /* If we found a superset, continue with the next
1221 * subset structure */
1225 /* If we found no superset for this subset structure
1226 * we return FALSE immediately */
1237 * gst_caps_is_subset_structure:
1239 * @structure: a potential #GstStructure subset of @caps
1241 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1242 * for more information.
1244 * Returns: %TRUE if @structure is a subset of @caps
1247 gst_caps_is_subset_structure (const GstCaps * caps,
1248 const GstStructure * structure)
1253 g_return_val_if_fail (caps != NULL, FALSE);
1254 g_return_val_if_fail (structure != NULL, FALSE);
1256 if (CAPS_IS_ANY (caps))
1258 if (CAPS_IS_EMPTY (caps))
1261 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1262 s = gst_caps_get_structure_unchecked (caps, i);
1263 if (gst_structure_is_subset (structure, s)) {
1264 /* If we found a superset return TRUE */
1273 * gst_caps_is_subset_structure_full:
1275 * @structure: a potential #GstStructure subset of @caps
1276 * @features: (allow-none): a #GstCapsFeatures for @structure
1278 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1279 * for more information.
1281 * Returns: %TRUE if @structure is a subset of @caps
1286 gst_caps_is_subset_structure_full (const GstCaps * caps,
1287 const GstStructure * structure, const GstCapsFeatures * features)
1293 g_return_val_if_fail (caps != NULL, FALSE);
1294 g_return_val_if_fail (structure != NULL, FALSE);
1296 if (CAPS_IS_ANY (caps))
1298 if (CAPS_IS_EMPTY (caps))
1302 features = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1304 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1305 s = gst_caps_get_structure_unchecked (caps, i);
1306 f = gst_caps_get_features_unchecked (caps, i);
1308 f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1309 if ((!gst_caps_features_is_any (features) || gst_caps_features_is_any (f))
1310 && gst_caps_features_is_equal (features, f)
1311 && gst_structure_is_subset (structure, s)) {
1312 /* If we found a superset return TRUE */
1321 * gst_caps_is_equal:
1322 * @caps1: a #GstCaps
1323 * @caps2: another #GstCaps
1325 * Checks if the given caps represent the same set of caps.
1327 * Returns: %TRUE if both caps are equal.
1330 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1332 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1333 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1335 if (G_UNLIKELY (caps1 == caps2))
1338 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1339 return gst_caps_is_equal_fixed (caps1, caps2);
1341 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1345 * gst_caps_is_strictly_equal:
1346 * @caps1: a #GstCaps
1347 * @caps2: another #GstCaps
1349 * Checks if the given caps are exactly the same set of caps.
1351 * Returns: %TRUE if both caps are strictly equal.
1354 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1357 GstStructure *s1, *s2;
1358 GstCapsFeatures *f1, *f2;
1360 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1361 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1363 if (G_UNLIKELY (caps1 == caps2))
1366 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1369 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1370 s1 = gst_caps_get_structure_unchecked (caps1, i);
1371 f1 = gst_caps_get_features_unchecked (caps1, i);
1373 f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1374 s2 = gst_caps_get_structure_unchecked (caps2, i);
1375 f2 = gst_caps_get_features_unchecked (caps2, i);
1377 f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1379 if (gst_caps_features_is_any (f1) != gst_caps_features_is_any (f2) ||
1380 !gst_caps_features_is_equal (f1, f2) ||
1381 !gst_structure_is_equal (s1, s2))
1388 /* intersect operation */
1391 * gst_caps_can_intersect:
1392 * @caps1: a #GstCaps to intersect
1393 * @caps2: a #GstCaps to intersect
1395 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1398 * Returns: %TRUE if intersection would be not empty
1401 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1403 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1404 guint j, k, len1, len2;
1405 GstStructure *struct1;
1406 GstStructure *struct2;
1407 GstCapsFeatures *features1;
1408 GstCapsFeatures *features2;
1410 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1411 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1413 /* caps are exactly the same pointers */
1414 if (G_UNLIKELY (caps1 == caps2))
1417 /* empty caps on either side, return empty */
1418 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1421 /* one of the caps is any */
1422 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1425 /* run zigzag on top line then right line, this preserves the caps order
1426 * much better than a simple loop.
1428 * This algorithm zigzags over the caps structures as demonstrated in
1429 * the following matrix:
1432 * +------------- total distance: +-------------
1433 * | 1 2 4 7 0 | 0 1 2 3
1434 * caps2 | 3 5 8 10 1 | 1 2 3 4
1435 * | 6 9 11 12 2 | 2 3 4 5
1437 * First we iterate over the caps1 structures (top line) intersecting
1438 * the structures diagonally down, then we iterate over the caps2
1439 * structures. The result is that the intersections are ordered based on the
1440 * sum of the indexes in the list.
1442 len1 = GST_CAPS_LEN (caps1);
1443 len2 = GST_CAPS_LEN (caps2);
1444 for (i = 0; i < len1 + len2 - 1; i++) {
1445 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1446 j = MIN (i, len1 - 1);
1447 /* subset index stays 0 until i reaches superset->structs->len, then it
1448 * counts up from 1 to subset->structs->len - 1 */
1449 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1450 /* now run the diagonal line, end condition is the left or bottom
1453 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1454 features1 = gst_caps_get_features_unchecked (caps1, j);
1456 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1457 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1458 features2 = gst_caps_get_features_unchecked (caps2, k);
1460 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1461 if (gst_caps_features_is_equal (features1, features2) &&
1462 gst_structure_can_intersect (struct1, struct2)) {
1465 /* move down left */
1467 if (G_UNLIKELY (j == 0))
1468 break; /* so we don't roll back to G_MAXUINT */
1477 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1479 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1480 guint j, k, len1, len2;
1481 GstStructure *struct1;
1482 GstStructure *struct2;
1483 GstCapsFeatures *features1;
1484 GstCapsFeatures *features2;
1486 GstStructure *istruct;
1488 /* caps are exactly the same pointers, just copy one caps */
1489 if (G_UNLIKELY (caps1 == caps2))
1490 return gst_caps_ref (caps1);
1492 /* empty caps on either side, return empty */
1493 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1494 return gst_caps_ref (GST_CAPS_NONE);
1496 /* one of the caps is any, just copy the other caps */
1497 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1498 return gst_caps_ref (caps2);
1500 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1501 return gst_caps_ref (caps1);
1503 dest = gst_caps_new_empty ();
1504 /* run zigzag on top line then right line, this preserves the caps order
1505 * much better than a simple loop.
1507 * This algorithm zigzags over the caps structures as demonstrated in
1508 * the following matrix:
1516 * First we iterate over the caps1 structures (top line) intersecting
1517 * the structures diagonally down, then we iterate over the caps2
1520 len1 = GST_CAPS_LEN (caps1);
1521 len2 = GST_CAPS_LEN (caps2);
1522 for (i = 0; i < len1 + len2 - 1; i++) {
1523 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1524 j = MIN (i, len1 - 1);
1525 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1526 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1527 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1528 /* now run the diagonal line, end condition is the left or bottom
1531 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1532 features1 = gst_caps_get_features_unchecked (caps1, j);
1534 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1535 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1536 features2 = gst_caps_get_features_unchecked (caps2, k);
1538 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1539 if (gst_caps_features_is_equal (features1, features2)) {
1540 istruct = gst_structure_intersect (struct1, struct2);
1542 if (gst_caps_features_is_any (features1))
1544 gst_caps_merge_structure_full (dest, istruct,
1545 gst_caps_features_copy_conditional (features2));
1548 gst_caps_merge_structure_full (dest, istruct,
1549 gst_caps_features_copy_conditional (features1));
1552 /* move down left */
1554 if (G_UNLIKELY (j == 0))
1555 break; /* so we don't roll back to G_MAXUINT */
1563 * gst_caps_intersect_first:
1564 * @caps1: a #GstCaps to intersect
1565 * @caps2: a #GstCaps to intersect
1567 * Creates a new #GstCaps that contains all the formats that are common
1568 * to both @caps1 and @caps2.
1570 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1571 * fashion as @caps1.
1573 * Returns: the new #GstCaps
1576 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1579 guint j, len1, len2;
1580 GstStructure *struct1;
1581 GstStructure *struct2;
1582 GstCapsFeatures *features1;
1583 GstCapsFeatures *features2;
1585 GstStructure *istruct;
1587 /* caps are exactly the same pointers, just copy one caps */
1588 if (G_UNLIKELY (caps1 == caps2))
1589 return gst_caps_ref (caps1);
1591 /* empty caps on either side, return empty */
1592 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1593 return gst_caps_ref (GST_CAPS_NONE);
1595 /* one of the caps is any, just copy the other caps */
1596 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1597 return gst_caps_ref (caps2);
1599 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1600 return gst_caps_ref (caps1);
1602 dest = gst_caps_new_empty ();
1603 len1 = GST_CAPS_LEN (caps1);
1604 len2 = GST_CAPS_LEN (caps2);
1605 for (i = 0; i < len1; i++) {
1606 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1607 features1 = gst_caps_get_features_unchecked (caps1, i);
1609 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1610 for (j = 0; j < len2; j++) {
1611 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1612 features2 = gst_caps_get_features_unchecked (caps2, j);
1614 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1615 if (gst_caps_features_is_equal (features1, features2)) {
1616 istruct = gst_structure_intersect (struct1, struct2);
1618 if (gst_caps_features_is_any (features1))
1620 gst_caps_merge_structure_full (dest, istruct,
1621 gst_caps_features_copy_conditional (features2));
1624 gst_caps_merge_structure_full (dest, istruct,
1625 gst_caps_features_copy_conditional (features1));
1635 * gst_caps_intersect_full:
1636 * @caps1: a #GstCaps to intersect
1637 * @caps2: a #GstCaps to intersect
1638 * @mode: The intersection algorithm/mode to use
1640 * Creates a new #GstCaps that contains all the formats that are common
1641 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1644 * Returns: the new #GstCaps
1647 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1648 GstCapsIntersectMode mode)
1650 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1651 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1654 case GST_CAPS_INTERSECT_FIRST:
1655 return gst_caps_intersect_first (caps1, caps2);
1657 g_warning ("Unknown caps intersect mode: %d", mode);
1659 case GST_CAPS_INTERSECT_ZIG_ZAG:
1660 return gst_caps_intersect_zig_zag (caps1, caps2);
1665 * gst_caps_intersect:
1666 * @caps1: a #GstCaps to intersect
1667 * @caps2: a #GstCaps to intersect
1669 * Creates a new #GstCaps that contains all the formats that are common
1670 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1672 * Returns: the new #GstCaps
1675 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1677 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1680 /* subtract operation */
1684 const GstStructure *subtract_from;
1689 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1692 SubtractionEntry *e = user_data;
1693 GValue subtraction = { 0, };
1694 const GValue *other;
1695 GstStructure *structure;
1697 other = gst_structure_id_get_value (e->subtract_from, field_id);
1703 if (!gst_value_subtract (&subtraction, other, value))
1706 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1707 g_value_unset (&subtraction);
1710 structure = gst_structure_copy (e->subtract_from);
1711 gst_structure_id_take_value (structure, field_id, &subtraction);
1712 e->put_into = g_slist_prepend (e->put_into, structure);
1718 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1719 const GstStructure * subtrahend)
1724 e.subtract_from = minuend;
1726 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1727 gst_caps_structure_subtract_field, &e);
1734 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1735 gst_structure_free (walk->data);
1737 g_slist_free (e.put_into);
1744 * gst_caps_subtract:
1745 * @minuend: #GstCaps to subtract from
1746 * @subtrahend: #GstCaps to subtract
1748 * Subtracts the @subtrahend from the @minuend.
1749 * <note>This function does not work reliably if optional properties for caps
1750 * are included on one caps and omitted on the other.</note>
1752 * Returns: the resulting caps
1755 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1760 GstCapsFeatures *min_f, *sub_f;
1761 GstCaps *dest = NULL, *src;
1763 g_return_val_if_fail (minuend != NULL, NULL);
1764 g_return_val_if_fail (subtrahend != NULL, NULL);
1766 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1767 return gst_caps_new_empty ();
1770 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1771 return gst_caps_ref (minuend);
1773 /* FIXME: Do we want this here or above?
1774 The reason we need this is that there is no definition about what
1775 ANY means for specific types, so it's not possible to reduce ANY partially
1776 You can only remove everything or nothing and that is done above.
1777 Note: there's a test that checks this behaviour. */
1779 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1780 sublen = GST_CAPS_LEN (subtrahend);
1781 g_assert (sublen > 0);
1783 src = _gst_caps_copy (minuend);
1784 for (i = 0; i < sublen; i++) {
1787 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1788 sub_f = gst_caps_get_features_unchecked (subtrahend, i);
1790 sub_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1792 gst_caps_unref (src);
1795 dest = gst_caps_new_empty ();
1796 srclen = GST_CAPS_LEN (src);
1797 for (j = 0; j < srclen; j++) {
1798 min = gst_caps_get_structure_unchecked (src, j);
1799 min_f = gst_caps_get_features_unchecked (src, j);
1801 min_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1803 /* Same reason as above for ANY caps */
1804 g_return_val_if_fail (!gst_caps_features_is_any (min_f), NULL);
1806 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub) &&
1807 gst_caps_features_is_equal (min_f, sub_f)) {
1810 if (gst_caps_structure_subtract (&list, min, sub)) {
1813 for (walk = list; walk; walk = g_slist_next (walk)) {
1814 gst_caps_append_structure_unchecked (dest,
1815 (GstStructure *) walk->data,
1816 gst_caps_features_copy_conditional (min_f));
1818 g_slist_free (list);
1820 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1821 gst_caps_features_copy_conditional (min_f));
1824 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1825 gst_caps_features_copy_conditional (min_f));
1829 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1830 gst_caps_unref (src);
1835 gst_caps_unref (src);
1836 dest = gst_caps_simplify (dest);
1841 /* normalize/simplify operations */
1843 typedef struct _NormalizeForeach
1846 GstStructure *structure;
1847 GstCapsFeatures *features;
1851 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1853 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1857 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1858 guint len = gst_value_list_get_size (value);
1860 for (i = 1; i < len; i++) {
1861 const GValue *v = gst_value_list_get_value (value, i);
1862 GstStructure *structure = gst_structure_copy (nf->structure);
1864 gst_structure_id_set_value (structure, field_id, v);
1865 gst_caps_append_structure_unchecked (nf->caps, structure,
1866 gst_caps_features_copy_conditional (nf->features));
1869 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1870 gst_structure_id_take_value (nf->structure, field_id, &val);
1878 * gst_caps_normalize:
1879 * @caps: (transfer full): a #GstCaps to normalize
1881 * Returns a #GstCaps that represents the same set of formats as
1882 * @caps, but contains no lists. Each list is expanded into separate
1885 * This function takes ownership of @caps.
1887 * Returns: (transfer full): the normalized #GstCaps
1890 gst_caps_normalize (GstCaps * caps)
1892 NormalizeForeach nf;
1895 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1897 caps = gst_caps_make_writable (caps);
1900 for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1901 nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1902 nf.features = gst_caps_get_features_unchecked (nf.caps, i);
1903 while (!gst_structure_foreach (nf.structure,
1904 gst_caps_normalize_foreach, &nf));
1911 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1914 const GstStructure *struct1 = ((const GstCapsArrayElement *) one)->structure;
1915 const GstStructure *struct2 = ((const GstCapsArrayElement *) two)->structure;
1917 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1918 So what's the best way? */
1919 ret = strcmp (gst_structure_get_name (struct1),
1920 gst_structure_get_name (struct2));
1925 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1932 GstStructure *compare;
1936 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1939 UnionField *u = user_data;
1940 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1944 g_value_unset (&u->value);
1948 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1952 g_value_unset (&u->value);
1957 gst_value_union (&u->value, val, value);
1963 gst_caps_structure_simplify (GstStructure ** result,
1964 GstStructure * simplify, GstStructure * compare)
1967 UnionField field = { 0, {0,}, NULL };
1969 /* try to subtract to get a real subset */
1970 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1971 if (list == NULL) { /* no result */
1974 } else if (list->next == NULL) { /* one result */
1975 *result = list->data;
1976 g_slist_free (list);
1978 } else { /* multiple results */
1979 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1980 g_slist_free (list);
1985 /* try to union both structs */
1986 field.compare = compare;
1987 if (gst_structure_foreach (simplify,
1988 gst_caps_structure_figure_out_union, &field)) {
1989 gboolean ret = FALSE;
1991 /* now we know all of simplify's fields are the same in compare
1992 * but at most one field: field.name */
1993 if (G_IS_VALUE (&field.value)) {
1994 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1995 gst_structure_id_take_value (compare, field.name, &field.value);
1999 g_value_unset (&field.value);
2002 if (gst_structure_n_fields (simplify) <=
2003 gst_structure_n_fields (compare)) {
2004 /* compare is just more specific, will be optimized away later */
2005 /* FIXME: do this here? */
2006 GST_LOG ("found a case that will be optimized later.");
2008 gchar *one = gst_structure_to_string (simplify);
2009 gchar *two = gst_structure_to_string (compare);
2012 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
2024 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
2025 GstStructure * new, gint i)
2027 gst_structure_set_parent_refcount (old, NULL);
2028 gst_structure_free (old);
2029 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
2030 g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, i).structure = new;
2034 * gst_caps_simplify:
2035 * @caps: (transfer full): a #GstCaps to simplify
2037 * Converts the given @caps into a representation that represents the
2038 * same set of formats, but in a simpler form. Component structures that are
2039 * identical are merged. Component structures that have values that can be
2040 * merged are also merged.
2042 * This method does not preserve the original order of @caps.
2044 * Returns: The simplified caps.
2047 gst_caps_simplify (GstCaps * caps)
2049 GstStructure *simplify, *compare, *result = NULL;
2050 GstCapsFeatures *simplify_f, *compare_f;
2053 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2055 start = GST_CAPS_LEN (caps) - 1;
2056 /* one caps, already as simple as can be */
2060 caps = gst_caps_make_writable (caps);
2062 g_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
2064 for (i = start; i >= 0; i--) {
2065 simplify = gst_caps_get_structure_unchecked (caps, i);
2066 simplify_f = gst_caps_get_features_unchecked (caps, i);
2068 simplify_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2069 compare = gst_caps_get_structure_unchecked (caps, start);
2070 compare_f = gst_caps_get_features_unchecked (caps, start);
2072 compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2073 if (gst_structure_get_name_id (simplify) !=
2074 gst_structure_get_name_id (compare) ||
2075 !gst_caps_features_is_equal (simplify_f, compare_f))
2077 for (j = start; j >= 0; j--) {
2080 compare = gst_caps_get_structure_unchecked (caps, j);
2081 compare_f = gst_caps_get_features_unchecked (caps, j);
2083 compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2084 if (gst_structure_get_name_id (simplify) !=
2085 gst_structure_get_name_id (compare) ||
2086 !gst_caps_features_is_equal (simplify_f, compare_f)) {
2089 if (gst_caps_structure_simplify (&result, simplify, compare)) {
2091 gst_caps_switch_structures (caps, simplify, result, i);
2094 gst_caps_remove_structure (caps, i);
2106 * @caps: (transfer full): a #GstCaps to fixate
2108 * Modifies the given @caps into a representation with only fixed
2109 * values. First the caps will be truncated and then the first structure will be
2110 * fixated with gst_structure_fixate().
2112 * Returns: (transfer full): the fixated caps
2115 gst_caps_fixate (GstCaps * caps)
2120 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2122 /* default fixation */
2123 caps = gst_caps_truncate (caps);
2124 caps = gst_caps_make_writable (caps);
2125 s = gst_caps_get_structure (caps, 0);
2126 gst_structure_fixate (s);
2128 /* Set features to sysmem if they're still ANY */
2129 f = gst_caps_get_features_unchecked (caps, 0);
2130 if (f && gst_caps_features_is_any (f)) {
2131 f = gst_caps_features_new_empty ();
2132 gst_caps_set_features (caps, 0, f);
2141 * gst_caps_to_string:
2144 * Converts @caps to a string representation. This string representation
2145 * can be converted back to a #GstCaps by gst_caps_from_string().
2147 * For debugging purposes its easier to do something like this:
2149 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2151 * This prints the caps in human readable form.
2153 * The current implementation of serialization will lead to unexpected results
2154 * when there are nested #GstCaps / #GstStructure deeper than one level.
2156 * Returns: (transfer full): a newly allocated string representing @caps.
2159 gst_caps_to_string (const GstCaps * caps)
2161 guint i, slen, clen;
2164 /* NOTE: This function is potentially called by the debug system,
2165 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2166 * should be careful to avoid recursion. This includes any functions
2167 * called by gst_caps_to_string. In particular, calls should
2168 * not use the GST_PTR_FORMAT extension. */
2171 return g_strdup ("NULL");
2173 if (CAPS_IS_ANY (caps)) {
2174 return g_strdup ("ANY");
2176 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2177 return g_strdup ("EMPTY");
2180 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2182 clen = GST_CAPS_LEN (caps);
2183 for (i = 0; i < clen; i++) {
2187 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked
2189 f = gst_caps_get_features_unchecked (caps, i);
2191 slen += FEATURES_ESTIMATED_STRING_LEN (f);
2194 s = g_string_sized_new (slen);
2195 for (i = 0; i < clen; i++) {
2196 GstStructure *structure;
2197 GstCapsFeatures *features;
2200 /* ';' is now added by gst_structure_to_string */
2201 g_string_append_c (s, ' ');
2204 structure = gst_caps_get_structure_unchecked (caps, i);
2205 features = gst_caps_get_features_unchecked (caps, i);
2207 g_string_append (s, gst_structure_get_name (structure));
2208 if (features && (gst_caps_features_is_any (features)
2209 || !gst_caps_features_is_equal (features,
2210 GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY))) {
2211 g_string_append_c (s, '(');
2212 priv_gst_caps_features_append_to_gstring (features, s);
2213 g_string_append_c (s, ')');
2215 priv_gst_structure_append_to_gstring (structure, s);
2217 if (s->len && s->str[s->len - 1] == ';') {
2218 /* remove latest ';' */
2219 s->str[--s->len] = '\0';
2221 return g_string_free (s, FALSE);
2225 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2227 GstStructure *structure;
2228 gchar *s, *copy, *end, *next, save;
2230 if (strcmp ("ANY", string) == 0) {
2231 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
2235 if (strcmp ("EMPTY", string) == 0 || strcmp ("NONE", string) == 0) {
2239 copy = s = g_strdup (string);
2241 GstCapsFeatures *features = NULL;
2243 while (g_ascii_isspace (*s))
2249 if (!priv_gst_structure_parse_name (s, &s, &end, &next)) {
2256 structure = gst_structure_new_empty (s);
2259 if (structure == NULL) {
2277 } else if (*end == ')') {
2286 features = gst_caps_features_from_string (s);
2288 gst_structure_free (structure);
2302 if (!priv_gst_structure_parse_fields (s, &s, structure)) {
2303 gst_structure_free (structure);
2305 gst_caps_features_free (features);
2311 gst_caps_append_structure_unchecked (caps, structure, features);
2323 * gst_caps_from_string:
2324 * @string: a string to convert to #GstCaps
2326 * Converts @caps from a string representation.
2328 * The current implementation of serialization will lead to unexpected results
2329 * when there are nested #GstCaps / #GstStructure deeper than one level.
2331 * Returns: (transfer full): a newly allocated #GstCaps
2334 gst_caps_from_string (const gchar * string)
2338 g_return_val_if_fail (string, FALSE);
2340 caps = gst_caps_new_empty ();
2341 if (gst_caps_from_string_inplace (caps, string)) {
2344 gst_caps_unref (caps);
2350 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2352 g_return_if_fail (G_IS_VALUE (src_value));
2353 g_return_if_fail (G_IS_VALUE (dest_value));
2354 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2355 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2356 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2358 g_value_take_string (dest_value,
2359 gst_caps_to_string (gst_value_get_caps (src_value)));
2365 * @func: (scope call): a function to call for each field
2366 * @user_data: (closure): private data
2368 * Calls the provided function once for each structure and caps feature in the
2369 * #GstCaps. The function must not modify the fields.
2370 * Also see gst_caps_map_in_place().
2372 * Returns: %TRUE if the supplied function returns %TRUE for each call,
2378 gst_caps_foreach (const GstCaps * caps, GstCapsForeachFunc func,
2382 GstCapsFeatures *features;
2383 GstStructure *structure;
2386 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
2387 g_return_val_if_fail (func != NULL, FALSE);
2389 n = GST_CAPS_LEN (caps);
2391 for (i = 0; i < n; i++) {
2392 features = gst_caps_get_features_unchecked (caps, i);
2393 structure = gst_caps_get_structure_unchecked (caps, i);
2395 ret = func (features, structure, user_data);
2396 if (G_UNLIKELY (!ret))
2404 * gst_caps_map_in_place:
2406 * @func: (scope call): a function to call for each field
2407 * @user_data: (closure): private data
2409 * Calls the provided function once for each structure and caps feature in the
2410 * #GstCaps. In contrast to gst_caps_foreach(), the function may modify but not
2411 * delete the structures and features. The caps must be mutable.
2413 * Returns: %TRUE if the supplied function returns %TRUE for each call,
2419 gst_caps_map_in_place (GstCaps * caps, GstCapsMapFunc func, gpointer user_data)
2422 GstCapsFeatures *features;
2423 GstStructure *structure;
2426 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
2427 g_return_val_if_fail (gst_caps_is_writable (caps), FALSE);
2428 g_return_val_if_fail (func != NULL, FALSE);
2430 n = GST_CAPS_LEN (caps);
2432 for (i = 0; i < n; i++) {
2433 features = gst_caps_get_features_unchecked (caps, i);
2434 structure = gst_caps_get_structure_unchecked (caps, i);
2436 /* Provide sysmem features if there are none yet */
2439 gst_caps_features_copy (GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY);
2440 gst_caps_set_features (caps, i, features);
2443 ret = func (features, structure, user_data);
2444 if (G_UNLIKELY (!ret))