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 (g_atomic_int_get (&caps->refcount) == 1)
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);
515 static GstStructure *
516 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
518 /* don't use index_fast, gst_caps_do_simplify relies on the order */
519 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
521 gst_structure_set_parent_refcount (s, NULL);
526 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
529 GstStructure *struct1 = (GstStructure *) data;
530 const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
532 if (G_UNLIKELY (val1 == NULL))
534 if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
542 gst_caps_structure_is_subset_field (GQuark field_id, const GValue * value,
545 GstStructure *subtract_from = user_data;
546 GValue subtraction = { 0, };
549 if (!(other = gst_structure_id_get_value (subtract_from, field_id)))
550 /* field is missing in one set */
553 /* equal values are subset */
554 if (gst_value_compare (other, value) == GST_VALUE_EQUAL)
562 * -> 1 - [1,2] = empty
566 * -> [1,2] - [1,3] = empty
570 * -> {1,3} - {1,2} = 3
573 * First caps subtraction needs to return a non-empty set, second
574 * subtractions needs to give en empty set.
576 if (gst_value_subtract (&subtraction, other, value)) {
577 g_value_unset (&subtraction);
578 /* !empty result, swapping must be empty */
579 if (!gst_value_subtract (&subtraction, value, other))
582 g_value_unset (&subtraction);
588 gst_caps_structure_is_subset (const GstStructure * minuend,
589 const GstStructure * subtrahend)
591 if ((minuend->name != subtrahend->name) ||
592 (gst_structure_n_fields (minuend) !=
593 gst_structure_n_fields (subtrahend))) {
597 return gst_structure_foreach ((GstStructure *) subtrahend,
598 gst_caps_structure_is_subset_field, (gpointer) minuend);
603 * @caps1: the #GstCaps that will be appended to
604 * @caps2: the #GstCaps to append
606 * Appends the structures contained in @caps2 to @caps1. The structures in
607 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
608 * freed. If either caps is ANY, the resulting caps will be ANY.
611 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
613 GstStructure *structure;
616 g_return_if_fail (GST_IS_CAPS (caps1));
617 g_return_if_fail (GST_IS_CAPS (caps2));
618 g_return_if_fail (IS_WRITABLE (caps1));
619 g_return_if_fail (IS_WRITABLE (caps2));
624 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
625 /* FIXME: this leaks */
626 caps1->flags |= GST_CAPS_FLAGS_ANY;
627 for (i = caps2->structs->len - 1; i >= 0; i--) {
628 structure = gst_caps_remove_and_get_structure (caps2, i);
629 gst_structure_free (structure);
632 for (i = caps2->structs->len; i; i--) {
633 structure = gst_caps_remove_and_get_structure (caps2, 0);
634 gst_caps_append_structure (caps1, structure);
637 gst_caps_unref (caps2); /* guaranteed to free it */
642 * @caps1: the #GstCaps that will take the new entries
643 * @caps2: the #GstCaps to merge in
645 * Appends the structures contained in @caps2 to @caps1 if they are not yet
646 * expressed by @caps1. The structures in @caps2 are not copied -- they are
647 * transferred to @caps1, and then @caps2 is freed.
648 * If either caps is ANY, the resulting caps will be ANY.
653 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
655 GstStructure *structure;
658 g_return_if_fail (GST_IS_CAPS (caps1));
659 g_return_if_fail (GST_IS_CAPS (caps2));
660 g_return_if_fail (IS_WRITABLE (caps1));
661 g_return_if_fail (IS_WRITABLE (caps2));
666 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
667 for (i = caps2->structs->len - 1; i >= 0; i--) {
668 structure = gst_caps_remove_and_get_structure (caps2, i);
669 gst_structure_free (structure);
671 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
672 caps1->flags |= GST_CAPS_FLAGS_ANY;
673 for (i = caps1->structs->len - 1; i >= 0; i--) {
674 structure = gst_caps_remove_and_get_structure (caps1, i);
675 gst_structure_free (structure);
678 for (i = caps2->structs->len; i; i--) {
679 structure = gst_caps_remove_and_get_structure (caps2, 0);
680 gst_caps_merge_structure (caps1, structure);
683 GstCaps *com = gst_caps_intersect (caps1, caps2);
684 GstCaps *add = gst_caps_subtract (caps2, com);
686 GST_DEBUG ("common : %d", gst_caps_get_size (com));
687 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
688 gst_caps_append (caps1, add);
689 gst_caps_unref (com);
692 gst_caps_unref (caps2); /* guaranteed to free it */
696 * gst_caps_append_structure:
697 * @caps: the #GstCaps that will be appended to
698 * @structure: the #GstStructure to append
700 * Appends @structure to @caps. The structure is not copied; @caps
701 * becomes the owner of @structure.
704 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
706 g_return_if_fail (GST_IS_CAPS (caps));
707 g_return_if_fail (IS_WRITABLE (caps));
709 if (G_LIKELY (structure)) {
710 g_return_if_fail (structure->parent_refcount == NULL);
713 STRUCTURE_POISON (structure);
716 gst_structure_set_parent_refcount (structure, &caps->refcount);
717 g_ptr_array_add (caps->structs, structure);
722 * gst_caps_remove_structure:
723 * @caps: the #GstCaps to remove from
724 * @idx: Index of the structure to remove
726 * removes the stucture with the given index from the list of structures
727 * contained in @caps.
730 gst_caps_remove_structure (GstCaps * caps, guint idx)
732 GstStructure *structure;
734 g_return_if_fail (caps != NULL);
735 g_return_if_fail (idx <= gst_caps_get_size (caps));
736 g_return_if_fail (IS_WRITABLE (caps));
738 structure = gst_caps_remove_and_get_structure (caps, idx);
739 gst_structure_free (structure);
743 * gst_caps_merge_structure:
744 * @caps: the #GstCaps that will the the new structure
745 * @structure: the #GstStructure to merge
747 * Appends @structure to @caps if its not already expressed by @caps. The
748 * structure is not copied; @caps becomes the owner of @structure.
751 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
753 g_return_if_fail (GST_IS_CAPS (caps));
754 g_return_if_fail (IS_WRITABLE (caps));
756 if (G_LIKELY (structure)) {
757 GstStructure *structure1;
759 gboolean unique = TRUE;
761 g_return_if_fail (structure->parent_refcount == NULL);
764 STRUCTURE_POISON (structure);
767 /* check each structure */
768 for (i = caps->structs->len - 1; i >= 0; i--) {
769 structure1 = gst_caps_get_structure_unchecked (caps, i);
770 /* if structure is a subset of structure1, then skip it */
771 if (gst_caps_structure_is_subset (structure1, structure)) {
777 gst_structure_set_parent_refcount (structure, &caps->refcount);
778 g_ptr_array_add (caps->structs, structure);
780 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 #ifndef G_VALUE_COLLECT_INIT
944 g_value_init (&value, type);
945 G_VALUE_COLLECT (&value, varargs, 0, &err);
947 G_VALUE_COLLECT_INIT (&value, type, 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);
1177 const GstStructure *intersect;
1182 gst_caps_structure_intersect_field1 (GQuark id, const GValue * val1,
1185 IntersectData *idata = (IntersectData *) data;
1186 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1188 if (G_UNLIKELY (val2 == NULL)) {
1189 gst_structure_id_set_value (idata->dest, id, val1);
1191 GValue dest_value = { 0 };
1192 if (gst_value_intersect (&dest_value, val1, val2)) {
1193 gst_structure_id_set_value (idata->dest, id, &dest_value);
1194 g_value_unset (&dest_value);
1203 gst_caps_structure_intersect_field2 (GQuark id, const GValue * val1,
1206 IntersectData *idata = (IntersectData *) data;
1207 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1209 if (G_UNLIKELY (val2 == NULL)) {
1210 gst_structure_id_set_value (idata->dest, id, val1);
1215 static GstStructure *
1216 gst_caps_structure_intersect (const GstStructure * struct1,
1217 const GstStructure * struct2)
1221 g_assert (struct1 != NULL);
1222 g_assert (struct2 != NULL);
1224 if (G_UNLIKELY (struct1->name != struct2->name))
1227 /* copy fields from struct1 which we have not in struct2 to target
1228 * intersect if we have the field in both */
1229 data.dest = gst_structure_id_empty_new (struct1->name);
1230 data.intersect = struct2;
1231 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1232 gst_caps_structure_intersect_field1, &data)))
1235 /* copy fields from struct2 which we have not in struct1 to target */
1236 data.intersect = struct1;
1237 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
1238 gst_caps_structure_intersect_field2, &data)))
1244 gst_structure_free (data.dest);
1249 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
1252 GstStructure *other = (GstStructure *) data;
1253 const GValue *val2 = gst_structure_id_get_value (other, id);
1255 if (G_LIKELY (val2)) {
1256 if (!gst_value_can_intersect (val1, val2)) {
1259 gint eq = gst_value_compare (val1, val2);
1261 if (eq == GST_VALUE_UNORDERED) {
1262 /* we need to try interseting */
1263 GValue dest_value = { 0 };
1264 if (gst_value_intersect (&dest_value, val1, val2)) {
1265 g_value_unset (&dest_value);
1269 } else if (eq != GST_VALUE_EQUAL) {
1278 gst_caps_structure_can_intersect (const GstStructure * struct1,
1279 const GstStructure * struct2)
1281 g_assert (struct1 != NULL);
1282 g_assert (struct2 != NULL);
1284 if (G_UNLIKELY (struct1->name != struct2->name))
1287 /* tries to intersect if we have the field in both */
1288 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1289 gst_caps_structure_can_intersect_field, (gpointer) struct2)))
1296 * gst_caps_can_intersect:
1297 * @caps1: a #GstCaps to intersect
1298 * @caps2: a #GstCaps to intersect
1300 * Tries intersecting @caps1 and @caps2 and reports wheter the result would not
1303 * Returns: %TRUE if intersection would be not empty
1308 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1310 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1311 guint j, k, len1, len2;
1312 GstStructure *struct1;
1313 GstStructure *struct2;
1315 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1316 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1318 /* caps are exactly the same pointers */
1319 if (G_UNLIKELY (caps1 == caps2))
1322 /* empty caps on either side, return empty */
1323 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1326 /* one of the caps is any */
1327 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1330 /* run zigzag on top line then right line, this preserves the caps order
1331 * much better than a simple loop.
1333 * This algorithm zigzags over the caps structures as demonstrated in
1334 * the folowing matrix:
1342 * First we iterate over the caps1 structures (top line) intersecting
1343 * the structures diagonally down, then we iterate over the caps2
1346 len1 = caps1->structs->len;
1347 len2 = caps2->structs->len;
1348 for (i = 0; i < len1 + len2 - 1; i++) {
1349 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1350 j = MIN (i, len1 - 1);
1351 /* subset index stays 0 until i reaches superset->structs->len, then it
1352 * counts up from 1 to subset->structs->len - 1 */
1355 /* now run the diagonal line, end condition is the left or bottom
1358 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1359 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1361 if (gst_caps_structure_can_intersect (struct1, struct2)) {
1364 /* move down left */
1366 if (G_UNLIKELY (j == 0))
1367 break; /* so we don't roll back to G_MAXUINT */
1375 static GstStructure *
1376 gst_caps_structure_union (const GstStructure * struct1,
1377 const GstStructure * struct2)
1381 const GstStructureField *field1;
1382 const GstStructureField *field2;
1385 /* FIXME this doesn't actually work */
1387 if (struct1->name != struct2->name)
1390 dest = gst_structure_id_empty_new (struct1->name);
1392 for (i = 0; i < struct1->fields->len; i++) {
1393 GValue dest_value = { 0 };
1395 field1 = GST_STRUCTURE_FIELD (struct1, i);
1396 field2 = gst_structure_id_get_field (struct2, field1->name);
1398 if (field2 == NULL) {
1401 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1402 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1405 ret = gst_value_compare (&field1->value, &field2->value);
1417 * gst_caps_intersect:
1418 * @caps1: a #GstCaps to intersect
1419 * @caps2: a #GstCaps to intersect
1421 * Creates a new #GstCaps that contains all the formats that are common
1422 * to both @caps1 and @caps2.
1424 * Returns: the new #GstCaps
1427 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1429 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1430 guint j, k, len1, len2;
1432 GstStructure *struct1;
1433 GstStructure *struct2;
1435 GstStructure *istruct;
1437 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1438 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1440 /* caps are exactly the same pointers, just copy one caps */
1441 if (G_UNLIKELY (caps1 == caps2))
1442 return gst_caps_copy (caps1);
1444 /* empty caps on either side, return empty */
1445 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1446 return gst_caps_new_empty ();
1448 /* one of the caps is any, just copy the other caps */
1449 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1450 return gst_caps_copy (caps2);
1451 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1452 return gst_caps_copy (caps1);
1454 dest = gst_caps_new_empty ();
1456 /* run zigzag on top line then right line, this preserves the caps order
1457 * much better than a simple loop.
1459 * This algorithm zigzags over the caps structures as demonstrated in
1460 * the folowing matrix:
1468 * First we iterate over the caps1 structures (top line) intersecting
1469 * the structures diagonally down, then we iterate over the caps2
1472 len1 = caps1->structs->len;
1473 len2 = caps2->structs->len;
1474 for (i = 0; i < len1 + len2 - 1; i++) {
1475 /* caps1 index goes from 0 to caps1->structs->len-1 */
1476 j = MIN (i, len1 - 1);
1477 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1478 * up from 1 to caps2->structs->len - 1 */
1481 /* now run the diagonal line, end condition is the left or bottom
1484 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1485 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1487 istruct = gst_caps_structure_intersect (struct1, struct2);
1489 gst_caps_append_structure (dest, istruct);
1490 /* move down left */
1492 if (G_UNLIKELY (j == 0))
1493 break; /* so we don't roll back to G_MAXUINT */
1502 const GstStructure *subtract_from;
1509 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1512 SubtractionEntry *e = user_data;
1513 GValue subtraction = { 0, };
1514 const GValue *other;
1515 GstStructure *structure;
1517 other = gst_structure_id_get_value (e->subtract_from, field_id);
1521 if (!gst_value_subtract (&subtraction, other, value))
1523 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1524 g_value_unset (&subtraction);
1527 structure = gst_structure_copy (e->subtract_from);
1528 gst_structure_id_set_value (structure, field_id, &subtraction);
1529 g_value_unset (&subtraction);
1530 e->put_into = g_slist_prepend (e->put_into, structure);
1536 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1537 const GstStructure * subtrahend)
1542 e.subtract_from = minuend;
1545 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1546 gst_caps_structure_subtract_field, &e);
1552 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1553 gst_structure_free (walk->data);
1555 g_slist_free (e.put_into);
1561 * gst_caps_subtract:
1562 * @minuend: #GstCaps to substract from
1563 * @subtrahend: #GstCaps to substract
1565 * Subtracts the @subtrahend from the @minuend.
1566 * <note>This function does not work reliably if optional properties for caps
1567 * are included on one caps and omitted on the other.</note>
1569 * Returns: the resulting caps
1572 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1577 GstCaps *dest = NULL, *src;
1579 g_return_val_if_fail (minuend != NULL, NULL);
1580 g_return_val_if_fail (subtrahend != NULL, NULL);
1582 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1583 return gst_caps_new_empty ();
1585 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1586 return gst_caps_copy (minuend);
1588 /* FIXME: Do we want this here or above?
1589 The reason we need this is that there is no definition about what
1590 ANY means for specific types, so it's not possible to reduce ANY partially
1591 You can only remove everything or nothing and that is done above.
1592 Note: there's a test that checks this behaviour. */
1593 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1594 sublen = subtrahend->structs->len;
1595 g_assert (sublen > 0);
1597 src = gst_caps_copy (minuend);
1598 for (i = 0; i < sublen; i++) {
1601 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1603 gst_caps_unref (src);
1606 dest = gst_caps_new_empty ();
1607 srclen = src->structs->len;
1608 for (j = 0; j < srclen; j++) {
1609 min = gst_caps_get_structure_unchecked (src, j);
1610 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1613 if (gst_caps_structure_subtract (&list, min, sub)) {
1616 for (walk = list; walk; walk = g_slist_next (walk)) {
1617 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1619 g_slist_free (list);
1621 gst_caps_append_structure (dest, gst_structure_copy (min));
1624 gst_caps_append_structure (dest, gst_structure_copy (min));
1627 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1628 gst_caps_unref (src);
1633 gst_caps_unref (src);
1634 gst_caps_do_simplify (dest);
1640 * @caps1: a #GstCaps to union
1641 * @caps2: a #GstCaps to union
1643 * Creates a new #GstCaps that contains all the formats that are in
1644 * either @caps1 and @caps2.
1646 * Returns: the new #GstCaps
1649 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1654 /* NULL pointers are no correct GstCaps */
1655 g_return_val_if_fail (caps1 != NULL, NULL);
1656 g_return_val_if_fail (caps2 != NULL, NULL);
1658 if (CAPS_IS_EMPTY (caps1))
1659 return gst_caps_copy (caps2);
1661 if (CAPS_IS_EMPTY (caps2))
1662 return gst_caps_copy (caps1);
1664 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1665 return gst_caps_new_any ();
1667 dest1 = gst_caps_copy (caps1);
1668 dest2 = gst_caps_copy (caps2);
1669 gst_caps_append (dest1, dest2);
1671 gst_caps_do_simplify (dest1);
1675 typedef struct _NormalizeForeach
1678 GstStructure *structure;
1683 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1685 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1689 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1690 guint len = gst_value_list_get_size (value);
1691 for (i = 1; i < len; i++) {
1692 const GValue *v = gst_value_list_get_value (value, i);
1693 GstStructure *structure = gst_structure_copy (nf->structure);
1695 gst_structure_id_set_value (structure, field_id, v);
1696 gst_caps_append_structure (nf->caps, structure);
1699 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1700 gst_structure_id_set_value (nf->structure, field_id, &val);
1701 g_value_unset (&val);
1709 * gst_caps_normalize:
1710 * @caps: a #GstCaps to normalize
1712 * Creates a new #GstCaps that represents the same set of formats as
1713 * @caps, but contains no lists. Each list is expanded into separate
1716 * Returns: the new #GstCaps
1719 gst_caps_normalize (const GstCaps * caps)
1721 NormalizeForeach nf;
1725 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1727 newcaps = gst_caps_copy (caps);
1729 nlen = newcaps->structs->len;
1731 for (i = 0; i < nlen; i++) {
1732 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1734 while (!gst_structure_foreach (nf.structure,
1735 gst_caps_normalize_foreach, &nf));
1742 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1745 const GstStructure *struct1 = *((const GstStructure **) one);
1746 const GstStructure *struct2 = *((const GstStructure **) two);
1748 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1749 So what's the best way? */
1750 ret = strcmp (gst_structure_get_name (struct1),
1751 gst_structure_get_name (struct2));
1755 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1762 GstStructure *compare;
1767 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1770 UnionField *u = user_data;
1771 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1775 g_value_unset (&u->value);
1778 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1781 g_value_unset (&u->value);
1785 gst_value_union (&u->value, val, value);
1790 gst_caps_structure_simplify (GstStructure ** result,
1791 const GstStructure * simplify, GstStructure * compare)
1794 UnionField field = { 0, {0,}, NULL };
1796 /* try to subtract to get a real subset */
1797 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1798 switch (g_slist_length (list)) {
1803 *result = list->data;
1804 g_slist_free (list);
1810 for (walk = list; walk; walk = g_slist_next (walk)) {
1811 gst_structure_free (walk->data);
1813 g_slist_free (list);
1819 /* try to union both structs */
1820 field.compare = compare;
1821 if (gst_structure_foreach ((GstStructure *) simplify,
1822 gst_caps_structure_figure_out_union, &field)) {
1823 gboolean ret = FALSE;
1825 /* now we know all of simplify's fields are the same in compare
1826 * but at most one field: field.name */
1827 if (G_IS_VALUE (&field.value)) {
1828 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1829 gst_structure_id_set_value (compare, field.name, &field.value);
1833 g_value_unset (&field.value);
1834 } else if (gst_structure_n_fields (simplify) <=
1835 gst_structure_n_fields (compare)) {
1836 /* compare is just more specific, will be optimized away later */
1837 /* FIXME: do this here? */
1838 GST_LOG ("found a case that will be optimized later.");
1840 gchar *one = gst_structure_to_string (simplify);
1841 gchar *two = gst_structure_to_string (compare);
1844 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1856 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1857 GstStructure * new, gint i)
1859 gst_structure_set_parent_refcount (old, NULL);
1860 gst_structure_free (old);
1861 gst_structure_set_parent_refcount (new, &caps->refcount);
1862 g_ptr_array_index (caps->structs, i) = new;
1866 * gst_caps_do_simplify:
1867 * @caps: a #GstCaps to simplify
1869 * Modifies the given @caps inplace into a representation that represents the
1870 * same set of formats, but in a simpler form. Component structures that are
1871 * identical are merged. Component structures that have values that can be
1872 * merged are also merged.
1874 * Returns: TRUE, if the caps could be simplified
1877 gst_caps_do_simplify (GstCaps * caps)
1879 GstStructure *simplify, *compare, *result = NULL;
1881 gboolean changed = FALSE;
1883 g_return_val_if_fail (caps != NULL, FALSE);
1884 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1886 if (gst_caps_get_size (caps) < 2)
1889 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1891 start = caps->structs->len - 1;
1892 for (i = caps->structs->len - 1; i >= 0; i--) {
1893 simplify = gst_caps_get_structure_unchecked (caps, i);
1894 if (gst_structure_get_name_id (simplify) !=
1895 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1898 for (j = start; j >= 0; j--) {
1901 compare = gst_caps_get_structure_unchecked (caps, j);
1902 if (gst_structure_get_name_id (simplify) !=
1903 gst_structure_get_name_id (compare)) {
1906 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1908 gst_caps_switch_structures (caps, simplify, result, i);
1911 gst_caps_remove_structure (caps, i);
1923 /* gst_caps_do_simplify (caps); */
1927 #ifndef GST_DISABLE_LOADSAVE
1929 * gst_caps_save_thyself:
1930 * @caps: a #GstCaps structure
1931 * @parent: a XML parent node
1933 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1935 * Returns: a XML node pointer
1938 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1940 char *s = gst_caps_to_string (caps);
1942 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1948 * gst_caps_load_thyself:
1949 * @parent: a XML node
1951 * Creates a #GstCaps from its XML serialization.
1953 * Returns: a new #GstCaps structure
1956 gst_caps_load_thyself (xmlNodePtr parent)
1958 if (strcmp ("caps", (char *) parent->name) == 0) {
1959 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1970 * @caps: a pointer to #GstCaps
1971 * @newcaps: a #GstCaps to replace *caps
1973 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1974 * pointed to by @caps, if applicable, then modifies @caps to point to
1975 * @newcaps. An additional ref on @newcaps is taken.
1977 * This function does not take any locks so you might want to lock
1978 * the object owning @caps pointer.
1981 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1985 g_return_if_fail (caps != NULL);
1989 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1991 if (newcaps != oldcaps) {
1993 gst_caps_ref (newcaps);
1998 gst_caps_unref (oldcaps);
2003 * gst_caps_to_string:
2006 * Converts @caps to a string representation. This string representation
2007 * can be converted back to a #GstCaps by gst_caps_from_string().
2009 * For debugging purposes its easier to do something like this:
2011 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2013 * This prints the caps in human readble form.
2015 * Returns: a newly allocated string representing @caps.
2018 gst_caps_to_string (const GstCaps * caps)
2020 guint i, slen, clen;
2023 /* NOTE: This function is potentially called by the debug system,
2024 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2025 * should be careful to avoid recursion. This includes any functions
2026 * called by gst_caps_to_string. In particular, calls should
2027 * not use the GST_PTR_FORMAT extension. */
2030 return g_strdup ("NULL");
2032 if (CAPS_IS_ANY (caps)) {
2033 return g_strdup ("ANY");
2035 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2036 return g_strdup ("EMPTY");
2039 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2041 clen = caps->structs->len;
2042 for (i = 0; i < clen; i++) {
2044 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
2048 s = g_string_sized_new (slen);
2049 for (i = 0; i < clen; i++) {
2050 GstStructure *structure;
2053 /* ';' is now added by gst_structure_to_string */
2054 g_string_append_c (s, ' ');
2057 structure = gst_caps_get_structure_unchecked (caps, i);
2058 priv_gst_structure_append_to_gstring (structure, s);
2060 if (s->len && s->str[s->len - 1] == ';') {
2061 /* remove latest ';' */
2062 s->str[--s->len] = '\0';
2064 return g_string_free (s, FALSE);
2068 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2070 GstStructure *structure;
2073 g_return_val_if_fail (string, FALSE);
2074 if (strcmp ("ANY", string) == 0) {
2075 caps->flags = GST_CAPS_FLAGS_ANY;
2078 if (strcmp ("EMPTY", string) == 0) {
2082 structure = gst_structure_from_string (string, &s);
2083 if (structure == NULL) {
2086 gst_caps_append_structure (caps, structure);
2090 while (g_ascii_isspace (*s))
2095 structure = gst_structure_from_string (s, &s);
2096 if (structure == NULL) {
2099 gst_caps_append_structure (caps, structure);
2107 * gst_caps_from_string:
2108 * @string: a string to convert to #GstCaps
2110 * Converts @caps from a string representation.
2112 * Returns: a newly allocated #GstCaps
2115 gst_caps_from_string (const gchar * string)
2119 caps = gst_caps_new_empty ();
2120 if (gst_caps_from_string_inplace (caps, string)) {
2123 gst_caps_unref (caps);
2129 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2131 g_return_if_fail (G_IS_VALUE (src_value));
2132 g_return_if_fail (G_IS_VALUE (dest_value));
2133 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2134 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2135 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2137 dest_value->data[0].v_pointer =
2138 gst_caps_to_string (src_value->data[0].v_pointer);
2142 gst_caps_copy_conditional (GstCaps * src)
2145 return gst_caps_ref (src);