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;
944 g_value_init (&value, type);
945 G_VALUE_COLLECT (&value, varargs, 0, &err);
946 if (G_UNLIKELY (err)) {
947 g_critical ("%s", err);
951 gst_caps_set_value (caps, field, &value);
953 g_value_unset (&value);
955 field = va_arg (varargs, const gchar *);
960 * gst_caps_set_simple:
961 * @caps: the #GstCaps to set
962 * @field: first field to set
963 * @...: additional parameters
965 * Sets fields in a #GstCaps. The arguments must be passed in the same
966 * manner as gst_structure_set(), and be NULL-terminated.
967 * <note>Prior to GStreamer version 0.10.26, this function failed when
968 * @caps was not simple. If your code needs to work with those versions
969 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
970 * is %TRUE for @caps.</note>
973 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
977 g_return_if_fail (GST_IS_CAPS (caps));
978 g_return_if_fail (IS_WRITABLE (caps));
980 va_start (var_args, field);
981 gst_caps_set_simple_valist (caps, field, var_args);
989 * @caps: the #GstCaps to test
991 * Determines if @caps represents any media format.
993 * Returns: TRUE if @caps represents any format.
996 gst_caps_is_any (const GstCaps * caps)
998 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1000 return (caps->flags & GST_CAPS_FLAGS_ANY);
1004 * gst_caps_is_empty:
1005 * @caps: the #GstCaps to test
1007 * Determines if @caps represents no media formats.
1009 * Returns: TRUE if @caps represents no formats.
1012 gst_caps_is_empty (const GstCaps * caps)
1014 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1016 if (caps->flags & GST_CAPS_FLAGS_ANY)
1019 return (caps->structs == NULL) || (caps->structs->len == 0);
1023 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
1026 return gst_value_is_fixed (value);
1030 * gst_caps_is_fixed:
1031 * @caps: the #GstCaps to test
1033 * Fixed #GstCaps describe exactly one format, that is, they have exactly
1034 * one structure, and each field in the structure describes a fixed type.
1035 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
1037 * Returns: TRUE if @caps is fixed
1040 gst_caps_is_fixed (const GstCaps * caps)
1042 GstStructure *structure;
1044 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1046 if (caps->structs->len != 1)
1049 structure = gst_caps_get_structure_unchecked (caps, 0);
1051 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
1055 * gst_caps_is_equal_fixed:
1056 * @caps1: the #GstCaps to test
1057 * @caps2: the #GstCaps to test
1059 * Tests if two #GstCaps are equal. This function only works on fixed
1062 * Returns: TRUE if the arguments represent the same format
1065 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
1067 GstStructure *struct1, *struct2;
1069 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1070 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1072 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1073 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1075 if (struct1->name != struct2->name) {
1078 if (struct1->fields->len != struct2->fields->len) {
1082 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
1087 * gst_caps_is_always_compatible:
1088 * @caps1: the #GstCaps to test
1089 * @caps2: the #GstCaps to test
1091 * A given #GstCaps structure is always compatible with another if
1092 * every media format that is in the first is also contained in the
1093 * second. That is, @caps1 is a subset of @caps2.
1095 * Returns: TRUE if @caps1 is a subset of @caps2.
1098 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1100 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1101 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1103 return gst_caps_is_subset (caps1, caps2);
1107 * gst_caps_is_subset:
1108 * @subset: a #GstCaps
1109 * @superset: a potentially greater #GstCaps
1111 * Checks if all caps represented by @subset are also represented by @superset.
1112 * <note>This function does not work reliably if optional properties for caps
1113 * are included on one caps and omitted on the other.</note>
1115 * Returns: %TRUE if @subset is a subset of @superset
1118 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1123 g_return_val_if_fail (subset != NULL, FALSE);
1124 g_return_val_if_fail (superset != NULL, FALSE);
1126 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1128 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1131 caps = gst_caps_subtract (subset, superset);
1132 ret = CAPS_IS_EMPTY_SIMPLE (caps);
1133 gst_caps_unref (caps);
1138 * gst_caps_is_equal:
1139 * @caps1: a #GstCaps
1140 * @caps2: another #GstCaps
1142 * Checks if the given caps represent the same set of caps.
1143 * <note>This function does not work reliably if optional properties for caps
1144 * are included on one caps and omitted on the other.</note>
1146 * This function deals correctly with passing NULL for any of the caps.
1148 * Returns: TRUE if both caps are equal.
1151 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1153 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1154 * So there should be an assertion that caps1 and caps2 != NULL */
1156 /* NULL <-> NULL is allowed here */
1157 if (G_UNLIKELY (caps1 == caps2))
1160 /* one of them NULL => they are different (can't be both NULL because
1161 * we checked that above) */
1162 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1165 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1166 return gst_caps_is_equal_fixed (caps1, caps2);
1168 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1174 const GstStructure *intersect;
1179 gst_caps_structure_intersect_field1 (GQuark id, const GValue * val1,
1182 IntersectData *idata = (IntersectData *) data;
1183 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1185 if (G_UNLIKELY (val2 == NULL)) {
1186 gst_structure_id_set_value (idata->dest, id, val1);
1188 GValue dest_value = { 0 };
1189 if (gst_value_intersect (&dest_value, val1, val2)) {
1190 gst_structure_id_set_value (idata->dest, id, &dest_value);
1191 g_value_unset (&dest_value);
1200 gst_caps_structure_intersect_field2 (GQuark id, const GValue * val1,
1203 IntersectData *idata = (IntersectData *) data;
1204 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1206 if (G_UNLIKELY (val2 == NULL)) {
1207 gst_structure_id_set_value (idata->dest, id, val1);
1212 static GstStructure *
1213 gst_caps_structure_intersect (const GstStructure * struct1,
1214 const GstStructure * struct2)
1218 g_return_val_if_fail (struct1 != NULL, NULL);
1219 g_return_val_if_fail (struct2 != NULL, NULL);
1221 if (G_UNLIKELY (struct1->name != struct2->name))
1224 /* copy fields from struct1 which we have not in struct2 to target
1225 * intersect if we have the field in both */
1226 data.dest = gst_structure_id_empty_new (struct1->name);
1227 data.intersect = struct2;
1228 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1229 gst_caps_structure_intersect_field1, &data)))
1232 /* copy fields from struct2 which we have not in struct1 to target */
1233 data.intersect = struct1;
1234 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
1235 gst_caps_structure_intersect_field2, &data)))
1241 gst_structure_free (data.dest);
1246 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
1249 GstStructure *other = (GstStructure *) data;
1250 const GValue *val2 = gst_structure_id_get_value (other, id);
1252 if (G_LIKELY (val2)) {
1253 if (!gst_value_can_intersect (val1, val2)) {
1256 gint eq = gst_value_compare (val1, val2);
1258 if (eq == GST_VALUE_UNORDERED) {
1259 /* we need to try interseting */
1260 GValue dest_value = { 0 };
1261 if (gst_value_intersect (&dest_value, val1, val2)) {
1262 g_value_unset (&dest_value);
1266 } else if (eq != GST_VALUE_EQUAL) {
1275 gst_caps_structure_can_intersect (const GstStructure * struct1,
1276 const GstStructure * struct2)
1278 g_return_val_if_fail (struct1 != NULL, FALSE);
1279 g_return_val_if_fail (struct2 != NULL, FALSE);
1281 if (G_UNLIKELY (struct1->name != struct2->name))
1284 /* tries to intersect if we have the field in both */
1285 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1286 gst_caps_structure_can_intersect_field, (gpointer) struct2)))
1293 * gst_caps_can_intersect:
1294 * @caps1: a #GstCaps to intersect
1295 * @caps2: a #GstCaps to intersect
1297 * Tries intersecting @caps1 and @caps2 and reports wheter the result would not
1300 * Returns: %TRUE if intersection would be not empty
1305 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1307 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1308 guint j, k, len1, len2;
1309 GstStructure *struct1;
1310 GstStructure *struct2;
1312 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1313 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1315 /* caps are exactly the same pointers */
1316 if (G_UNLIKELY (caps1 == caps2))
1319 /* empty caps on either side, return empty */
1320 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1323 /* one of the caps is any */
1324 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1327 /* run zigzag on top line then right line, this preserves the caps order
1328 * much better than a simple loop.
1330 * This algorithm zigzags over the caps structures as demonstrated in
1331 * the folowing matrix:
1339 * First we iterate over the caps1 structures (top line) intersecting
1340 * the structures diagonally down, then we iterate over the caps2
1343 len1 = caps1->structs->len;
1344 len2 = caps2->structs->len;
1345 for (i = 0; i < len1 + len2 - 1; i++) {
1346 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1347 j = MIN (i, len1 - 1);
1348 /* subset index stays 0 until i reaches superset->structs->len, then it
1349 * counts up from 1 to subset->structs->len - 1 */
1352 /* now run the diagonal line, end condition is the left or bottom
1355 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1356 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1358 if (gst_caps_structure_can_intersect (struct1, struct2)) {
1361 /* move down left */
1363 if (G_UNLIKELY (j == 0))
1364 break; /* so we don't roll back to G_MAXUINT */
1372 static GstStructure *
1373 gst_caps_structure_union (const GstStructure * struct1,
1374 const GstStructure * struct2)
1378 const GstStructureField *field1;
1379 const GstStructureField *field2;
1382 /* FIXME this doesn't actually work */
1384 if (struct1->name != struct2->name)
1387 dest = gst_structure_id_empty_new (struct1->name);
1389 for (i = 0; i < struct1->fields->len; i++) {
1390 GValue dest_value = { 0 };
1392 field1 = GST_STRUCTURE_FIELD (struct1, i);
1393 field2 = gst_structure_id_get_field (struct2, field1->name);
1395 if (field2 == NULL) {
1398 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1399 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1402 ret = gst_value_compare (&field1->value, &field2->value);
1414 * gst_caps_intersect:
1415 * @caps1: a #GstCaps to intersect
1416 * @caps2: a #GstCaps to intersect
1418 * Creates a new #GstCaps that contains all the formats that are common
1419 * to both @caps1 and @caps2.
1421 * Returns: the new #GstCaps
1424 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1426 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1427 guint j, k, len1, len2;
1429 GstStructure *struct1;
1430 GstStructure *struct2;
1432 GstStructure *istruct;
1434 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1435 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1437 /* caps are exactly the same pointers, just copy one caps */
1438 if (G_UNLIKELY (caps1 == caps2))
1439 return gst_caps_copy (caps1);
1441 /* empty caps on either side, return empty */
1442 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1443 return gst_caps_new_empty ();
1445 /* one of the caps is any, just copy the other caps */
1446 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1447 return gst_caps_copy (caps2);
1448 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1449 return gst_caps_copy (caps1);
1451 dest = gst_caps_new_empty ();
1453 /* run zigzag on top line then right line, this preserves the caps order
1454 * much better than a simple loop.
1456 * This algorithm zigzags over the caps structures as demonstrated in
1457 * the folowing matrix:
1465 * First we iterate over the caps1 structures (top line) intersecting
1466 * the structures diagonally down, then we iterate over the caps2
1469 len1 = caps1->structs->len;
1470 len2 = caps2->structs->len;
1471 for (i = 0; i < len1 + len2 - 1; i++) {
1472 /* caps1 index goes from 0 to caps1->structs->len-1 */
1473 j = MIN (i, len1 - 1);
1474 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1475 * up from 1 to caps2->structs->len - 1 */
1478 /* now run the diagonal line, end condition is the left or bottom
1481 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1482 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1484 istruct = gst_caps_structure_intersect (struct1, struct2);
1486 gst_caps_append_structure (dest, istruct);
1487 /* move down left */
1489 if (G_UNLIKELY (j == 0))
1490 break; /* so we don't roll back to G_MAXUINT */
1499 const GstStructure *subtract_from;
1506 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1509 SubtractionEntry *e = user_data;
1510 GValue subtraction = { 0, };
1511 const GValue *other;
1512 GstStructure *structure;
1514 other = gst_structure_id_get_value (e->subtract_from, field_id);
1518 if (!gst_value_subtract (&subtraction, other, value))
1520 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1521 g_value_unset (&subtraction);
1524 structure = gst_structure_copy (e->subtract_from);
1525 gst_structure_id_set_value (structure, field_id, &subtraction);
1526 g_value_unset (&subtraction);
1527 e->put_into = g_slist_prepend (e->put_into, structure);
1533 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1534 const GstStructure * subtrahend)
1539 e.subtract_from = minuend;
1542 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1543 gst_caps_structure_subtract_field, &e);
1549 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1550 gst_structure_free (walk->data);
1552 g_slist_free (e.put_into);
1558 * gst_caps_subtract:
1559 * @minuend: #GstCaps to substract from
1560 * @subtrahend: #GstCaps to substract
1562 * Subtracts the @subtrahend from the @minuend.
1563 * <note>This function does not work reliably if optional properties for caps
1564 * are included on one caps and omitted on the other.</note>
1566 * Returns: the resulting caps
1569 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1574 GstCaps *dest = NULL, *src;
1576 g_return_val_if_fail (minuend != NULL, NULL);
1577 g_return_val_if_fail (subtrahend != NULL, NULL);
1579 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1580 return gst_caps_new_empty ();
1582 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1583 return gst_caps_copy (minuend);
1585 /* FIXME: Do we want this here or above?
1586 The reason we need this is that there is no definition about what
1587 ANY means for specific types, so it's not possible to reduce ANY partially
1588 You can only remove everything or nothing and that is done above.
1589 Note: there's a test that checks this behaviour. */
1590 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1591 sublen = subtrahend->structs->len;
1592 g_assert (sublen > 0);
1594 src = gst_caps_copy (minuend);
1595 for (i = 0; i < sublen; i++) {
1598 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1600 gst_caps_unref (src);
1603 dest = gst_caps_new_empty ();
1604 srclen = src->structs->len;
1605 for (j = 0; j < srclen; j++) {
1606 min = gst_caps_get_structure_unchecked (src, j);
1607 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1610 if (gst_caps_structure_subtract (&list, min, sub)) {
1613 for (walk = list; walk; walk = g_slist_next (walk)) {
1614 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1616 g_slist_free (list);
1618 gst_caps_append_structure (dest, gst_structure_copy (min));
1621 gst_caps_append_structure (dest, gst_structure_copy (min));
1624 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1625 gst_caps_unref (src);
1630 gst_caps_unref (src);
1631 gst_caps_do_simplify (dest);
1637 * @caps1: a #GstCaps to union
1638 * @caps2: a #GstCaps to union
1640 * Creates a new #GstCaps that contains all the formats that are in
1641 * either @caps1 and @caps2.
1643 * Returns: the new #GstCaps
1646 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1651 /* NULL pointers are no correct GstCaps */
1652 g_return_val_if_fail (caps1 != NULL, NULL);
1653 g_return_val_if_fail (caps2 != NULL, NULL);
1655 if (CAPS_IS_EMPTY (caps1))
1656 return gst_caps_copy (caps2);
1658 if (CAPS_IS_EMPTY (caps2))
1659 return gst_caps_copy (caps1);
1661 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1662 return gst_caps_new_any ();
1664 dest1 = gst_caps_copy (caps1);
1665 dest2 = gst_caps_copy (caps2);
1666 gst_caps_append (dest1, dest2);
1668 gst_caps_do_simplify (dest1);
1672 typedef struct _NormalizeForeach
1675 GstStructure *structure;
1680 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1682 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1686 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1687 guint len = gst_value_list_get_size (value);
1688 for (i = 1; i < len; i++) {
1689 const GValue *v = gst_value_list_get_value (value, i);
1690 GstStructure *structure = gst_structure_copy (nf->structure);
1692 gst_structure_id_set_value (structure, field_id, v);
1693 gst_caps_append_structure (nf->caps, structure);
1696 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1697 gst_structure_id_set_value (nf->structure, field_id, &val);
1698 g_value_unset (&val);
1706 * gst_caps_normalize:
1707 * @caps: a #GstCaps to normalize
1709 * Creates a new #GstCaps that represents the same set of formats as
1710 * @caps, but contains no lists. Each list is expanded into separate
1713 * Returns: the new #GstCaps
1716 gst_caps_normalize (const GstCaps * caps)
1718 NormalizeForeach nf;
1722 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1724 newcaps = gst_caps_copy (caps);
1726 nlen = newcaps->structs->len;
1728 for (i = 0; i < nlen; i++) {
1729 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1731 while (!gst_structure_foreach (nf.structure,
1732 gst_caps_normalize_foreach, &nf));
1739 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1742 const GstStructure *struct1 = *((const GstStructure **) one);
1743 const GstStructure *struct2 = *((const GstStructure **) two);
1745 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1746 So what's the best way? */
1747 ret = strcmp (gst_structure_get_name (struct1),
1748 gst_structure_get_name (struct2));
1752 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1759 GstStructure *compare;
1764 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1767 UnionField *u = user_data;
1768 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1772 g_value_unset (&u->value);
1775 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1778 g_value_unset (&u->value);
1782 gst_value_union (&u->value, val, value);
1787 gst_caps_structure_simplify (GstStructure ** result,
1788 const GstStructure * simplify, GstStructure * compare)
1791 UnionField field = { 0, {0,}, NULL };
1793 /* try to subtract to get a real subset */
1794 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1795 switch (g_slist_length (list)) {
1800 *result = list->data;
1801 g_slist_free (list);
1807 for (walk = list; walk; walk = g_slist_next (walk)) {
1808 gst_structure_free (walk->data);
1810 g_slist_free (list);
1816 /* try to union both structs */
1817 field.compare = compare;
1818 if (gst_structure_foreach ((GstStructure *) simplify,
1819 gst_caps_structure_figure_out_union, &field)) {
1820 gboolean ret = FALSE;
1822 /* now we know all of simplify's fields are the same in compare
1823 * but at most one field: field.name */
1824 if (G_IS_VALUE (&field.value)) {
1825 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1826 gst_structure_id_set_value (compare, field.name, &field.value);
1830 g_value_unset (&field.value);
1831 } else if (gst_structure_n_fields (simplify) <=
1832 gst_structure_n_fields (compare)) {
1833 /* compare is just more specific, will be optimized away later */
1834 /* FIXME: do this here? */
1835 GST_LOG ("found a case that will be optimized later.");
1837 gchar *one = gst_structure_to_string (simplify);
1838 gchar *two = gst_structure_to_string (compare);
1841 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1853 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1854 GstStructure * new, gint i)
1856 gst_structure_set_parent_refcount (old, NULL);
1857 gst_structure_free (old);
1858 gst_structure_set_parent_refcount (new, &caps->refcount);
1859 g_ptr_array_index (caps->structs, i) = new;
1863 * gst_caps_do_simplify:
1864 * @caps: a #GstCaps to simplify
1866 * Modifies the given @caps inplace into a representation that represents the
1867 * same set of formats, but in a simpler form. Component structures that are
1868 * identical are merged. Component structures that have values that can be
1869 * merged are also merged.
1871 * Returns: TRUE, if the caps could be simplified
1874 gst_caps_do_simplify (GstCaps * caps)
1876 GstStructure *simplify, *compare, *result = NULL;
1878 gboolean changed = FALSE;
1880 g_return_val_if_fail (caps != NULL, FALSE);
1881 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1883 if (gst_caps_get_size (caps) < 2)
1886 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1888 start = caps->structs->len - 1;
1889 for (i = caps->structs->len - 1; i >= 0; i--) {
1890 simplify = gst_caps_get_structure_unchecked (caps, i);
1891 if (gst_structure_get_name_id (simplify) !=
1892 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1895 for (j = start; j >= 0; j--) {
1898 compare = gst_caps_get_structure_unchecked (caps, j);
1899 if (gst_structure_get_name_id (simplify) !=
1900 gst_structure_get_name_id (compare)) {
1903 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1905 gst_caps_switch_structures (caps, simplify, result, i);
1908 gst_caps_remove_structure (caps, i);
1920 /* gst_caps_do_simplify (caps); */
1924 #ifndef GST_DISABLE_LOADSAVE
1926 * gst_caps_save_thyself:
1927 * @caps: a #GstCaps structure
1928 * @parent: a XML parent node
1930 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1932 * Returns: a XML node pointer
1935 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1937 char *s = gst_caps_to_string (caps);
1939 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1945 * gst_caps_load_thyself:
1946 * @parent: a XML node
1948 * Creates a #GstCaps from its XML serialization.
1950 * Returns: a new #GstCaps structure
1953 gst_caps_load_thyself (xmlNodePtr parent)
1955 if (strcmp ("caps", (char *) parent->name) == 0) {
1956 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1967 * @caps: a pointer to #GstCaps
1968 * @newcaps: a #GstCaps to replace *caps
1970 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1971 * pointed to by @caps, if applicable, then modifies @caps to point to
1972 * @newcaps. An additional ref on @newcaps is taken.
1974 * This function does not take any locks so you might want to lock
1975 * the object owning @caps pointer.
1978 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1982 g_return_if_fail (caps != NULL);
1986 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1988 if (newcaps != oldcaps) {
1990 gst_caps_ref (newcaps);
1995 gst_caps_unref (oldcaps);
2000 * gst_caps_to_string:
2003 * Converts @caps to a string representation. This string representation
2004 * can be converted back to a #GstCaps by gst_caps_from_string().
2006 * For debugging purposes its easier to do something like this:
2008 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2010 * This prints the caps in human readble form.
2012 * Returns: a newly allocated string representing @caps.
2015 gst_caps_to_string (const GstCaps * caps)
2017 guint i, slen, clen;
2020 /* NOTE: This function is potentially called by the debug system,
2021 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2022 * should be careful to avoid recursion. This includes any functions
2023 * called by gst_caps_to_string. In particular, calls should
2024 * not use the GST_PTR_FORMAT extension. */
2027 return g_strdup ("NULL");
2029 if (CAPS_IS_ANY (caps)) {
2030 return g_strdup ("ANY");
2032 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2033 return g_strdup ("EMPTY");
2036 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2038 clen = caps->structs->len;
2039 for (i = 0; i < clen; i++) {
2041 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
2045 s = g_string_sized_new (slen);
2046 for (i = 0; i < clen; i++) {
2047 GstStructure *structure;
2050 /* ';' is now added by gst_structure_to_string */
2051 g_string_append_c (s, ' ');
2054 structure = gst_caps_get_structure_unchecked (caps, i);
2055 priv_gst_structure_append_to_gstring (structure, s);
2057 if (s->len && s->str[s->len - 1] == ';') {
2058 /* remove latest ';' */
2059 s->str[--s->len] = '\0';
2061 return g_string_free (s, FALSE);
2065 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2067 GstStructure *structure;
2070 g_return_val_if_fail (string, FALSE);
2071 if (strcmp ("ANY", string) == 0) {
2072 caps->flags = GST_CAPS_FLAGS_ANY;
2075 if (strcmp ("EMPTY", string) == 0) {
2079 structure = gst_structure_from_string (string, &s);
2080 if (structure == NULL) {
2083 gst_caps_append_structure (caps, structure);
2087 while (g_ascii_isspace (*s))
2092 structure = gst_structure_from_string (s, &s);
2093 if (structure == NULL) {
2096 gst_caps_append_structure (caps, structure);
2104 * gst_caps_from_string:
2105 * @string: a string to convert to #GstCaps
2107 * Converts @caps from a string representation.
2109 * Returns: a newly allocated #GstCaps
2112 gst_caps_from_string (const gchar * string)
2116 caps = gst_caps_new_empty ();
2117 if (gst_caps_from_string_inplace (caps, string)) {
2120 gst_caps_unref (caps);
2126 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2128 g_return_if_fail (G_IS_VALUE (src_value));
2129 g_return_if_fail (G_IS_VALUE (dest_value));
2130 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2131 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2132 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2134 dest_value->data[0].v_pointer =
2135 gst_caps_to_string (src_value->data[0].v_pointer);
2139 gst_caps_copy_conditional (GstCaps * src)
2142 return gst_caps_ref (src);