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 registry along with
30 * a description of the element.
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", G_TYPE_DOUBLE, 25.0,
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 2005-11-23 (0.9.5)
72 #include "gst_private.h"
75 #define DEBUG_REFCOUNT
77 #define CAPS_POISON(caps) G_STMT_START{ \
79 GstCaps *_newcaps = gst_caps_copy (caps); \
80 gst_caps_unref(caps); \
84 #define STRUCTURE_POISON(structure) G_STMT_START{ \
86 GstStructure *_newstruct = gst_structure_copy (structure); \
87 gst_structure_free(structure); \
88 structure = _newstruct; \
91 #define IS_WRITABLE(caps) \
92 (g_atomic_int_get (&(caps)->refcount) == 1)
95 static void gst_caps_transform_to_string (const GValue * src_value,
97 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
98 const gchar * string);
99 static GstCaps *gst_caps_copy_conditional (GstCaps * src);
102 gst_caps_get_type (void)
104 static GType gst_caps_type = 0;
106 if (G_UNLIKELY (gst_caps_type == 0)) {
107 gst_caps_type = g_boxed_type_register_static ("GstCaps",
108 (GBoxedCopyFunc) gst_caps_copy_conditional,
109 (GBoxedFreeFunc) gst_caps_unref);
111 g_value_register_transform_func (gst_caps_type,
112 G_TYPE_STRING, gst_caps_transform_to_string);
115 return gst_caps_type;
118 /* creation/deletion */
121 * gst_caps_new_empty:
123 * Creates a new #GstCaps that is empty. That is, the returned
124 * #GstCaps contains no media formats.
125 * Caller is responsible for unreffing the returned caps.
127 * Returns: the new #GstCaps
130 gst_caps_new_empty (void)
132 GstCaps *caps = g_new0 (GstCaps, 1);
134 g_atomic_int_inc (&caps->refcount);
135 caps->type = GST_TYPE_CAPS;
136 caps->structs = g_ptr_array_new ();
138 #ifdef DEBUG_REFCOUNT
139 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
148 * Creates a new #GstCaps that indicates that it is compatible with
151 * Returns: the new #GstCaps
154 gst_caps_new_any (void)
156 GstCaps *caps = gst_caps_new_empty ();
158 caps->flags = GST_CAPS_FLAGS_ANY;
164 * gst_caps_new_simple:
165 * @media_type: the media type of the structure
166 * @fieldname: first field to set
167 * @...: additional arguments
169 * Creates a new #GstCaps that contains one #GstStructure. The
170 * structure is defined by the arguments, which have the same format
171 * as gst_structure_new().
172 * Caller is responsible for unreffing the returned caps.
174 * Returns: the new #GstCaps
177 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
180 GstStructure *structure;
183 caps = gst_caps_new_empty ();
185 va_start (var_args, fieldname);
186 structure = gst_structure_new_valist (media_type, fieldname, var_args);
189 gst_caps_append_structure (caps, structure);
196 * @struct1: the first structure to add
197 * @...: additional structures to add
199 * Creates a new #GstCaps and adds all the structures listed as
200 * arguments. The list must be NULL-terminated. The structures
201 * are not copied; the returned #GstCaps owns the structures.
203 * Returns: the new #GstCaps
206 gst_caps_new_full (GstStructure * struct1, ...)
211 va_start (var_args, struct1);
212 caps = gst_caps_new_full_valist (struct1, var_args);
219 * gst_caps_new_full_valist:
220 * @structure: the first structure to add
221 * @var_args: additional structures to add
223 * Creates a new #GstCaps and adds all the structures listed as
224 * arguments. The list must be NULL-terminated. The structures
225 * are not copied; the returned #GstCaps owns the structures.
227 * Returns: the new #GstCaps
230 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
234 caps = gst_caps_new_empty ();
237 gst_caps_append_structure (caps, structure);
238 structure = va_arg (var_args, GstStructure *);
246 * @caps: the #GstCaps to copy
248 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
249 * refcount of 1, owned by the caller. The structures are copied as well.
251 * Note that this function is the semantic equivalent of a gst_caps_ref()
252 * followed by a gst_caps_make_writable(). If you only want to hold on to a
253 * reference to the data, you should use gst_caps_ref().
255 * When you are finished with the caps, call gst_caps_unref() on it.
257 * Returns: the new #GstCaps
260 gst_caps_copy (const GstCaps * caps)
263 GstStructure *structure;
266 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
268 newcaps = gst_caps_new_empty ();
269 newcaps->flags = caps->flags;
271 for (i = 0; i < caps->structs->len; i++) {
272 structure = gst_caps_get_structure (caps, i);
273 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
280 _gst_caps_free (GstCaps * caps)
282 GstStructure *structure;
285 /* The refcount must be 0, but since we're only called by gst_caps_unref,
286 * don't bother testing. */
288 for (i = 0; i < caps->structs->len; i++) {
289 structure = (GstStructure *) gst_caps_get_structure (caps, i);
290 gst_structure_set_parent_refcount (structure, NULL);
291 gst_structure_free (structure);
293 g_ptr_array_free (caps->structs, TRUE);
295 memset (caps, 0xff, sizeof (GstCaps));
301 * gst_caps_make_writable:
302 * @caps: the #GstCaps to make writable
304 * Returns a writable copy of @caps.
306 * If there is only one reference count on @caps, the caller must be the owner,
307 * and so this function will return the caps object unchanged. If on the other
308 * hand there is more than one reference on the object, a new caps object will
309 * be returned. The caller's reference on @caps will be removed, and instead the
310 * caller will own a reference to the returned object.
312 * In short, this function unrefs the caps in the argument and refs the caps
313 * that it returns. Don't access the argument after calling this function. See
314 * also: gst_caps_ref().
316 * Returns: the same #GstCaps object.
319 gst_caps_make_writable (GstCaps * caps)
323 g_return_val_if_fail (caps != NULL, NULL);
325 /* we are the only instance reffing this caps */
326 if (g_atomic_int_get (&caps->refcount) == 1)
330 copy = gst_caps_copy (caps);
331 gst_caps_unref (caps);
338 * @caps: the #GstCaps to reference
340 * Add a reference to a #GstCaps object.
342 * From this point on, until the caller calls gst_caps_unref() or
343 * gst_caps_make_writable(), it is guaranteed that the caps object will not
344 * change. This means its structures won't change, etc. To use a #GstCaps
345 * object, you must always have a refcount on it -- either the one made
346 * implicitly by gst_caps_new(), or via taking one explicitly with this
349 * Returns: the same #GstCaps object.
352 gst_caps_ref (GstCaps * caps)
354 g_return_val_if_fail (caps != NULL, NULL);
356 #ifdef DEBUG_REFCOUNT
357 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
358 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) + 1);
360 g_return_val_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0, NULL);
362 g_atomic_int_inc (&caps->refcount);
369 * @caps: the #GstCaps to unref
371 * Unref a #GstCaps and and free all its structures and the
372 * structures' values when the refcount reaches 0.
375 gst_caps_unref (GstCaps * caps)
377 g_return_if_fail (caps != NULL);
379 #ifdef DEBUG_REFCOUNT
380 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
381 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) - 1);
384 g_return_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0);
386 /* if we ended up with the refcount at zero, free the caps */
387 if (g_atomic_int_dec_and_test (&caps->refcount)) {
388 _gst_caps_free (caps);
393 gst_static_caps_get_type (void)
395 static GType staticcaps_type = 0;
397 if (G_UNLIKELY (staticcaps_type == 0)) {
398 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
400 return staticcaps_type;
405 * gst_static_caps_get:
406 * @static_caps: the #GstStaticCaps to convert
408 * Converts a #GstStaticCaps to a #GstCaps.
410 * Returns: A pointer to the #GstCaps. Unref after usage. Since the
411 * core holds an additional ref to the returned caps,
412 * use gst_caps_make_writable() on the returned caps to modify it.
415 gst_static_caps_get (GstStaticCaps * static_caps)
417 GstCaps *caps = (GstCaps *) static_caps;
420 if (caps->type == 0) {
421 if (static_caps->string == NULL) {
422 g_warning ("static caps is NULL");
426 caps->type = GST_TYPE_CAPS;
427 /* initialize the caps to a refcount of 1 so the caps can be writable... */
428 gst_atomic_int_set (&caps->refcount, 1);
429 caps->structs = g_ptr_array_new ();
430 ret = gst_caps_from_string_inplace (caps, static_caps->string);
433 g_critical ("Could not convert static caps \"%s\"", static_caps->string);
436 /* ref the caps, makes it not writable */
444 static GstStructure *
445 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
447 /* don't use index_fast, gst_caps_simplify relies on the order */
448 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
450 gst_structure_set_parent_refcount (s, NULL);
456 * @caps1: the #GstCaps that will be appended to
457 * @caps2: the #GstCaps to append
459 * Appends the structures contained in @caps2 to @caps1. The structures in
460 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
461 * freed. If either caps is ANY, the resulting caps will be ANY.
464 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
466 GstStructure *structure;
469 g_return_if_fail (GST_IS_CAPS (caps1));
470 g_return_if_fail (GST_IS_CAPS (caps2));
471 g_return_if_fail (IS_WRITABLE (caps1));
472 g_return_if_fail (IS_WRITABLE (caps2));
477 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2)) {
478 /* FIXME: this leaks */
479 caps1->flags |= GST_CAPS_FLAGS_ANY;
480 for (i = caps2->structs->len - 1; i >= 0; i--) {
481 structure = gst_caps_remove_and_get_structure (caps2, i);
482 gst_structure_free (structure);
485 int len = caps2->structs->len;
487 for (i = 0; i < len; i++) {
488 structure = gst_caps_remove_and_get_structure (caps2, 0);
489 gst_caps_append_structure (caps1, structure);
492 gst_caps_unref (caps2); /* guaranteed to free it */
496 * gst_caps_append_structure:
497 * @caps: the #GstCaps that will be appended to
498 * @structure: the #GstStructure to append
500 * Appends @structure to @caps. The structure is not copied; @caps
501 * becomes the owner of @structure.
504 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
506 g_return_if_fail (GST_IS_CAPS (caps));
507 g_return_if_fail (IS_WRITABLE (caps));
510 g_return_if_fail (structure->parent_refcount == NULL);
513 STRUCTURE_POISON (structure);
516 gst_structure_set_parent_refcount (structure, &caps->refcount);
517 g_ptr_array_add (caps->structs, structure);
522 * gst_caps_remove_structure:
523 * @caps: the #GstCaps to remove from
524 * @idx: Index of the structure to remove
526 * removes the stucture with the given index from the list of structures
527 * contained in @caps.
530 gst_caps_remove_structure (GstCaps * caps, guint idx)
532 GstStructure *structure;
534 g_return_if_fail (caps != NULL);
535 g_return_if_fail (idx <= gst_caps_get_size (caps));
536 g_return_if_fail (IS_WRITABLE (caps));
538 structure = gst_caps_remove_and_get_structure (caps, idx);
539 gst_structure_free (structure);
543 * gst_caps_split_one:
546 * This function is not implemented.
551 gst_caps_split_one (GstCaps * caps)
554 g_critical ("unimplemented");
563 * Gets the number of structures contained in @caps.
565 * Returns: the number of structures that @caps contains
568 gst_caps_get_size (const GstCaps * caps)
570 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
572 return caps->structs->len;
576 * gst_caps_get_structure:
578 * @index: the index of the structure
580 * Finds the structure in @caps that has the index @index, and
583 * WARNING: This function takes a const GstCaps *, but returns a
584 * non-const GstStructure *. This is for programming convenience --
585 * the caller should be aware that structures inside a constant
586 * #GstCaps should not be modified.
588 * Returns: a pointer to the #GstStructure corresponding to @index
591 gst_caps_get_structure (const GstCaps * caps, guint index)
593 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
594 g_return_val_if_fail (index >= 0, NULL);
595 g_return_val_if_fail (index < caps->structs->len, NULL);
597 return g_ptr_array_index (caps->structs, index);
602 * @caps: the #GstCaps to copy
603 * @nth: the nth structure to copy
605 * Creates a new #GstCaps and appends a copy of the nth structure
606 * contained in @caps.
608 * Returns: the new #GstCaps
611 gst_caps_copy_nth (const GstCaps * caps, guint nth)
614 GstStructure *structure;
616 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
618 newcaps = gst_caps_new_empty ();
619 newcaps->flags = caps->flags;
621 if (caps->structs->len > nth) {
622 structure = gst_caps_get_structure (caps, nth);
623 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
631 * @caps: the #GstCaps to truncate
633 * Destructively discard all but the first structure from @caps. Useful when
634 * fixating. @caps must be writable.
637 gst_caps_truncate (GstCaps * caps)
641 g_return_if_fail (GST_IS_CAPS (caps));
642 g_return_if_fail (IS_WRITABLE (caps));
644 i = caps->structs->len - 1;
647 gst_caps_remove_structure (caps, i--);
651 * gst_caps_set_simple:
652 * @caps: the #GstCaps to set
653 * @field: first field to set
654 * @...: additional parameters
656 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
657 * only has one structure. The arguments must be passed in the same
658 * manner as gst_structure_set(), and be NULL-terminated.
661 gst_caps_set_simple (GstCaps * caps, char *field, ...)
663 GstStructure *structure;
666 g_return_if_fail (GST_IS_CAPS (caps));
667 g_return_if_fail (caps->structs->len == 1);
668 g_return_if_fail (IS_WRITABLE (caps));
670 structure = gst_caps_get_structure (caps, 0);
672 va_start (var_args, field);
673 gst_structure_set_valist (structure, field, var_args);
678 * gst_caps_set_simple_valist:
679 * @caps: the #GstCaps to copy
680 * @field: first field to set
681 * @varargs: additional parameters
683 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
684 * only has one structure. The arguments must be passed in the same
685 * manner as gst_structure_set(), and be NULL-terminated.
688 gst_caps_set_simple_valist (GstCaps * caps, char *field, va_list varargs)
690 GstStructure *structure;
692 g_return_if_fail (GST_IS_CAPS (caps));
693 g_return_if_fail (caps->structs->len != 1);
694 g_return_if_fail (IS_WRITABLE (caps));
696 structure = gst_caps_get_structure (caps, 0);
698 gst_structure_set_valist (structure, field, varargs);
705 * @caps: the #GstCaps to test
707 * Determines if @caps represents any media format.
709 * Returns: TRUE if @caps represents any format.
712 gst_caps_is_any (const GstCaps * caps)
714 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
716 return (caps->flags & GST_CAPS_FLAGS_ANY);
721 * @caps: the #GstCaps to test
723 * Determines if @caps represents no media formats.
725 * Returns: TRUE if @caps represents no formats.
728 gst_caps_is_empty (const GstCaps * caps)
730 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
732 if (caps->flags & GST_CAPS_FLAGS_ANY)
735 return (caps->structs == NULL) || (caps->structs->len == 0);
739 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
742 return gst_value_is_fixed (value);
747 * @caps: the #GstCaps to test
749 * Fixed #GstCaps describe exactly one format, that is, they have exactly
750 * one structure, and each field in the structure describes a fixed type.
751 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
753 * Returns: TRUE if @caps is fixed
756 gst_caps_is_fixed (const GstCaps * caps)
758 GstStructure *structure;
760 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
762 if (caps->structs->len != 1)
765 structure = gst_caps_get_structure (caps, 0);
767 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
771 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
774 GstStructure *struct1 = (GstStructure *) data;
775 const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
779 if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
787 * gst_caps_is_equal_fixed:
788 * @caps1: the #GstCaps to test
789 * @caps2: the #GstCaps to test
791 * Tests if two #GstCaps are equal. This function only works on fixed
794 * Returns: TRUE if the arguments represent the same format
797 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
799 GstStructure *struct1, *struct2;
801 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
802 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
804 struct1 = gst_caps_get_structure (caps1, 0);
805 struct2 = gst_caps_get_structure (caps2, 0);
807 if (struct1->name != struct2->name) {
810 if (struct1->fields->len != struct2->fields->len) {
814 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
819 * gst_caps_is_always_compatible:
820 * @caps1: the #GstCaps to test
821 * @caps2: the #GstCaps to test
823 * A given #GstCaps structure is always compatible with another if
824 * every media format that is in the first is also contained in the
825 * second. That is, @caps1 is a subset of @caps2.
827 * Returns: TRUE if @caps1 is a subset of @caps2.
830 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
832 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
833 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
835 return gst_caps_is_subset (caps1, caps2);
839 * gst_caps_is_subset:
840 * @subset: a #GstCaps
841 * @superset: a potentially greater #GstCaps
843 * Checks if all caps represented by @subset are also represented by @superset
844 * <note>This function does not work reliably if optional properties for caps
845 * are included on one caps and omitted on the other.</note>
847 * Returns: TRUE if @subset is a subset of @superset
850 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
855 g_return_val_if_fail (subset != NULL, FALSE);
856 g_return_val_if_fail (superset != NULL, FALSE);
858 if (gst_caps_is_empty (subset) || gst_caps_is_any (superset))
860 if (gst_caps_is_any (subset) || gst_caps_is_empty (superset))
863 caps = gst_caps_subtract (subset, superset);
864 ret = gst_caps_is_empty (caps);
865 gst_caps_unref (caps);
872 * @caps2: another #GstCaps
874 * Checks if the given caps represent the same set of caps.
875 * <note>This function does not work reliably if optional properties for caps
876 * are included on one caps and omitted on the other.</note>
878 * This function deals correctly with passing NULL for any of the caps.
880 * Returns: TRUE if both caps are equal.
883 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
885 /* NULL <-> NULL is allowed here */
889 /* one of them NULL => they are different (can't be both NULL because
890 * we checked that above) */
891 if (caps1 == NULL || caps2 == NULL)
894 if (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2))
895 return gst_caps_is_equal_fixed (caps1, caps2);
897 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
903 const GstStructure *intersect;
909 gst_caps_structure_intersect_field (GQuark id, const GValue * val1,
912 IntersectData *idata = (IntersectData *) data;
913 GValue dest_value = { 0 };
914 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
917 gst_structure_id_set_value (idata->dest, id, val1);
918 } else if (idata->first_run) {
919 if (gst_value_intersect (&dest_value, val1, val2)) {
920 gst_structure_id_set_value (idata->dest, id, &dest_value);
921 g_value_unset (&dest_value);
930 static GstStructure *
931 gst_caps_structure_intersect (const GstStructure * struct1,
932 const GstStructure * struct2)
936 g_return_val_if_fail (struct1 != NULL, NULL);
937 g_return_val_if_fail (struct2 != NULL, NULL);
939 if (struct1->name != struct2->name)
942 data.dest = gst_structure_id_empty_new (struct1->name);
943 data.intersect = struct2;
944 data.first_run = TRUE;
945 if (!gst_structure_foreach ((GstStructure *) struct1,
946 gst_caps_structure_intersect_field, &data))
949 data.intersect = struct1;
950 data.first_run = FALSE;
951 if (!gst_structure_foreach ((GstStructure *) struct2,
952 gst_caps_structure_intersect_field, &data))
958 gst_structure_free (data.dest);
963 static GstStructure *
964 gst_caps_structure_union (const GstStructure * struct1,
965 const GstStructure * struct2)
969 const GstStructureField *field1;
970 const GstStructureField *field2;
973 /* FIXME this doesn't actually work */
975 if (struct1->name != struct2->name)
978 dest = gst_structure_id_empty_new (struct1->name);
980 for (i = 0; i < struct1->fields->len; i++) {
981 GValue dest_value = { 0 };
983 field1 = GST_STRUCTURE_FIELD (struct1, i);
984 field2 = gst_structure_id_get_field (struct2, field1->name);
986 if (field2 == NULL) {
989 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
990 gst_structure_set_value (dest, g_quark_to_string (field1->name),
993 ret = gst_value_compare (&field1->value, &field2->value);
1005 * gst_caps_intersect:
1006 * @caps1: a #GstCaps to intersect
1007 * @caps2: a #GstCaps to intersect
1009 * Creates a new #GstCaps that contains all the formats that are common
1010 * to both @caps1 and @caps2.
1012 * Returns: the new #GstCaps
1015 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1017 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1020 GstStructure *struct1;
1021 GstStructure *struct2;
1023 GstStructure *istruct;
1025 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1026 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1028 if (gst_caps_is_empty (caps1) || gst_caps_is_empty (caps2)) {
1029 return gst_caps_new_empty ();
1031 if (gst_caps_is_any (caps1))
1032 return gst_caps_copy (caps2);
1033 if (gst_caps_is_any (caps2))
1034 return gst_caps_copy (caps1);
1036 dest = gst_caps_new_empty ();
1038 /* run zigzag on top line then right line, this preserves the caps order
1039 * much better than a simple loop.
1041 * This algorithm zigzags over the caps structures as demonstrated in
1042 * the folowing matrix:
1050 * First we iterate over the caps1 structures (top line) intersecting
1051 * the structures diagonally down, then we iterate over the caps2
1054 for (i = 0; i < caps1->structs->len + caps2->structs->len - 1; i++) {
1055 /* caps1 index goes from 0 to caps1->structs->len-1 */
1056 j = MIN (i, caps1->structs->len - 1);
1057 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1058 * up from 1 to caps2->structs->len - 1 */
1061 /* now run the diagonal line, end condition is the left or bottom
1063 while (k < caps2->structs->len) {
1064 struct1 = gst_caps_get_structure (caps1, j);
1065 struct2 = gst_caps_get_structure (caps2, k);
1067 istruct = gst_caps_structure_intersect (struct1, struct2);
1069 gst_caps_append_structure (dest, istruct);
1070 /* move down left */
1073 break; /* so we don't roll back to G_MAXUINT */
1082 const GstStructure *subtract_from;
1089 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1092 SubtractionEntry *e = user_data;
1093 GValue subtraction = { 0, };
1094 const GValue *other;
1095 GstStructure *structure;
1097 other = gst_structure_id_get_value (e->subtract_from, field_id);
1101 if (!gst_value_subtract (&subtraction, other, value))
1103 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1104 g_value_unset (&subtraction);
1107 structure = gst_structure_copy (e->subtract_from);
1108 gst_structure_id_set_value (structure, field_id, &subtraction);
1109 g_value_unset (&subtraction);
1110 e->put_into = g_slist_prepend (e->put_into, structure);
1116 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1117 const GstStructure * subtrahend)
1122 e.subtract_from = minuend;
1125 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1126 gst_caps_structure_subtract_field, &e);
1132 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1133 gst_structure_free (walk->data);
1135 g_slist_free (e.put_into);
1141 * gst_caps_subtract:
1142 * @minuend: #GstCaps to substract from
1143 * @subtrahend: #GstCaps to substract
1145 * Subtracts the @subtrahend from the @minuend.
1146 * <note>This function does not work reliably if optional properties for caps
1147 * are included on one caps and omitted on the other.</note>
1149 * Returns: the resulting caps
1152 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1157 GstCaps *dest = NULL, *src;
1159 g_return_val_if_fail (minuend != NULL, NULL);
1160 g_return_val_if_fail (subtrahend != NULL, NULL);
1162 if (gst_caps_is_empty (minuend) || gst_caps_is_any (subtrahend)) {
1163 return gst_caps_new_empty ();
1165 if (gst_caps_is_empty (subtrahend))
1166 return gst_caps_copy (minuend);
1168 /* FIXME: Do we want this here or above?
1169 The reason we need this is that there is no definition about what
1170 ANY means for specific types, so it's not possible to reduce ANY partially
1171 You can only remove everything or nothing and that is done above.
1172 Note: there's a test that checks this behaviour. */
1173 g_return_val_if_fail (!gst_caps_is_any (minuend), NULL);
1174 g_assert (subtrahend->structs->len > 0);
1176 src = gst_caps_copy (minuend);
1177 for (i = 0; i < subtrahend->structs->len; i++) {
1178 sub = gst_caps_get_structure (subtrahend, i);
1180 gst_caps_unref (src);
1183 dest = gst_caps_new_empty ();
1184 for (j = 0; j < src->structs->len; j++) {
1185 min = gst_caps_get_structure (src, j);
1186 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1189 if (gst_caps_structure_subtract (&list, min, sub)) {
1192 for (walk = list; walk; walk = g_slist_next (walk)) {
1193 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1195 g_slist_free (list);
1197 gst_caps_append_structure (dest, gst_structure_copy (min));
1200 gst_caps_append_structure (dest, gst_structure_copy (min));
1203 if (gst_caps_is_empty (dest)) {
1204 gst_caps_unref (src);
1209 gst_caps_unref (src);
1210 gst_caps_do_simplify (dest);
1216 * @caps1: a #GstCaps to union
1217 * @caps2: a #GstCaps to union
1219 * Creates a new #GstCaps that contains all the formats that are in
1220 * either @caps1 and @caps2.
1222 * Returns: the new #GstCaps
1225 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1230 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2))
1231 return gst_caps_new_any ();
1233 dest1 = gst_caps_copy (caps1);
1234 dest2 = gst_caps_copy (caps2);
1235 gst_caps_append (dest1, dest2);
1237 gst_caps_do_simplify (dest1);
1241 typedef struct _NormalizeForeach
1244 GstStructure *structure;
1249 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1251 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1255 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1256 for (i = 1; i < gst_value_list_get_size (value); i++) {
1257 const GValue *v = gst_value_list_get_value (value, i);
1258 GstStructure *structure = gst_structure_copy (nf->structure);
1260 gst_structure_id_set_value (structure, field_id, v);
1261 gst_caps_append_structure (nf->caps, structure);
1264 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1265 gst_structure_id_set_value (nf->structure, field_id, &val);
1266 g_value_unset (&val);
1274 * gst_caps_normalize:
1275 * @caps: a #GstCaps to normalize
1277 * Creates a new #GstCaps that represents the same set of formats as
1278 * @caps, but contains no lists. Each list is expanded into separate
1281 * Returns: the new #GstCaps
1284 gst_caps_normalize (const GstCaps * caps)
1286 NormalizeForeach nf;
1290 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1292 newcaps = gst_caps_copy (caps);
1295 for (i = 0; i < newcaps->structs->len; i++) {
1296 nf.structure = gst_caps_get_structure (newcaps, i);
1298 while (!gst_structure_foreach (nf.structure,
1299 gst_caps_normalize_foreach, &nf));
1306 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1309 const GstStructure *struct1 = *((const GstStructure **) one);
1310 const GstStructure *struct2 = *((const GstStructure **) two);
1312 /* FIXME: this orders aphabetically, but ordering the quarks might be faster
1313 So what's the best way? */
1314 ret = strcmp (gst_structure_get_name (struct1),
1315 gst_structure_get_name (struct2));
1319 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1323 * gst_caps_simplify:
1324 * @caps: a #GstCaps to simplify
1326 * Creates a new #GstCaps that represents the same set of formats as
1327 * @caps, but simpler. Component structures that are identical are
1328 * merged. Component structures that have ranges or lists that can
1329 * be merged are also merged.
1331 * Returns: the new #GstCaps
1334 gst_caps_simplify (const GstCaps * caps)
1338 g_return_val_if_fail (caps != NULL, NULL);
1340 ret = gst_caps_copy (caps);
1341 gst_caps_do_simplify (ret);
1350 GstStructure *compare;
1355 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1358 UnionField *u = user_data;
1359 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1363 g_value_unset (&u->value);
1366 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1369 g_value_unset (&u->value);
1373 gst_value_union (&u->value, val, value);
1378 gst_caps_structure_simplify (GstStructure ** result,
1379 const GstStructure * simplify, GstStructure * compare)
1382 UnionField field = { 0, {0,}, NULL };
1384 /* try to subtract to get a real subset */
1385 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1386 switch (g_slist_length (list)) {
1391 *result = list->data;
1392 g_slist_free (list);
1398 for (walk = list; walk; walk = g_slist_next (walk)) {
1399 gst_structure_free (walk->data);
1401 g_slist_free (list);
1407 /* try to union both structs */
1408 field.compare = compare;
1409 if (gst_structure_foreach ((GstStructure *) simplify,
1410 gst_caps_structure_figure_out_union, &field)) {
1411 gboolean ret = FALSE;
1413 /* now we know all of simplify's fields are the same in compare
1414 * but at most one field: field.name */
1415 if (G_IS_VALUE (&field.value)) {
1416 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1417 gst_structure_id_set_value (compare, field.name, &field.value);
1421 g_value_unset (&field.value);
1422 } else if (gst_structure_n_fields (simplify) <=
1423 gst_structure_n_fields (compare)) {
1424 /* compare is just more specific, will be optimized away later */
1425 /* FIXME: do this here? */
1426 GST_LOG ("found a case that will be optimized later.");
1428 gchar *one = gst_structure_to_string (simplify);
1429 gchar *two = gst_structure_to_string (compare);
1432 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1444 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1445 GstStructure * new, gint i)
1447 gst_structure_set_parent_refcount (old, NULL);
1448 gst_structure_free (old);
1449 gst_structure_set_parent_refcount (new, &caps->refcount);
1450 g_ptr_array_index (caps->structs, i) = new;
1454 * gst_caps_do_simplify:
1455 * @caps: a #GstCaps to simplify
1457 * Modifies the given @caps inplace into a representation that represents the
1458 * same set of formats, but in a simpler form. Component structures that are
1459 * identical are merged. Component structures that have values that can be
1460 * merged are also merged.
1462 * Returns: TRUE, if the caps could be simplified
1465 gst_caps_do_simplify (GstCaps * caps)
1467 GstStructure *simplify, *compare, *result = NULL;
1469 gboolean changed = FALSE;
1471 g_return_val_if_fail (caps != NULL, FALSE);
1472 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1474 if (gst_caps_get_size (caps) < 2)
1477 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1479 start = caps->structs->len - 1;
1480 for (i = caps->structs->len - 1; i >= 0; i--) {
1481 simplify = gst_caps_get_structure (caps, i);
1482 if (gst_structure_get_name_id (simplify) !=
1483 gst_structure_get_name_id (gst_caps_get_structure (caps, start)))
1485 for (j = start; j >= 0; j--) {
1488 compare = gst_caps_get_structure (caps, j);
1489 if (gst_structure_get_name_id (simplify) !=
1490 gst_structure_get_name_id (compare)) {
1493 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1495 gst_caps_switch_structures (caps, simplify, result, i);
1498 gst_caps_remove_structure (caps, i);
1510 /* gst_caps_do_simplify (caps); */
1514 #ifndef GST_DISABLE_LOADSAVE
1516 * gst_caps_save_thyself:
1517 * @caps: a #GstCaps structure
1518 * @parent: a XML parent node
1520 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1522 * Returns: a XML node pointer
1525 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1527 char *s = gst_caps_to_string (caps);
1529 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1535 * gst_caps_load_thyself:
1536 * @parent: a XML node
1538 * Creates a #GstCaps from its XML serialization.
1540 * Returns: a new #GstCaps structure
1543 gst_caps_load_thyself (xmlNodePtr parent)
1545 if (strcmp ("caps", (char *) parent->name) == 0) {
1546 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1557 * @caps: a pointer to #GstCaps
1558 * @newcaps: a #GstCaps to replace *caps
1560 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1561 * pointed to by @caps, if applicable, then modifies @caps to point to
1562 * @newcaps. An additional ref on @newcaps is taken.
1565 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1569 #if 0 /* disable this, since too many plugins rely on undefined behavior */
1570 #ifdef USE_POISONING
1571 //if (newcaps) CAPS_POISON (newcaps);
1577 gst_caps_ref (newcaps);
1582 gst_caps_unref (oldcaps);
1586 * gst_caps_to_string:
1589 * Converts @caps to a string representation. This string representation
1590 * can be converted back to a #GstCaps by gst_caps_from_string().
1592 * Returns: a newly allocated string representing @caps.
1595 gst_caps_to_string (const GstCaps * caps)
1600 /* NOTE: This function is potentially called by the debug system,
1601 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1602 * should be careful to avoid recursion. This includes any functions
1603 * called by gst_caps_to_string. In particular, calls should
1604 * not use the GST_PTR_FORMAT extension. */
1607 return g_strdup ("NULL");
1609 if (gst_caps_is_any (caps)) {
1610 return g_strdup ("ANY");
1612 if (gst_caps_is_empty (caps)) {
1613 return g_strdup ("EMPTY");
1616 s = g_string_new ("");
1617 for (i = 0; i < caps->structs->len; i++) {
1618 GstStructure *structure;
1622 g_string_append (s, "; ");
1624 structure = gst_caps_get_structure (caps, i);
1625 sstr = gst_structure_to_string (structure);
1626 g_string_append (s, sstr);
1630 return g_string_free (s, FALSE);
1634 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1636 GstStructure *structure;
1639 g_return_val_if_fail (string, FALSE);
1640 if (strcmp ("ANY", string) == 0) {
1641 caps->flags = GST_CAPS_FLAGS_ANY;
1644 if (strcmp ("EMPTY", string) == 0) {
1648 structure = gst_structure_from_string (string, &s);
1649 if (structure == NULL) {
1652 gst_caps_append_structure (caps, structure);
1656 while (g_ascii_isspace (*s))
1658 structure = gst_structure_from_string (s, &s);
1659 if (structure == NULL) {
1662 gst_caps_append_structure (caps, structure);
1663 while (g_ascii_isspace (*s))
1675 * gst_caps_from_string:
1676 * @string: a string to convert to #GstCaps
1678 * Converts @caps from a string representation.
1680 * Returns: a newly allocated #GstCaps
1683 gst_caps_from_string (const gchar * string)
1687 caps = gst_caps_new_empty ();
1688 if (gst_caps_from_string_inplace (caps, string)) {
1691 gst_caps_unref (caps);
1697 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1699 g_return_if_fail (G_IS_VALUE (src_value));
1700 g_return_if_fail (G_IS_VALUE (dest_value));
1701 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1702 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1703 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1705 dest_value->data[0].v_pointer =
1706 gst_caps_to_string (src_value->data[0].v_pointer);
1710 gst_caps_copy_conditional (GstCaps * src)
1713 return gst_caps_ref (src);