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 */
501 if (!gst_value_subtract (&subtraction, other, value)) {
502 /* empty result -> values are the same, or first was a value and
504 * verify that result is empty by swapping args */
505 if (!gst_value_subtract (&subtraction, value, other)) {
508 g_value_unset (&subtraction);
512 res = gst_value_compare (&subtraction, other);
513 g_value_unset (&subtraction);
515 if (res == GST_VALUE_EQUAL) {
516 /* value was empty ? */
524 gst_caps_structure_is_subset (const GstStructure * minuend,
525 const GstStructure * subtrahend)
527 if ((minuend->name != subtrahend->name) ||
528 (gst_structure_n_fields (minuend) !=
529 gst_structure_n_fields (subtrahend))) {
533 return gst_structure_foreach ((GstStructure *) subtrahend,
534 gst_caps_structure_is_subset_field, (gpointer) minuend);
539 * @caps1: the #GstCaps that will be appended to
540 * @caps2: the #GstCaps to append
542 * Appends the structures contained in @caps2 to @caps1. The structures in
543 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
544 * freed. If either caps is ANY, the resulting caps will be ANY.
547 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
549 GstStructure *structure;
552 g_return_if_fail (GST_IS_CAPS (caps1));
553 g_return_if_fail (GST_IS_CAPS (caps2));
554 g_return_if_fail (IS_WRITABLE (caps1));
555 g_return_if_fail (IS_WRITABLE (caps2));
560 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2)) {
561 /* FIXME: this leaks */
562 caps1->flags |= GST_CAPS_FLAGS_ANY;
563 for (i = caps2->structs->len - 1; i >= 0; i--) {
564 structure = gst_caps_remove_and_get_structure (caps2, i);
565 gst_structure_free (structure);
568 int len = caps2->structs->len;
570 for (i = 0; i < len; i++) {
571 structure = gst_caps_remove_and_get_structure (caps2, 0);
572 gst_caps_append_structure (caps1, structure);
575 gst_caps_unref (caps2); /* guaranteed to free it */
580 * @caps1: the #GstCaps that will take the new entries
581 * @caps2: the #GstCaps to merge in
583 * Appends the structures contained in @caps2 to @caps1 if they are not yet
584 * expressed by @caps1. The structures in @caps2 are not copied -- they are
585 * transferred to @caps1, and then @caps2 is freed.
586 * If either caps is ANY, the resulting caps will be ANY.
591 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
593 GstStructure *structure;
596 g_return_if_fail (GST_IS_CAPS (caps1));
597 g_return_if_fail (GST_IS_CAPS (caps2));
598 g_return_if_fail (IS_WRITABLE (caps1));
599 g_return_if_fail (IS_WRITABLE (caps2));
604 if (gst_caps_is_any (caps1)) {
605 for (i = caps2->structs->len - 1; i >= 0; i--) {
606 structure = gst_caps_remove_and_get_structure (caps2, i);
607 gst_structure_free (structure);
609 } else if (gst_caps_is_any (caps2)) {
610 caps1->flags |= GST_CAPS_FLAGS_ANY;
611 for (i = caps1->structs->len - 1; i >= 0; i--) {
612 structure = gst_caps_remove_and_get_structure (caps1, i);
613 gst_structure_free (structure);
616 int len = caps2->structs->len;
618 for (i = 0; i < len; i++) {
619 structure = gst_caps_remove_and_get_structure (caps2, 0);
620 gst_caps_merge_structure (caps1, structure);
623 GstCaps *com = gst_caps_intersect (caps1, caps2);
624 GstCaps *add = gst_caps_subtract (caps2, com);
626 GST_DEBUG ("common : %d", gst_caps_get_size (com));
627 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
628 gst_caps_append (caps1, add);
629 gst_caps_unref (com);
632 gst_caps_unref (caps2); /* guaranteed to free it */
636 * gst_caps_append_structure:
637 * @caps: the #GstCaps that will be appended to
638 * @structure: the #GstStructure to append
640 * Appends @structure to @caps. The structure is not copied; @caps
641 * becomes the owner of @structure.
644 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
646 g_return_if_fail (GST_IS_CAPS (caps));
647 g_return_if_fail (IS_WRITABLE (caps));
649 if (G_LIKELY (structure)) {
650 g_return_if_fail (structure->parent_refcount == NULL);
653 STRUCTURE_POISON (structure);
656 gst_structure_set_parent_refcount (structure, &caps->refcount);
657 g_ptr_array_add (caps->structs, structure);
662 * gst_caps_remove_structure:
663 * @caps: the #GstCaps to remove from
664 * @idx: Index of the structure to remove
666 * removes the stucture with the given index from the list of structures
667 * contained in @caps.
670 gst_caps_remove_structure (GstCaps * caps, guint idx)
672 GstStructure *structure;
674 g_return_if_fail (caps != NULL);
675 g_return_if_fail (idx <= gst_caps_get_size (caps));
676 g_return_if_fail (IS_WRITABLE (caps));
678 structure = gst_caps_remove_and_get_structure (caps, idx);
679 gst_structure_free (structure);
683 * gst_caps_merge_structure:
684 * @caps: the #GstCaps that will the the new structure
685 * @structure: the #GstStructure to merge
687 * Appends @structure to @caps if its not already expressed by @caps. The
688 * structure is not copied; @caps becomes the owner of @structure.
691 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
693 g_return_if_fail (GST_IS_CAPS (caps));
694 g_return_if_fail (IS_WRITABLE (caps));
696 if (G_LIKELY (structure)) {
697 GstStructure *structure1;
699 gboolean unique = TRUE;
701 g_return_if_fail (structure->parent_refcount == NULL);
704 STRUCTURE_POISON (structure);
707 /* check each structure */
708 for (i = caps->structs->len - 1; i >= 0; i--) {
709 structure1 = gst_caps_get_structure (caps, i);
710 /* if structure is a subset of structure1, then skip it */
711 if (gst_caps_structure_is_subset (structure1, structure)) {
717 gst_structure_set_parent_refcount (structure, &caps->refcount);
718 g_ptr_array_add (caps->structs, structure);
720 gst_structure_free (structure);
730 * Gets the number of structures contained in @caps.
732 * Returns: the number of structures that @caps contains
735 gst_caps_get_size (const GstCaps * caps)
737 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
739 return caps->structs->len;
743 * gst_caps_get_structure:
745 * @index: the index of the structure
747 * Finds the structure in @caps that has the index @index, and
750 * WARNING: This function takes a const GstCaps *, but returns a
751 * non-const GstStructure *. This is for programming convenience --
752 * the caller should be aware that structures inside a constant
753 * #GstCaps should not be modified.
755 * Returns: a pointer to the #GstStructure corresponding to @index
758 gst_caps_get_structure (const GstCaps * caps, guint index)
760 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
761 g_return_val_if_fail (index < caps->structs->len, NULL);
763 return g_ptr_array_index (caps->structs, index);
768 * @caps: the #GstCaps to copy
769 * @nth: the nth structure to copy
771 * Creates a new #GstCaps and appends a copy of the nth structure
772 * contained in @caps.
774 * Returns: the new #GstCaps
777 gst_caps_copy_nth (const GstCaps * caps, guint nth)
780 GstStructure *structure;
782 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
784 newcaps = gst_caps_new_empty ();
785 newcaps->flags = caps->flags;
787 if (caps->structs->len > nth) {
788 structure = gst_caps_get_structure (caps, nth);
789 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
797 * @caps: the #GstCaps to truncate
799 * Destructively discard all but the first structure from @caps. Useful when
800 * fixating. @caps must be writable.
803 gst_caps_truncate (GstCaps * caps)
807 g_return_if_fail (GST_IS_CAPS (caps));
808 g_return_if_fail (IS_WRITABLE (caps));
810 i = caps->structs->len - 1;
813 gst_caps_remove_structure (caps, i--);
817 * gst_caps_set_simple:
818 * @caps: the #GstCaps to set
819 * @field: first field to set
820 * @...: additional parameters
822 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
823 * only has one structure. The arguments must be passed in the same
824 * manner as gst_structure_set(), and be NULL-terminated.
827 gst_caps_set_simple (GstCaps * caps, char *field, ...)
829 GstStructure *structure;
832 g_return_if_fail (GST_IS_CAPS (caps));
833 g_return_if_fail (caps->structs->len == 1);
834 g_return_if_fail (IS_WRITABLE (caps));
836 structure = gst_caps_get_structure (caps, 0);
838 va_start (var_args, field);
839 gst_structure_set_valist (structure, field, var_args);
844 * gst_caps_set_simple_valist:
845 * @caps: the #GstCaps to copy
846 * @field: first field to set
847 * @varargs: additional parameters
849 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
850 * only has one structure. The arguments must be passed in the same
851 * manner as gst_structure_set(), and be NULL-terminated.
854 gst_caps_set_simple_valist (GstCaps * caps, char *field, va_list varargs)
856 GstStructure *structure;
858 g_return_if_fail (GST_IS_CAPS (caps));
859 g_return_if_fail (caps->structs->len != 1);
860 g_return_if_fail (IS_WRITABLE (caps));
862 structure = gst_caps_get_structure (caps, 0);
864 gst_structure_set_valist (structure, field, varargs);
871 * @caps: the #GstCaps to test
873 * Determines if @caps represents any media format.
875 * Returns: TRUE if @caps represents any format.
878 gst_caps_is_any (const GstCaps * caps)
880 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
882 return (caps->flags & GST_CAPS_FLAGS_ANY);
887 * @caps: the #GstCaps to test
889 * Determines if @caps represents no media formats.
891 * Returns: TRUE if @caps represents no formats.
894 gst_caps_is_empty (const GstCaps * caps)
896 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
898 if (caps->flags & GST_CAPS_FLAGS_ANY)
901 return (caps->structs == NULL) || (caps->structs->len == 0);
905 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
908 return gst_value_is_fixed (value);
913 * @caps: the #GstCaps to test
915 * Fixed #GstCaps describe exactly one format, that is, they have exactly
916 * one structure, and each field in the structure describes a fixed type.
917 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
919 * Returns: TRUE if @caps is fixed
922 gst_caps_is_fixed (const GstCaps * caps)
924 GstStructure *structure;
926 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
928 if (caps->structs->len != 1)
931 structure = gst_caps_get_structure (caps, 0);
933 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
937 * gst_caps_is_equal_fixed:
938 * @caps1: the #GstCaps to test
939 * @caps2: the #GstCaps to test
941 * Tests if two #GstCaps are equal. This function only works on fixed
944 * Returns: TRUE if the arguments represent the same format
947 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
949 GstStructure *struct1, *struct2;
951 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
952 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
954 struct1 = gst_caps_get_structure (caps1, 0);
955 struct2 = gst_caps_get_structure (caps2, 0);
957 if (struct1->name != struct2->name) {
960 if (struct1->fields->len != struct2->fields->len) {
964 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
969 * gst_caps_is_always_compatible:
970 * @caps1: the #GstCaps to test
971 * @caps2: the #GstCaps to test
973 * A given #GstCaps structure is always compatible with another if
974 * every media format that is in the first is also contained in the
975 * second. That is, @caps1 is a subset of @caps2.
977 * Returns: TRUE if @caps1 is a subset of @caps2.
980 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
982 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
983 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
985 return gst_caps_is_subset (caps1, caps2);
989 * gst_caps_is_subset:
990 * @subset: a #GstCaps
991 * @superset: a potentially greater #GstCaps
993 * Checks if all caps represented by @subset are also represented by @superset
994 * <note>This function does not work reliably if optional properties for caps
995 * are included on one caps and omitted on the other.</note>
997 * Returns: TRUE if @subset is a subset of @superset
1000 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1005 g_return_val_if_fail (subset != NULL, FALSE);
1006 g_return_val_if_fail (superset != NULL, FALSE);
1008 if (gst_caps_is_empty (subset) || gst_caps_is_any (superset))
1010 if (gst_caps_is_any (subset) || gst_caps_is_empty (superset))
1013 caps = gst_caps_subtract (subset, superset);
1014 ret = gst_caps_is_empty (caps);
1015 gst_caps_unref (caps);
1020 * gst_caps_is_equal:
1021 * @caps1: a #GstCaps
1022 * @caps2: another #GstCaps
1024 * Checks if the given caps represent the same set of caps.
1025 * <note>This function does not work reliably if optional properties for caps
1026 * are included on one caps and omitted on the other.</note>
1028 * This function deals correctly with passing NULL for any of the caps.
1030 * Returns: TRUE if both caps are equal.
1033 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1035 /* NULL <-> NULL is allowed here */
1039 /* one of them NULL => they are different (can't be both NULL because
1040 * we checked that above) */
1041 if (caps1 == NULL || caps2 == NULL)
1044 if (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2))
1045 return gst_caps_is_equal_fixed (caps1, caps2);
1047 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1053 const GstStructure *intersect;
1059 gst_caps_structure_intersect_field (GQuark id, const GValue * val1,
1062 IntersectData *idata = (IntersectData *) data;
1063 GValue dest_value = { 0 };
1064 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1067 gst_structure_id_set_value (idata->dest, id, val1);
1068 } else if (idata->first_run) {
1069 if (gst_value_intersect (&dest_value, val1, val2)) {
1070 gst_structure_id_set_value (idata->dest, id, &dest_value);
1071 g_value_unset (&dest_value);
1080 static GstStructure *
1081 gst_caps_structure_intersect (const GstStructure * struct1,
1082 const GstStructure * struct2)
1086 g_return_val_if_fail (struct1 != NULL, NULL);
1087 g_return_val_if_fail (struct2 != NULL, NULL);
1089 if (struct1->name != struct2->name)
1092 data.dest = gst_structure_id_empty_new (struct1->name);
1093 data.intersect = struct2;
1094 data.first_run = TRUE;
1095 if (!gst_structure_foreach ((GstStructure *) struct1,
1096 gst_caps_structure_intersect_field, &data))
1099 data.intersect = struct1;
1100 data.first_run = FALSE;
1101 if (!gst_structure_foreach ((GstStructure *) struct2,
1102 gst_caps_structure_intersect_field, &data))
1108 gst_structure_free (data.dest);
1113 static GstStructure *
1114 gst_caps_structure_union (const GstStructure * struct1,
1115 const GstStructure * struct2)
1119 const GstStructureField *field1;
1120 const GstStructureField *field2;
1123 /* FIXME this doesn't actually work */
1125 if (struct1->name != struct2->name)
1128 dest = gst_structure_id_empty_new (struct1->name);
1130 for (i = 0; i < struct1->fields->len; i++) {
1131 GValue dest_value = { 0 };
1133 field1 = GST_STRUCTURE_FIELD (struct1, i);
1134 field2 = gst_structure_id_get_field (struct2, field1->name);
1136 if (field2 == NULL) {
1139 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1140 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1143 ret = gst_value_compare (&field1->value, &field2->value);
1155 * gst_caps_intersect:
1156 * @caps1: a #GstCaps to intersect
1157 * @caps2: a #GstCaps to intersect
1159 * Creates a new #GstCaps that contains all the formats that are common
1160 * to both @caps1 and @caps2.
1162 * Returns: the new #GstCaps
1165 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1167 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1170 GstStructure *struct1;
1171 GstStructure *struct2;
1173 GstStructure *istruct;
1175 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1176 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1178 if (gst_caps_is_empty (caps1) || gst_caps_is_empty (caps2)) {
1179 return gst_caps_new_empty ();
1181 if (gst_caps_is_any (caps1))
1182 return gst_caps_copy (caps2);
1183 if (gst_caps_is_any (caps2))
1184 return gst_caps_copy (caps1);
1186 dest = gst_caps_new_empty ();
1188 /* run zigzag on top line then right line, this preserves the caps order
1189 * much better than a simple loop.
1191 * This algorithm zigzags over the caps structures as demonstrated in
1192 * the folowing matrix:
1200 * First we iterate over the caps1 structures (top line) intersecting
1201 * the structures diagonally down, then we iterate over the caps2
1204 for (i = 0; i < caps1->structs->len + caps2->structs->len - 1; i++) {
1205 /* caps1 index goes from 0 to caps1->structs->len-1 */
1206 j = MIN (i, caps1->structs->len - 1);
1207 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1208 * up from 1 to caps2->structs->len - 1 */
1211 /* now run the diagonal line, end condition is the left or bottom
1213 while (k < caps2->structs->len) {
1214 struct1 = gst_caps_get_structure (caps1, j);
1215 struct2 = gst_caps_get_structure (caps2, k);
1217 istruct = gst_caps_structure_intersect (struct1, struct2);
1219 gst_caps_append_structure (dest, istruct);
1220 /* move down left */
1223 break; /* so we don't roll back to G_MAXUINT */
1232 const GstStructure *subtract_from;
1239 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1242 SubtractionEntry *e = user_data;
1243 GValue subtraction = { 0, };
1244 const GValue *other;
1245 GstStructure *structure;
1247 other = gst_structure_id_get_value (e->subtract_from, field_id);
1251 if (!gst_value_subtract (&subtraction, other, value))
1253 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1254 g_value_unset (&subtraction);
1257 structure = gst_structure_copy (e->subtract_from);
1258 gst_structure_id_set_value (structure, field_id, &subtraction);
1259 g_value_unset (&subtraction);
1260 e->put_into = g_slist_prepend (e->put_into, structure);
1266 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1267 const GstStructure * subtrahend)
1272 e.subtract_from = minuend;
1275 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1276 gst_caps_structure_subtract_field, &e);
1282 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1283 gst_structure_free (walk->data);
1285 g_slist_free (e.put_into);
1291 * gst_caps_subtract:
1292 * @minuend: #GstCaps to substract from
1293 * @subtrahend: #GstCaps to substract
1295 * Subtracts the @subtrahend from the @minuend.
1296 * <note>This function does not work reliably if optional properties for caps
1297 * are included on one caps and omitted on the other.</note>
1299 * Returns: the resulting caps
1302 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1307 GstCaps *dest = NULL, *src;
1309 g_return_val_if_fail (minuend != NULL, NULL);
1310 g_return_val_if_fail (subtrahend != NULL, NULL);
1312 if (gst_caps_is_empty (minuend) || gst_caps_is_any (subtrahend)) {
1313 return gst_caps_new_empty ();
1315 if (gst_caps_is_empty (subtrahend))
1316 return gst_caps_copy (minuend);
1318 /* FIXME: Do we want this here or above?
1319 The reason we need this is that there is no definition about what
1320 ANY means for specific types, so it's not possible to reduce ANY partially
1321 You can only remove everything or nothing and that is done above.
1322 Note: there's a test that checks this behaviour. */
1323 g_return_val_if_fail (!gst_caps_is_any (minuend), NULL);
1324 g_assert (subtrahend->structs->len > 0);
1326 src = gst_caps_copy (minuend);
1327 for (i = 0; i < subtrahend->structs->len; i++) {
1328 sub = gst_caps_get_structure (subtrahend, i);
1330 gst_caps_unref (src);
1333 dest = gst_caps_new_empty ();
1334 for (j = 0; j < src->structs->len; j++) {
1335 min = gst_caps_get_structure (src, j);
1336 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1339 if (gst_caps_structure_subtract (&list, min, sub)) {
1342 for (walk = list; walk; walk = g_slist_next (walk)) {
1343 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1345 g_slist_free (list);
1347 gst_caps_append_structure (dest, gst_structure_copy (min));
1350 gst_caps_append_structure (dest, gst_structure_copy (min));
1353 if (gst_caps_is_empty (dest)) {
1354 gst_caps_unref (src);
1359 gst_caps_unref (src);
1360 gst_caps_do_simplify (dest);
1366 * @caps1: a #GstCaps to union
1367 * @caps2: a #GstCaps to union
1369 * Creates a new #GstCaps that contains all the formats that are in
1370 * either @caps1 and @caps2.
1372 * Returns: the new #GstCaps
1375 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1380 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2))
1381 return gst_caps_new_any ();
1383 dest1 = gst_caps_copy (caps1);
1384 dest2 = gst_caps_copy (caps2);
1385 gst_caps_append (dest1, dest2);
1387 gst_caps_do_simplify (dest1);
1391 typedef struct _NormalizeForeach
1394 GstStructure *structure;
1399 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1401 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1405 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1406 for (i = 1; i < gst_value_list_get_size (value); i++) {
1407 const GValue *v = gst_value_list_get_value (value, i);
1408 GstStructure *structure = gst_structure_copy (nf->structure);
1410 gst_structure_id_set_value (structure, field_id, v);
1411 gst_caps_append_structure (nf->caps, structure);
1414 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1415 gst_structure_id_set_value (nf->structure, field_id, &val);
1416 g_value_unset (&val);
1424 * gst_caps_normalize:
1425 * @caps: a #GstCaps to normalize
1427 * Creates a new #GstCaps that represents the same set of formats as
1428 * @caps, but contains no lists. Each list is expanded into separate
1431 * Returns: the new #GstCaps
1434 gst_caps_normalize (const GstCaps * caps)
1436 NormalizeForeach nf;
1440 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1442 newcaps = gst_caps_copy (caps);
1445 for (i = 0; i < newcaps->structs->len; i++) {
1446 nf.structure = gst_caps_get_structure (newcaps, i);
1448 while (!gst_structure_foreach (nf.structure,
1449 gst_caps_normalize_foreach, &nf));
1456 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1459 const GstStructure *struct1 = *((const GstStructure **) one);
1460 const GstStructure *struct2 = *((const GstStructure **) two);
1462 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1463 So what's the best way? */
1464 ret = strcmp (gst_structure_get_name (struct1),
1465 gst_structure_get_name (struct2));
1469 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1476 GstStructure *compare;
1481 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1484 UnionField *u = user_data;
1485 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1489 g_value_unset (&u->value);
1492 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1495 g_value_unset (&u->value);
1499 gst_value_union (&u->value, val, value);
1504 gst_caps_structure_simplify (GstStructure ** result,
1505 const GstStructure * simplify, GstStructure * compare)
1508 UnionField field = { 0, {0,}, NULL };
1510 /* try to subtract to get a real subset */
1511 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1512 switch (g_slist_length (list)) {
1517 *result = list->data;
1518 g_slist_free (list);
1524 for (walk = list; walk; walk = g_slist_next (walk)) {
1525 gst_structure_free (walk->data);
1527 g_slist_free (list);
1533 /* try to union both structs */
1534 field.compare = compare;
1535 if (gst_structure_foreach ((GstStructure *) simplify,
1536 gst_caps_structure_figure_out_union, &field)) {
1537 gboolean ret = FALSE;
1539 /* now we know all of simplify's fields are the same in compare
1540 * but at most one field: field.name */
1541 if (G_IS_VALUE (&field.value)) {
1542 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1543 gst_structure_id_set_value (compare, field.name, &field.value);
1547 g_value_unset (&field.value);
1548 } else if (gst_structure_n_fields (simplify) <=
1549 gst_structure_n_fields (compare)) {
1550 /* compare is just more specific, will be optimized away later */
1551 /* FIXME: do this here? */
1552 GST_LOG ("found a case that will be optimized later.");
1554 gchar *one = gst_structure_to_string (simplify);
1555 gchar *two = gst_structure_to_string (compare);
1558 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1570 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1571 GstStructure * new, gint i)
1573 gst_structure_set_parent_refcount (old, NULL);
1574 gst_structure_free (old);
1575 gst_structure_set_parent_refcount (new, &caps->refcount);
1576 g_ptr_array_index (caps->structs, i) = new;
1580 * gst_caps_do_simplify:
1581 * @caps: a #GstCaps to simplify
1583 * Modifies the given @caps inplace into a representation that represents the
1584 * same set of formats, but in a simpler form. Component structures that are
1585 * identical are merged. Component structures that have values that can be
1586 * merged are also merged.
1588 * Returns: TRUE, if the caps could be simplified
1591 gst_caps_do_simplify (GstCaps * caps)
1593 GstStructure *simplify, *compare, *result = NULL;
1595 gboolean changed = FALSE;
1597 g_return_val_if_fail (caps != NULL, FALSE);
1598 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1600 if (gst_caps_get_size (caps) < 2)
1603 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1605 start = caps->structs->len - 1;
1606 for (i = caps->structs->len - 1; i >= 0; i--) {
1607 simplify = gst_caps_get_structure (caps, i);
1608 if (gst_structure_get_name_id (simplify) !=
1609 gst_structure_get_name_id (gst_caps_get_structure (caps, start)))
1611 for (j = start; j >= 0; j--) {
1614 compare = gst_caps_get_structure (caps, j);
1615 if (gst_structure_get_name_id (simplify) !=
1616 gst_structure_get_name_id (compare)) {
1619 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1621 gst_caps_switch_structures (caps, simplify, result, i);
1624 gst_caps_remove_structure (caps, i);
1636 /* gst_caps_do_simplify (caps); */
1640 #ifndef GST_DISABLE_LOADSAVE
1642 * gst_caps_save_thyself:
1643 * @caps: a #GstCaps structure
1644 * @parent: a XML parent node
1646 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1648 * Returns: a XML node pointer
1651 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1653 char *s = gst_caps_to_string (caps);
1655 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1661 * gst_caps_load_thyself:
1662 * @parent: a XML node
1664 * Creates a #GstCaps from its XML serialization.
1666 * Returns: a new #GstCaps structure
1669 gst_caps_load_thyself (xmlNodePtr parent)
1671 if (strcmp ("caps", (char *) parent->name) == 0) {
1672 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1683 * @caps: a pointer to #GstCaps
1684 * @newcaps: a #GstCaps to replace *caps
1686 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1687 * pointed to by @caps, if applicable, then modifies @caps to point to
1688 * @newcaps. An additional ref on @newcaps is taken.
1690 * This function does not take any locks so you might want to lock
1691 * the object owning @caps pointer.
1694 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1698 g_return_if_fail (caps != NULL);
1702 if (newcaps != oldcaps) {
1704 gst_caps_ref (newcaps);
1709 gst_caps_unref (oldcaps);
1714 * gst_caps_to_string:
1717 * Converts @caps to a string representation. This string representation
1718 * can be converted back to a #GstCaps by gst_caps_from_string().
1720 * For debugging purposes its easier to do something like this:
1722 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1724 * This prints the caps in human readble form.
1726 * Returns: a newly allocated string representing @caps.
1729 gst_caps_to_string (const GstCaps * caps)
1734 /* NOTE: This function is potentially called by the debug system,
1735 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1736 * should be careful to avoid recursion. This includes any functions
1737 * called by gst_caps_to_string. In particular, calls should
1738 * not use the GST_PTR_FORMAT extension. */
1741 return g_strdup ("NULL");
1743 if (gst_caps_is_any (caps)) {
1744 return g_strdup ("ANY");
1746 if (gst_caps_is_empty (caps)) {
1747 return g_strdup ("EMPTY");
1750 s = g_string_new ("");
1751 for (i = 0; i < caps->structs->len; i++) {
1752 GstStructure *structure;
1756 g_string_append (s, "; ");
1758 structure = gst_caps_get_structure (caps, i);
1759 sstr = gst_structure_to_string (structure);
1760 g_string_append (s, sstr);
1764 return g_string_free (s, FALSE);
1768 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1770 GstStructure *structure;
1773 g_return_val_if_fail (string, FALSE);
1774 if (strcmp ("ANY", string) == 0) {
1775 caps->flags = GST_CAPS_FLAGS_ANY;
1778 if (strcmp ("EMPTY", string) == 0) {
1782 structure = gst_structure_from_string (string, &s);
1783 if (structure == NULL) {
1786 gst_caps_append_structure (caps, structure);
1790 while (g_ascii_isspace (*s))
1792 structure = gst_structure_from_string (s, &s);
1793 if (structure == NULL) {
1796 gst_caps_append_structure (caps, structure);
1797 while (g_ascii_isspace (*s))
1809 * gst_caps_from_string:
1810 * @string: a string to convert to #GstCaps
1812 * Converts @caps from a string representation.
1814 * Returns: a newly allocated #GstCaps
1817 gst_caps_from_string (const gchar * string)
1821 caps = gst_caps_new_empty ();
1822 if (gst_caps_from_string_inplace (caps, string)) {
1825 gst_caps_unref (caps);
1831 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1833 g_return_if_fail (G_IS_VALUE (src_value));
1834 g_return_if_fail (G_IS_VALUE (dest_value));
1835 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1836 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1837 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1839 dest_value->data[0].v_pointer =
1840 gst_caps_to_string (src_value->data[0].v_pointer);
1844 gst_caps_copy_conditional (GstCaps * src)
1847 return gst_caps_ref (src);