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 * structure2)
706 g_return_if_fail (GST_IS_CAPS (caps));
707 g_return_if_fail (IS_WRITABLE (caps));
709 if (G_LIKELY (structure2)) {
710 GstStructure *structure1;
712 gboolean unique = TRUE;
714 g_return_if_fail (structure2->parent_refcount == NULL);
717 STRUCTURE_POISON (structure2);
720 /*GST_DEBUG ("merge ?: %" GST_PTR_FORMAT, structure2); */
721 /* check each structure */
722 for (i = caps->structs->len - 1; i >= 0; i--) {
723 structure1 = gst_caps_get_structure (caps, i);
724 /*GST_DEBUG (" with: %" GST_PTR_FORMAT, structure1); */
725 /* if structure2 is a subset of structure1, then skip it */
726 if (gst_caps_structure_is_subset (structure1, structure2)) {
727 /*GST_DEBUG (" no"); */
733 /*GST_DEBUG (" yes"); */
734 gst_structure_set_parent_refcount (structure2, &caps->refcount);
735 g_ptr_array_add (caps->structs, structure2);
737 gst_structure_free (structure2);
747 * Gets the number of structures contained in @caps.
749 * Returns: the number of structures that @caps contains
752 gst_caps_get_size (const GstCaps * caps)
754 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
756 return caps->structs->len;
760 * gst_caps_get_structure:
762 * @index: the index of the structure
764 * Finds the structure in @caps that has the index @index, and
767 * WARNING: This function takes a const GstCaps *, but returns a
768 * non-const GstStructure *. This is for programming convenience --
769 * the caller should be aware that structures inside a constant
770 * #GstCaps should not be modified.
772 * Returns: a pointer to the #GstStructure corresponding to @index
775 gst_caps_get_structure (const GstCaps * caps, guint index)
777 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
778 g_return_val_if_fail (index < caps->structs->len, NULL);
780 return g_ptr_array_index (caps->structs, index);
785 * @caps: the #GstCaps to copy
786 * @nth: the nth structure to copy
788 * Creates a new #GstCaps and appends a copy of the nth structure
789 * contained in @caps.
791 * Returns: the new #GstCaps
794 gst_caps_copy_nth (const GstCaps * caps, guint nth)
797 GstStructure *structure;
799 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
801 newcaps = gst_caps_new_empty ();
802 newcaps->flags = caps->flags;
804 if (caps->structs->len > nth) {
805 structure = gst_caps_get_structure (caps, nth);
806 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
814 * @caps: the #GstCaps to truncate
816 * Destructively discard all but the first structure from @caps. Useful when
817 * fixating. @caps must be writable.
820 gst_caps_truncate (GstCaps * caps)
824 g_return_if_fail (GST_IS_CAPS (caps));
825 g_return_if_fail (IS_WRITABLE (caps));
827 i = caps->structs->len - 1;
830 gst_caps_remove_structure (caps, i--);
834 * gst_caps_set_simple:
835 * @caps: the #GstCaps to set
836 * @field: first field to set
837 * @...: additional parameters
839 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
840 * only has one structure. The arguments must be passed in the same
841 * manner as gst_structure_set(), and be NULL-terminated.
844 gst_caps_set_simple (GstCaps * caps, char *field, ...)
846 GstStructure *structure;
849 g_return_if_fail (GST_IS_CAPS (caps));
850 g_return_if_fail (caps->structs->len == 1);
851 g_return_if_fail (IS_WRITABLE (caps));
853 structure = gst_caps_get_structure (caps, 0);
855 va_start (var_args, field);
856 gst_structure_set_valist (structure, field, var_args);
861 * gst_caps_set_simple_valist:
862 * @caps: the #GstCaps to copy
863 * @field: first field to set
864 * @varargs: additional parameters
866 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
867 * only has one structure. The arguments must be passed in the same
868 * manner as gst_structure_set(), and be NULL-terminated.
871 gst_caps_set_simple_valist (GstCaps * caps, char *field, va_list varargs)
873 GstStructure *structure;
875 g_return_if_fail (GST_IS_CAPS (caps));
876 g_return_if_fail (caps->structs->len != 1);
877 g_return_if_fail (IS_WRITABLE (caps));
879 structure = gst_caps_get_structure (caps, 0);
881 gst_structure_set_valist (structure, field, varargs);
888 * @caps: the #GstCaps to test
890 * Determines if @caps represents any media format.
892 * Returns: TRUE if @caps represents any format.
895 gst_caps_is_any (const GstCaps * caps)
897 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
899 return (caps->flags & GST_CAPS_FLAGS_ANY);
904 * @caps: the #GstCaps to test
906 * Determines if @caps represents no media formats.
908 * Returns: TRUE if @caps represents no formats.
911 gst_caps_is_empty (const GstCaps * caps)
913 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
915 if (caps->flags & GST_CAPS_FLAGS_ANY)
918 return (caps->structs == NULL) || (caps->structs->len == 0);
922 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
925 return gst_value_is_fixed (value);
930 * @caps: the #GstCaps to test
932 * Fixed #GstCaps describe exactly one format, that is, they have exactly
933 * one structure, and each field in the structure describes a fixed type.
934 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
936 * Returns: TRUE if @caps is fixed
939 gst_caps_is_fixed (const GstCaps * caps)
941 GstStructure *structure;
943 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
945 if (caps->structs->len != 1)
948 structure = gst_caps_get_structure (caps, 0);
950 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
954 * gst_caps_is_equal_fixed:
955 * @caps1: the #GstCaps to test
956 * @caps2: the #GstCaps to test
958 * Tests if two #GstCaps are equal. This function only works on fixed
961 * Returns: TRUE if the arguments represent the same format
964 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
966 GstStructure *struct1, *struct2;
968 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
969 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
971 struct1 = gst_caps_get_structure (caps1, 0);
972 struct2 = gst_caps_get_structure (caps2, 0);
974 if (struct1->name != struct2->name) {
977 if (struct1->fields->len != struct2->fields->len) {
981 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
986 * gst_caps_is_always_compatible:
987 * @caps1: the #GstCaps to test
988 * @caps2: the #GstCaps to test
990 * A given #GstCaps structure is always compatible with another if
991 * every media format that is in the first is also contained in the
992 * second. That is, @caps1 is a subset of @caps2.
994 * Returns: TRUE if @caps1 is a subset of @caps2.
997 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
999 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1000 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1002 return gst_caps_is_subset (caps1, caps2);
1006 * gst_caps_is_subset:
1007 * @subset: a #GstCaps
1008 * @superset: a potentially greater #GstCaps
1010 * Checks if all caps represented by @subset are also represented by @superset
1011 * <note>This function does not work reliably if optional properties for caps
1012 * are included on one caps and omitted on the other.</note>
1014 * Returns: TRUE if @subset is a subset of @superset
1017 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1022 g_return_val_if_fail (subset != NULL, FALSE);
1023 g_return_val_if_fail (superset != NULL, FALSE);
1025 if (gst_caps_is_empty (subset) || gst_caps_is_any (superset))
1027 if (gst_caps_is_any (subset) || gst_caps_is_empty (superset))
1030 caps = gst_caps_subtract (subset, superset);
1031 ret = gst_caps_is_empty (caps);
1032 gst_caps_unref (caps);
1037 * gst_caps_is_equal:
1038 * @caps1: a #GstCaps
1039 * @caps2: another #GstCaps
1041 * Checks if the given caps represent the same set of caps.
1042 * <note>This function does not work reliably if optional properties for caps
1043 * are included on one caps and omitted on the other.</note>
1045 * This function deals correctly with passing NULL for any of the caps.
1047 * Returns: TRUE if both caps are equal.
1050 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1052 /* NULL <-> NULL is allowed here */
1056 /* one of them NULL => they are different (can't be both NULL because
1057 * we checked that above) */
1058 if (caps1 == NULL || caps2 == NULL)
1061 if (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2))
1062 return gst_caps_is_equal_fixed (caps1, caps2);
1064 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1070 const GstStructure *intersect;
1076 gst_caps_structure_intersect_field (GQuark id, const GValue * val1,
1079 IntersectData *idata = (IntersectData *) data;
1080 GValue dest_value = { 0 };
1081 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1084 gst_structure_id_set_value (idata->dest, id, val1);
1085 } else if (idata->first_run) {
1086 if (gst_value_intersect (&dest_value, val1, val2)) {
1087 gst_structure_id_set_value (idata->dest, id, &dest_value);
1088 g_value_unset (&dest_value);
1097 static GstStructure *
1098 gst_caps_structure_intersect (const GstStructure * struct1,
1099 const GstStructure * struct2)
1103 g_return_val_if_fail (struct1 != NULL, NULL);
1104 g_return_val_if_fail (struct2 != NULL, NULL);
1106 if (struct1->name != struct2->name)
1109 data.dest = gst_structure_id_empty_new (struct1->name);
1110 data.intersect = struct2;
1111 data.first_run = TRUE;
1112 if (!gst_structure_foreach ((GstStructure *) struct1,
1113 gst_caps_structure_intersect_field, &data))
1116 data.intersect = struct1;
1117 data.first_run = FALSE;
1118 if (!gst_structure_foreach ((GstStructure *) struct2,
1119 gst_caps_structure_intersect_field, &data))
1125 gst_structure_free (data.dest);
1130 static GstStructure *
1131 gst_caps_structure_union (const GstStructure * struct1,
1132 const GstStructure * struct2)
1136 const GstStructureField *field1;
1137 const GstStructureField *field2;
1140 /* FIXME this doesn't actually work */
1142 if (struct1->name != struct2->name)
1145 dest = gst_structure_id_empty_new (struct1->name);
1147 for (i = 0; i < struct1->fields->len; i++) {
1148 GValue dest_value = { 0 };
1150 field1 = GST_STRUCTURE_FIELD (struct1, i);
1151 field2 = gst_structure_id_get_field (struct2, field1->name);
1153 if (field2 == NULL) {
1156 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1157 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1160 ret = gst_value_compare (&field1->value, &field2->value);
1172 * gst_caps_intersect:
1173 * @caps1: a #GstCaps to intersect
1174 * @caps2: a #GstCaps to intersect
1176 * Creates a new #GstCaps that contains all the formats that are common
1177 * to both @caps1 and @caps2.
1179 * Returns: the new #GstCaps
1182 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1184 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1187 GstStructure *struct1;
1188 GstStructure *struct2;
1190 GstStructure *istruct;
1192 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1193 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1195 if (gst_caps_is_empty (caps1) || gst_caps_is_empty (caps2)) {
1196 return gst_caps_new_empty ();
1198 if (gst_caps_is_any (caps1))
1199 return gst_caps_copy (caps2);
1200 if (gst_caps_is_any (caps2))
1201 return gst_caps_copy (caps1);
1203 dest = gst_caps_new_empty ();
1205 /* run zigzag on top line then right line, this preserves the caps order
1206 * much better than a simple loop.
1208 * This algorithm zigzags over the caps structures as demonstrated in
1209 * the folowing matrix:
1217 * First we iterate over the caps1 structures (top line) intersecting
1218 * the structures diagonally down, then we iterate over the caps2
1221 for (i = 0; i < caps1->structs->len + caps2->structs->len - 1; i++) {
1222 /* caps1 index goes from 0 to caps1->structs->len-1 */
1223 j = MIN (i, caps1->structs->len - 1);
1224 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1225 * up from 1 to caps2->structs->len - 1 */
1228 /* now run the diagonal line, end condition is the left or bottom
1230 while (k < caps2->structs->len) {
1231 struct1 = gst_caps_get_structure (caps1, j);
1232 struct2 = gst_caps_get_structure (caps2, k);
1234 istruct = gst_caps_structure_intersect (struct1, struct2);
1236 gst_caps_append_structure (dest, istruct);
1237 /* move down left */
1240 break; /* so we don't roll back to G_MAXUINT */
1249 const GstStructure *subtract_from;
1256 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1259 SubtractionEntry *e = user_data;
1260 GValue subtraction = { 0, };
1261 const GValue *other;
1262 GstStructure *structure;
1264 other = gst_structure_id_get_value (e->subtract_from, field_id);
1268 if (!gst_value_subtract (&subtraction, other, value))
1270 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1271 g_value_unset (&subtraction);
1274 structure = gst_structure_copy (e->subtract_from);
1275 gst_structure_id_set_value (structure, field_id, &subtraction);
1276 g_value_unset (&subtraction);
1277 e->put_into = g_slist_prepend (e->put_into, structure);
1283 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1284 const GstStructure * subtrahend)
1289 e.subtract_from = minuend;
1292 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1293 gst_caps_structure_subtract_field, &e);
1299 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1300 gst_structure_free (walk->data);
1302 g_slist_free (e.put_into);
1308 * gst_caps_subtract:
1309 * @minuend: #GstCaps to substract from
1310 * @subtrahend: #GstCaps to substract
1312 * Subtracts the @subtrahend from the @minuend.
1313 * <note>This function does not work reliably if optional properties for caps
1314 * are included on one caps and omitted on the other.</note>
1316 * Returns: the resulting caps
1319 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1324 GstCaps *dest = NULL, *src;
1326 g_return_val_if_fail (minuend != NULL, NULL);
1327 g_return_val_if_fail (subtrahend != NULL, NULL);
1329 if (gst_caps_is_empty (minuend) || gst_caps_is_any (subtrahend)) {
1330 return gst_caps_new_empty ();
1332 if (gst_caps_is_empty (subtrahend))
1333 return gst_caps_copy (minuend);
1335 /* FIXME: Do we want this here or above?
1336 The reason we need this is that there is no definition about what
1337 ANY means for specific types, so it's not possible to reduce ANY partially
1338 You can only remove everything or nothing and that is done above.
1339 Note: there's a test that checks this behaviour. */
1340 g_return_val_if_fail (!gst_caps_is_any (minuend), NULL);
1341 g_assert (subtrahend->structs->len > 0);
1343 src = gst_caps_copy (minuend);
1344 for (i = 0; i < subtrahend->structs->len; i++) {
1345 sub = gst_caps_get_structure (subtrahend, i);
1347 gst_caps_unref (src);
1350 dest = gst_caps_new_empty ();
1351 for (j = 0; j < src->structs->len; j++) {
1352 min = gst_caps_get_structure (src, j);
1353 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1356 if (gst_caps_structure_subtract (&list, min, sub)) {
1359 for (walk = list; walk; walk = g_slist_next (walk)) {
1360 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1362 g_slist_free (list);
1364 gst_caps_append_structure (dest, gst_structure_copy (min));
1367 gst_caps_append_structure (dest, gst_structure_copy (min));
1370 if (gst_caps_is_empty (dest)) {
1371 gst_caps_unref (src);
1376 gst_caps_unref (src);
1377 gst_caps_do_simplify (dest);
1383 * @caps1: a #GstCaps to union
1384 * @caps2: a #GstCaps to union
1386 * Creates a new #GstCaps that contains all the formats that are in
1387 * either @caps1 and @caps2.
1389 * Returns: the new #GstCaps
1392 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1397 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2))
1398 return gst_caps_new_any ();
1400 dest1 = gst_caps_copy (caps1);
1401 dest2 = gst_caps_copy (caps2);
1402 gst_caps_append (dest1, dest2);
1404 gst_caps_do_simplify (dest1);
1408 typedef struct _NormalizeForeach
1411 GstStructure *structure;
1416 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1418 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1422 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1423 for (i = 1; i < gst_value_list_get_size (value); i++) {
1424 const GValue *v = gst_value_list_get_value (value, i);
1425 GstStructure *structure = gst_structure_copy (nf->structure);
1427 gst_structure_id_set_value (structure, field_id, v);
1428 gst_caps_append_structure (nf->caps, structure);
1431 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1432 gst_structure_id_set_value (nf->structure, field_id, &val);
1433 g_value_unset (&val);
1441 * gst_caps_normalize:
1442 * @caps: a #GstCaps to normalize
1444 * Creates a new #GstCaps that represents the same set of formats as
1445 * @caps, but contains no lists. Each list is expanded into separate
1448 * Returns: the new #GstCaps
1451 gst_caps_normalize (const GstCaps * caps)
1453 NormalizeForeach nf;
1457 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1459 newcaps = gst_caps_copy (caps);
1462 for (i = 0; i < newcaps->structs->len; i++) {
1463 nf.structure = gst_caps_get_structure (newcaps, i);
1465 while (!gst_structure_foreach (nf.structure,
1466 gst_caps_normalize_foreach, &nf));
1473 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1476 const GstStructure *struct1 = *((const GstStructure **) one);
1477 const GstStructure *struct2 = *((const GstStructure **) two);
1479 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1480 So what's the best way? */
1481 ret = strcmp (gst_structure_get_name (struct1),
1482 gst_structure_get_name (struct2));
1486 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1493 GstStructure *compare;
1498 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1501 UnionField *u = user_data;
1502 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1506 g_value_unset (&u->value);
1509 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1512 g_value_unset (&u->value);
1516 gst_value_union (&u->value, val, value);
1521 gst_caps_structure_simplify (GstStructure ** result,
1522 const GstStructure * simplify, GstStructure * compare)
1525 UnionField field = { 0, {0,}, NULL };
1527 /* try to subtract to get a real subset */
1528 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1529 switch (g_slist_length (list)) {
1534 *result = list->data;
1535 g_slist_free (list);
1541 for (walk = list; walk; walk = g_slist_next (walk)) {
1542 gst_structure_free (walk->data);
1544 g_slist_free (list);
1550 /* try to union both structs */
1551 field.compare = compare;
1552 if (gst_structure_foreach ((GstStructure *) simplify,
1553 gst_caps_structure_figure_out_union, &field)) {
1554 gboolean ret = FALSE;
1556 /* now we know all of simplify's fields are the same in compare
1557 * but at most one field: field.name */
1558 if (G_IS_VALUE (&field.value)) {
1559 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1560 gst_structure_id_set_value (compare, field.name, &field.value);
1564 g_value_unset (&field.value);
1565 } else if (gst_structure_n_fields (simplify) <=
1566 gst_structure_n_fields (compare)) {
1567 /* compare is just more specific, will be optimized away later */
1568 /* FIXME: do this here? */
1569 GST_LOG ("found a case that will be optimized later.");
1571 gchar *one = gst_structure_to_string (simplify);
1572 gchar *two = gst_structure_to_string (compare);
1575 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1587 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1588 GstStructure * new, gint i)
1590 gst_structure_set_parent_refcount (old, NULL);
1591 gst_structure_free (old);
1592 gst_structure_set_parent_refcount (new, &caps->refcount);
1593 g_ptr_array_index (caps->structs, i) = new;
1597 * gst_caps_do_simplify:
1598 * @caps: a #GstCaps to simplify
1600 * Modifies the given @caps inplace into a representation that represents the
1601 * same set of formats, but in a simpler form. Component structures that are
1602 * identical are merged. Component structures that have values that can be
1603 * merged are also merged.
1605 * Returns: TRUE, if the caps could be simplified
1608 gst_caps_do_simplify (GstCaps * caps)
1610 GstStructure *simplify, *compare, *result = NULL;
1612 gboolean changed = FALSE;
1614 g_return_val_if_fail (caps != NULL, FALSE);
1615 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1617 if (gst_caps_get_size (caps) < 2)
1620 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1622 start = caps->structs->len - 1;
1623 for (i = caps->structs->len - 1; i >= 0; i--) {
1624 simplify = gst_caps_get_structure (caps, i);
1625 if (gst_structure_get_name_id (simplify) !=
1626 gst_structure_get_name_id (gst_caps_get_structure (caps, start)))
1628 for (j = start; j >= 0; j--) {
1631 compare = gst_caps_get_structure (caps, j);
1632 if (gst_structure_get_name_id (simplify) !=
1633 gst_structure_get_name_id (compare)) {
1636 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1638 gst_caps_switch_structures (caps, simplify, result, i);
1641 gst_caps_remove_structure (caps, i);
1653 /* gst_caps_do_simplify (caps); */
1657 #ifndef GST_DISABLE_LOADSAVE
1659 * gst_caps_save_thyself:
1660 * @caps: a #GstCaps structure
1661 * @parent: a XML parent node
1663 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1665 * Returns: a XML node pointer
1668 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1670 char *s = gst_caps_to_string (caps);
1672 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1678 * gst_caps_load_thyself:
1679 * @parent: a XML node
1681 * Creates a #GstCaps from its XML serialization.
1683 * Returns: a new #GstCaps structure
1686 gst_caps_load_thyself (xmlNodePtr parent)
1688 if (strcmp ("caps", (char *) parent->name) == 0) {
1689 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1700 * @caps: a pointer to #GstCaps
1701 * @newcaps: a #GstCaps to replace *caps
1703 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1704 * pointed to by @caps, if applicable, then modifies @caps to point to
1705 * @newcaps. An additional ref on @newcaps is taken.
1707 * This function does not take any locks so you might want to lock
1708 * the object owning @caps pointer.
1711 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1715 g_return_if_fail (caps != NULL);
1719 if (newcaps != oldcaps) {
1721 gst_caps_ref (newcaps);
1726 gst_caps_unref (oldcaps);
1731 * gst_caps_to_string:
1734 * Converts @caps to a string representation. This string representation
1735 * can be converted back to a #GstCaps by gst_caps_from_string().
1737 * For debugging purposes its easier to do something like this:
1739 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1741 * This prints the caps in human readble form.
1743 * Returns: a newly allocated string representing @caps.
1746 gst_caps_to_string (const GstCaps * caps)
1751 /* NOTE: This function is potentially called by the debug system,
1752 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1753 * should be careful to avoid recursion. This includes any functions
1754 * called by gst_caps_to_string. In particular, calls should
1755 * not use the GST_PTR_FORMAT extension. */
1758 return g_strdup ("NULL");
1760 if (gst_caps_is_any (caps)) {
1761 return g_strdup ("ANY");
1763 if (gst_caps_is_empty (caps)) {
1764 return g_strdup ("EMPTY");
1767 s = g_string_new ("");
1768 for (i = 0; i < caps->structs->len; i++) {
1769 GstStructure *structure;
1773 g_string_append (s, "; ");
1775 structure = gst_caps_get_structure (caps, i);
1776 sstr = gst_structure_to_string (structure);
1777 g_string_append (s, sstr);
1781 return g_string_free (s, FALSE);
1785 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1787 GstStructure *structure;
1790 g_return_val_if_fail (string, FALSE);
1791 if (strcmp ("ANY", string) == 0) {
1792 caps->flags = GST_CAPS_FLAGS_ANY;
1795 if (strcmp ("EMPTY", string) == 0) {
1799 structure = gst_structure_from_string (string, &s);
1800 if (structure == NULL) {
1803 gst_caps_append_structure (caps, structure);
1807 while (g_ascii_isspace (*s))
1809 structure = gst_structure_from_string (s, &s);
1810 if (structure == NULL) {
1813 gst_caps_append_structure (caps, structure);
1814 while (g_ascii_isspace (*s))
1826 * gst_caps_from_string:
1827 * @string: a string to convert to #GstCaps
1829 * Converts @caps from a string representation.
1831 * Returns: a newly allocated #GstCaps
1834 gst_caps_from_string (const gchar * string)
1838 caps = gst_caps_new_empty ();
1839 if (gst_caps_from_string_inplace (caps, string)) {
1842 gst_caps_unref (caps);
1848 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1850 g_return_if_fail (G_IS_VALUE (src_value));
1851 g_return_if_fail (G_IS_VALUE (dest_value));
1852 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1853 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1854 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1856 dest_value->data[0].v_pointer =
1857 gst_caps_to_string (src_value->data[0].v_pointer);
1861 gst_caps_copy_conditional (GstCaps * src)
1864 return gst_caps_ref (src);