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., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
22 * @short_description: Structure describing sets of media formats
23 * @see_also: #GstStructure
25 * Caps (capabilities) are lighweight 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_get_caps() pad
33 * function. This function describes the possible types that the pad can
34 * handle or produce at runtime.
36 * Caps are also attached to buffers to describe to content of the data
37 * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
38 * a #GstBuffer allow for format negotiation upstream and downstream.
40 * A #GstCaps can be constructed with the following code fragment:
43 * <title>Creating caps</title>
46 * caps = gst_caps_new_simple ("video/x-raw-yuv",
47 * "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
48 * "framerate", GST_TYPE_FRACTION, 25, 1,
49 * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
50 * "width", G_TYPE_INT, 320,
51 * "height", G_TYPE_INT, 240,
56 * A #GstCaps is fixed when it has no properties with ranges or lists. Use
57 * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
58 * set on a #GstPad or #GstBuffer.
60 * Various methods exist to work with the media types such as subtracting
63 * Last reviewed on 2007-02-13 (0.10.10)
72 #include "gst_private.h"
74 #include <gobject/gvaluecollector.h>
76 #define DEBUG_REFCOUNT
78 #define CAPS_POISON(caps) G_STMT_START{ \
80 GstCaps *_newcaps = gst_caps_copy (caps); \
81 gst_caps_unref(caps); \
85 #define STRUCTURE_POISON(structure) G_STMT_START{ \
87 GstStructure *_newstruct = gst_structure_copy (structure); \
88 gst_structure_free(structure); \
89 structure = _newstruct; \
92 #define IS_WRITABLE(caps) \
93 (g_atomic_int_get (&(caps)->refcount) == 1)
95 /* same as gst_caps_is_any () */
96 #define CAPS_IS_ANY(caps) \
97 ((caps)->flags & GST_CAPS_FLAGS_ANY)
99 /* same as gst_caps_is_empty () */
100 #define CAPS_IS_EMPTY(caps) \
101 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
103 #define CAPS_IS_EMPTY_SIMPLE(caps) \
104 (((caps)->structs == NULL) || ((caps)->structs->len == 0))
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 ((GstStructure *)g_ptr_array_index ((caps)->structs, (index)))
112 /* lock to protect multiple invocations of static caps to caps conversion */
113 G_LOCK_DEFINE_STATIC (static_caps_lock);
115 static void gst_caps_transform_to_string (const GValue * src_value,
116 GValue * dest_value);
117 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
118 const gchar * string);
119 static GstCaps *gst_caps_copy_conditional (GstCaps * src);
122 gst_caps_get_type (void)
124 static GType gst_caps_type = 0;
126 if (G_UNLIKELY (gst_caps_type == 0)) {
127 gst_caps_type = g_boxed_type_register_static ("GstCaps",
128 (GBoxedCopyFunc) gst_caps_copy_conditional,
129 (GBoxedFreeFunc) gst_caps_unref);
131 g_value_register_transform_func (gst_caps_type,
132 G_TYPE_STRING, gst_caps_transform_to_string);
135 return gst_caps_type;
138 /* creation/deletion */
141 * gst_caps_new_empty:
143 * Creates a new #GstCaps that is empty. That is, the returned
144 * #GstCaps contains no media formats.
145 * Caller is responsible for unreffing the returned caps.
147 * Returns: the new #GstCaps
150 gst_caps_new_empty (void)
152 GstCaps *caps = g_slice_new (GstCaps);
154 caps->type = GST_TYPE_CAPS;
157 caps->structs = g_ptr_array_new ();
158 /* the 32 has been determined by logging caps sizes in _gst_caps_free
159 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
161 * caps->structs = g_ptr_array_sized_new (32);
164 #ifdef DEBUG_REFCOUNT
165 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
174 * Creates a new #GstCaps that indicates that it is compatible with
177 * Returns: the new #GstCaps
180 gst_caps_new_any (void)
182 GstCaps *caps = gst_caps_new_empty ();
184 caps->flags = GST_CAPS_FLAGS_ANY;
190 * gst_caps_new_simple:
191 * @media_type: the media type of the structure
192 * @fieldname: first field to set
193 * @...: additional arguments
195 * Creates a new #GstCaps that contains one #GstStructure. The
196 * structure is defined by the arguments, which have the same format
197 * as gst_structure_new().
198 * Caller is responsible for unreffing the returned caps.
200 * Returns: the new #GstCaps
203 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
206 GstStructure *structure;
209 caps = gst_caps_new_empty ();
211 va_start (var_args, fieldname);
212 structure = gst_structure_new_valist (media_type, fieldname, var_args);
215 gst_caps_append_structure (caps, structure);
222 * @struct1: the first structure to add
223 * @...: additional structures to add
225 * Creates a new #GstCaps and adds all the structures listed as
226 * arguments. The list must be NULL-terminated. The structures
227 * are not copied; the returned #GstCaps owns the structures.
229 * Returns: the new #GstCaps
232 gst_caps_new_full (GstStructure * struct1, ...)
237 va_start (var_args, struct1);
238 caps = gst_caps_new_full_valist (struct1, var_args);
245 * gst_caps_new_full_valist:
246 * @structure: the first structure to add
247 * @var_args: additional structures to add
249 * Creates a new #GstCaps and adds all the structures listed as
250 * arguments. The list must be NULL-terminated. The structures
251 * are not copied; the returned #GstCaps owns the structures.
253 * Returns: the new #GstCaps
256 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
260 caps = gst_caps_new_empty ();
263 gst_caps_append_structure (caps, structure);
264 structure = va_arg (var_args, GstStructure *);
272 * @caps: the #GstCaps to copy
274 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
275 * refcount of 1, owned by the caller. The structures are copied as well.
277 * Note that this function is the semantic equivalent of a gst_caps_ref()
278 * followed by a gst_caps_make_writable(). If you only want to hold on to a
279 * reference to the data, you should use gst_caps_ref().
281 * When you are finished with the caps, call gst_caps_unref() on it.
283 * Returns: the new #GstCaps
286 gst_caps_copy (const GstCaps * caps)
289 GstStructure *structure;
292 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
294 newcaps = gst_caps_new_empty ();
295 newcaps->flags = caps->flags;
296 n = caps->structs->len;
298 for (i = 0; i < n; i++) {
299 structure = gst_caps_get_structure_unchecked (caps, i);
300 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
307 _gst_caps_free (GstCaps * caps)
309 GstStructure *structure;
312 /* The refcount must be 0, but since we're only called by gst_caps_unref,
313 * don't bother testing. */
314 len = caps->structs->len;
315 /* This can be used to get statistics about caps sizes */
316 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
317 for (i = 0; i < len; i++) {
318 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
319 gst_structure_set_parent_refcount (structure, NULL);
320 gst_structure_free (structure);
322 g_ptr_array_free (caps->structs, TRUE);
324 memset (caps, 0xff, sizeof (GstCaps));
327 #ifdef DEBUG_REFCOUNT
328 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
330 g_slice_free (GstCaps, caps);
334 * gst_caps_make_writable:
335 * @caps: the #GstCaps to make writable
337 * Returns a writable copy of @caps.
339 * If there is only one reference count on @caps, the caller must be the owner,
340 * and so this function will return the caps object unchanged. If on the other
341 * hand there is more than one reference on the object, a new caps object will
342 * be returned. The caller's reference on @caps will be removed, and instead the
343 * caller will own a reference to the returned object.
345 * In short, this function unrefs the caps in the argument and refs the caps
346 * that it returns. Don't access the argument after calling this function. See
347 * also: gst_caps_ref().
349 * Returns: the same #GstCaps object.
352 gst_caps_make_writable (GstCaps * caps)
356 g_return_val_if_fail (caps != NULL, NULL);
358 /* we are the only instance reffing this caps */
359 if (IS_WRITABLE (caps))
363 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy caps");
364 copy = gst_caps_copy (caps);
365 gst_caps_unref (caps);
372 * @caps: the #GstCaps to reference
374 * Add a reference to a #GstCaps object.
376 * From this point on, until the caller calls gst_caps_unref() or
377 * gst_caps_make_writable(), it is guaranteed that the caps object will not
378 * change. This means its structures won't change, etc. To use a #GstCaps
379 * object, you must always have a refcount on it -- either the one made
380 * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
383 * Returns: the same #GstCaps object.
386 gst_caps_ref (GstCaps * caps)
388 g_return_val_if_fail (caps != NULL, NULL);
390 #ifdef DEBUG_REFCOUNT
391 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
392 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) + 1);
394 g_return_val_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0, NULL);
396 g_atomic_int_inc (&caps->refcount);
403 * @caps: the #GstCaps to unref
405 * Unref a #GstCaps and and free all its structures and the
406 * structures' values when the refcount reaches 0.
409 gst_caps_unref (GstCaps * caps)
411 g_return_if_fail (caps != NULL);
413 #ifdef DEBUG_REFCOUNT
414 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
415 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) - 1);
418 g_return_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0);
420 /* if we ended up with the refcount at zero, free the caps */
421 if (G_UNLIKELY (g_atomic_int_dec_and_test (&caps->refcount)))
422 _gst_caps_free (caps);
426 gst_static_caps_get_type (void)
428 static GType staticcaps_type = 0;
430 if (G_UNLIKELY (staticcaps_type == 0)) {
431 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
433 return staticcaps_type;
438 * gst_static_caps_get:
439 * @static_caps: the #GstStaticCaps to convert
441 * Converts a #GstStaticCaps to a #GstCaps.
443 * Returns: A pointer to the #GstCaps. Unref after usage. Since the
444 * core holds an additional ref to the returned caps,
445 * use gst_caps_make_writable() on the returned caps to modify it.
448 gst_static_caps_get (GstStaticCaps * static_caps)
452 g_return_val_if_fail (static_caps != NULL, NULL);
454 caps = (GstCaps *) static_caps;
456 /* refcount is 0 when we need to convert */
457 if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) == 0)) {
461 G_LOCK (static_caps_lock);
462 /* check if other thread already updated */
463 if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) > 0))
466 string = static_caps->string;
468 if (G_UNLIKELY (string == NULL))
471 GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);
473 /* we construct the caps on the stack, then copy over the struct into our
474 * real caps, refcount last. We do this because we must leave the refcount
475 * of the result caps to 0 so that other threads don't run away with the
476 * caps while we are constructing it. */
477 temp.type = GST_TYPE_CAPS;
479 temp.structs = g_ptr_array_new ();
481 /* initialize the caps to a refcount of 1 so the caps can be writable for
482 * the next statement */
485 /* convert to string */
486 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
487 g_critical ("Could not convert static caps \"%s\"", string);
489 /* now copy stuff over to the real caps. */
490 caps->type = temp.type;
491 caps->flags = temp.flags;
492 caps->structs = temp.structs;
493 /* and bump the refcount so other threads can now read */
494 g_atomic_int_set (&caps->refcount, 1);
496 GST_CAT_LOG (GST_CAT_CAPS, "created %p", static_caps);
498 G_UNLOCK (static_caps_lock);
500 /* ref the caps, makes it not writable */
508 G_UNLOCK (static_caps_lock);
509 g_warning ("static caps %p string is NULL", static_caps);
516 static GstStructure *
517 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
519 /* don't use index_fast, gst_caps_do_simplify relies on the order */
520 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
522 gst_structure_set_parent_refcount (s, NULL);
527 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
530 GstStructure *struct1 = (GstStructure *) data;
531 const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
533 if (G_UNLIKELY (val1 == NULL))
535 if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
543 gst_caps_structure_is_subset_field (GQuark field_id, const GValue * value,
546 GstStructure *subtract_from = user_data;
547 GValue subtraction = { 0, };
550 if (!(other = gst_structure_id_get_value (subtract_from, field_id)))
551 /* field is missing in one set */
554 /* equal values are subset */
555 if (gst_value_compare (other, value) == GST_VALUE_EQUAL)
563 * -> 1 - [1,2] = empty
567 * -> [1,2] - [1,3] = empty
571 * -> {1,3} - {1,2} = 3
574 * First caps subtraction needs to return a non-empty set, second
575 * subtractions needs to give en empty set.
577 if (gst_value_subtract (&subtraction, other, value)) {
578 g_value_unset (&subtraction);
579 /* !empty result, swapping must be empty */
580 if (!gst_value_subtract (&subtraction, value, other))
583 g_value_unset (&subtraction);
589 gst_caps_structure_is_subset (const GstStructure * minuend,
590 const GstStructure * subtrahend)
592 if ((minuend->name != subtrahend->name) ||
593 (gst_structure_n_fields (minuend) !=
594 gst_structure_n_fields (subtrahend))) {
598 return gst_structure_foreach ((GstStructure *) subtrahend,
599 gst_caps_structure_is_subset_field, (gpointer) minuend);
604 * @caps1: the #GstCaps that will be appended to
605 * @caps2: the #GstCaps to append
607 * Appends the structures contained in @caps2 to @caps1. The structures in
608 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
609 * freed. If either caps is ANY, the resulting caps will be ANY.
612 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
614 GstStructure *structure;
617 g_return_if_fail (GST_IS_CAPS (caps1));
618 g_return_if_fail (GST_IS_CAPS (caps2));
619 g_return_if_fail (IS_WRITABLE (caps1));
620 g_return_if_fail (IS_WRITABLE (caps2));
625 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
626 /* FIXME: this leaks */
627 caps1->flags |= GST_CAPS_FLAGS_ANY;
628 for (i = caps2->structs->len - 1; i >= 0; i--) {
629 structure = gst_caps_remove_and_get_structure (caps2, i);
630 gst_structure_free (structure);
633 for (i = caps2->structs->len; i; i--) {
634 structure = gst_caps_remove_and_get_structure (caps2, 0);
635 gst_caps_append_structure (caps1, structure);
638 gst_caps_unref (caps2); /* guaranteed to free it */
643 * @caps1: the #GstCaps that will take the new entries
644 * @caps2: the #GstCaps to merge in
646 * Appends the structures contained in @caps2 to @caps1 if they are not yet
647 * expressed by @caps1. The structures in @caps2 are not copied -- they are
648 * transferred to @caps1, and then @caps2 is freed.
649 * If either caps is ANY, the resulting caps will be ANY.
654 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
656 GstStructure *structure;
659 g_return_if_fail (GST_IS_CAPS (caps1));
660 g_return_if_fail (GST_IS_CAPS (caps2));
661 g_return_if_fail (IS_WRITABLE (caps1));
662 g_return_if_fail (IS_WRITABLE (caps2));
667 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
668 for (i = caps2->structs->len - 1; i >= 0; i--) {
669 structure = gst_caps_remove_and_get_structure (caps2, i);
670 gst_structure_free (structure);
672 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
673 caps1->flags |= GST_CAPS_FLAGS_ANY;
674 for (i = caps1->structs->len - 1; i >= 0; i--) {
675 structure = gst_caps_remove_and_get_structure (caps1, i);
676 gst_structure_free (structure);
679 for (i = caps2->structs->len; i; i--) {
680 structure = gst_caps_remove_and_get_structure (caps2, 0);
681 gst_caps_merge_structure (caps1, structure);
684 GstCaps *com = gst_caps_intersect (caps1, caps2);
685 GstCaps *add = gst_caps_subtract (caps2, com);
687 GST_DEBUG ("common : %d", gst_caps_get_size (com));
688 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
689 gst_caps_append (caps1, add);
690 gst_caps_unref (com);
693 gst_caps_unref (caps2); /* guaranteed to free it */
697 * gst_caps_append_structure:
698 * @caps: the #GstCaps that will be appended to
699 * @structure: the #GstStructure to append
701 * Appends @structure to @caps. The structure is not copied; @caps
702 * becomes the owner of @structure.
705 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
707 g_return_if_fail (GST_IS_CAPS (caps));
708 g_return_if_fail (IS_WRITABLE (caps));
710 if (G_LIKELY (structure)) {
711 g_return_if_fail (structure->parent_refcount == NULL);
714 STRUCTURE_POISON (structure);
717 gst_structure_set_parent_refcount (structure, &caps->refcount);
718 g_ptr_array_add (caps->structs, structure);
723 * gst_caps_remove_structure:
724 * @caps: the #GstCaps to remove from
725 * @idx: Index of the structure to remove
727 * removes the stucture with the given index from the list of structures
728 * contained in @caps.
731 gst_caps_remove_structure (GstCaps * caps, guint idx)
733 GstStructure *structure;
735 g_return_if_fail (caps != NULL);
736 g_return_if_fail (idx <= gst_caps_get_size (caps));
737 g_return_if_fail (IS_WRITABLE (caps));
739 structure = gst_caps_remove_and_get_structure (caps, idx);
740 gst_structure_free (structure);
744 * gst_caps_merge_structure:
745 * @caps: the #GstCaps that will the the new structure
746 * @structure: the #GstStructure to merge
748 * Appends @structure to @caps if its not already expressed by @caps. The
749 * structure is not copied; @caps becomes the owner of @structure.
752 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
754 g_return_if_fail (GST_IS_CAPS (caps));
755 g_return_if_fail (IS_WRITABLE (caps));
757 if (G_LIKELY (structure)) {
758 GstStructure *structure1;
760 gboolean unique = TRUE;
762 g_return_if_fail (structure->parent_refcount == NULL);
765 STRUCTURE_POISON (structure);
768 /* check each structure */
769 for (i = caps->structs->len - 1; i >= 0; i--) {
770 structure1 = gst_caps_get_structure_unchecked (caps, i);
771 /* if structure is a subset of structure1, then skip it */
772 if (gst_caps_structure_is_subset (structure1, structure)) {
778 gst_structure_set_parent_refcount (structure, &caps->refcount);
779 g_ptr_array_add (caps->structs, structure);
781 gst_structure_free (structure);
790 * Gets the number of structures contained in @caps.
792 * Returns: the number of structures that @caps contains
795 gst_caps_get_size (const GstCaps * caps)
797 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
799 return caps->structs->len;
803 * gst_caps_get_structure:
805 * @index: the index of the structure
807 * Finds the structure in @caps that has the index @index, and
810 * WARNING: This function takes a const GstCaps *, but returns a
811 * non-const GstStructure *. This is for programming convenience --
812 * the caller should be aware that structures inside a constant
813 * #GstCaps should not be modified. However, if you know the caps
814 * are writable, either because you have just copied them or made
815 * them writable with gst_caps_make_writable(), you may modify the
816 * structure returned in the usual way, e.g. with functions like
817 * gst_structure_set().
819 * You do not need to free or unref the structure returned, it
820 * belongs to the #GstCaps.
822 * Returns: a pointer to the #GstStructure corresponding to @index
825 gst_caps_get_structure (const GstCaps * caps, guint index)
827 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
828 g_return_val_if_fail (index < caps->structs->len, NULL);
830 return gst_caps_get_structure_unchecked (caps, index);
835 * @caps: the #GstCaps to copy
836 * @nth: the nth structure to copy
838 * Creates a new #GstCaps and appends a copy of the nth structure
839 * contained in @caps.
841 * Returns: the new #GstCaps
844 gst_caps_copy_nth (const GstCaps * caps, guint nth)
847 GstStructure *structure;
849 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
851 newcaps = gst_caps_new_empty ();
852 newcaps->flags = caps->flags;
854 if (G_LIKELY (caps->structs->len > nth)) {
855 structure = gst_caps_get_structure_unchecked (caps, nth);
856 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
864 * @caps: the #GstCaps to truncate
866 * Destructively discard all but the first structure from @caps. Useful when
867 * fixating. @caps must be writable.
870 gst_caps_truncate (GstCaps * caps)
874 g_return_if_fail (GST_IS_CAPS (caps));
875 g_return_if_fail (IS_WRITABLE (caps));
877 i = caps->structs->len - 1;
880 gst_caps_remove_structure (caps, i--);
884 * gst_caps_set_value:
885 * @caps: a writable caps
886 * @field: name of the field to set
887 * @value: value to set the field to
889 * Sets the given @field on all structures of @caps to the given @value.
890 * This is a convenience function for calling gst_structure_set_value() on
891 * all structures of @caps.
896 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
900 g_return_if_fail (GST_IS_CAPS (caps));
901 g_return_if_fail (IS_WRITABLE (caps));
902 g_return_if_fail (field != NULL);
903 g_return_if_fail (G_IS_VALUE (value));
905 len = caps->structs->len;
906 for (i = 0; i < len; i++) {
907 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
908 gst_structure_set_value (structure, field, value);
913 * gst_caps_set_simple_valist:
914 * @caps: the #GstCaps to set
915 * @field: first field to set
916 * @varargs: additional parameters
918 * Sets fields in a #GstCaps. The arguments must be passed in the same
919 * manner as gst_structure_set(), and be NULL-terminated.
920 * <note>Prior to GStreamer version 0.10.26, this function failed when
921 * @caps was not simple. If your code needs to work with those versions
922 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
923 * is %TRUE for @caps.</note>
926 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
928 GValue value = { 0, };
930 g_return_if_fail (GST_IS_CAPS (caps));
931 g_return_if_fail (IS_WRITABLE (caps));
937 type = va_arg (varargs, GType);
939 if (G_UNLIKELY (type == G_TYPE_DATE)) {
940 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
941 type = GST_TYPE_DATE;
943 #if GLIB_CHECK_VERSION(2,23,3)
944 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
946 g_value_init (&value, type);
947 G_VALUE_COLLECT (&value, varargs, 0, &err);
949 if (G_UNLIKELY (err)) {
950 g_critical ("%s", err);
954 gst_caps_set_value (caps, field, &value);
956 g_value_unset (&value);
958 field = va_arg (varargs, const gchar *);
963 * gst_caps_set_simple:
964 * @caps: the #GstCaps to set
965 * @field: first field to set
966 * @...: additional parameters
968 * Sets fields in a #GstCaps. The arguments must be passed in the same
969 * manner as gst_structure_set(), and be NULL-terminated.
970 * <note>Prior to GStreamer version 0.10.26, this function failed when
971 * @caps was not simple. If your code needs to work with those versions
972 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
973 * is %TRUE for @caps.</note>
976 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
980 g_return_if_fail (GST_IS_CAPS (caps));
981 g_return_if_fail (IS_WRITABLE (caps));
983 va_start (var_args, field);
984 gst_caps_set_simple_valist (caps, field, var_args);
992 * @caps: the #GstCaps to test
994 * Determines if @caps represents any media format.
996 * Returns: TRUE if @caps represents any format.
999 gst_caps_is_any (const GstCaps * caps)
1001 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1003 return (caps->flags & GST_CAPS_FLAGS_ANY);
1007 * gst_caps_is_empty:
1008 * @caps: the #GstCaps to test
1010 * Determines if @caps represents no media formats.
1012 * Returns: TRUE if @caps represents no formats.
1015 gst_caps_is_empty (const GstCaps * caps)
1017 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1019 if (caps->flags & GST_CAPS_FLAGS_ANY)
1022 return (caps->structs == NULL) || (caps->structs->len == 0);
1026 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
1029 return gst_value_is_fixed (value);
1033 * gst_caps_is_fixed:
1034 * @caps: the #GstCaps to test
1036 * Fixed #GstCaps describe exactly one format, that is, they have exactly
1037 * one structure, and each field in the structure describes a fixed type.
1038 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
1040 * Returns: TRUE if @caps is fixed
1043 gst_caps_is_fixed (const GstCaps * caps)
1045 GstStructure *structure;
1047 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1049 if (caps->structs->len != 1)
1052 structure = gst_caps_get_structure_unchecked (caps, 0);
1054 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
1058 * gst_caps_is_equal_fixed:
1059 * @caps1: the #GstCaps to test
1060 * @caps2: the #GstCaps to test
1062 * Tests if two #GstCaps are equal. This function only works on fixed
1065 * Returns: TRUE if the arguments represent the same format
1068 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
1070 GstStructure *struct1, *struct2;
1072 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1073 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1075 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1076 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1078 if (struct1->name != struct2->name) {
1081 if (struct1->fields->len != struct2->fields->len) {
1085 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
1090 * gst_caps_is_always_compatible:
1091 * @caps1: the #GstCaps to test
1092 * @caps2: the #GstCaps to test
1094 * A given #GstCaps structure is always compatible with another if
1095 * every media format that is in the first is also contained in the
1096 * second. That is, @caps1 is a subset of @caps2.
1098 * Returns: TRUE if @caps1 is a subset of @caps2.
1101 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1103 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1104 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1106 return gst_caps_is_subset (caps1, caps2);
1110 * gst_caps_is_subset:
1111 * @subset: a #GstCaps
1112 * @superset: a potentially greater #GstCaps
1114 * Checks if all caps represented by @subset are also represented by @superset.
1115 * <note>This function does not work reliably if optional properties for caps
1116 * are included on one caps and omitted on the other.</note>
1118 * Returns: %TRUE if @subset is a subset of @superset
1121 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1126 g_return_val_if_fail (subset != NULL, FALSE);
1127 g_return_val_if_fail (superset != NULL, FALSE);
1129 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1131 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1134 caps = gst_caps_subtract (subset, superset);
1135 ret = CAPS_IS_EMPTY_SIMPLE (caps);
1136 gst_caps_unref (caps);
1141 * gst_caps_is_equal:
1142 * @caps1: a #GstCaps
1143 * @caps2: another #GstCaps
1145 * Checks if the given caps represent the same set of caps.
1146 * <note>This function does not work reliably if optional properties for caps
1147 * are included on one caps and omitted on the other.</note>
1149 * This function deals correctly with passing NULL for any of the caps.
1151 * Returns: TRUE if both caps are equal.
1154 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1156 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1157 * So there should be an assertion that caps1 and caps2 != NULL */
1159 /* NULL <-> NULL is allowed here */
1160 if (G_UNLIKELY (caps1 == caps2))
1163 /* one of them NULL => they are different (can't be both NULL because
1164 * we checked that above) */
1165 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1168 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1169 return gst_caps_is_equal_fixed (caps1, caps2);
1171 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1174 /* intersect operation */
1179 const GstStructure *intersect;
1184 gst_caps_structure_intersect_field1 (GQuark id, const GValue * val1,
1187 IntersectData *idata = (IntersectData *) data;
1188 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1190 if (G_UNLIKELY (val2 == NULL)) {
1191 gst_structure_id_set_value (idata->dest, id, val1);
1193 GValue dest_value = { 0 };
1194 if (gst_value_intersect (&dest_value, val1, val2)) {
1195 gst_structure_id_set_value (idata->dest, id, &dest_value);
1196 g_value_unset (&dest_value);
1205 gst_caps_structure_intersect_field2 (GQuark id, const GValue * val1,
1208 IntersectData *idata = (IntersectData *) data;
1209 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1211 if (G_UNLIKELY (val2 == NULL)) {
1212 gst_structure_id_set_value (idata->dest, id, val1);
1217 static GstStructure *
1218 gst_caps_structure_intersect (const GstStructure * struct1,
1219 const GstStructure * struct2)
1223 g_assert (struct1 != NULL);
1224 g_assert (struct2 != NULL);
1226 if (G_UNLIKELY (struct1->name != struct2->name))
1229 /* copy fields from struct1 which we have not in struct2 to target
1230 * intersect if we have the field in both */
1231 data.dest = gst_structure_id_empty_new (struct1->name);
1232 data.intersect = struct2;
1233 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1234 gst_caps_structure_intersect_field1, &data)))
1237 /* copy fields from struct2 which we have not in struct1 to target */
1238 data.intersect = struct1;
1239 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
1240 gst_caps_structure_intersect_field2, &data)))
1246 gst_structure_free (data.dest);
1251 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
1254 GstStructure *other = (GstStructure *) data;
1255 const GValue *val2 = gst_structure_id_get_value (other, id);
1257 if (G_LIKELY (val2)) {
1258 if (!gst_value_can_intersect (val1, val2)) {
1261 gint eq = gst_value_compare (val1, val2);
1263 if (eq == GST_VALUE_UNORDERED) {
1264 /* we need to try interseting */
1265 GValue dest_value = { 0 };
1266 if (gst_value_intersect (&dest_value, val1, val2)) {
1267 g_value_unset (&dest_value);
1271 } else if (eq != GST_VALUE_EQUAL) {
1280 gst_caps_structure_can_intersect (const GstStructure * struct1,
1281 const GstStructure * struct2)
1283 g_assert (struct1 != NULL);
1284 g_assert (struct2 != NULL);
1286 if (G_UNLIKELY (struct1->name != struct2->name))
1289 /* tries to intersect if we have the field in both */
1290 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1291 gst_caps_structure_can_intersect_field, (gpointer) struct2)))
1298 * gst_caps_can_intersect:
1299 * @caps1: a #GstCaps to intersect
1300 * @caps2: a #GstCaps to intersect
1302 * Tries intersecting @caps1 and @caps2 and reports wheter the result would not
1305 * Returns: %TRUE if intersection would be not empty
1310 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1312 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1313 guint j, k, len1, len2;
1314 GstStructure *struct1;
1315 GstStructure *struct2;
1317 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1318 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1320 /* caps are exactly the same pointers */
1321 if (G_UNLIKELY (caps1 == caps2))
1324 /* empty caps on either side, return empty */
1325 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1328 /* one of the caps is any */
1329 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1332 /* run zigzag on top line then right line, this preserves the caps order
1333 * much better than a simple loop.
1335 * This algorithm zigzags over the caps structures as demonstrated in
1336 * the folowing matrix:
1344 * First we iterate over the caps1 structures (top line) intersecting
1345 * the structures diagonally down, then we iterate over the caps2
1348 len1 = caps1->structs->len;
1349 len2 = caps2->structs->len;
1350 for (i = 0; i < len1 + len2 - 1; i++) {
1351 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1352 j = MIN (i, len1 - 1);
1353 /* subset index stays 0 until i reaches superset->structs->len, then it
1354 * counts up from 1 to subset->structs->len - 1 */
1357 /* now run the diagonal line, end condition is the left or bottom
1360 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1361 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1363 if (gst_caps_structure_can_intersect (struct1, struct2)) {
1366 /* move down left */
1368 if (G_UNLIKELY (j == 0))
1369 break; /* so we don't roll back to G_MAXUINT */
1377 * gst_caps_intersect:
1378 * @caps1: a #GstCaps to intersect
1379 * @caps2: a #GstCaps to intersect
1381 * Creates a new #GstCaps that contains all the formats that are common
1382 * to both @caps1 and @caps2.
1384 * Returns: the new #GstCaps
1387 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1389 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1390 guint j, k, len1, len2;
1392 GstStructure *struct1;
1393 GstStructure *struct2;
1395 GstStructure *istruct;
1397 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1398 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1400 /* caps are exactly the same pointers, just copy one caps */
1401 if (G_UNLIKELY (caps1 == caps2))
1402 return gst_caps_copy (caps1);
1404 /* empty caps on either side, return empty */
1405 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1406 return gst_caps_new_empty ();
1408 /* one of the caps is any, just copy the other caps */
1409 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1410 return gst_caps_copy (caps2);
1411 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1412 return gst_caps_copy (caps1);
1414 dest = gst_caps_new_empty ();
1416 /* run zigzag on top line then right line, this preserves the caps order
1417 * much better than a simple loop.
1419 * This algorithm zigzags over the caps structures as demonstrated in
1420 * the folowing matrix:
1428 * First we iterate over the caps1 structures (top line) intersecting
1429 * the structures diagonally down, then we iterate over the caps2
1432 len1 = caps1->structs->len;
1433 len2 = caps2->structs->len;
1434 for (i = 0; i < len1 + len2 - 1; i++) {
1435 /* caps1 index goes from 0 to caps1->structs->len-1 */
1436 j = MIN (i, len1 - 1);
1437 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1438 * up from 1 to caps2->structs->len - 1 */
1441 /* now run the diagonal line, end condition is the left or bottom
1444 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1445 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1447 istruct = gst_caps_structure_intersect (struct1, struct2);
1449 gst_caps_append_structure (dest, istruct);
1450 /* move down left */
1452 if (G_UNLIKELY (j == 0))
1453 break; /* so we don't roll back to G_MAXUINT */
1460 /* subtract operation */
1464 const GstStructure *subtract_from;
1470 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1473 SubtractionEntry *e = user_data;
1474 GValue subtraction = { 0, };
1475 const GValue *other;
1476 GstStructure *structure;
1478 other = gst_structure_id_get_value (e->subtract_from, field_id);
1482 if (!gst_value_subtract (&subtraction, other, value))
1484 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1485 g_value_unset (&subtraction);
1488 structure = gst_structure_copy (e->subtract_from);
1489 gst_structure_id_set_value (structure, field_id, &subtraction);
1490 g_value_unset (&subtraction);
1491 e->put_into = g_slist_prepend (e->put_into, structure);
1497 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1498 const GstStructure * subtrahend)
1503 e.subtract_from = minuend;
1506 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1507 gst_caps_structure_subtract_field, &e);
1513 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1514 gst_structure_free (walk->data);
1516 g_slist_free (e.put_into);
1522 * gst_caps_subtract:
1523 * @minuend: #GstCaps to substract from
1524 * @subtrahend: #GstCaps to substract
1526 * Subtracts the @subtrahend from the @minuend.
1527 * <note>This function does not work reliably if optional properties for caps
1528 * are included on one caps and omitted on the other.</note>
1530 * Returns: the resulting caps
1533 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1538 GstCaps *dest = NULL, *src;
1540 g_return_val_if_fail (minuend != NULL, NULL);
1541 g_return_val_if_fail (subtrahend != NULL, NULL);
1543 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1544 return gst_caps_new_empty ();
1546 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1547 return gst_caps_copy (minuend);
1549 /* FIXME: Do we want this here or above?
1550 The reason we need this is that there is no definition about what
1551 ANY means for specific types, so it's not possible to reduce ANY partially
1552 You can only remove everything or nothing and that is done above.
1553 Note: there's a test that checks this behaviour. */
1554 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1555 sublen = subtrahend->structs->len;
1556 g_assert (sublen > 0);
1558 src = gst_caps_copy (minuend);
1559 for (i = 0; i < sublen; i++) {
1562 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1564 gst_caps_unref (src);
1567 dest = gst_caps_new_empty ();
1568 srclen = src->structs->len;
1569 for (j = 0; j < srclen; j++) {
1570 min = gst_caps_get_structure_unchecked (src, j);
1571 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1574 if (gst_caps_structure_subtract (&list, min, sub)) {
1577 for (walk = list; walk; walk = g_slist_next (walk)) {
1578 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1580 g_slist_free (list);
1582 gst_caps_append_structure (dest, gst_structure_copy (min));
1585 gst_caps_append_structure (dest, gst_structure_copy (min));
1588 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1589 gst_caps_unref (src);
1594 gst_caps_unref (src);
1595 gst_caps_do_simplify (dest);
1599 /* union operation */
1602 static GstStructure *
1603 gst_caps_structure_union (const GstStructure * struct1,
1604 const GstStructure * struct2)
1608 const GstStructureField *field1;
1609 const GstStructureField *field2;
1612 /* FIXME this doesn't actually work */
1614 if (struct1->name != struct2->name)
1617 dest = gst_structure_id_empty_new (struct1->name);
1619 for (i = 0; i < struct1->fields->len; i++) {
1620 GValue dest_value = { 0 };
1622 field1 = GST_STRUCTURE_FIELD (struct1, i);
1623 field2 = gst_structure_id_get_field (struct2, field1->name);
1625 if (field2 == NULL) {
1628 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1629 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1632 ret = gst_value_compare (&field1->value, &field2->value);
1643 * @caps1: a #GstCaps to union
1644 * @caps2: a #GstCaps to union
1646 * Creates a new #GstCaps that contains all the formats that are in
1647 * either @caps1 and @caps2.
1649 * Returns: the new #GstCaps
1652 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1657 /* NULL pointers are no correct GstCaps */
1658 g_return_val_if_fail (caps1 != NULL, NULL);
1659 g_return_val_if_fail (caps2 != NULL, NULL);
1661 if (CAPS_IS_EMPTY (caps1))
1662 return gst_caps_copy (caps2);
1664 if (CAPS_IS_EMPTY (caps2))
1665 return gst_caps_copy (caps1);
1667 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1668 return gst_caps_new_any ();
1670 dest1 = gst_caps_copy (caps1);
1671 dest2 = gst_caps_copy (caps2);
1672 gst_caps_append (dest1, dest2);
1674 gst_caps_do_simplify (dest1);
1678 /* normalize/simplify operations */
1680 typedef struct _NormalizeForeach
1683 GstStructure *structure;
1688 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1690 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1694 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1695 guint len = gst_value_list_get_size (value);
1696 for (i = 1; i < len; i++) {
1697 const GValue *v = gst_value_list_get_value (value, i);
1698 GstStructure *structure = gst_structure_copy (nf->structure);
1700 gst_structure_id_set_value (structure, field_id, v);
1701 gst_caps_append_structure (nf->caps, structure);
1704 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1705 gst_structure_id_set_value (nf->structure, field_id, &val);
1706 g_value_unset (&val);
1714 * gst_caps_normalize:
1715 * @caps: a #GstCaps to normalize
1717 * Creates a new #GstCaps that represents the same set of formats as
1718 * @caps, but contains no lists. Each list is expanded into separate
1721 * Returns: the new #GstCaps
1724 gst_caps_normalize (const GstCaps * caps)
1726 NormalizeForeach nf;
1730 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1732 newcaps = gst_caps_copy (caps);
1734 nlen = newcaps->structs->len;
1736 for (i = 0; i < nlen; i++) {
1737 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1739 while (!gst_structure_foreach (nf.structure,
1740 gst_caps_normalize_foreach, &nf));
1747 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1750 const GstStructure *struct1 = *((const GstStructure **) one);
1751 const GstStructure *struct2 = *((const GstStructure **) two);
1753 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1754 So what's the best way? */
1755 ret = strcmp (gst_structure_get_name (struct1),
1756 gst_structure_get_name (struct2));
1760 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1767 GstStructure *compare;
1772 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1775 UnionField *u = user_data;
1776 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1780 g_value_unset (&u->value);
1783 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1786 g_value_unset (&u->value);
1790 gst_value_union (&u->value, val, value);
1795 gst_caps_structure_simplify (GstStructure ** result,
1796 const GstStructure * simplify, GstStructure * compare)
1799 UnionField field = { 0, {0,}, NULL };
1801 /* try to subtract to get a real subset */
1802 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1803 switch (g_slist_length (list)) {
1808 *result = list->data;
1809 g_slist_free (list);
1815 for (walk = list; walk; walk = g_slist_next (walk)) {
1816 gst_structure_free (walk->data);
1818 g_slist_free (list);
1824 /* try to union both structs */
1825 field.compare = compare;
1826 if (gst_structure_foreach ((GstStructure *) simplify,
1827 gst_caps_structure_figure_out_union, &field)) {
1828 gboolean ret = FALSE;
1830 /* now we know all of simplify's fields are the same in compare
1831 * but at most one field: field.name */
1832 if (G_IS_VALUE (&field.value)) {
1833 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1834 gst_structure_id_set_value (compare, field.name, &field.value);
1838 g_value_unset (&field.value);
1839 } else if (gst_structure_n_fields (simplify) <=
1840 gst_structure_n_fields (compare)) {
1841 /* compare is just more specific, will be optimized away later */
1842 /* FIXME: do this here? */
1843 GST_LOG ("found a case that will be optimized later.");
1845 gchar *one = gst_structure_to_string (simplify);
1846 gchar *two = gst_structure_to_string (compare);
1849 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1861 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1862 GstStructure * new, gint i)
1864 gst_structure_set_parent_refcount (old, NULL);
1865 gst_structure_free (old);
1866 gst_structure_set_parent_refcount (new, &caps->refcount);
1867 g_ptr_array_index (caps->structs, i) = new;
1871 * gst_caps_do_simplify:
1872 * @caps: a #GstCaps to simplify
1874 * Modifies the given @caps inplace into a representation that represents the
1875 * same set of formats, but in a simpler form. Component structures that are
1876 * identical are merged. Component structures that have values that can be
1877 * merged are also merged.
1879 * Returns: TRUE, if the caps could be simplified
1882 gst_caps_do_simplify (GstCaps * caps)
1884 GstStructure *simplify, *compare, *result = NULL;
1886 gboolean changed = FALSE;
1888 g_return_val_if_fail (caps != NULL, FALSE);
1889 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1891 if (gst_caps_get_size (caps) < 2)
1894 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1896 start = caps->structs->len - 1;
1897 for (i = caps->structs->len - 1; i >= 0; i--) {
1898 simplify = gst_caps_get_structure_unchecked (caps, i);
1899 if (gst_structure_get_name_id (simplify) !=
1900 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1903 for (j = start; j >= 0; j--) {
1906 compare = gst_caps_get_structure_unchecked (caps, j);
1907 if (gst_structure_get_name_id (simplify) !=
1908 gst_structure_get_name_id (compare)) {
1911 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1913 gst_caps_switch_structures (caps, simplify, result, i);
1916 gst_caps_remove_structure (caps, i);
1928 /* gst_caps_do_simplify (caps); */
1934 #ifndef GST_DISABLE_LOADSAVE
1936 * gst_caps_save_thyself:
1937 * @caps: a #GstCaps structure
1938 * @parent: a XML parent node
1940 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1942 * Returns: a XML node pointer
1945 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1947 char *s = gst_caps_to_string (caps);
1949 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1955 * gst_caps_load_thyself:
1956 * @parent: a XML node
1958 * Creates a #GstCaps from its XML serialization.
1960 * Returns: a new #GstCaps structure
1963 gst_caps_load_thyself (xmlNodePtr parent)
1965 if (strcmp ("caps", (char *) parent->name) == 0) {
1966 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1977 * @caps: a pointer to #GstCaps
1978 * @newcaps: a #GstCaps to replace *caps
1980 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1981 * pointed to by @caps, if applicable, then modifies @caps to point to
1982 * @newcaps. An additional ref on @newcaps is taken.
1984 * This function does not take any locks so you might want to lock
1985 * the object owning @caps pointer.
1988 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1992 g_return_if_fail (caps != NULL);
1996 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1998 if (newcaps != oldcaps) {
2000 gst_caps_ref (newcaps);
2005 gst_caps_unref (oldcaps);
2010 * gst_caps_to_string:
2013 * Converts @caps to a string representation. This string representation
2014 * can be converted back to a #GstCaps by gst_caps_from_string().
2016 * For debugging purposes its easier to do something like this:
2018 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2020 * This prints the caps in human readble form.
2022 * Returns: a newly allocated string representing @caps.
2025 gst_caps_to_string (const GstCaps * caps)
2027 guint i, slen, clen;
2030 /* NOTE: This function is potentially called by the debug system,
2031 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2032 * should be careful to avoid recursion. This includes any functions
2033 * called by gst_caps_to_string. In particular, calls should
2034 * not use the GST_PTR_FORMAT extension. */
2037 return g_strdup ("NULL");
2039 if (CAPS_IS_ANY (caps)) {
2040 return g_strdup ("ANY");
2042 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2043 return g_strdup ("EMPTY");
2046 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2048 clen = caps->structs->len;
2049 for (i = 0; i < clen; i++) {
2051 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
2055 s = g_string_sized_new (slen);
2056 for (i = 0; i < clen; i++) {
2057 GstStructure *structure;
2060 /* ';' is now added by gst_structure_to_string */
2061 g_string_append_c (s, ' ');
2064 structure = gst_caps_get_structure_unchecked (caps, i);
2065 priv_gst_structure_append_to_gstring (structure, s);
2067 if (s->len && s->str[s->len - 1] == ';') {
2068 /* remove latest ';' */
2069 s->str[--s->len] = '\0';
2071 return g_string_free (s, FALSE);
2075 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2077 GstStructure *structure;
2080 if (strcmp ("ANY", string) == 0) {
2081 caps->flags = GST_CAPS_FLAGS_ANY;
2084 if (strcmp ("EMPTY", string) == 0) {
2088 structure = gst_structure_from_string (string, &s);
2089 if (structure == NULL) {
2092 gst_caps_append_structure (caps, structure);
2096 while (g_ascii_isspace (*s))
2101 structure = gst_structure_from_string (s, &s);
2102 if (structure == NULL) {
2105 gst_caps_append_structure (caps, structure);
2113 * gst_caps_from_string:
2114 * @string: a string to convert to #GstCaps
2116 * Converts @caps from a string representation.
2118 * Returns: a newly allocated #GstCaps
2121 gst_caps_from_string (const gchar * string)
2125 g_return_val_if_fail (string, FALSE);
2127 caps = gst_caps_new_empty ();
2128 if (gst_caps_from_string_inplace (caps, string)) {
2131 gst_caps_unref (caps);
2137 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2139 g_return_if_fail (G_IS_VALUE (src_value));
2140 g_return_if_fail (G_IS_VALUE (dest_value));
2141 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2142 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2143 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2145 dest_value->data[0].v_pointer =
2146 gst_caps_to_string (src_value->data[0].v_pointer);
2150 gst_caps_copy_conditional (GstCaps * src)
2153 return gst_caps_ref (src);