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 IS_WRITABLE(caps) \
79 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
81 /* same as gst_caps_is_any () */
82 #define CAPS_IS_ANY(caps) \
83 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAGS_ANY)
85 /* same as gst_caps_is_empty () */
86 #define CAPS_IS_EMPTY(caps) \
87 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
89 #define CAPS_IS_EMPTY_SIMPLE(caps) \
90 (((caps)->structs == NULL) || ((caps)->structs->len == 0))
92 /* quick way to get a caps structure at an index without doing a type or array
94 #define gst_caps_get_structure_unchecked(caps, index) \
95 ((GstStructure *)g_ptr_array_index ((caps)->structs, (index)))
96 /* quick way to append a structure without checking the args */
97 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
98 GstStructure *__s=structure; \
99 gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps)); \
100 g_ptr_array_add (caps->structs, __s); \
103 /* lock to protect multiple invocations of static caps to caps conversion */
104 G_LOCK_DEFINE_STATIC (static_caps_lock);
106 static void gst_caps_transform_to_string (const GValue * src_value,
107 GValue * dest_value);
108 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
109 const gchar * string);
111 GType _gst_caps_type = 0;
114 _gst_caps_initialize (void)
116 _gst_caps_type = gst_mini_object_register ("GstCaps");
118 g_value_register_transform_func (_gst_caps_type,
119 G_TYPE_STRING, gst_caps_transform_to_string);
123 _gst_caps_copy (const GstCaps * caps)
126 GstStructure *structure;
129 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
131 newcaps = gst_caps_new_empty ();
132 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
133 n = caps->structs->len;
135 for (i = 0; i < n; i++) {
136 structure = gst_caps_get_structure_unchecked (caps, i);
137 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
143 /* creation/deletion */
145 _gst_caps_free (GstCaps * caps)
147 GstStructure *structure;
150 /* The refcount must be 0, but since we're only called by gst_caps_unref,
151 * don't bother testing. */
152 len = caps->structs->len;
153 /* This can be used to get statistics about caps sizes */
154 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
155 for (i = 0; i < len; i++) {
156 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
157 gst_structure_set_parent_refcount (structure, NULL);
158 gst_structure_free (structure);
160 g_ptr_array_free (caps->structs, TRUE);
162 #ifdef DEBUG_REFCOUNT
163 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
165 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
169 gst_caps_init (GstCaps * caps, gsize size)
171 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
173 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
174 caps->mini_object.dispose = NULL;
175 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
177 /* the 32 has been determined by logging caps sizes in _gst_caps_free
178 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
180 * caps->structs = g_ptr_array_sized_new (32);
182 caps->structs = g_ptr_array_new ();
186 * gst_caps_new_empty:
188 * Creates a new #GstCaps that is empty. That is, the returned
189 * #GstCaps contains no media formats.
190 * Caller is responsible for unreffing the returned caps.
192 * Returns: (transfer full): the new #GstCaps
195 gst_caps_new_empty (void)
199 caps = g_slice_new (GstCaps);
201 gst_caps_init (caps, sizeof (GstCaps));
203 #ifdef DEBUG_REFCOUNT
204 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
213 * Creates a new #GstCaps that indicates that it is compatible with
216 * Returns: (transfer full): the new #GstCaps
219 gst_caps_new_any (void)
221 GstCaps *caps = gst_caps_new_empty ();
223 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAGS_ANY);
229 * gst_caps_new_simple:
230 * @media_type: the media type of the structure
231 * @fieldname: first field to set
232 * @...: additional arguments
234 * Creates a new #GstCaps that contains one #GstStructure. The
235 * structure is defined by the arguments, which have the same format
236 * as gst_structure_new().
237 * Caller is responsible for unreffing the returned caps.
239 * Returns: (transfer full): the new #GstCaps
242 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
245 GstStructure *structure;
248 caps = gst_caps_new_empty ();
250 va_start (var_args, fieldname);
251 structure = gst_structure_new_valist (media_type, fieldname, var_args);
255 gst_caps_append_structure_unchecked (caps, structure);
257 gst_caps_replace (&caps, NULL);
264 * @struct1: the first structure to add
265 * @...: additional structures to add
267 * Creates a new #GstCaps and adds all the structures listed as
268 * arguments. The list must be NULL-terminated. The structures
269 * are not copied; the returned #GstCaps owns the structures.
271 * Returns: (transfer full): the new #GstCaps
274 gst_caps_new_full (GstStructure * struct1, ...)
279 va_start (var_args, struct1);
280 caps = gst_caps_new_full_valist (struct1, var_args);
287 * gst_caps_new_full_valist:
288 * @structure: the first structure to add
289 * @var_args: additional structures to add
291 * Creates a new #GstCaps and adds all the structures listed as
292 * arguments. The list must be NULL-terminated. The structures
293 * are not copied; the returned #GstCaps owns the structures.
295 * Returns: (transfer full): the new #GstCaps
298 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
302 caps = gst_caps_new_empty ();
305 gst_caps_append_structure_unchecked (caps, structure);
306 structure = va_arg (var_args, GstStructure *);
313 * gst_caps_make_writable:
314 * @caps: (transfer full): the #GstCaps to make writable
316 * Returns a writable copy of @caps.
318 * If there is only one reference count on @caps, the caller must be the owner,
319 * and so this function will return the caps object unchanged. If on the other
320 * hand there is more than one reference on the object, a new caps object will
321 * be returned. The caller's reference on @caps will be removed, and instead the
322 * caller will own a reference to the returned object.
324 * In short, this function unrefs the caps in the argument and refs the caps
325 * that it returns. Don't access the argument after calling this function. See
326 * also: gst_caps_ref().
328 * Returns: (transfer full): the same #GstCaps object.
331 gst_caps_make_writable (GstCaps * caps)
335 g_return_val_if_fail (caps != NULL, NULL);
337 /* we are the only instance reffing this caps */
338 if (IS_WRITABLE (caps))
342 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy caps");
343 copy = _gst_caps_copy (caps);
344 gst_caps_unref (caps);
350 gst_static_caps_get_type (void)
352 static GType staticcaps_type = 0;
354 if (G_UNLIKELY (staticcaps_type == 0)) {
355 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
357 return staticcaps_type;
362 * gst_static_caps_get:
363 * @static_caps: the #GstStaticCaps to convert
365 * Converts a #GstStaticCaps to a #GstCaps.
367 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
368 * Since the core holds an additional ref to the returned caps,
369 * use gst_caps_make_writable() on the returned caps to modify it.
372 gst_static_caps_get (GstStaticCaps * static_caps)
376 g_return_val_if_fail (static_caps != NULL, NULL);
378 caps = (GstCaps *) static_caps;
380 /* refcount is 0 when we need to convert */
381 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) == 0)) {
385 G_LOCK (static_caps_lock);
386 /* check if other thread already updated */
387 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) > 0))
390 string = static_caps->string;
392 if (G_UNLIKELY (string == NULL))
395 GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);
397 /* we construct the caps on the stack, then copy over the struct into our
398 * real caps, refcount last. We do this because we must leave the refcount
399 * of the result caps to 0 so that other threads don't run away with the
400 * caps while we are constructing it. */
401 gst_caps_init (&temp, sizeof (GstCaps));
403 /* convert to string */
404 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
405 g_critical ("Could not convert static caps \"%s\"", string);
407 gst_caps_init (caps, sizeof (GstCaps));
408 /* now copy stuff over to the real caps. */
409 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS (&temp);
410 caps->structs = temp.structs;
412 GST_CAT_LOG (GST_CAT_CAPS, "created %p", static_caps);
414 G_UNLOCK (static_caps_lock);
416 /* ref the caps, makes it not writable */
424 G_UNLOCK (static_caps_lock);
425 g_warning ("static caps %p string is NULL", static_caps);
432 static GstStructure *
433 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
435 /* don't use index_fast, gst_caps_do_simplify relies on the order */
436 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
438 gst_structure_set_parent_refcount (s, NULL);
443 * gst_caps_steal_structure:
444 * @caps: the #GstCaps to retrieve from
445 * @index: Index of the structure to retrieve
447 * Retrieves the stucture with the given index from the list of structures
448 * contained in @caps. The caller becomes the owner of the returned structure.
450 * Returns: (transfer full): a pointer to the #GstStructure corresponding
456 gst_caps_steal_structure (GstCaps * caps, guint index)
458 g_return_val_if_fail (caps != NULL, NULL);
459 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
461 if (G_UNLIKELY (index >= caps->structs->len))
464 return gst_caps_remove_and_get_structure (caps, index);
468 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
471 GstStructure *struct1 = (GstStructure *) data;
472 const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
474 if (G_UNLIKELY (val1 == NULL))
476 if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
484 gst_caps_structure_is_subset_field (GQuark field_id, const GValue * value,
487 GstStructure *subtract_from = user_data;
488 GValue subtraction = { 0, };
491 if (!(other = gst_structure_id_get_value (subtract_from, field_id)))
492 /* field is missing in one set */
495 /* equal values are subset */
496 if (gst_value_compare (other, value) == GST_VALUE_EQUAL)
504 * -> 1 - [1,2] = empty
508 * -> [1,2] - [1,3] = empty
512 * -> {1,3} - {1,2} = 3
515 * First caps subtraction needs to return a non-empty set, second
516 * subtractions needs to give en empty set.
518 if (gst_value_subtract (&subtraction, other, value)) {
519 g_value_unset (&subtraction);
520 /* !empty result, swapping must be empty */
521 if (!gst_value_subtract (&subtraction, value, other))
524 g_value_unset (&subtraction);
530 gst_caps_structure_is_subset (const GstStructure * minuend,
531 const GstStructure * subtrahend)
533 if ((minuend->name != subtrahend->name) ||
534 (gst_structure_n_fields (minuend) !=
535 gst_structure_n_fields (subtrahend))) {
539 return gst_structure_foreach ((GstStructure *) subtrahend,
540 gst_caps_structure_is_subset_field, (gpointer) minuend);
545 * @caps1: the #GstCaps that will be appended to
546 * @caps2: (transfer full): the #GstCaps to append
548 * Appends the structures contained in @caps2 to @caps1. The structures in
549 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
550 * freed. If either caps is ANY, the resulting caps will be ANY.
553 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
555 GstStructure *structure;
558 g_return_if_fail (GST_IS_CAPS (caps1));
559 g_return_if_fail (GST_IS_CAPS (caps2));
560 g_return_if_fail (IS_WRITABLE (caps1));
561 g_return_if_fail (IS_WRITABLE (caps2));
563 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
564 /* FIXME: this leaks */
565 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
566 for (i = caps2->structs->len - 1; i >= 0; i--) {
567 structure = gst_caps_remove_and_get_structure (caps2, i);
568 gst_structure_free (structure);
571 for (i = caps2->structs->len; i; i--) {
572 structure = gst_caps_remove_and_get_structure (caps2, 0);
573 gst_caps_append_structure_unchecked (caps1, structure);
576 gst_caps_unref (caps2); /* guaranteed to free it */
581 * @caps1: the #GstCaps that will take the new entries
582 * @caps2: (transfer full): the #GstCaps to merge in
584 * Appends the structures contained in @caps2 to @caps1 if they are not yet
585 * expressed by @caps1. The structures in @caps2 are not copied -- they are
586 * transferred to @caps1, and then @caps2 is freed.
587 * If either caps is ANY, the resulting caps will be ANY.
592 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
594 GstStructure *structure;
597 g_return_if_fail (GST_IS_CAPS (caps1));
598 g_return_if_fail (GST_IS_CAPS (caps2));
599 g_return_if_fail (IS_WRITABLE (caps1));
600 g_return_if_fail (IS_WRITABLE (caps2));
602 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
603 for (i = caps2->structs->len - 1; i >= 0; i--) {
604 structure = gst_caps_remove_and_get_structure (caps2, i);
605 gst_structure_free (structure);
607 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
608 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
609 for (i = caps1->structs->len - 1; i >= 0; i--) {
610 structure = gst_caps_remove_and_get_structure (caps1, i);
611 gst_structure_free (structure);
614 for (i = caps2->structs->len; i; i--) {
615 structure = gst_caps_remove_and_get_structure (caps2, 0);
616 gst_caps_merge_structure (caps1, structure);
619 GstCaps *com = gst_caps_intersect (caps1, caps2);
620 GstCaps *add = gst_caps_subtract (caps2, com);
622 GST_DEBUG ("common : %d", gst_caps_get_size (com));
623 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
624 gst_caps_append (caps1, add);
625 gst_caps_unref (com);
628 gst_caps_unref (caps2); /* guaranteed to free it */
632 * gst_caps_append_structure:
633 * @caps: the #GstCaps that will be appended to
634 * @structure: (transfer full): the #GstStructure to append
636 * Appends @structure to @caps. The structure is not copied; @caps
637 * becomes the owner of @structure.
640 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
642 g_return_if_fail (GST_IS_CAPS (caps));
643 g_return_if_fail (IS_WRITABLE (caps));
645 if (G_LIKELY (structure)) {
646 g_return_if_fail (structure->parent_refcount == NULL);
647 gst_caps_append_structure_unchecked (caps, structure);
652 * gst_caps_remove_structure:
653 * @caps: the #GstCaps to remove from
654 * @idx: Index of the structure to remove
656 * removes the stucture with the given index from the list of structures
657 * contained in @caps.
660 gst_caps_remove_structure (GstCaps * caps, guint idx)
662 GstStructure *structure;
664 g_return_if_fail (caps != NULL);
665 g_return_if_fail (idx <= gst_caps_get_size (caps));
666 g_return_if_fail (IS_WRITABLE (caps));
668 structure = gst_caps_remove_and_get_structure (caps, idx);
669 gst_structure_free (structure);
673 * gst_caps_merge_structure:
674 * @caps: the #GstCaps that will the the new structure
675 * @structure: (transfer full): the #GstStructure to merge
677 * Appends @structure to @caps if its not already expressed by @caps. The
678 * structure is not copied; @caps becomes the owner of @structure.
681 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
683 g_return_if_fail (GST_IS_CAPS (caps));
684 g_return_if_fail (IS_WRITABLE (caps));
686 if (G_LIKELY (structure)) {
687 GstStructure *structure1;
689 gboolean unique = TRUE;
691 g_return_if_fail (structure->parent_refcount == NULL);
692 /* check each structure */
693 for (i = caps->structs->len - 1; i >= 0; i--) {
694 structure1 = gst_caps_get_structure_unchecked (caps, i);
695 /* if structure is a subset of structure1, then skip it */
696 if (gst_caps_structure_is_subset (structure1, structure)) {
702 gst_caps_append_structure_unchecked (caps, structure);
704 gst_structure_free (structure);
713 * Gets the number of structures contained in @caps.
715 * Returns: the number of structures that @caps contains
718 gst_caps_get_size (const GstCaps * caps)
720 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
722 return caps->structs->len;
726 * gst_caps_get_structure:
728 * @index: the index of the structure
730 * Finds the structure in @caps that has the index @index, and
733 * WARNING: This function takes a const GstCaps *, but returns a
734 * non-const GstStructure *. This is for programming convenience --
735 * the caller should be aware that structures inside a constant
736 * #GstCaps should not be modified. However, if you know the caps
737 * are writable, either because you have just copied them or made
738 * them writable with gst_caps_make_writable(), you may modify the
739 * structure returned in the usual way, e.g. with functions like
740 * gst_structure_set().
742 * You do not need to free or unref the structure returned, it
743 * belongs to the #GstCaps.
745 * Returns: (transfer none): a pointer to the #GstStructure corresponding
749 gst_caps_get_structure (const GstCaps * caps, guint index)
751 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
752 g_return_val_if_fail (index < caps->structs->len, NULL);
754 return gst_caps_get_structure_unchecked (caps, index);
759 * @caps: the #GstCaps to copy
760 * @nth: the nth structure to copy
762 * Creates a new #GstCaps and appends a copy of the nth structure
763 * contained in @caps.
765 * Returns: (transfer full): the new #GstCaps
768 gst_caps_copy_nth (const GstCaps * caps, guint nth)
771 GstStructure *structure;
773 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
775 newcaps = gst_caps_new_empty ();
776 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
778 if (G_LIKELY (caps->structs->len > nth)) {
779 structure = gst_caps_get_structure_unchecked (caps, nth);
780 gst_caps_append_structure_unchecked (newcaps,
781 gst_structure_copy (structure));
789 * @caps: the #GstCaps to truncate
791 * Destructively discard all but the first structure from @caps. Useful when
792 * fixating. @caps must be writable.
795 gst_caps_truncate (GstCaps * caps)
799 g_return_if_fail (GST_IS_CAPS (caps));
800 g_return_if_fail (IS_WRITABLE (caps));
802 i = caps->structs->len - 1;
805 gst_caps_remove_structure (caps, i--);
809 * gst_caps_set_value:
810 * @caps: a writable caps
811 * @field: name of the field to set
812 * @value: value to set the field to
814 * Sets the given @field on all structures of @caps to the given @value.
815 * This is a convenience function for calling gst_structure_set_value() on
816 * all structures of @caps.
821 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
825 g_return_if_fail (GST_IS_CAPS (caps));
826 g_return_if_fail (IS_WRITABLE (caps));
827 g_return_if_fail (field != NULL);
828 g_return_if_fail (G_IS_VALUE (value));
830 len = caps->structs->len;
831 for (i = 0; i < len; i++) {
832 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
833 gst_structure_set_value (structure, field, value);
838 * gst_caps_set_simple_valist:
839 * @caps: the #GstCaps to set
840 * @field: first field to set
841 * @varargs: additional parameters
843 * Sets fields in a #GstCaps. The arguments must be passed in the same
844 * manner as gst_structure_set(), and be NULL-terminated.
845 * <note>Prior to GStreamer version 0.10.26, this function failed when
846 * @caps was not simple. If your code needs to work with those versions
847 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
848 * is %TRUE for @caps.</note>
851 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
853 GValue value = { 0, };
855 g_return_if_fail (GST_IS_CAPS (caps));
856 g_return_if_fail (IS_WRITABLE (caps));
862 type = va_arg (varargs, GType);
864 if (G_UNLIKELY (type == G_TYPE_DATE)) {
865 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
866 type = GST_TYPE_DATE;
868 #if GLIB_CHECK_VERSION(2,23,3)
869 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
871 g_value_init (&value, type);
872 G_VALUE_COLLECT (&value, varargs, 0, &err);
874 if (G_UNLIKELY (err)) {
875 g_critical ("%s", err);
879 gst_caps_set_value (caps, field, &value);
881 g_value_unset (&value);
883 field = va_arg (varargs, const gchar *);
888 * gst_caps_set_simple:
889 * @caps: the #GstCaps to set
890 * @field: first field to set
891 * @...: additional parameters
893 * Sets fields in a #GstCaps. The arguments must be passed in the same
894 * manner as gst_structure_set(), and be NULL-terminated.
895 * <note>Prior to GStreamer version 0.10.26, this function failed when
896 * @caps was not simple. If your code needs to work with those versions
897 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
898 * is %TRUE for @caps.</note>
901 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
905 g_return_if_fail (GST_IS_CAPS (caps));
906 g_return_if_fail (IS_WRITABLE (caps));
908 va_start (var_args, field);
909 gst_caps_set_simple_valist (caps, field, var_args);
917 * @caps: the #GstCaps to test
919 * Determines if @caps represents any media format.
921 * Returns: TRUE if @caps represents any format.
924 gst_caps_is_any (const GstCaps * caps)
926 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
928 return (CAPS_IS_ANY (caps));
933 * @caps: the #GstCaps to test
935 * Determines if @caps represents no media formats.
937 * Returns: TRUE if @caps represents no formats.
940 gst_caps_is_empty (const GstCaps * caps)
942 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
944 if (CAPS_IS_ANY (caps))
947 return CAPS_IS_EMPTY_SIMPLE (caps);
951 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
954 return gst_value_is_fixed (value);
959 * @caps: the #GstCaps to test
961 * Fixed #GstCaps describe exactly one format, that is, they have exactly
962 * one structure, and each field in the structure describes a fixed type.
963 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
965 * Returns: TRUE if @caps is fixed
968 gst_caps_is_fixed (const GstCaps * caps)
970 GstStructure *structure;
972 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
974 if (caps->structs->len != 1)
977 structure = gst_caps_get_structure_unchecked (caps, 0);
979 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
983 * gst_caps_is_equal_fixed:
984 * @caps1: the #GstCaps to test
985 * @caps2: the #GstCaps to test
987 * Tests if two #GstCaps are equal. This function only works on fixed
990 * Returns: TRUE if the arguments represent the same format
993 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
995 GstStructure *struct1, *struct2;
997 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
998 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1000 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1001 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1003 if (struct1->name != struct2->name) {
1006 if (struct1->fields->len != struct2->fields->len) {
1010 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
1015 * gst_caps_is_always_compatible:
1016 * @caps1: the #GstCaps to test
1017 * @caps2: the #GstCaps to test
1019 * A given #GstCaps structure is always compatible with another if
1020 * every media format that is in the first is also contained in the
1021 * second. That is, @caps1 is a subset of @caps2.
1023 * Returns: TRUE if @caps1 is a subset of @caps2.
1026 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1028 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1029 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1031 return gst_caps_is_subset (caps1, caps2);
1035 * gst_caps_is_subset:
1036 * @subset: a #GstCaps
1037 * @superset: a potentially greater #GstCaps
1039 * Checks if all caps represented by @subset are also represented by @superset.
1040 * <note>This function does not work reliably if optional properties for caps
1041 * are included on one caps and omitted on the other.</note>
1043 * Returns: %TRUE if @subset is a subset of @superset
1046 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1051 g_return_val_if_fail (subset != NULL, FALSE);
1052 g_return_val_if_fail (superset != NULL, FALSE);
1054 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1056 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1059 caps = gst_caps_subtract (subset, superset);
1060 ret = CAPS_IS_EMPTY_SIMPLE (caps);
1061 gst_caps_unref (caps);
1066 * gst_caps_is_equal:
1067 * @caps1: a #GstCaps
1068 * @caps2: another #GstCaps
1070 * Checks if the given caps represent the same set of caps.
1071 * <note>This function does not work reliably if optional properties for caps
1072 * are included on one caps and omitted on the other.</note>
1074 * This function deals correctly with passing NULL for any of the caps.
1076 * Returns: TRUE if both caps are equal.
1079 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1081 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1082 * So there should be an assertion that caps1 and caps2 != NULL */
1084 /* NULL <-> NULL is allowed here */
1085 if (G_UNLIKELY (caps1 == caps2))
1088 /* one of them NULL => they are different (can't be both NULL because
1089 * we checked that above) */
1090 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1093 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1094 return gst_caps_is_equal_fixed (caps1, caps2);
1096 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1099 /* intersect operation */
1104 const GstStructure *intersect;
1109 gst_caps_structure_intersect_field1 (GQuark id, const GValue * val1,
1112 IntersectData *idata = (IntersectData *) data;
1113 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1115 if (G_UNLIKELY (val2 == NULL)) {
1116 gst_structure_id_set_value (idata->dest, id, val1);
1118 GValue dest_value = { 0 };
1119 if (gst_value_intersect (&dest_value, val1, val2)) {
1120 gst_structure_id_set_value (idata->dest, id, &dest_value);
1121 g_value_unset (&dest_value);
1130 gst_caps_structure_intersect_field2 (GQuark id, const GValue * val1,
1133 IntersectData *idata = (IntersectData *) data;
1134 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1136 if (G_UNLIKELY (val2 == NULL)) {
1137 gst_structure_id_set_value (idata->dest, id, val1);
1142 static GstStructure *
1143 gst_caps_structure_intersect (const GstStructure * struct1,
1144 const GstStructure * struct2)
1148 g_assert (struct1 != NULL);
1149 g_assert (struct2 != NULL);
1151 if (G_UNLIKELY (struct1->name != struct2->name))
1154 /* copy fields from struct1 which we have not in struct2 to target
1155 * intersect if we have the field in both */
1156 data.dest = gst_structure_id_empty_new (struct1->name);
1157 data.intersect = struct2;
1158 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1159 gst_caps_structure_intersect_field1, &data)))
1162 /* copy fields from struct2 which we have not in struct1 to target */
1163 data.intersect = struct1;
1164 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
1165 gst_caps_structure_intersect_field2, &data)))
1171 gst_structure_free (data.dest);
1176 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
1179 GstStructure *other = (GstStructure *) data;
1180 const GValue *val2 = gst_structure_id_get_value (other, id);
1182 if (G_LIKELY (val2)) {
1183 if (!gst_value_can_intersect (val1, val2)) {
1186 gint eq = gst_value_compare (val1, val2);
1188 if (eq == GST_VALUE_UNORDERED) {
1189 /* we need to try interseting */
1190 GValue dest_value = { 0 };
1191 if (gst_value_intersect (&dest_value, val1, val2)) {
1192 g_value_unset (&dest_value);
1196 } else if (eq != GST_VALUE_EQUAL) {
1205 gst_caps_structure_can_intersect (const GstStructure * struct1,
1206 const GstStructure * struct2)
1208 g_assert (struct1 != NULL);
1209 g_assert (struct2 != NULL);
1211 if (G_UNLIKELY (struct1->name != struct2->name))
1214 /* tries to intersect if we have the field in both */
1215 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1216 gst_caps_structure_can_intersect_field, (gpointer) struct2)))
1223 * gst_caps_can_intersect:
1224 * @caps1: a #GstCaps to intersect
1225 * @caps2: a #GstCaps to intersect
1227 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1230 * Returns: %TRUE if intersection would be not empty
1235 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1237 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1238 guint j, k, len1, len2;
1239 GstStructure *struct1;
1240 GstStructure *struct2;
1242 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1243 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1245 /* caps are exactly the same pointers */
1246 if (G_UNLIKELY (caps1 == caps2))
1249 /* empty caps on either side, return empty */
1250 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1253 /* one of the caps is any */
1254 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1257 /* run zigzag on top line then right line, this preserves the caps order
1258 * much better than a simple loop.
1260 * This algorithm zigzags over the caps structures as demonstrated in
1261 * the folowing matrix:
1264 * +------------- total distance: +-------------
1265 * | 1 2 4 7 0 | 0 1 2 3
1266 * caps2 | 3 5 8 10 1 | 1 2 3 4
1267 * | 6 9 11 12 2 | 2 3 4 5
1269 * First we iterate over the caps1 structures (top line) intersecting
1270 * the structures diagonally down, then we iterate over the caps2
1271 * structures. The result is that the intersections are ordered based on the
1272 * sum of the indexes in the list.
1274 len1 = caps1->structs->len;
1275 len2 = caps2->structs->len;
1276 for (i = 0; i < len1 + len2 - 1; i++) {
1277 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1278 j = MIN (i, len1 - 1);
1279 /* subset index stays 0 until i reaches superset->structs->len, then it
1280 * counts up from 1 to subset->structs->len - 1 */
1283 /* now run the diagonal line, end condition is the left or bottom
1286 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1287 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1289 if (gst_caps_structure_can_intersect (struct1, struct2)) {
1292 /* move down left */
1294 if (G_UNLIKELY (j == 0))
1295 break; /* so we don't roll back to G_MAXUINT */
1303 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1305 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1306 guint j, k, len1, len2;
1308 GstStructure *struct1;
1309 GstStructure *struct2;
1311 GstStructure *istruct;
1313 /* caps are exactly the same pointers, just copy one caps */
1314 if (G_UNLIKELY (caps1 == caps2))
1315 return _gst_caps_copy (caps1);
1317 /* empty caps on either side, return empty */
1318 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1319 return gst_caps_new_empty ();
1321 /* one of the caps is any, just copy the other caps */
1322 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1323 return _gst_caps_copy (caps2);
1324 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1325 return _gst_caps_copy (caps1);
1327 dest = gst_caps_new_empty ();
1329 /* run zigzag on top line then right line, this preserves the caps order
1330 * much better than a simple loop.
1332 * This algorithm zigzags over the caps structures as demonstrated in
1333 * the folowing matrix:
1341 * First we iterate over the caps1 structures (top line) intersecting
1342 * the structures diagonally down, then we iterate over the caps2
1345 len1 = caps1->structs->len;
1346 len2 = caps2->structs->len;
1347 for (i = 0; i < len1 + len2 - 1; i++) {
1348 /* caps1 index goes from 0 to caps1->structs->len-1 */
1349 j = MIN (i, len1 - 1);
1350 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1351 * up from 1 to caps2->structs->len - 1 */
1354 /* now run the diagonal line, end condition is the left or bottom
1357 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1358 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1360 istruct = gst_caps_structure_intersect (struct1, struct2);
1362 gst_caps_merge_structure (dest, istruct);
1363 /* move down left */
1365 if (G_UNLIKELY (j == 0))
1366 break; /* so we don't roll back to G_MAXUINT */
1374 * gst_caps_intersect_first:
1375 * @caps1: a #GstCaps to intersect
1376 * @caps2: a #GstCaps to intersect
1378 * Creates a new #GstCaps that contains all the formats that are common
1379 * to both @caps1 and @caps2.
1381 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1382 * fashion as @caps1.
1384 * Returns: the new #GstCaps
1387 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1389 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1390 guint j, len1, len2;
1392 GstStructure *struct1;
1393 GstStructure *struct2;
1395 GstStructure *istruct;
1397 /* caps are exactly the same pointers, just copy one caps */
1398 if (G_UNLIKELY (caps1 == caps2))
1399 return gst_caps_copy (caps1);
1401 /* empty caps on either side, return empty */
1402 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1403 return gst_caps_new_empty ();
1405 /* one of the caps is any, just copy the other caps */
1406 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1407 return gst_caps_copy (caps2);
1408 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1409 return gst_caps_copy (caps1);
1411 dest = gst_caps_new_empty ();
1413 len1 = caps1->structs->len;
1414 len2 = caps2->structs->len;
1415 for (i = 0; i < len1; i++) {
1416 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1417 for (j = 0; j < len2; j++) {
1418 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1419 istruct = gst_caps_structure_intersect (struct1, struct2);
1421 gst_caps_merge_structure (dest, istruct);
1429 * gst_caps_intersect_full:
1430 * @caps1: a #GstCaps to intersect
1431 * @caps2: a #GstCaps to intersect
1432 * @mode: The intersection algorithm/mode to use
1434 * Creates a new #GstCaps that contains all the formats that are common
1435 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1438 * Returns: the new #GstCaps
1442 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1443 GstCapsIntersectMode mode)
1445 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1446 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1449 case GST_CAPS_INTERSECT_FIRST:
1450 return gst_caps_intersect_first (caps1, caps2);
1452 g_warning ("Unknown caps intersect mode: %d", mode);
1454 case GST_CAPS_INTERSECT_ZIG_ZAG:
1455 return gst_caps_intersect_zig_zag (caps1, caps2);
1460 * gst_caps_intersect:
1461 * @caps1: a #GstCaps to intersect
1462 * @caps2: a #GstCaps to intersect
1464 * Creates a new #GstCaps that contains all the formats that are common
1465 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1467 * Returns: the new #GstCaps
1470 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1472 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1476 /* subtract operation */
1480 const GstStructure *subtract_from;
1486 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1489 SubtractionEntry *e = user_data;
1490 GValue subtraction = { 0, };
1491 const GValue *other;
1492 GstStructure *structure;
1494 other = gst_structure_id_get_value (e->subtract_from, field_id);
1498 if (!gst_value_subtract (&subtraction, other, value))
1500 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1501 g_value_unset (&subtraction);
1504 structure = gst_structure_copy (e->subtract_from);
1505 gst_structure_id_set_value (structure, field_id, &subtraction);
1506 g_value_unset (&subtraction);
1507 e->put_into = g_slist_prepend (e->put_into, structure);
1513 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1514 const GstStructure * subtrahend)
1519 e.subtract_from = minuend;
1522 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1523 gst_caps_structure_subtract_field, &e);
1529 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1530 gst_structure_free (walk->data);
1532 g_slist_free (e.put_into);
1538 * gst_caps_subtract:
1539 * @minuend: #GstCaps to substract from
1540 * @subtrahend: #GstCaps to substract
1542 * Subtracts the @subtrahend from the @minuend.
1543 * <note>This function does not work reliably if optional properties for caps
1544 * are included on one caps and omitted on the other.</note>
1546 * Returns: the resulting caps
1549 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1554 GstCaps *dest = NULL, *src;
1556 g_return_val_if_fail (minuend != NULL, NULL);
1557 g_return_val_if_fail (subtrahend != NULL, NULL);
1559 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1560 return gst_caps_new_empty ();
1562 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1563 return _gst_caps_copy (minuend);
1565 /* FIXME: Do we want this here or above?
1566 The reason we need this is that there is no definition about what
1567 ANY means for specific types, so it's not possible to reduce ANY partially
1568 You can only remove everything or nothing and that is done above.
1569 Note: there's a test that checks this behaviour. */
1570 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1571 sublen = subtrahend->structs->len;
1572 g_assert (sublen > 0);
1574 src = _gst_caps_copy (minuend);
1575 for (i = 0; i < sublen; i++) {
1578 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1580 gst_caps_unref (src);
1583 dest = gst_caps_new_empty ();
1584 srclen = src->structs->len;
1585 for (j = 0; j < srclen; j++) {
1586 min = gst_caps_get_structure_unchecked (src, j);
1587 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1590 if (gst_caps_structure_subtract (&list, min, sub)) {
1593 for (walk = list; walk; walk = g_slist_next (walk)) {
1594 gst_caps_append_structure_unchecked (dest,
1595 (GstStructure *) walk->data);
1597 g_slist_free (list);
1599 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1602 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1605 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1606 gst_caps_unref (src);
1611 gst_caps_unref (src);
1612 gst_caps_do_simplify (dest);
1616 /* union operation */
1619 static GstStructure *
1620 gst_caps_structure_union (const GstStructure * struct1,
1621 const GstStructure * struct2)
1625 const GstStructureField *field1;
1626 const GstStructureField *field2;
1629 /* FIXME this doesn't actually work */
1631 if (struct1->name != struct2->name)
1634 dest = gst_structure_id_empty_new (struct1->name);
1636 for (i = 0; i < struct1->fields->len; i++) {
1637 GValue dest_value = { 0 };
1639 field1 = GST_STRUCTURE_FIELD (struct1, i);
1640 field2 = gst_structure_id_get_field (struct2, field1->name);
1642 if (field2 == NULL) {
1645 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1646 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1649 ret = gst_value_compare (&field1->value, &field2->value);
1660 * @caps1: a #GstCaps to union
1661 * @caps2: a #GstCaps to union
1663 * Creates a new #GstCaps that contains all the formats that are in
1664 * either @caps1 and @caps2.
1666 * Returns: the new #GstCaps
1669 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1674 /* NULL pointers are no correct GstCaps */
1675 g_return_val_if_fail (caps1 != NULL, NULL);
1676 g_return_val_if_fail (caps2 != NULL, NULL);
1678 if (CAPS_IS_EMPTY (caps1))
1679 return _gst_caps_copy (caps2);
1681 if (CAPS_IS_EMPTY (caps2))
1682 return _gst_caps_copy (caps1);
1684 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1685 return gst_caps_new_any ();
1687 dest1 = _gst_caps_copy (caps1);
1688 dest2 = _gst_caps_copy (caps2);
1689 gst_caps_append (dest1, dest2);
1691 gst_caps_do_simplify (dest1);
1695 /* normalize/simplify operations */
1697 typedef struct _NormalizeForeach
1700 GstStructure *structure;
1705 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1707 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1711 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1712 guint len = gst_value_list_get_size (value);
1713 for (i = 1; i < len; i++) {
1714 const GValue *v = gst_value_list_get_value (value, i);
1715 GstStructure *structure = gst_structure_copy (nf->structure);
1717 gst_structure_id_set_value (structure, field_id, v);
1718 gst_caps_append_structure_unchecked (nf->caps, structure);
1721 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1722 gst_structure_id_set_value (nf->structure, field_id, &val);
1723 g_value_unset (&val);
1731 * gst_caps_normalize:
1732 * @caps: a #GstCaps to normalize
1734 * Creates a new #GstCaps that represents the same set of formats as
1735 * @caps, but contains no lists. Each list is expanded into separate
1738 * Returns: the new #GstCaps
1741 gst_caps_normalize (const GstCaps * caps)
1743 NormalizeForeach nf;
1747 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1749 newcaps = _gst_caps_copy (caps);
1752 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1753 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1755 while (!gst_structure_foreach (nf.structure,
1756 gst_caps_normalize_foreach, &nf));
1763 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1766 const GstStructure *struct1 = *((const GstStructure **) one);
1767 const GstStructure *struct2 = *((const GstStructure **) two);
1769 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1770 So what's the best way? */
1771 ret = strcmp (gst_structure_get_name (struct1),
1772 gst_structure_get_name (struct2));
1776 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1783 GstStructure *compare;
1788 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1791 UnionField *u = user_data;
1792 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1796 g_value_unset (&u->value);
1799 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1802 g_value_unset (&u->value);
1806 gst_value_union (&u->value, val, value);
1811 gst_caps_structure_simplify (GstStructure ** result,
1812 const GstStructure * simplify, GstStructure * compare)
1815 UnionField field = { 0, {0,}, NULL };
1817 /* try to subtract to get a real subset */
1818 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1819 if (list == NULL) { /* no result */
1822 } else if (list->next == NULL) { /* one result */
1823 *result = list->data;
1824 g_slist_free (list);
1826 } else { /* multiple results */
1827 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1828 g_slist_free (list);
1833 /* try to union both structs */
1834 field.compare = compare;
1835 if (gst_structure_foreach ((GstStructure *) simplify,
1836 gst_caps_structure_figure_out_union, &field)) {
1837 gboolean ret = FALSE;
1839 /* now we know all of simplify's fields are the same in compare
1840 * but at most one field: field.name */
1841 if (G_IS_VALUE (&field.value)) {
1842 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1843 gst_structure_id_set_value (compare, field.name, &field.value);
1847 g_value_unset (&field.value);
1848 } else if (gst_structure_n_fields (simplify) <=
1849 gst_structure_n_fields (compare)) {
1850 /* compare is just more specific, will be optimized away later */
1851 /* FIXME: do this here? */
1852 GST_LOG ("found a case that will be optimized later.");
1854 gchar *one = gst_structure_to_string (simplify);
1855 gchar *two = gst_structure_to_string (compare);
1858 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1870 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1871 GstStructure * new, gint i)
1873 gst_structure_set_parent_refcount (old, NULL);
1874 gst_structure_free (old);
1875 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1876 g_ptr_array_index (caps->structs, i) = new;
1880 * gst_caps_do_simplify:
1881 * @caps: a #GstCaps to simplify
1883 * Modifies the given @caps inplace into a representation that represents the
1884 * same set of formats, but in a simpler form. Component structures that are
1885 * identical are merged. Component structures that have values that can be
1886 * merged are also merged.
1888 * Returns: TRUE, if the caps could be simplified
1891 gst_caps_do_simplify (GstCaps * caps)
1893 GstStructure *simplify, *compare, *result = NULL;
1895 gboolean changed = FALSE;
1897 g_return_val_if_fail (caps != NULL, FALSE);
1898 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1900 if (gst_caps_get_size (caps) < 2)
1903 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1905 start = caps->structs->len - 1;
1906 for (i = caps->structs->len - 1; i >= 0; i--) {
1907 simplify = gst_caps_get_structure_unchecked (caps, i);
1908 if (gst_structure_get_name_id (simplify) !=
1909 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1912 for (j = start; j >= 0; j--) {
1915 compare = gst_caps_get_structure_unchecked (caps, j);
1916 if (gst_structure_get_name_id (simplify) !=
1917 gst_structure_get_name_id (compare)) {
1920 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1922 gst_caps_switch_structures (caps, simplify, result, i);
1925 gst_caps_remove_structure (caps, i);
1937 /* gst_caps_do_simplify (caps); */
1945 * @caps: (inout) (transfer full): a pointer to #GstCaps
1946 * @newcaps: a #GstCaps to replace *caps
1948 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1949 * pointed to by @caps, if applicable, then modifies @caps to point to
1950 * @newcaps. An additional ref on @newcaps is taken.
1952 * This function does not take any locks so you might want to lock
1953 * the object owning @caps pointer.
1956 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1960 g_return_if_fail (caps != NULL);
1964 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1966 if (newcaps != oldcaps) {
1968 gst_caps_ref (newcaps);
1973 gst_caps_unref (oldcaps);
1978 * gst_caps_to_string:
1981 * Converts @caps to a string representation. This string representation
1982 * can be converted back to a #GstCaps by gst_caps_from_string().
1984 * For debugging purposes its easier to do something like this:
1986 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1988 * This prints the caps in human readble form.
1990 * Returns: (transfer full): a newly allocated string representing @caps.
1993 gst_caps_to_string (const GstCaps * caps)
1995 guint i, slen, clen;
1998 /* NOTE: This function is potentially called by the debug system,
1999 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2000 * should be careful to avoid recursion. This includes any functions
2001 * called by gst_caps_to_string. In particular, calls should
2002 * not use the GST_PTR_FORMAT extension. */
2005 return g_strdup ("NULL");
2007 if (CAPS_IS_ANY (caps)) {
2008 return g_strdup ("ANY");
2010 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2011 return g_strdup ("EMPTY");
2014 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2016 clen = caps->structs->len;
2017 for (i = 0; i < clen; i++) {
2019 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
2023 s = g_string_sized_new (slen);
2024 for (i = 0; i < clen; i++) {
2025 GstStructure *structure;
2028 /* ';' is now added by gst_structure_to_string */
2029 g_string_append_c (s, ' ');
2032 structure = gst_caps_get_structure_unchecked (caps, i);
2033 priv_gst_structure_append_to_gstring (structure, s);
2035 if (s->len && s->str[s->len - 1] == ';') {
2036 /* remove latest ';' */
2037 s->str[--s->len] = '\0';
2039 return g_string_free (s, FALSE);
2043 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2045 GstStructure *structure;
2048 if (strcmp ("ANY", string) == 0) {
2049 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
2052 if (strcmp ("EMPTY", string) == 0) {
2056 structure = gst_structure_from_string (string, &s);
2057 if (structure == NULL) {
2060 gst_caps_append_structure_unchecked (caps, structure);
2064 while (g_ascii_isspace (*s))
2069 structure = gst_structure_from_string (s, &s);
2070 if (structure == NULL) {
2073 gst_caps_append_structure_unchecked (caps, structure);
2081 * gst_caps_from_string:
2082 * @string: a string to convert to #GstCaps
2084 * Converts @caps from a string representation.
2086 * Returns: (transfer full): a newly allocated #GstCaps
2089 gst_caps_from_string (const gchar * string)
2093 g_return_val_if_fail (string, FALSE);
2095 caps = gst_caps_new_empty ();
2096 if (gst_caps_from_string_inplace (caps, string)) {
2099 gst_caps_unref (caps);
2105 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2107 g_return_if_fail (G_IS_VALUE (src_value));
2108 g_return_if_fail (G_IS_VALUE (dest_value));
2109 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2110 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2111 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2113 dest_value->data[0].v_pointer =
2114 gst_caps_to_string (src_value->data[0].v_pointer);