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)
94 #if GLIB_CHECK_VERSION (2, 10, 0)
95 #define ALLOC_CAPS() g_slice_new (GstCaps)
96 #define FREE_CAPS(caps) g_slice_free (GstCaps, caps)
98 #define ALLOC_CAPS() g_new (GstCaps, 1)
99 #define FREE_CAPS(caps) g_free (caps)
102 static void gst_caps_transform_to_string (const GValue * src_value,
103 GValue * dest_value);
104 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
105 const gchar * string);
106 static GstCaps *gst_caps_copy_conditional (GstCaps * src);
109 gst_caps_get_type (void)
111 static GType gst_caps_type = 0;
113 if (G_UNLIKELY (gst_caps_type == 0)) {
114 gst_caps_type = g_boxed_type_register_static ("GstCaps",
115 (GBoxedCopyFunc) gst_caps_copy_conditional,
116 (GBoxedFreeFunc) gst_caps_unref);
118 g_value_register_transform_func (gst_caps_type,
119 G_TYPE_STRING, gst_caps_transform_to_string);
122 return gst_caps_type;
125 /* creation/deletion */
128 * gst_caps_new_empty:
130 * Creates a new #GstCaps that is empty. That is, the returned
131 * #GstCaps contains no media formats.
132 * Caller is responsible for unreffing the returned caps.
134 * Returns: the new #GstCaps
137 gst_caps_new_empty (void)
139 GstCaps *caps = ALLOC_CAPS ();
141 caps->type = GST_TYPE_CAPS;
144 caps->structs = g_ptr_array_new ();
146 #ifdef DEBUG_REFCOUNT
147 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
156 * Creates a new #GstCaps that indicates that it is compatible with
159 * Returns: the new #GstCaps
162 gst_caps_new_any (void)
164 GstCaps *caps = gst_caps_new_empty ();
166 caps->flags = GST_CAPS_FLAGS_ANY;
172 * gst_caps_new_simple:
173 * @media_type: the media type of the structure
174 * @fieldname: first field to set
175 * @...: additional arguments
177 * Creates a new #GstCaps that contains one #GstStructure. The
178 * structure is defined by the arguments, which have the same format
179 * as gst_structure_new().
180 * Caller is responsible for unreffing the returned caps.
182 * Returns: the new #GstCaps
185 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
188 GstStructure *structure;
191 caps = gst_caps_new_empty ();
193 va_start (var_args, fieldname);
194 structure = gst_structure_new_valist (media_type, fieldname, var_args);
197 gst_caps_append_structure (caps, structure);
204 * @struct1: the first structure to add
205 * @...: additional structures to add
207 * Creates a new #GstCaps and adds all the structures listed as
208 * arguments. The list must be NULL-terminated. The structures
209 * are not copied; the returned #GstCaps owns the structures.
211 * Returns: the new #GstCaps
214 gst_caps_new_full (GstStructure * struct1, ...)
219 va_start (var_args, struct1);
220 caps = gst_caps_new_full_valist (struct1, var_args);
227 * gst_caps_new_full_valist:
228 * @structure: the first structure to add
229 * @var_args: additional structures to add
231 * Creates a new #GstCaps and adds all the structures listed as
232 * arguments. The list must be NULL-terminated. The structures
233 * are not copied; the returned #GstCaps owns the structures.
235 * Returns: the new #GstCaps
238 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
242 caps = gst_caps_new_empty ();
245 gst_caps_append_structure (caps, structure);
246 structure = va_arg (var_args, GstStructure *);
254 * @caps: the #GstCaps to copy
256 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
257 * refcount of 1, owned by the caller. The structures are copied as well.
259 * Note that this function is the semantic equivalent of a gst_caps_ref()
260 * followed by a gst_caps_make_writable(). If you only want to hold on to a
261 * reference to the data, you should use gst_caps_ref().
263 * When you are finished with the caps, call gst_caps_unref() on it.
265 * Returns: the new #GstCaps
268 gst_caps_copy (const GstCaps * caps)
271 GstStructure *structure;
274 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
276 newcaps = gst_caps_new_empty ();
277 newcaps->flags = caps->flags;
279 for (i = 0; i < caps->structs->len; i++) {
280 structure = gst_caps_get_structure (caps, i);
281 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
288 _gst_caps_free (GstCaps * caps)
290 GstStructure *structure;
293 /* The refcount must be 0, but since we're only called by gst_caps_unref,
294 * don't bother testing. */
296 for (i = 0; i < caps->structs->len; i++) {
297 structure = (GstStructure *) gst_caps_get_structure (caps, i);
298 gst_structure_set_parent_refcount (structure, NULL);
299 gst_structure_free (structure);
301 g_ptr_array_free (caps->structs, TRUE);
303 memset (caps, 0xff, sizeof (GstCaps));
309 * gst_caps_make_writable:
310 * @caps: the #GstCaps to make writable
312 * Returns a writable copy of @caps.
314 * If there is only one reference count on @caps, the caller must be the owner,
315 * and so this function will return the caps object unchanged. If on the other
316 * hand there is more than one reference on the object, a new caps object will
317 * be returned. The caller's reference on @caps will be removed, and instead the
318 * caller will own a reference to the returned object.
320 * In short, this function unrefs the caps in the argument and refs the caps
321 * that it returns. Don't access the argument after calling this function. See
322 * also: gst_caps_ref().
324 * Returns: the same #GstCaps object.
327 gst_caps_make_writable (GstCaps * caps)
331 g_return_val_if_fail (caps != NULL, NULL);
333 /* we are the only instance reffing this caps */
334 if (g_atomic_int_get (&caps->refcount) == 1)
338 copy = gst_caps_copy (caps);
339 gst_caps_unref (caps);
346 * @caps: the #GstCaps to reference
348 * Add a reference to a #GstCaps object.
350 * From this point on, until the caller calls gst_caps_unref() or
351 * gst_caps_make_writable(), it is guaranteed that the caps object will not
352 * change. This means its structures won't change, etc. To use a #GstCaps
353 * object, you must always have a refcount on it -- either the one made
354 * implicitly by gst_caps_new(), or via taking one explicitly with this
357 * Returns: the same #GstCaps object.
360 gst_caps_ref (GstCaps * caps)
362 g_return_val_if_fail (caps != NULL, NULL);
364 #ifdef DEBUG_REFCOUNT
365 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
366 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) + 1);
368 g_return_val_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0, NULL);
370 g_atomic_int_inc (&caps->refcount);
377 * @caps: the #GstCaps to unref
379 * Unref a #GstCaps and and free all its structures and the
380 * structures' values when the refcount reaches 0.
383 gst_caps_unref (GstCaps * caps)
385 g_return_if_fail (caps != NULL);
387 #ifdef DEBUG_REFCOUNT
388 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
389 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) - 1);
392 g_return_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0);
394 /* if we ended up with the refcount at zero, free the caps */
395 if (G_UNLIKELY (g_atomic_int_dec_and_test (&caps->refcount)))
396 _gst_caps_free (caps);
400 gst_static_caps_get_type (void)
402 static GType staticcaps_type = 0;
404 if (G_UNLIKELY (staticcaps_type == 0)) {
405 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
407 return staticcaps_type;
412 * gst_static_caps_get:
413 * @static_caps: the #GstStaticCaps to convert
415 * Converts a #GstStaticCaps to a #GstCaps.
417 * Returns: A pointer to the #GstCaps. Unref after usage. Since the
418 * core holds an additional ref to the returned caps,
419 * use gst_caps_make_writable() on the returned caps to modify it.
422 gst_static_caps_get (GstStaticCaps * static_caps)
426 g_return_val_if_fail (static_caps != NULL, NULL);
428 caps = (GstCaps *) static_caps;
430 if (caps->type == 0) {
431 if (G_UNLIKELY (static_caps->string == NULL))
434 caps->type = GST_TYPE_CAPS;
435 /* initialize the caps to a refcount of 1 so the caps can be writable... */
436 gst_atomic_int_set (&caps->refcount, 1);
437 caps->structs = g_ptr_array_new ();
439 /* convert to string */
440 if (G_UNLIKELY (!gst_caps_from_string_inplace (caps, static_caps->string)))
441 g_critical ("Could not convert static caps \"%s\"", static_caps->string);
443 /* ref the caps, makes it not writable */
451 g_warning ("static caps string is NULL");
457 static GstStructure *
458 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
460 /* don't use index_fast, gst_caps_do_simplify relies on the order */
461 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
463 gst_structure_set_parent_refcount (s, NULL);
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);
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, };
492 other = gst_structure_id_get_value (subtract_from, field_id);
494 /* field is missing in one set */
498 gchar *str = g_strdup_value_contents (value);
499 GST_DEBUG (" value: '%s'", str);
501 str = g_strdup_value_contents (other);
502 GST_DEBUG (" other: '%s'", str);
509 if (!gst_value_subtract (&subtraction, other, value)) {
510 /* empty result -> values are the same, or first was a value and
513 /* verify that result is empty by swapping args */
514 if (!gst_value_subtract (&subtraction, value, other)) {
515 /*GST_DEBUG (" values are the same"); */
518 g_value_unset (&subtraction);
522 gchar *str = g_strdup_value_contents (&subtraction);
523 GST_DEBUG (" diff: '%s'", str);
526 res = gst_value_compare (&subtraction, other);
527 if (res == GST_VALUE_EQUAL) {
528 /* value was empty ? */
529 g_value_unset (&subtraction);
530 /*GST_DEBUG (" compare = equal (%d)",res); */
533 /*GST_DEBUG (" compare = unequal/unordered (%d)",res); */
539 gst_caps_structure_is_subset (const GstStructure * minuend,
540 const GstStructure * subtrahend)
542 if ((minuend->name != subtrahend->name) ||
543 (gst_structure_n_fields (minuend) !=
544 gst_structure_n_fields (subtrahend))) {
548 return gst_structure_foreach ((GstStructure *) subtrahend,
549 gst_caps_structure_is_subset_field, (gpointer) minuend);
554 * @caps1: the #GstCaps that will be appended to
555 * @caps2: the #GstCaps to append
557 * Appends the structures contained in @caps2 to @caps1. The structures in
558 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
559 * freed. If either caps is ANY, the resulting caps will be ANY.
562 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
564 GstStructure *structure;
567 g_return_if_fail (GST_IS_CAPS (caps1));
568 g_return_if_fail (GST_IS_CAPS (caps2));
569 g_return_if_fail (IS_WRITABLE (caps1));
570 g_return_if_fail (IS_WRITABLE (caps2));
575 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2)) {
576 /* FIXME: this leaks */
577 caps1->flags |= GST_CAPS_FLAGS_ANY;
578 for (i = caps2->structs->len - 1; i >= 0; i--) {
579 structure = gst_caps_remove_and_get_structure (caps2, i);
580 gst_structure_free (structure);
583 int len = caps2->structs->len;
585 for (i = 0; i < len; i++) {
586 structure = gst_caps_remove_and_get_structure (caps2, 0);
587 gst_caps_append_structure (caps1, structure);
590 gst_caps_unref (caps2); /* guaranteed to free it */
595 * @caps1: the #GstCaps that will take the new entries
596 * @caps2: the #GstCaps to merge in
598 * Appends the structures contained in @caps2 to @caps1 if they are not yet
599 * expressed by @caps1. The structures in @caps2 are not copied -- they are
600 * transferred to @caps1, and then @caps2 is freed.
601 * If either caps is ANY, the resulting caps will be ANY.
604 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
606 GstStructure *structure;
609 g_return_if_fail (GST_IS_CAPS (caps1));
610 g_return_if_fail (GST_IS_CAPS (caps2));
611 g_return_if_fail (IS_WRITABLE (caps1));
612 g_return_if_fail (IS_WRITABLE (caps2));
617 if (gst_caps_is_any (caps1)) {
618 for (i = caps2->structs->len - 1; i >= 0; i--) {
619 structure = gst_caps_remove_and_get_structure (caps2, i);
620 gst_structure_free (structure);
622 } else if (gst_caps_is_any (caps2)) {
623 caps1->flags |= GST_CAPS_FLAGS_ANY;
624 for (i = caps1->structs->len - 1; i >= 0; i--) {
625 structure = gst_caps_remove_and_get_structure (caps1, i);
626 gst_structure_free (structure);
629 int len = caps2->structs->len;
631 for (i = 0; i < len; i++) {
632 structure = gst_caps_remove_and_get_structure (caps2, 0);
633 gst_caps_merge_structure (caps1, structure);
636 GstCaps *com = gst_caps_intersect (caps1, caps2);
637 GstCaps *add = gst_caps_subtract (caps2, com);
639 GST_DEBUG ("common : %d", gst_caps_get_size (com));
640 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
641 gst_caps_append (caps1, add);
642 gst_caps_unref (com);
645 gst_caps_unref (caps2); /* guaranteed to free it */
649 * gst_caps_append_structure:
650 * @caps: the #GstCaps that will be appended to
651 * @structure: the #GstStructure to append
653 * Appends @structure to @caps. The structure is not copied; @caps
654 * becomes the owner of @structure.
657 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
659 g_return_if_fail (GST_IS_CAPS (caps));
660 g_return_if_fail (IS_WRITABLE (caps));
662 if (G_LIKELY (structure)) {
663 g_return_if_fail (structure->parent_refcount == NULL);
666 STRUCTURE_POISON (structure);
669 gst_structure_set_parent_refcount (structure, &caps->refcount);
670 g_ptr_array_add (caps->structs, structure);
675 * gst_caps_remove_structure:
676 * @caps: the #GstCaps to remove from
677 * @idx: Index of the structure to remove
679 * removes the stucture with the given index from the list of structures
680 * contained in @caps.
683 gst_caps_remove_structure (GstCaps * caps, guint idx)
685 GstStructure *structure;
687 g_return_if_fail (caps != NULL);
688 g_return_if_fail (idx <= gst_caps_get_size (caps));
689 g_return_if_fail (IS_WRITABLE (caps));
691 structure = gst_caps_remove_and_get_structure (caps, idx);
692 gst_structure_free (structure);
696 * gst_caps_merge_structure:
697 * @caps: the #GstCaps that will the the new structure
698 * @structure: the #GstStructure to merge
700 * Appends @structure to @caps if its not already expressed by @caps. The
701 * structure is not copied; @caps becomes the owner of @structure.
704 gst_caps_merge_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 GstStructure *structure1;
712 gboolean unique = TRUE;
714 g_return_if_fail (structure->parent_refcount == NULL);
717 STRUCTURE_POISON (structure);
720 /* check each structure */
721 for (i = caps->structs->len - 1; i >= 0; i--) {
722 structure1 = gst_caps_get_structure (caps, i);
723 /* if structure is a subset of structure1, then skip it */
724 if (gst_caps_structure_is_subset (structure1, structure)) {
730 gst_structure_set_parent_refcount (structure, &caps->refcount);
731 g_ptr_array_add (caps->structs, structure);
733 gst_structure_free (structure);
743 * Gets the number of structures contained in @caps.
745 * Returns: the number of structures that @caps contains
748 gst_caps_get_size (const GstCaps * caps)
750 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
752 return caps->structs->len;
756 * gst_caps_get_structure:
758 * @index: the index of the structure
760 * Finds the structure in @caps that has the index @index, and
763 * WARNING: This function takes a const GstCaps *, but returns a
764 * non-const GstStructure *. This is for programming convenience --
765 * the caller should be aware that structures inside a constant
766 * #GstCaps should not be modified.
768 * Returns: a pointer to the #GstStructure corresponding to @index
771 gst_caps_get_structure (const GstCaps * caps, guint index)
773 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
774 g_return_val_if_fail (index < caps->structs->len, NULL);
776 return g_ptr_array_index (caps->structs, index);
781 * @caps: the #GstCaps to copy
782 * @nth: the nth structure to copy
784 * Creates a new #GstCaps and appends a copy of the nth structure
785 * contained in @caps.
787 * Returns: the new #GstCaps
790 gst_caps_copy_nth (const GstCaps * caps, guint nth)
793 GstStructure *structure;
795 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
797 newcaps = gst_caps_new_empty ();
798 newcaps->flags = caps->flags;
800 if (caps->structs->len > nth) {
801 structure = gst_caps_get_structure (caps, nth);
802 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
810 * @caps: the #GstCaps to truncate
812 * Destructively discard all but the first structure from @caps. Useful when
813 * fixating. @caps must be writable.
816 gst_caps_truncate (GstCaps * caps)
820 g_return_if_fail (GST_IS_CAPS (caps));
821 g_return_if_fail (IS_WRITABLE (caps));
823 i = caps->structs->len - 1;
826 gst_caps_remove_structure (caps, i--);
830 * gst_caps_set_simple:
831 * @caps: the #GstCaps to set
832 * @field: first field to set
833 * @...: additional parameters
835 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
836 * only has one structure. The arguments must be passed in the same
837 * manner as gst_structure_set(), and be NULL-terminated.
840 gst_caps_set_simple (GstCaps * caps, char *field, ...)
842 GstStructure *structure;
845 g_return_if_fail (GST_IS_CAPS (caps));
846 g_return_if_fail (caps->structs->len == 1);
847 g_return_if_fail (IS_WRITABLE (caps));
849 structure = gst_caps_get_structure (caps, 0);
851 va_start (var_args, field);
852 gst_structure_set_valist (structure, field, var_args);
857 * gst_caps_set_simple_valist:
858 * @caps: the #GstCaps to copy
859 * @field: first field to set
860 * @varargs: additional parameters
862 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
863 * only has one structure. The arguments must be passed in the same
864 * manner as gst_structure_set(), and be NULL-terminated.
867 gst_caps_set_simple_valist (GstCaps * caps, char *field, va_list varargs)
869 GstStructure *structure;
871 g_return_if_fail (GST_IS_CAPS (caps));
872 g_return_if_fail (caps->structs->len != 1);
873 g_return_if_fail (IS_WRITABLE (caps));
875 structure = gst_caps_get_structure (caps, 0);
877 gst_structure_set_valist (structure, field, varargs);
884 * @caps: the #GstCaps to test
886 * Determines if @caps represents any media format.
888 * Returns: TRUE if @caps represents any format.
891 gst_caps_is_any (const GstCaps * caps)
893 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
895 return (caps->flags & GST_CAPS_FLAGS_ANY);
900 * @caps: the #GstCaps to test
902 * Determines if @caps represents no media formats.
904 * Returns: TRUE if @caps represents no formats.
907 gst_caps_is_empty (const GstCaps * caps)
909 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
911 if (caps->flags & GST_CAPS_FLAGS_ANY)
914 return (caps->structs == NULL) || (caps->structs->len == 0);
918 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
921 return gst_value_is_fixed (value);
926 * @caps: the #GstCaps to test
928 * Fixed #GstCaps describe exactly one format, that is, they have exactly
929 * one structure, and each field in the structure describes a fixed type.
930 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
932 * Returns: TRUE if @caps is fixed
935 gst_caps_is_fixed (const GstCaps * caps)
937 GstStructure *structure;
939 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
941 if (caps->structs->len != 1)
944 structure = gst_caps_get_structure (caps, 0);
946 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
950 * gst_caps_is_equal_fixed:
951 * @caps1: the #GstCaps to test
952 * @caps2: the #GstCaps to test
954 * Tests if two #GstCaps are equal. This function only works on fixed
957 * Returns: TRUE if the arguments represent the same format
960 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
962 GstStructure *struct1, *struct2;
964 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
965 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
967 struct1 = gst_caps_get_structure (caps1, 0);
968 struct2 = gst_caps_get_structure (caps2, 0);
970 if (struct1->name != struct2->name) {
973 if (struct1->fields->len != struct2->fields->len) {
977 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
982 * gst_caps_is_always_compatible:
983 * @caps1: the #GstCaps to test
984 * @caps2: the #GstCaps to test
986 * A given #GstCaps structure is always compatible with another if
987 * every media format that is in the first is also contained in the
988 * second. That is, @caps1 is a subset of @caps2.
990 * Returns: TRUE if @caps1 is a subset of @caps2.
993 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
995 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
996 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
998 return gst_caps_is_subset (caps1, caps2);
1002 * gst_caps_is_subset:
1003 * @subset: a #GstCaps
1004 * @superset: a potentially greater #GstCaps
1006 * Checks if all caps represented by @subset are also represented by @superset
1007 * <note>This function does not work reliably if optional properties for caps
1008 * are included on one caps and omitted on the other.</note>
1010 * Returns: TRUE if @subset is a subset of @superset
1013 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1018 g_return_val_if_fail (subset != NULL, FALSE);
1019 g_return_val_if_fail (superset != NULL, FALSE);
1021 if (gst_caps_is_empty (subset) || gst_caps_is_any (superset))
1023 if (gst_caps_is_any (subset) || gst_caps_is_empty (superset))
1026 caps = gst_caps_subtract (subset, superset);
1027 ret = gst_caps_is_empty (caps);
1028 gst_caps_unref (caps);
1033 * gst_caps_is_equal:
1034 * @caps1: a #GstCaps
1035 * @caps2: another #GstCaps
1037 * Checks if the given caps represent the same set of caps.
1038 * <note>This function does not work reliably if optional properties for caps
1039 * are included on one caps and omitted on the other.</note>
1041 * This function deals correctly with passing NULL for any of the caps.
1043 * Returns: TRUE if both caps are equal.
1046 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1048 /* NULL <-> NULL is allowed here */
1052 /* one of them NULL => they are different (can't be both NULL because
1053 * we checked that above) */
1054 if (caps1 == NULL || caps2 == NULL)
1057 if (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2))
1058 return gst_caps_is_equal_fixed (caps1, caps2);
1060 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1066 const GstStructure *intersect;
1072 gst_caps_structure_intersect_field (GQuark id, const GValue * val1,
1075 IntersectData *idata = (IntersectData *) data;
1076 GValue dest_value = { 0 };
1077 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1080 gst_structure_id_set_value (idata->dest, id, val1);
1081 } else if (idata->first_run) {
1082 if (gst_value_intersect (&dest_value, val1, val2)) {
1083 gst_structure_id_set_value (idata->dest, id, &dest_value);
1084 g_value_unset (&dest_value);
1093 static GstStructure *
1094 gst_caps_structure_intersect (const GstStructure * struct1,
1095 const GstStructure * struct2)
1099 g_return_val_if_fail (struct1 != NULL, NULL);
1100 g_return_val_if_fail (struct2 != NULL, NULL);
1102 if (struct1->name != struct2->name)
1105 data.dest = gst_structure_id_empty_new (struct1->name);
1106 data.intersect = struct2;
1107 data.first_run = TRUE;
1108 if (!gst_structure_foreach ((GstStructure *) struct1,
1109 gst_caps_structure_intersect_field, &data))
1112 data.intersect = struct1;
1113 data.first_run = FALSE;
1114 if (!gst_structure_foreach ((GstStructure *) struct2,
1115 gst_caps_structure_intersect_field, &data))
1121 gst_structure_free (data.dest);
1126 static GstStructure *
1127 gst_caps_structure_union (const GstStructure * struct1,
1128 const GstStructure * struct2)
1132 const GstStructureField *field1;
1133 const GstStructureField *field2;
1136 /* FIXME this doesn't actually work */
1138 if (struct1->name != struct2->name)
1141 dest = gst_structure_id_empty_new (struct1->name);
1143 for (i = 0; i < struct1->fields->len; i++) {
1144 GValue dest_value = { 0 };
1146 field1 = GST_STRUCTURE_FIELD (struct1, i);
1147 field2 = gst_structure_id_get_field (struct2, field1->name);
1149 if (field2 == NULL) {
1152 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1153 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1156 ret = gst_value_compare (&field1->value, &field2->value);
1168 * gst_caps_intersect:
1169 * @caps1: a #GstCaps to intersect
1170 * @caps2: a #GstCaps to intersect
1172 * Creates a new #GstCaps that contains all the formats that are common
1173 * to both @caps1 and @caps2.
1175 * Returns: the new #GstCaps
1178 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1180 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1183 GstStructure *struct1;
1184 GstStructure *struct2;
1186 GstStructure *istruct;
1188 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1189 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1191 if (gst_caps_is_empty (caps1) || gst_caps_is_empty (caps2)) {
1192 return gst_caps_new_empty ();
1194 if (gst_caps_is_any (caps1))
1195 return gst_caps_copy (caps2);
1196 if (gst_caps_is_any (caps2))
1197 return gst_caps_copy (caps1);
1199 dest = gst_caps_new_empty ();
1201 /* run zigzag on top line then right line, this preserves the caps order
1202 * much better than a simple loop.
1204 * This algorithm zigzags over the caps structures as demonstrated in
1205 * the folowing matrix:
1213 * First we iterate over the caps1 structures (top line) intersecting
1214 * the structures diagonally down, then we iterate over the caps2
1217 for (i = 0; i < caps1->structs->len + caps2->structs->len - 1; i++) {
1218 /* caps1 index goes from 0 to caps1->structs->len-1 */
1219 j = MIN (i, caps1->structs->len - 1);
1220 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1221 * up from 1 to caps2->structs->len - 1 */
1224 /* now run the diagonal line, end condition is the left or bottom
1226 while (k < caps2->structs->len) {
1227 struct1 = gst_caps_get_structure (caps1, j);
1228 struct2 = gst_caps_get_structure (caps2, k);
1230 istruct = gst_caps_structure_intersect (struct1, struct2);
1232 gst_caps_append_structure (dest, istruct);
1233 /* move down left */
1236 break; /* so we don't roll back to G_MAXUINT */
1245 const GstStructure *subtract_from;
1252 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1255 SubtractionEntry *e = user_data;
1256 GValue subtraction = { 0, };
1257 const GValue *other;
1258 GstStructure *structure;
1260 other = gst_structure_id_get_value (e->subtract_from, field_id);
1264 if (!gst_value_subtract (&subtraction, other, value))
1266 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1267 g_value_unset (&subtraction);
1270 structure = gst_structure_copy (e->subtract_from);
1271 gst_structure_id_set_value (structure, field_id, &subtraction);
1272 g_value_unset (&subtraction);
1273 e->put_into = g_slist_prepend (e->put_into, structure);
1279 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1280 const GstStructure * subtrahend)
1285 e.subtract_from = minuend;
1288 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1289 gst_caps_structure_subtract_field, &e);
1295 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1296 gst_structure_free (walk->data);
1298 g_slist_free (e.put_into);
1304 * gst_caps_subtract:
1305 * @minuend: #GstCaps to substract from
1306 * @subtrahend: #GstCaps to substract
1308 * Subtracts the @subtrahend from the @minuend.
1309 * <note>This function does not work reliably if optional properties for caps
1310 * are included on one caps and omitted on the other.</note>
1312 * Returns: the resulting caps
1315 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1320 GstCaps *dest = NULL, *src;
1322 g_return_val_if_fail (minuend != NULL, NULL);
1323 g_return_val_if_fail (subtrahend != NULL, NULL);
1325 if (gst_caps_is_empty (minuend) || gst_caps_is_any (subtrahend)) {
1326 return gst_caps_new_empty ();
1328 if (gst_caps_is_empty (subtrahend))
1329 return gst_caps_copy (minuend);
1331 /* FIXME: Do we want this here or above?
1332 The reason we need this is that there is no definition about what
1333 ANY means for specific types, so it's not possible to reduce ANY partially
1334 You can only remove everything or nothing and that is done above.
1335 Note: there's a test that checks this behaviour. */
1336 g_return_val_if_fail (!gst_caps_is_any (minuend), NULL);
1337 g_assert (subtrahend->structs->len > 0);
1339 src = gst_caps_copy (minuend);
1340 for (i = 0; i < subtrahend->structs->len; i++) {
1341 sub = gst_caps_get_structure (subtrahend, i);
1343 gst_caps_unref (src);
1346 dest = gst_caps_new_empty ();
1347 for (j = 0; j < src->structs->len; j++) {
1348 min = gst_caps_get_structure (src, j);
1349 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1352 if (gst_caps_structure_subtract (&list, min, sub)) {
1355 for (walk = list; walk; walk = g_slist_next (walk)) {
1356 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1358 g_slist_free (list);
1360 gst_caps_append_structure (dest, gst_structure_copy (min));
1363 gst_caps_append_structure (dest, gst_structure_copy (min));
1366 if (gst_caps_is_empty (dest)) {
1367 gst_caps_unref (src);
1372 gst_caps_unref (src);
1373 gst_caps_do_simplify (dest);
1379 * @caps1: a #GstCaps to union
1380 * @caps2: a #GstCaps to union
1382 * Creates a new #GstCaps that contains all the formats that are in
1383 * either @caps1 and @caps2.
1385 * Returns: the new #GstCaps
1388 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1393 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2))
1394 return gst_caps_new_any ();
1396 dest1 = gst_caps_copy (caps1);
1397 dest2 = gst_caps_copy (caps2);
1398 gst_caps_append (dest1, dest2);
1400 gst_caps_do_simplify (dest1);
1404 typedef struct _NormalizeForeach
1407 GstStructure *structure;
1412 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1414 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1418 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1419 for (i = 1; i < gst_value_list_get_size (value); i++) {
1420 const GValue *v = gst_value_list_get_value (value, i);
1421 GstStructure *structure = gst_structure_copy (nf->structure);
1423 gst_structure_id_set_value (structure, field_id, v);
1424 gst_caps_append_structure (nf->caps, structure);
1427 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1428 gst_structure_id_set_value (nf->structure, field_id, &val);
1429 g_value_unset (&val);
1437 * gst_caps_normalize:
1438 * @caps: a #GstCaps to normalize
1440 * Creates a new #GstCaps that represents the same set of formats as
1441 * @caps, but contains no lists. Each list is expanded into separate
1444 * Returns: the new #GstCaps
1447 gst_caps_normalize (const GstCaps * caps)
1449 NormalizeForeach nf;
1453 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1455 newcaps = gst_caps_copy (caps);
1458 for (i = 0; i < newcaps->structs->len; i++) {
1459 nf.structure = gst_caps_get_structure (newcaps, i);
1461 while (!gst_structure_foreach (nf.structure,
1462 gst_caps_normalize_foreach, &nf));
1469 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1472 const GstStructure *struct1 = *((const GstStructure **) one);
1473 const GstStructure *struct2 = *((const GstStructure **) two);
1475 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1476 So what's the best way? */
1477 ret = strcmp (gst_structure_get_name (struct1),
1478 gst_structure_get_name (struct2));
1482 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1489 GstStructure *compare;
1494 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1497 UnionField *u = user_data;
1498 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1502 g_value_unset (&u->value);
1505 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1508 g_value_unset (&u->value);
1512 gst_value_union (&u->value, val, value);
1517 gst_caps_structure_simplify (GstStructure ** result,
1518 const GstStructure * simplify, GstStructure * compare)
1521 UnionField field = { 0, {0,}, NULL };
1523 /* try to subtract to get a real subset */
1524 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1525 switch (g_slist_length (list)) {
1530 *result = list->data;
1531 g_slist_free (list);
1537 for (walk = list; walk; walk = g_slist_next (walk)) {
1538 gst_structure_free (walk->data);
1540 g_slist_free (list);
1546 /* try to union both structs */
1547 field.compare = compare;
1548 if (gst_structure_foreach ((GstStructure *) simplify,
1549 gst_caps_structure_figure_out_union, &field)) {
1550 gboolean ret = FALSE;
1552 /* now we know all of simplify's fields are the same in compare
1553 * but at most one field: field.name */
1554 if (G_IS_VALUE (&field.value)) {
1555 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1556 gst_structure_id_set_value (compare, field.name, &field.value);
1560 g_value_unset (&field.value);
1561 } else if (gst_structure_n_fields (simplify) <=
1562 gst_structure_n_fields (compare)) {
1563 /* compare is just more specific, will be optimized away later */
1564 /* FIXME: do this here? */
1565 GST_LOG ("found a case that will be optimized later.");
1567 gchar *one = gst_structure_to_string (simplify);
1568 gchar *two = gst_structure_to_string (compare);
1571 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1583 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1584 GstStructure * new, gint i)
1586 gst_structure_set_parent_refcount (old, NULL);
1587 gst_structure_free (old);
1588 gst_structure_set_parent_refcount (new, &caps->refcount);
1589 g_ptr_array_index (caps->structs, i) = new;
1593 * gst_caps_do_simplify:
1594 * @caps: a #GstCaps to simplify
1596 * Modifies the given @caps inplace into a representation that represents the
1597 * same set of formats, but in a simpler form. Component structures that are
1598 * identical are merged. Component structures that have values that can be
1599 * merged are also merged.
1601 * Returns: TRUE, if the caps could be simplified
1604 gst_caps_do_simplify (GstCaps * caps)
1606 GstStructure *simplify, *compare, *result = NULL;
1608 gboolean changed = FALSE;
1610 g_return_val_if_fail (caps != NULL, FALSE);
1611 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1613 if (gst_caps_get_size (caps) < 2)
1616 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1618 start = caps->structs->len - 1;
1619 for (i = caps->structs->len - 1; i >= 0; i--) {
1620 simplify = gst_caps_get_structure (caps, i);
1621 if (gst_structure_get_name_id (simplify) !=
1622 gst_structure_get_name_id (gst_caps_get_structure (caps, start)))
1624 for (j = start; j >= 0; j--) {
1627 compare = gst_caps_get_structure (caps, j);
1628 if (gst_structure_get_name_id (simplify) !=
1629 gst_structure_get_name_id (compare)) {
1632 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1634 gst_caps_switch_structures (caps, simplify, result, i);
1637 gst_caps_remove_structure (caps, i);
1649 /* gst_caps_do_simplify (caps); */
1653 #ifndef GST_DISABLE_LOADSAVE
1655 * gst_caps_save_thyself:
1656 * @caps: a #GstCaps structure
1657 * @parent: a XML parent node
1659 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1661 * Returns: a XML node pointer
1664 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1666 char *s = gst_caps_to_string (caps);
1668 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1674 * gst_caps_load_thyself:
1675 * @parent: a XML node
1677 * Creates a #GstCaps from its XML serialization.
1679 * Returns: a new #GstCaps structure
1682 gst_caps_load_thyself (xmlNodePtr parent)
1684 if (strcmp ("caps", (char *) parent->name) == 0) {
1685 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1696 * @caps: a pointer to #GstCaps
1697 * @newcaps: a #GstCaps to replace *caps
1699 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1700 * pointed to by @caps, if applicable, then modifies @caps to point to
1701 * @newcaps. An additional ref on @newcaps is taken.
1703 * This function does not take any locks so you might want to lock
1704 * the object owning @caps pointer.
1707 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1711 g_return_if_fail (caps != NULL);
1715 if (newcaps != oldcaps) {
1717 gst_caps_ref (newcaps);
1722 gst_caps_unref (oldcaps);
1727 * gst_caps_to_string:
1730 * Converts @caps to a string representation. This string representation
1731 * can be converted back to a #GstCaps by gst_caps_from_string().
1733 * For debugging purposes its easier to do something like this:
1735 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1737 * This prints the caps in human readble form.
1739 * Returns: a newly allocated string representing @caps.
1742 gst_caps_to_string (const GstCaps * caps)
1747 /* NOTE: This function is potentially called by the debug system,
1748 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1749 * should be careful to avoid recursion. This includes any functions
1750 * called by gst_caps_to_string. In particular, calls should
1751 * not use the GST_PTR_FORMAT extension. */
1754 return g_strdup ("NULL");
1756 if (gst_caps_is_any (caps)) {
1757 return g_strdup ("ANY");
1759 if (gst_caps_is_empty (caps)) {
1760 return g_strdup ("EMPTY");
1763 s = g_string_new ("");
1764 for (i = 0; i < caps->structs->len; i++) {
1765 GstStructure *structure;
1769 g_string_append (s, "; ");
1771 structure = gst_caps_get_structure (caps, i);
1772 sstr = gst_structure_to_string (structure);
1773 g_string_append (s, sstr);
1777 return g_string_free (s, FALSE);
1781 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1783 GstStructure *structure;
1786 g_return_val_if_fail (string, FALSE);
1787 if (strcmp ("ANY", string) == 0) {
1788 caps->flags = GST_CAPS_FLAGS_ANY;
1791 if (strcmp ("EMPTY", string) == 0) {
1795 structure = gst_structure_from_string (string, &s);
1796 if (structure == NULL) {
1799 gst_caps_append_structure (caps, structure);
1803 while (g_ascii_isspace (*s))
1805 structure = gst_structure_from_string (s, &s);
1806 if (structure == NULL) {
1809 gst_caps_append_structure (caps, structure);
1810 while (g_ascii_isspace (*s))
1822 * gst_caps_from_string:
1823 * @string: a string to convert to #GstCaps
1825 * Converts @caps from a string representation.
1827 * Returns: a newly allocated #GstCaps
1830 gst_caps_from_string (const gchar * string)
1834 caps = gst_caps_new_empty ();
1835 if (gst_caps_from_string_inplace (caps, string)) {
1838 gst_caps_unref (caps);
1844 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1846 g_return_if_fail (G_IS_VALUE (src_value));
1847 g_return_if_fail (G_IS_VALUE (dest_value));
1848 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1849 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1850 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1852 dest_value->data[0].v_pointer =
1853 gst_caps_to_string (src_value->data[0].v_pointer);
1857 gst_caps_copy_conditional (GstCaps * src)
1860 return gst_caps_ref (src);