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_free (old);
910 * @caps: the #GstCaps to copy
911 * @nth: the nth structure to copy
913 * Creates a new #GstCaps and appends a copy of the nth structure
914 * contained in @caps.
916 * Returns: (transfer full): the new #GstCaps
919 gst_caps_copy_nth (const GstCaps * caps, guint nth)
922 GstStructure *structure;
923 GstCapsFeatures *features;
925 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
927 newcaps = gst_caps_new_empty ();
928 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
930 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
931 structure = gst_caps_get_structure_unchecked (caps, nth);
932 features = gst_caps_get_features_unchecked (caps, nth);
933 gst_caps_append_structure_unchecked (newcaps,
934 gst_structure_copy (structure),
935 gst_caps_features_copy_conditional (features));
943 * @caps: (transfer full): the #GstCaps to truncate
945 * Discard all but the first structure from @caps. Useful when
948 * Returns: (transfer full): truncated caps
951 gst_caps_truncate (GstCaps * caps)
955 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
957 i = GST_CAPS_LEN (caps) - 1;
961 caps = gst_caps_make_writable (caps);
963 gst_caps_remove_structure (caps, i--);
969 * gst_caps_set_value:
970 * @caps: a writable caps
971 * @field: name of the field to set
972 * @value: value to set the field to
974 * Sets the given @field on all structures of @caps to the given @value.
975 * This is a convenience function for calling gst_structure_set_value() on
976 * all structures of @caps.
979 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
983 g_return_if_fail (GST_IS_CAPS (caps));
984 g_return_if_fail (IS_WRITABLE (caps));
985 g_return_if_fail (field != NULL);
986 g_return_if_fail (G_IS_VALUE (value));
988 len = GST_CAPS_LEN (caps);
989 for (i = 0; i < len; i++) {
990 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
991 gst_structure_set_value (structure, field, value);
996 * gst_caps_set_simple_valist:
997 * @caps: the #GstCaps to set
998 * @field: first field to set
999 * @varargs: additional parameters
1001 * Sets fields in a #GstCaps. The arguments must be passed in the same
1002 * manner as gst_structure_set(), and be NULL-terminated.
1005 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
1007 GValue value = { 0, };
1009 g_return_if_fail (GST_IS_CAPS (caps));
1010 g_return_if_fail (IS_WRITABLE (caps));
1016 type = va_arg (varargs, GType);
1018 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
1019 if (G_UNLIKELY (err)) {
1020 g_critical ("%s", err);
1024 gst_caps_set_value (caps, field, &value);
1026 g_value_unset (&value);
1028 field = va_arg (varargs, const gchar *);
1033 * gst_caps_set_simple:
1034 * @caps: the #GstCaps to set
1035 * @field: first field to set
1036 * @...: additional parameters
1038 * Sets fields in a #GstCaps. The arguments must be passed in the same
1039 * manner as gst_structure_set(), and be NULL-terminated.
1042 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
1046 g_return_if_fail (GST_IS_CAPS (caps));
1047 g_return_if_fail (IS_WRITABLE (caps));
1049 va_start (var_args, field);
1050 gst_caps_set_simple_valist (caps, field, var_args);
1058 * @caps: the #GstCaps to test
1060 * Determines if @caps represents any media format.
1062 * Returns: TRUE if @caps represents any format.
1065 gst_caps_is_any (const GstCaps * caps)
1067 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1069 return (CAPS_IS_ANY (caps));
1073 * gst_caps_is_empty:
1074 * @caps: the #GstCaps to test
1076 * Determines if @caps represents no media formats.
1078 * Returns: TRUE if @caps represents no formats.
1081 gst_caps_is_empty (const GstCaps * caps)
1083 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1085 if (CAPS_IS_ANY (caps))
1088 return CAPS_IS_EMPTY_SIMPLE (caps);
1092 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
1095 return gst_value_is_fixed (value);
1099 * gst_caps_is_fixed:
1100 * @caps: the #GstCaps to test
1102 * Fixed #GstCaps describe exactly one format, that is, they have exactly
1103 * one structure, and each field in the structure describes a fixed type.
1104 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
1106 * Returns: TRUE if @caps is fixed
1109 gst_caps_is_fixed (const GstCaps * caps)
1111 GstStructure *structure;
1112 GstCapsFeatures *features;
1114 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1116 if (GST_CAPS_LEN (caps) != 1)
1119 features = gst_caps_get_features_unchecked (caps, 0);
1120 if (features && gst_caps_features_is_any (features))
1123 structure = gst_caps_get_structure_unchecked (caps, 0);
1125 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
1129 * gst_caps_is_equal_fixed:
1130 * @caps1: the #GstCaps to test
1131 * @caps2: the #GstCaps to test
1133 * Tests if two #GstCaps are equal. This function only works on fixed
1136 * Returns: TRUE if the arguments represent the same format
1139 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
1141 GstStructure *struct1, *struct2;
1142 GstCapsFeatures *features1, *features2;
1144 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1145 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1147 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1148 features1 = gst_caps_get_features_unchecked (caps1, 0);
1150 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1151 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1152 features2 = gst_caps_get_features_unchecked (caps2, 0);
1154 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1156 return gst_structure_is_equal (struct1, struct2) &&
1157 gst_caps_features_is_equal (features1, features2);
1161 * gst_caps_is_always_compatible:
1162 * @caps1: the #GstCaps to test
1163 * @caps2: the #GstCaps to test
1165 * A given #GstCaps structure is always compatible with another if
1166 * every media format that is in the first is also contained in the
1167 * second. That is, @caps1 is a subset of @caps2.
1169 * Returns: TRUE if @caps1 is a subset of @caps2.
1172 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1174 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1175 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1177 return gst_caps_is_subset (caps1, caps2);
1181 * gst_caps_is_subset:
1182 * @subset: a #GstCaps
1183 * @superset: a potentially greater #GstCaps
1185 * Checks if all caps represented by @subset are also represented by @superset.
1187 * Returns: %TRUE if @subset is a subset of @superset
1190 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1192 GstStructure *s1, *s2;
1193 GstCapsFeatures *f1, *f2;
1194 gboolean ret = TRUE;
1197 g_return_val_if_fail (subset != NULL, FALSE);
1198 g_return_val_if_fail (superset != NULL, FALSE);
1200 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1202 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1205 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
1206 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
1207 s1 = gst_caps_get_structure_unchecked (subset, i);
1208 f1 = gst_caps_get_features_unchecked (subset, i);
1210 f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1211 s2 = gst_caps_get_structure_unchecked (superset, j);
1212 f2 = gst_caps_get_features_unchecked (superset, j);
1214 f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1215 if ((!gst_caps_features_is_any (f1) || gst_caps_features_is_any (f2)) &&
1216 gst_caps_features_is_equal (f1, f2)
1217 && gst_structure_is_subset (s1, s2)) {
1218 /* If we found a superset, continue with the next
1219 * subset structure */
1223 /* If we found no superset for this subset structure
1224 * we return FALSE immediately */
1235 * gst_caps_is_subset_structure:
1237 * @structure: a potential #GstStructure subset of @caps
1239 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1240 * for more information.
1242 * Returns: %TRUE if @structure is a subset of @caps
1245 gst_caps_is_subset_structure (const GstCaps * caps,
1246 const GstStructure * structure)
1251 g_return_val_if_fail (caps != NULL, FALSE);
1252 g_return_val_if_fail (structure != NULL, FALSE);
1254 if (CAPS_IS_ANY (caps))
1256 if (CAPS_IS_EMPTY (caps))
1259 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1260 s = gst_caps_get_structure_unchecked (caps, i);
1261 if (gst_structure_is_subset (structure, s)) {
1262 /* If we found a superset return TRUE */
1271 * gst_caps_is_subset_structure_full:
1273 * @structure: a potential #GstStructure subset of @caps
1274 * @features: (allow-none): a #GstCapsFeatures for @structure
1276 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1277 * for more information.
1279 * Returns: %TRUE if @structure is a subset of @caps
1284 gst_caps_is_subset_structure_full (const GstCaps * caps,
1285 const GstStructure * structure, const GstCapsFeatures * features)
1291 g_return_val_if_fail (caps != NULL, FALSE);
1292 g_return_val_if_fail (structure != NULL, FALSE);
1294 if (CAPS_IS_ANY (caps))
1296 if (CAPS_IS_EMPTY (caps))
1300 features = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1302 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1303 s = gst_caps_get_structure_unchecked (caps, i);
1304 f = gst_caps_get_features_unchecked (caps, i);
1306 f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1307 if ((!gst_caps_features_is_any (features) || gst_caps_features_is_any (f))
1308 && gst_caps_features_is_equal (features, f)
1309 && gst_structure_is_subset (structure, s)) {
1310 /* If we found a superset return TRUE */
1319 * gst_caps_is_equal:
1320 * @caps1: a #GstCaps
1321 * @caps2: another #GstCaps
1323 * Checks if the given caps represent the same set of caps.
1325 * Returns: TRUE if both caps are equal.
1328 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1330 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1331 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1333 if (G_UNLIKELY (caps1 == caps2))
1336 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1337 return gst_caps_is_equal_fixed (caps1, caps2);
1339 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1343 * gst_caps_is_strictly_equal:
1344 * @caps1: a #GstCaps
1345 * @caps2: another #GstCaps
1347 * Checks if the given caps are exactly the same set of caps.
1349 * Returns: TRUE if both caps are strictly equal.
1352 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1355 GstStructure *s1, *s2;
1356 GstCapsFeatures *f1, *f2;
1358 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1359 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1361 if (G_UNLIKELY (caps1 == caps2))
1364 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1367 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1368 s1 = gst_caps_get_structure_unchecked (caps1, i);
1369 f1 = gst_caps_get_features_unchecked (caps1, i);
1371 f1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1372 s2 = gst_caps_get_structure_unchecked (caps2, i);
1373 f2 = gst_caps_get_features_unchecked (caps2, i);
1375 f2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1377 if (gst_caps_features_is_any (f1) != gst_caps_features_is_any (f2) ||
1378 !gst_caps_features_is_equal (f1, f2) ||
1379 !gst_structure_is_equal (s1, s2))
1386 /* intersect operation */
1389 * gst_caps_can_intersect:
1390 * @caps1: a #GstCaps to intersect
1391 * @caps2: a #GstCaps to intersect
1393 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1396 * Returns: %TRUE if intersection would be not empty
1399 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1401 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1402 guint j, k, len1, len2;
1403 GstStructure *struct1;
1404 GstStructure *struct2;
1405 GstCapsFeatures *features1;
1406 GstCapsFeatures *features2;
1408 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1409 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1411 /* caps are exactly the same pointers */
1412 if (G_UNLIKELY (caps1 == caps2))
1415 /* empty caps on either side, return empty */
1416 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1419 /* one of the caps is any */
1420 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1423 /* run zigzag on top line then right line, this preserves the caps order
1424 * much better than a simple loop.
1426 * This algorithm zigzags over the caps structures as demonstrated in
1427 * the following matrix:
1430 * +------------- total distance: +-------------
1431 * | 1 2 4 7 0 | 0 1 2 3
1432 * caps2 | 3 5 8 10 1 | 1 2 3 4
1433 * | 6 9 11 12 2 | 2 3 4 5
1435 * First we iterate over the caps1 structures (top line) intersecting
1436 * the structures diagonally down, then we iterate over the caps2
1437 * structures. The result is that the intersections are ordered based on the
1438 * sum of the indexes in the list.
1440 len1 = GST_CAPS_LEN (caps1);
1441 len2 = GST_CAPS_LEN (caps2);
1442 for (i = 0; i < len1 + len2 - 1; i++) {
1443 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1444 j = MIN (i, len1 - 1);
1445 /* subset index stays 0 until i reaches superset->structs->len, then it
1446 * counts up from 1 to subset->structs->len - 1 */
1447 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1448 /* now run the diagonal line, end condition is the left or bottom
1451 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1452 features1 = gst_caps_get_features_unchecked (caps1, j);
1454 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1455 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1456 features2 = gst_caps_get_features_unchecked (caps2, k);
1458 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1459 if (gst_caps_features_is_equal (features1, features2) &&
1460 gst_structure_can_intersect (struct1, struct2)) {
1463 /* move down left */
1465 if (G_UNLIKELY (j == 0))
1466 break; /* so we don't roll back to G_MAXUINT */
1475 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1477 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1478 guint j, k, len1, len2;
1479 GstStructure *struct1;
1480 GstStructure *struct2;
1481 GstCapsFeatures *features1;
1482 GstCapsFeatures *features2;
1484 GstStructure *istruct;
1486 /* caps are exactly the same pointers, just copy one caps */
1487 if (G_UNLIKELY (caps1 == caps2))
1488 return gst_caps_ref (caps1);
1490 /* empty caps on either side, return empty */
1491 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1492 return gst_caps_ref (GST_CAPS_NONE);
1494 /* one of the caps is any, just copy the other caps */
1495 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1496 return gst_caps_ref (caps2);
1498 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1499 return gst_caps_ref (caps1);
1501 dest = gst_caps_new_empty ();
1502 /* run zigzag on top line then right line, this preserves the caps order
1503 * much better than a simple loop.
1505 * This algorithm zigzags over the caps structures as demonstrated in
1506 * the following matrix:
1514 * First we iterate over the caps1 structures (top line) intersecting
1515 * the structures diagonally down, then we iterate over the caps2
1518 len1 = GST_CAPS_LEN (caps1);
1519 len2 = GST_CAPS_LEN (caps2);
1520 for (i = 0; i < len1 + len2 - 1; i++) {
1521 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1522 j = MIN (i, len1 - 1);
1523 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1524 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1525 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1526 /* now run the diagonal line, end condition is the left or bottom
1529 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1530 features1 = gst_caps_get_features_unchecked (caps1, j);
1532 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1533 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1534 features2 = gst_caps_get_features_unchecked (caps2, k);
1536 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1537 if (gst_caps_features_is_equal (features1, features2)) {
1538 istruct = gst_structure_intersect (struct1, struct2);
1540 if (gst_caps_features_is_any (features1))
1542 gst_caps_merge_structure_full (dest, istruct,
1543 gst_caps_features_copy_conditional (features2));
1546 gst_caps_merge_structure_full (dest, istruct,
1547 gst_caps_features_copy_conditional (features1));
1550 /* move down left */
1552 if (G_UNLIKELY (j == 0))
1553 break; /* so we don't roll back to G_MAXUINT */
1561 * gst_caps_intersect_first:
1562 * @caps1: a #GstCaps to intersect
1563 * @caps2: a #GstCaps to intersect
1565 * Creates a new #GstCaps that contains all the formats that are common
1566 * to both @caps1 and @caps2.
1568 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1569 * fashion as @caps1.
1571 * Returns: the new #GstCaps
1574 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1577 guint j, len1, len2;
1578 GstStructure *struct1;
1579 GstStructure *struct2;
1580 GstCapsFeatures *features1;
1581 GstCapsFeatures *features2;
1583 GstStructure *istruct;
1585 /* caps are exactly the same pointers, just copy one caps */
1586 if (G_UNLIKELY (caps1 == caps2))
1587 return gst_caps_ref (caps1);
1589 /* empty caps on either side, return empty */
1590 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1591 return gst_caps_ref (GST_CAPS_NONE);
1593 /* one of the caps is any, just copy the other caps */
1594 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1595 return gst_caps_ref (caps2);
1597 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1598 return gst_caps_ref (caps1);
1600 dest = gst_caps_new_empty ();
1601 len1 = GST_CAPS_LEN (caps1);
1602 len2 = GST_CAPS_LEN (caps2);
1603 for (i = 0; i < len1; i++) {
1604 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1605 features1 = gst_caps_get_features_unchecked (caps1, i);
1607 features1 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1608 for (j = 0; j < len2; j++) {
1609 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1610 features2 = gst_caps_get_features_unchecked (caps2, j);
1612 features2 = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1613 if (gst_caps_features_is_equal (features1, features2)) {
1614 istruct = gst_structure_intersect (struct1, struct2);
1616 if (gst_caps_features_is_any (features1))
1618 gst_caps_merge_structure_full (dest, istruct,
1619 gst_caps_features_copy_conditional (features2));
1622 gst_caps_merge_structure_full (dest, istruct,
1623 gst_caps_features_copy_conditional (features1));
1633 * gst_caps_intersect_full:
1634 * @caps1: a #GstCaps to intersect
1635 * @caps2: a #GstCaps to intersect
1636 * @mode: The intersection algorithm/mode to use
1638 * Creates a new #GstCaps that contains all the formats that are common
1639 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1642 * Returns: the new #GstCaps
1645 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1646 GstCapsIntersectMode mode)
1648 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1649 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1652 case GST_CAPS_INTERSECT_FIRST:
1653 return gst_caps_intersect_first (caps1, caps2);
1655 g_warning ("Unknown caps intersect mode: %d", mode);
1657 case GST_CAPS_INTERSECT_ZIG_ZAG:
1658 return gst_caps_intersect_zig_zag (caps1, caps2);
1663 * gst_caps_intersect:
1664 * @caps1: a #GstCaps to intersect
1665 * @caps2: a #GstCaps to intersect
1667 * Creates a new #GstCaps that contains all the formats that are common
1668 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1670 * Returns: the new #GstCaps
1673 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1675 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1678 /* subtract operation */
1682 const GstStructure *subtract_from;
1687 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1690 SubtractionEntry *e = user_data;
1691 GValue subtraction = { 0, };
1692 const GValue *other;
1693 GstStructure *structure;
1695 other = gst_structure_id_get_value (e->subtract_from, field_id);
1701 if (!gst_value_subtract (&subtraction, other, value))
1704 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1705 g_value_unset (&subtraction);
1708 structure = gst_structure_copy (e->subtract_from);
1709 gst_structure_id_take_value (structure, field_id, &subtraction);
1710 e->put_into = g_slist_prepend (e->put_into, structure);
1716 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1717 const GstStructure * subtrahend)
1722 e.subtract_from = minuend;
1724 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1725 gst_caps_structure_subtract_field, &e);
1732 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1733 gst_structure_free (walk->data);
1735 g_slist_free (e.put_into);
1742 * gst_caps_subtract:
1743 * @minuend: #GstCaps to subtract from
1744 * @subtrahend: #GstCaps to subtract
1746 * Subtracts the @subtrahend from the @minuend.
1747 * <note>This function does not work reliably if optional properties for caps
1748 * are included on one caps and omitted on the other.</note>
1750 * Returns: the resulting caps
1753 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1758 GstCapsFeatures *min_f, *sub_f;
1759 GstCaps *dest = NULL, *src;
1761 g_return_val_if_fail (minuend != NULL, NULL);
1762 g_return_val_if_fail (subtrahend != NULL, NULL);
1764 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1765 return gst_caps_new_empty ();
1768 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1769 return gst_caps_ref (minuend);
1771 /* FIXME: Do we want this here or above?
1772 The reason we need this is that there is no definition about what
1773 ANY means for specific types, so it's not possible to reduce ANY partially
1774 You can only remove everything or nothing and that is done above.
1775 Note: there's a test that checks this behaviour. */
1777 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1778 sublen = GST_CAPS_LEN (subtrahend);
1779 g_assert (sublen > 0);
1781 src = _gst_caps_copy (minuend);
1782 for (i = 0; i < sublen; i++) {
1785 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1786 sub_f = gst_caps_get_features_unchecked (subtrahend, i);
1788 sub_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1790 gst_caps_unref (src);
1793 dest = gst_caps_new_empty ();
1794 srclen = GST_CAPS_LEN (src);
1795 for (j = 0; j < srclen; j++) {
1796 min = gst_caps_get_structure_unchecked (src, j);
1797 min_f = gst_caps_get_features_unchecked (src, j);
1799 min_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
1801 /* Same reason as above for ANY caps */
1802 g_return_val_if_fail (!gst_caps_features_is_any (min_f), NULL);
1804 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub) &&
1805 gst_caps_features_is_equal (min_f, sub_f)) {
1808 if (gst_caps_structure_subtract (&list, min, sub)) {
1811 for (walk = list; walk; walk = g_slist_next (walk)) {
1812 gst_caps_append_structure_unchecked (dest,
1813 (GstStructure *) walk->data,
1814 gst_caps_features_copy_conditional (min_f));
1816 g_slist_free (list);
1818 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1819 gst_caps_features_copy_conditional (min_f));
1822 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min),
1823 gst_caps_features_copy_conditional (min_f));
1827 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1828 gst_caps_unref (src);
1833 gst_caps_unref (src);
1834 dest = gst_caps_simplify (dest);
1839 /* normalize/simplify operations */
1841 typedef struct _NormalizeForeach
1844 GstStructure *structure;
1845 GstCapsFeatures *features;
1849 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1851 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1855 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1856 guint len = gst_value_list_get_size (value);
1858 for (i = 1; i < len; i++) {
1859 const GValue *v = gst_value_list_get_value (value, i);
1860 GstStructure *structure = gst_structure_copy (nf->structure);
1862 gst_structure_id_set_value (structure, field_id, v);
1863 gst_caps_append_structure_unchecked (nf->caps, structure,
1864 gst_caps_features_copy_conditional (nf->features));
1867 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1868 gst_structure_id_take_value (nf->structure, field_id, &val);
1876 * gst_caps_normalize:
1877 * @caps: (transfer full): a #GstCaps to normalize
1879 * Returns a #GstCaps that represents the same set of formats as
1880 * @caps, but contains no lists. Each list is expanded into separate
1883 * This function takes ownership of @caps.
1885 * Returns: (transfer full): the normalized #GstCaps
1888 gst_caps_normalize (GstCaps * caps)
1890 NormalizeForeach nf;
1893 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1895 caps = gst_caps_make_writable (caps);
1898 for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1899 nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1900 nf.features = gst_caps_get_features_unchecked (nf.caps, i);
1901 while (!gst_structure_foreach (nf.structure,
1902 gst_caps_normalize_foreach, &nf));
1909 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1912 const GstStructure *struct1 = ((const GstCapsArrayElement *) one)->structure;
1913 const GstStructure *struct2 = ((const GstCapsArrayElement *) two)->structure;
1915 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1916 So what's the best way? */
1917 ret = strcmp (gst_structure_get_name (struct1),
1918 gst_structure_get_name (struct2));
1923 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1930 GstStructure *compare;
1934 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1937 UnionField *u = user_data;
1938 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1942 g_value_unset (&u->value);
1946 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1950 g_value_unset (&u->value);
1955 gst_value_union (&u->value, val, value);
1961 gst_caps_structure_simplify (GstStructure ** result,
1962 GstStructure * simplify, GstStructure * compare)
1965 UnionField field = { 0, {0,}, NULL };
1967 /* try to subtract to get a real subset */
1968 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1969 if (list == NULL) { /* no result */
1972 } else if (list->next == NULL) { /* one result */
1973 *result = list->data;
1974 g_slist_free (list);
1976 } else { /* multiple results */
1977 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1978 g_slist_free (list);
1983 /* try to union both structs */
1984 field.compare = compare;
1985 if (gst_structure_foreach (simplify,
1986 gst_caps_structure_figure_out_union, &field)) {
1987 gboolean ret = FALSE;
1989 /* now we know all of simplify's fields are the same in compare
1990 * but at most one field: field.name */
1991 if (G_IS_VALUE (&field.value)) {
1992 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1993 gst_structure_id_take_value (compare, field.name, &field.value);
1997 g_value_unset (&field.value);
2000 if (gst_structure_n_fields (simplify) <=
2001 gst_structure_n_fields (compare)) {
2002 /* compare is just more specific, will be optimized away later */
2003 /* FIXME: do this here? */
2004 GST_LOG ("found a case that will be optimized later.");
2006 gchar *one = gst_structure_to_string (simplify);
2007 gchar *two = gst_structure_to_string (compare);
2010 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
2022 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
2023 GstStructure * new, gint i)
2025 gst_structure_set_parent_refcount (old, NULL);
2026 gst_structure_free (old);
2027 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
2028 g_array_index (GST_CAPS_ARRAY (caps), GstCapsArrayElement, i).structure = new;
2032 * gst_caps_simplify:
2033 * @caps: (transfer full): a #GstCaps to simplify
2035 * Converts the given @caps into a representation that represents the
2036 * same set of formats, but in a simpler form. Component structures that are
2037 * identical are merged. Component structures that have values that can be
2038 * merged are also merged.
2040 * This method does not preserve the original order of @caps.
2042 * Returns: The simplified caps.
2045 gst_caps_simplify (GstCaps * caps)
2047 GstStructure *simplify, *compare, *result = NULL;
2048 GstCapsFeatures *simplify_f, *compare_f;
2051 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2053 start = GST_CAPS_LEN (caps) - 1;
2054 /* one caps, already as simple as can be */
2058 caps = gst_caps_make_writable (caps);
2060 g_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
2062 for (i = start; i >= 0; i--) {
2063 simplify = gst_caps_get_structure_unchecked (caps, i);
2064 simplify_f = gst_caps_get_features_unchecked (caps, i);
2066 simplify_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2067 compare = gst_caps_get_structure_unchecked (caps, start);
2068 compare_f = gst_caps_get_features_unchecked (caps, start);
2070 compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2071 if (gst_structure_get_name_id (simplify) !=
2072 gst_structure_get_name_id (compare) ||
2073 !gst_caps_features_is_equal (simplify_f, compare_f))
2075 for (j = start; j >= 0; j--) {
2078 compare = gst_caps_get_structure_unchecked (caps, j);
2079 compare_f = gst_caps_get_features_unchecked (caps, j);
2081 compare_f = GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY;
2082 if (gst_structure_get_name_id (simplify) !=
2083 gst_structure_get_name_id (compare) ||
2084 !gst_caps_features_is_equal (simplify_f, compare_f)) {
2087 if (gst_caps_structure_simplify (&result, simplify, compare)) {
2089 gst_caps_switch_structures (caps, simplify, result, i);
2092 gst_caps_remove_structure (caps, i);
2104 * @caps: (transfer full): a #GstCaps to fixate
2106 * Modifies the given @caps into a representation with only fixed
2107 * values. First the caps will be truncated and then the first structure will be
2108 * fixated with gst_structure_fixate().
2110 * Returns: (transfer full): the fixated caps
2113 gst_caps_fixate (GstCaps * caps)
2118 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
2120 /* default fixation */
2121 caps = gst_caps_truncate (caps);
2122 caps = gst_caps_make_writable (caps);
2123 s = gst_caps_get_structure (caps, 0);
2124 gst_structure_fixate (s);
2126 /* Set features to sysmem if they're still ANY */
2127 f = gst_caps_get_features_unchecked (caps, 0);
2128 if (f && gst_caps_features_is_any (f)) {
2129 f = gst_caps_features_new_empty ();
2130 gst_caps_set_features (caps, 0, f);
2139 * gst_caps_to_string:
2142 * Converts @caps to a string representation. This string representation
2143 * can be converted back to a #GstCaps by gst_caps_from_string().
2145 * For debugging purposes its easier to do something like this:
2147 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2149 * This prints the caps in human readable form.
2151 * The current implementation of serialization will lead to unexpected results
2152 * when there are nested #GstCaps / #GstStructure deeper than one level.
2154 * Returns: (transfer full): a newly allocated string representing @caps.
2157 gst_caps_to_string (const GstCaps * caps)
2159 guint i, slen, clen;
2162 /* NOTE: This function is potentially called by the debug system,
2163 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2164 * should be careful to avoid recursion. This includes any functions
2165 * called by gst_caps_to_string. In particular, calls should
2166 * not use the GST_PTR_FORMAT extension. */
2169 return g_strdup ("NULL");
2171 if (CAPS_IS_ANY (caps)) {
2172 return g_strdup ("ANY");
2174 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2175 return g_strdup ("EMPTY");
2178 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2180 clen = GST_CAPS_LEN (caps);
2181 for (i = 0; i < clen; i++) {
2185 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked
2187 f = gst_caps_get_features_unchecked (caps, i);
2189 slen += FEATURES_ESTIMATED_STRING_LEN (f);
2192 s = g_string_sized_new (slen);
2193 for (i = 0; i < clen; i++) {
2194 GstStructure *structure;
2195 GstCapsFeatures *features;
2198 /* ';' is now added by gst_structure_to_string */
2199 g_string_append_c (s, ' ');
2202 structure = gst_caps_get_structure_unchecked (caps, i);
2203 features = gst_caps_get_features_unchecked (caps, i);
2205 g_string_append (s, gst_structure_get_name (structure));
2206 if (features && (gst_caps_features_is_any (features)
2207 || !gst_caps_features_is_equal (features,
2208 GST_CAPS_FEATURES_MEMORY_SYSTEM_MEMORY))) {
2209 g_string_append_c (s, '(');
2210 priv_gst_caps_features_append_to_gstring (features, s);
2211 g_string_append_c (s, ')');
2213 priv_gst_structure_append_to_gstring (structure, s);
2215 if (s->len && s->str[s->len - 1] == ';') {
2216 /* remove latest ';' */
2217 s->str[--s->len] = '\0';
2219 return g_string_free (s, FALSE);
2223 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2225 GstStructure *structure;
2226 gchar *s, *copy, *end, *next, save;
2228 if (strcmp ("ANY", string) == 0) {
2229 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
2233 if (strcmp ("EMPTY", string) == 0 || strcmp ("NONE", string) == 0) {
2237 copy = s = g_strdup (string);
2239 GstCapsFeatures *features = NULL;
2241 while (g_ascii_isspace (*s))
2247 if (!priv_gst_structure_parse_name (s, &s, &end, &next)) {
2254 structure = gst_structure_new_empty (s);
2257 if (structure == NULL) {
2275 } else if (*end == ')') {
2284 features = gst_caps_features_from_string (s);
2286 gst_structure_free (structure);
2300 if (!priv_gst_structure_parse_fields (s, &s, structure)) {
2301 gst_structure_free (structure);
2307 gst_caps_append_structure_unchecked (caps, structure, features);
2318 * gst_caps_from_string:
2319 * @string: a string to convert to #GstCaps
2321 * Converts @caps from a string representation.
2323 * The current implementation of serialization will lead to unexpected results
2324 * when there are nested #GstCaps / #GstStructure deeper than one level.
2326 * Returns: (transfer full): a newly allocated #GstCaps
2329 gst_caps_from_string (const gchar * string)
2333 g_return_val_if_fail (string, FALSE);
2335 caps = gst_caps_new_empty ();
2336 if (gst_caps_from_string_inplace (caps, string)) {
2339 gst_caps_unref (caps);
2345 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2347 g_return_if_fail (G_IS_VALUE (src_value));
2348 g_return_if_fail (G_IS_VALUE (dest_value));
2349 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2350 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2351 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2353 g_value_take_string (dest_value,
2354 gst_caps_to_string (gst_value_get_caps (src_value)));