2 * Copyright (C) <2003> David A. Schleef <ds@schleef.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
22 * @short_description: Structure describing sets of media formats
23 * @see_also: #GstStructure
25 * Caps (capabilities) are lighweight refcounted objects describing media types.
26 * They are composed of an array of #GstStructure.
28 * Caps are exposed on #GstPadTemplate to describe all possible types a
29 * given pad can handle. They are also stored in the registry along with
30 * a description of the element.
32 * Caps are exposed on the element pads using the gst_pad_get_caps() pad
33 * function. This function describes the possible types that the pad can
34 * handle or produce at runtime.
36 * Caps are also attached to buffers to describe to content of the data
37 * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
38 * a #GstBuffer allow for format negotiation upstream and downstream.
40 * A #GstCaps can be constructed with the following code fragment:
43 * <title>Creating caps</title>
46 * caps = gst_caps_new_simple ("video/x-raw-yuv",
47 * "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
48 * "framerate", G_TYPE_DOUBLE, 25.0,
49 * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
50 * "width", G_TYPE_INT, 320,
51 * "height", G_TYPE_INT, 240,
56 * A #GstCaps is fixed when it has no properties with ranges or lists. Use
57 * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
58 * set on a #GstPad or #GstBuffer.
60 * Various methods exist to work with the media types such as subtracting
63 * Last reviewed on 2005-11-23 (0.9.5)
72 #include "gst_private.h"
75 #define DEBUG_REFCOUNT
77 #define CAPS_POISON(caps) G_STMT_START{ \
79 GstCaps *_newcaps = gst_caps_copy (caps); \
80 gst_caps_unref(caps); \
84 #define STRUCTURE_POISON(structure) G_STMT_START{ \
86 GstStructure *_newstruct = gst_structure_copy (structure); \
87 gst_structure_free(structure); \
88 structure = _newstruct; \
91 #define IS_WRITABLE(caps) \
92 (g_atomic_int_get (&(caps)->refcount) == 1)
95 static void gst_caps_transform_to_string (const GValue * src_value,
97 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
98 const gchar * string);
99 static GstCaps *gst_caps_copy_conditional (GstCaps * src);
102 gst_caps_get_type (void)
104 static GType gst_caps_type = 0;
106 if (!gst_caps_type) {
107 gst_caps_type = g_boxed_type_register_static ("GstCaps",
108 (GBoxedCopyFunc) gst_caps_copy_conditional,
109 (GBoxedFreeFunc) gst_caps_unref);
111 g_value_register_transform_func (gst_caps_type,
112 G_TYPE_STRING, gst_caps_transform_to_string);
115 return gst_caps_type;
118 /* creation/deletion */
121 * gst_caps_new_empty:
123 * Creates a new #GstCaps that is empty. That is, the returned
124 * #GstCaps contains no media formats.
125 * Caller is responsible for unreffing the returned caps.
127 * Returns: the new #GstCaps
130 gst_caps_new_empty (void)
132 GstCaps *caps = g_new0 (GstCaps, 1);
134 g_atomic_int_inc (&caps->refcount);
135 caps->type = GST_TYPE_CAPS;
136 caps->structs = g_ptr_array_new ();
138 #ifdef DEBUG_REFCOUNT
139 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
148 * Creates a new #GstCaps that indicates that it is compatible with
151 * Returns: the new #GstCaps
154 gst_caps_new_any (void)
156 GstCaps *caps = gst_caps_new_empty ();
158 caps->flags = GST_CAPS_FLAGS_ANY;
164 * gst_caps_new_simple:
165 * @media_type: the media type of the structure
166 * @fieldname: first field to set
167 * @...: additional arguments
169 * Creates a new #GstCaps that contains one #GstStructure. The
170 * structure is defined by the arguments, which have the same format
171 * as gst_structure_new().
172 * Caller is responsible for unreffing the returned caps.
174 * Returns: the new #GstCaps
177 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
180 GstStructure *structure;
183 caps = gst_caps_new_empty ();
185 va_start (var_args, fieldname);
186 structure = gst_structure_new_valist (media_type, fieldname, var_args);
189 gst_caps_append_structure (caps, structure);
196 * @struct1: the first structure to add
197 * @...: additional structures to add
199 * Creates a new #GstCaps and adds all the structures listed as
200 * arguments. The list must be NULL-terminated. The structures
201 * are not copied; the returned #GstCaps owns the structures.
203 * Returns: the new #GstCaps
206 gst_caps_new_full (GstStructure * struct1, ...)
211 va_start (var_args, struct1);
212 caps = gst_caps_new_full_valist (struct1, var_args);
219 * gst_caps_new_full_valist:
220 * @structure: the first structure to add
221 * @var_args: additional structures to add
223 * Creates a new #GstCaps and adds all the structures listed as
224 * arguments. The list must be NULL-terminated. The structures
225 * are not copied; the returned #GstCaps owns the structures.
227 * Returns: the new #GstCaps
230 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
234 caps = gst_caps_new_empty ();
237 gst_caps_append_structure (caps, structure);
238 structure = va_arg (var_args, GstStructure *);
246 * @caps: the #GstCaps to copy
248 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
249 * refcount of 1, owned by the caller. The structures are copied as well.
251 * Note that this function is the semantic equivalent of a gst_caps_ref()
252 * followed by a gst_caps_make_writable(). If you only want to hold on to a
253 * reference to the data, you should use gst_caps_ref().
255 * When you are finished with the caps, call gst_caps_unref() on it.
257 * Returns: the new #GstCaps
260 gst_caps_copy (const GstCaps * caps)
263 GstStructure *structure;
266 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
268 newcaps = gst_caps_new_empty ();
269 newcaps->flags = caps->flags;
271 for (i = 0; i < caps->structs->len; i++) {
272 structure = gst_caps_get_structure (caps, i);
273 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
280 _gst_caps_free (GstCaps * caps)
282 GstStructure *structure;
285 /* The refcount must be 0, but since we're only called by gst_caps_unref,
286 * don't bother testing. */
288 for (i = 0; i < caps->structs->len; i++) {
289 structure = (GstStructure *) gst_caps_get_structure (caps, i);
290 gst_structure_set_parent_refcount (structure, NULL);
291 gst_structure_free (structure);
293 g_ptr_array_free (caps->structs, TRUE);
295 memset (caps, 0xff, sizeof (GstCaps));
301 * gst_caps_make_writable:
302 * @caps: the #GstCaps to make writable
304 * Returns a writable copy of @caps.
306 * If there is only one reference count on @caps, the caller must be the owner,
307 * and so this function will return the caps object unchanged. If on the other
308 * hand there is more than one reference on the object, a new caps object will
309 * be returned. The caller's reference on @caps will be removed, and instead the
310 * caller will own a reference to the returned object.
312 * In short, this function unrefs the caps in the argument and refs the caps
313 * that it returns. Don't access the argument after calling this function. See
314 * also: gst_caps_ref().
316 * Returns: the same #GstCaps object.
319 gst_caps_make_writable (GstCaps * caps)
323 g_return_val_if_fail (caps != NULL, NULL);
325 /* we are the only instance reffing this caps */
326 if (g_atomic_int_get (&caps->refcount) == 1)
330 copy = gst_caps_copy (caps);
331 gst_caps_unref (caps);
338 * @caps: the #GstCaps to reference
340 * Add a reference to a #GstCaps object.
342 * From this point on, until the caller calls gst_caps_unref() or
343 * gst_caps_make_writable(), it is guaranteed that the caps object will not
344 * change. This means its structures won't change, etc. To use a #GstCaps
345 * object, you must always have a refcount on it -- either the one made
346 * implicitly by gst_caps_new(), or via taking one explicitly with this
349 * Returns: the same #GstCaps object.
352 gst_caps_ref (GstCaps * caps)
354 g_return_val_if_fail (caps != NULL, NULL);
356 #ifdef DEBUG_REFCOUNT
357 GST_CAT_LOG (GST_CAT_CAPS, "%p %d->%d", caps,
358 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) + 1);
360 g_return_val_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0, NULL);
362 g_atomic_int_inc (&caps->refcount);
369 * @caps: the #GstCaps to unref
371 * Unref a #GstCaps and and free all its structures and the
372 * structures' values when the refcount reaches 0.
375 gst_caps_unref (GstCaps * caps)
377 g_return_if_fail (caps != NULL);
379 #ifdef DEBUG_REFCOUNT
380 GST_CAT_LOG (GST_CAT_CAPS, "%p %d->%d", caps,
381 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) - 1);
384 g_return_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0);
386 /* if we ended up with the refcount at zero, free the caps */
387 if (g_atomic_int_dec_and_test (&caps->refcount)) {
388 _gst_caps_free (caps);
393 * gst_static_caps_get:
394 * @static_caps: the #GstStaticCaps to convert
396 * Converts a #GstStaticCaps to a #GstCaps.
398 * Returns: A pointer to the #GstCaps. Unref after usage. Since the
399 * core holds an additional ref to the returned caps,
400 * use gst_caps_make_writable() on the returned caps to modify it.
403 gst_static_caps_get (GstStaticCaps * static_caps)
405 GstCaps *caps = (GstCaps *) static_caps;
408 if (caps->type == 0) {
409 if (static_caps->string == NULL) {
410 g_warning ("static caps is NULL");
414 caps->type = GST_TYPE_CAPS;
415 /* initialize the caps to a refcount of 1 so the caps can be writable... */
416 gst_atomic_int_set (&caps->refcount, 1);
417 caps->structs = g_ptr_array_new ();
418 ret = gst_caps_from_string_inplace (caps, static_caps->string);
421 g_critical ("Could not convert static caps \"%s\"", static_caps->string);
424 /* ref the caps, makes it not writable */
432 static GstStructure *
433 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
435 /* don't use index_fast, gst_caps_simplify relies on the order */
436 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
438 gst_structure_set_parent_refcount (s, NULL);
444 * @caps1: the #GstCaps that will be appended to
445 * @caps2: the #GstCaps to append
447 * Appends the structures contained in @caps2 to @caps1. The structures in
448 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
449 * freed. If either caps is ANY, the resulting caps will be ANY.
452 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
454 GstStructure *structure;
457 g_return_if_fail (GST_IS_CAPS (caps1));
458 g_return_if_fail (GST_IS_CAPS (caps2));
459 g_return_if_fail (IS_WRITABLE (caps1));
460 g_return_if_fail (IS_WRITABLE (caps2));
465 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2)) {
466 /* FIXME: this leaks */
467 caps1->flags |= GST_CAPS_FLAGS_ANY;
468 for (i = caps2->structs->len - 1; i >= 0; i--) {
469 structure = gst_caps_remove_and_get_structure (caps2, i);
470 gst_structure_free (structure);
473 int len = caps2->structs->len;
475 for (i = 0; i < len; i++) {
476 structure = gst_caps_remove_and_get_structure (caps2, 0);
477 gst_caps_append_structure (caps1, structure);
480 gst_caps_unref (caps2); /* guaranteed to free it */
484 * gst_caps_append_structure:
485 * @caps: the #GstCaps that will be appended to
486 * @structure: the #GstStructure to append
488 * Appends @structure to @caps. The structure is not copied; @caps
489 * becomes the owner of @structure.
492 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
494 g_return_if_fail (GST_IS_CAPS (caps));
495 g_return_if_fail (IS_WRITABLE (caps));
498 g_return_if_fail (structure->parent_refcount == NULL);
501 STRUCTURE_POISON (structure);
504 gst_structure_set_parent_refcount (structure, &caps->refcount);
505 g_ptr_array_add (caps->structs, structure);
510 * gst_caps_remove_structure:
511 * @caps: the #GstCaps to remove from
512 * @idx: Index of the structure to remove
514 * removes the stucture with the given index from the list of structures
515 * contained in @caps.
518 gst_caps_remove_structure (GstCaps * caps, guint idx)
520 GstStructure *structure;
522 g_return_if_fail (caps != NULL);
523 g_return_if_fail (idx <= gst_caps_get_size (caps));
524 g_return_if_fail (IS_WRITABLE (caps));
526 structure = gst_caps_remove_and_get_structure (caps, idx);
527 gst_structure_free (structure);
531 * gst_caps_split_one:
534 * This function is not implemented.
539 gst_caps_split_one (GstCaps * caps)
542 g_critical ("unimplemented");
551 * Gets the number of structures contained in @caps.
553 * Returns: the number of structures that @caps contains
556 gst_caps_get_size (const GstCaps * caps)
558 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
560 return caps->structs->len;
564 * gst_caps_get_structure:
566 * @index: the index of the structure
568 * Finds the structure in @caps that has the index @index, and
571 * WARNING: This function takes a const GstCaps *, but returns a
572 * non-const GstStructure *. This is for programming convenience --
573 * the caller should be aware that structures inside a constant
574 * #GstCaps should not be modified.
576 * Returns: a pointer to the #GstStructure corresponding to @index
579 gst_caps_get_structure (const GstCaps * caps, guint index)
581 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
582 g_return_val_if_fail (index >= 0, NULL);
583 g_return_val_if_fail (index < caps->structs->len, NULL);
585 return g_ptr_array_index (caps->structs, index);
590 * @caps: the #GstCaps to copy
591 * @nth: the nth structure to copy
593 * Creates a new #GstCaps and appends a copy of the nth structure
594 * contained in @caps.
596 * Returns: the new #GstCaps
599 gst_caps_copy_nth (const GstCaps * caps, guint nth)
602 GstStructure *structure;
604 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
606 newcaps = gst_caps_new_empty ();
607 newcaps->flags = caps->flags;
609 if (caps->structs->len > nth) {
610 structure = gst_caps_get_structure (caps, nth);
611 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
619 * @caps: the #GstCaps to truncate
621 * Destructively discard all but the first structure from @caps. Useful when
622 * fixating. @caps must be writable.
625 gst_caps_truncate (GstCaps * caps)
629 g_return_if_fail (GST_IS_CAPS (caps));
630 g_return_if_fail (IS_WRITABLE (caps));
632 i = caps->structs->len - 1;
635 gst_caps_remove_structure (caps, i--);
639 * gst_caps_set_simple:
640 * @caps: the #GstCaps to set
641 * @field: first field to set
642 * @...: additional parameters
644 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
645 * only has one structure. The arguments must be passed in the same
646 * manner as gst_structure_set(), and be NULL-terminated.
649 gst_caps_set_simple (GstCaps * caps, char *field, ...)
651 GstStructure *structure;
654 g_return_if_fail (GST_IS_CAPS (caps));
655 g_return_if_fail (caps->structs->len == 1);
656 g_return_if_fail (IS_WRITABLE (caps));
658 structure = gst_caps_get_structure (caps, 0);
660 va_start (var_args, field);
661 gst_structure_set_valist (structure, field, var_args);
666 * gst_caps_set_simple_valist:
667 * @caps: the #GstCaps to copy
668 * @field: first field to set
669 * @varargs: additional parameters
671 * Sets fields in a simple #GstCaps. A simple #GstCaps is one that
672 * only has one structure. The arguments must be passed in the same
673 * manner as gst_structure_set(), and be NULL-terminated.
676 gst_caps_set_simple_valist (GstCaps * caps, char *field, va_list varargs)
678 GstStructure *structure;
680 g_return_if_fail (GST_IS_CAPS (caps));
681 g_return_if_fail (caps->structs->len != 1);
682 g_return_if_fail (IS_WRITABLE (caps));
684 structure = gst_caps_get_structure (caps, 0);
686 gst_structure_set_valist (structure, field, varargs);
693 * @caps: the #GstCaps to test
695 * Determines if @caps represents any media format.
697 * Returns: TRUE if @caps represents any format.
700 gst_caps_is_any (const GstCaps * caps)
702 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
704 return (caps->flags & GST_CAPS_FLAGS_ANY);
709 * @caps: the #GstCaps to test
711 * Determines if @caps represents no media formats.
713 * Returns: TRUE if @caps represents no formats.
716 gst_caps_is_empty (const GstCaps * caps)
718 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
720 if (caps->flags & GST_CAPS_FLAGS_ANY)
723 return (caps->structs == NULL) || (caps->structs->len == 0);
727 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
730 return gst_value_is_fixed (value);
735 * @caps: the #GstCaps to test
737 * Fixed #GstCaps describe exactly one format, that is, they have exactly
738 * one structure, and each field in the structure describes a fixed type.
739 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
741 * Returns: TRUE if @caps is fixed
744 gst_caps_is_fixed (const GstCaps * caps)
746 GstStructure *structure;
748 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
750 if (caps->structs->len != 1)
753 structure = gst_caps_get_structure (caps, 0);
755 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
759 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
762 GstStructure *struct1 = (GstStructure *) data;
763 const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
767 if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
775 * gst_caps_is_equal_fixed:
776 * @caps1: the #GstCaps to test
777 * @caps2: the #GstCaps to test
779 * Tests if two #GstCaps are equal. This function only works on fixed
782 * Returns: TRUE if the arguments represent the same format
785 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
787 GstStructure *struct1, *struct2;
789 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
790 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
792 struct1 = gst_caps_get_structure (caps1, 0);
793 struct2 = gst_caps_get_structure (caps2, 0);
795 if (struct1->name != struct2->name) {
798 if (struct1->fields->len != struct2->fields->len) {
802 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
807 * gst_caps_is_always_compatible:
808 * @caps1: the #GstCaps to test
809 * @caps2: the #GstCaps to test
811 * A given #GstCaps structure is always compatible with another if
812 * every media format that is in the first is also contained in the
813 * second. That is, @caps1 is a subset of @caps2.
815 * Returns: TRUE if @caps1 is a subset of @caps2.
818 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
820 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
821 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
823 return gst_caps_is_subset (caps1, caps2);
827 * gst_caps_is_subset:
828 * @subset: a #GstCaps
829 * @superset: a potentially greater #GstCaps
831 * Checks if all caps represented by @subset are also represented by @superset
832 * <note>This function does not work reliably if optional properties for caps
833 * are included on one caps and omitted on the other.</note>
835 * Returns: TRUE if @subset is a subset of @superset
838 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
843 g_return_val_if_fail (subset != NULL, FALSE);
844 g_return_val_if_fail (superset != NULL, FALSE);
846 if (gst_caps_is_empty (subset) || gst_caps_is_any (superset))
848 if (gst_caps_is_any (subset) || gst_caps_is_empty (superset))
851 caps = gst_caps_subtract (subset, superset);
852 ret = gst_caps_is_empty (caps);
853 gst_caps_unref (caps);
860 * @caps2: another #GstCaps
862 * Checks if the given caps represent the same set of caps.
863 * <note>This function does not work reliably if optional properties for caps
864 * are included on one caps and omitted on the other.</note>
866 * Returns: TRUE if both caps are equal
869 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
871 /* NULL <-> NULL is allowed here */
875 /* one of them NULL => they are different (can't be both NULL because
876 * we checked that above) */
877 if (caps1 == NULL || caps2 == NULL)
880 if (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2))
881 return gst_caps_is_equal_fixed (caps1, caps2);
883 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
889 const GstStructure *intersect;
895 gst_caps_structure_intersect_field (GQuark id, const GValue * val1,
898 IntersectData *idata = (IntersectData *) data;
899 GValue dest_value = { 0 };
900 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
903 gst_structure_id_set_value (idata->dest, id, val1);
904 } else if (idata->first_run) {
905 if (gst_value_intersect (&dest_value, val1, val2)) {
906 gst_structure_id_set_value (idata->dest, id, &dest_value);
907 g_value_unset (&dest_value);
916 static GstStructure *
917 gst_caps_structure_intersect (const GstStructure * struct1,
918 const GstStructure * struct2)
922 g_return_val_if_fail (struct1 != NULL, NULL);
923 g_return_val_if_fail (struct2 != NULL, NULL);
925 if (struct1->name != struct2->name)
928 data.dest = gst_structure_id_empty_new (struct1->name);
929 data.intersect = struct2;
930 data.first_run = TRUE;
931 if (!gst_structure_foreach ((GstStructure *) struct1,
932 gst_caps_structure_intersect_field, &data))
935 data.intersect = struct1;
936 data.first_run = FALSE;
937 if (!gst_structure_foreach ((GstStructure *) struct2,
938 gst_caps_structure_intersect_field, &data))
944 gst_structure_free (data.dest);
949 static GstStructure *
950 gst_caps_structure_union (const GstStructure * struct1,
951 const GstStructure * struct2)
955 const GstStructureField *field1;
956 const GstStructureField *field2;
959 /* FIXME this doesn't actually work */
961 if (struct1->name != struct2->name)
964 dest = gst_structure_id_empty_new (struct1->name);
966 for (i = 0; i < struct1->fields->len; i++) {
967 GValue dest_value = { 0 };
969 field1 = GST_STRUCTURE_FIELD (struct1, i);
970 field2 = gst_structure_id_get_field (struct2, field1->name);
972 if (field2 == NULL) {
975 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
976 gst_structure_set_value (dest, g_quark_to_string (field1->name),
979 ret = gst_value_compare (&field1->value, &field2->value);
991 * gst_caps_intersect:
992 * @caps1: a #GstCaps to intersect
993 * @caps2: a #GstCaps to intersect
995 * Creates a new #GstCaps that contains all the formats that are common
996 * to both @caps1 and @caps2.
998 * Returns: the new #GstCaps
1001 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1003 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1006 GstStructure *struct1;
1007 GstStructure *struct2;
1009 GstStructure *istruct;
1011 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1012 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1014 if (gst_caps_is_empty (caps1) || gst_caps_is_empty (caps2)) {
1015 return gst_caps_new_empty ();
1017 if (gst_caps_is_any (caps1))
1018 return gst_caps_copy (caps2);
1019 if (gst_caps_is_any (caps2))
1020 return gst_caps_copy (caps1);
1022 dest = gst_caps_new_empty ();
1024 /* run zigzag on top line then right line, this preserves the caps order
1025 * much better than a simple loop.
1027 * This algorithm zigzags over the caps structures as demonstrated in
1028 * the folowing matrix:
1036 * First we iterate over the caps1 structures (top line) intersecting
1037 * the structures diagonally down, then we iterate over the caps2
1040 for (i = 0; i < caps1->structs->len + caps2->structs->len - 1; i++) {
1041 /* caps1 index goes from 0 to caps1->structs->len-1 */
1042 j = MIN (i, caps1->structs->len - 1);
1043 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1044 * up from 1 to caps2->structs->len - 1 */
1047 /* now run the diagonal line, end condition is the left or bottom
1049 while (k < caps2->structs->len) {
1050 struct1 = gst_caps_get_structure (caps1, j);
1051 struct2 = gst_caps_get_structure (caps2, k);
1053 istruct = gst_caps_structure_intersect (struct1, struct2);
1055 gst_caps_append_structure (dest, istruct);
1056 /* move down left */
1059 break; /* so we don't roll back to G_MAXUINT */
1068 const GstStructure *subtract_from;
1075 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1078 SubtractionEntry *e = user_data;
1079 GValue subtraction = { 0, };
1080 const GValue *other;
1081 GstStructure *structure;
1083 other = gst_structure_id_get_value (e->subtract_from, field_id);
1087 if (!gst_value_subtract (&subtraction, other, value))
1089 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1090 g_value_unset (&subtraction);
1093 structure = gst_structure_copy (e->subtract_from);
1094 gst_structure_id_set_value (structure, field_id, &subtraction);
1095 g_value_unset (&subtraction);
1096 e->put_into = g_slist_prepend (e->put_into, structure);
1102 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1103 const GstStructure * subtrahend)
1108 e.subtract_from = minuend;
1111 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1112 gst_caps_structure_subtract_field, &e);
1118 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1119 gst_structure_free (walk->data);
1121 g_slist_free (e.put_into);
1127 * gst_caps_subtract:
1128 * @minuend: #GstCaps to substract from
1129 * @subtrahend: #GstCaps to substract
1131 * Subtracts the @subtrahend from the @minuend.
1132 * <note>This function does not work reliably if optional properties for caps
1133 * are included on one caps and omitted on the other.</note>
1135 * Returns: the resulting caps
1138 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1143 GstCaps *dest = NULL, *src;
1145 g_return_val_if_fail (minuend != NULL, NULL);
1146 g_return_val_if_fail (subtrahend != NULL, NULL);
1148 if (gst_caps_is_empty (minuend) || gst_caps_is_any (subtrahend)) {
1149 return gst_caps_new_empty ();
1151 if (gst_caps_is_empty (subtrahend))
1152 return gst_caps_copy (minuend);
1154 /* FIXME: Do we want this here or above?
1155 The reason we need this is that there is no definition about what
1156 ANY means for specific types, so it's not possible to reduce ANY partially
1157 You can only remove everything or nothing and that is done above.
1158 Note: there's a test that checks this behaviour. */
1159 g_return_val_if_fail (!gst_caps_is_any (minuend), NULL);
1160 g_assert (subtrahend->structs->len > 0);
1162 src = gst_caps_copy (minuend);
1163 for (i = 0; i < subtrahend->structs->len; i++) {
1164 sub = gst_caps_get_structure (subtrahend, i);
1166 gst_caps_unref (src);
1169 dest = gst_caps_new_empty ();
1170 for (j = 0; j < src->structs->len; j++) {
1171 min = gst_caps_get_structure (src, j);
1172 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1175 if (gst_caps_structure_subtract (&list, min, sub)) {
1178 for (walk = list; walk; walk = g_slist_next (walk)) {
1179 gst_caps_append_structure (dest, (GstStructure *) walk->data);
1181 g_slist_free (list);
1183 gst_caps_append_structure (dest, gst_structure_copy (min));
1186 gst_caps_append_structure (dest, gst_structure_copy (min));
1189 if (gst_caps_is_empty (dest)) {
1190 gst_caps_unref (src);
1195 gst_caps_unref (src);
1196 gst_caps_do_simplify (dest);
1202 * @caps1: a #GstCaps to union
1203 * @caps2: a #GstCaps to union
1205 * Creates a new #GstCaps that contains all the formats that are in
1206 * either @caps1 and @caps2.
1208 * Returns: the new #GstCaps
1211 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1216 if (gst_caps_is_any (caps1) || gst_caps_is_any (caps2))
1217 return gst_caps_new_any ();
1219 dest1 = gst_caps_copy (caps1);
1220 dest2 = gst_caps_copy (caps2);
1221 gst_caps_append (dest1, dest2);
1223 gst_caps_do_simplify (dest1);
1227 typedef struct _NormalizeForeach
1230 GstStructure *structure;
1235 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1237 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1241 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1242 for (i = 1; i < gst_value_list_get_size (value); i++) {
1243 const GValue *v = gst_value_list_get_value (value, i);
1244 GstStructure *structure = gst_structure_copy (nf->structure);
1246 gst_structure_id_set_value (structure, field_id, v);
1247 gst_caps_append_structure (nf->caps, structure);
1250 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1251 gst_structure_id_set_value (nf->structure, field_id, &val);
1252 g_value_unset (&val);
1260 * gst_caps_normalize:
1261 * @caps: a #GstCaps to normalize
1263 * Creates a new #GstCaps that represents the same set of formats as
1264 * @caps, but contains no lists. Each list is expanded into separate
1267 * Returns: the new #GstCaps
1270 gst_caps_normalize (const GstCaps * caps)
1272 NormalizeForeach nf;
1276 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1278 newcaps = gst_caps_copy (caps);
1281 for (i = 0; i < newcaps->structs->len; i++) {
1282 nf.structure = gst_caps_get_structure (newcaps, i);
1284 while (!gst_structure_foreach (nf.structure,
1285 gst_caps_normalize_foreach, &nf));
1292 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1295 const GstStructure *struct1 = *((const GstStructure **) one);
1296 const GstStructure *struct2 = *((const GstStructure **) two);
1298 /* FIXME: this orders aphabetically, but ordering the quarks might be faster
1299 So what's the best way? */
1300 ret = strcmp (gst_structure_get_name (struct1),
1301 gst_structure_get_name (struct2));
1305 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1309 * gst_caps_simplify:
1310 * @caps: a #GstCaps to simplify
1312 * Creates a new #GstCaps that represents the same set of formats as
1313 * @caps, but simpler. Component structures that are identical are
1314 * merged. Component structures that have ranges or lists that can
1315 * be merged are also merged.
1317 * Returns: the new #GstCaps
1320 gst_caps_simplify (const GstCaps * caps)
1324 g_return_val_if_fail (caps != NULL, NULL);
1326 ret = gst_caps_copy (caps);
1327 gst_caps_do_simplify (ret);
1336 GstStructure *compare;
1341 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1344 UnionField *u = user_data;
1345 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1349 g_value_unset (&u->value);
1352 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1355 g_value_unset (&u->value);
1359 gst_value_union (&u->value, val, value);
1364 gst_caps_structure_simplify (GstStructure ** result,
1365 const GstStructure * simplify, GstStructure * compare)
1368 UnionField field = { 0, {0,}, NULL };
1370 /* try to subtract to get a real subset */
1371 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1372 switch (g_slist_length (list)) {
1377 *result = list->data;
1378 g_slist_free (list);
1384 for (walk = list; walk; walk = g_slist_next (walk)) {
1385 gst_structure_free (walk->data);
1387 g_slist_free (list);
1393 /* try to union both structs */
1394 field.compare = compare;
1395 if (gst_structure_foreach ((GstStructure *) simplify,
1396 gst_caps_structure_figure_out_union, &field)) {
1397 gboolean ret = FALSE;
1399 /* now we know all of simplify's fields are the same in compare
1400 * but at most one field: field.name */
1401 if (G_IS_VALUE (&field.value)) {
1402 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1403 gst_structure_id_set_value (compare, field.name, &field.value);
1407 g_value_unset (&field.value);
1408 } else if (gst_structure_n_fields (simplify) <=
1409 gst_structure_n_fields (compare)) {
1410 /* compare is just more specific, will be optimized away later */
1411 /* FIXME: do this here? */
1412 GST_LOG ("found a case that will be optimized later.");
1414 gchar *one = gst_structure_to_string (simplify);
1415 gchar *two = gst_structure_to_string (compare);
1418 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1430 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1431 GstStructure * new, gint i)
1433 gst_structure_set_parent_refcount (old, NULL);
1434 gst_structure_free (old);
1435 gst_structure_set_parent_refcount (new, &caps->refcount);
1436 g_ptr_array_index (caps->structs, i) = new;
1440 * gst_caps_do_simplify:
1441 * @caps: a #GstCaps to simplify
1443 * Modifies the given @caps inplace into a representation that represents the
1444 * same set of formats, but in a simpler form. Component structures that are
1445 * identical are merged. Component structures that have values that can be
1446 * merged are also merged.
1448 * Returns: TRUE, if the caps could be simplified
1451 gst_caps_do_simplify (GstCaps * caps)
1453 GstStructure *simplify, *compare, *result = NULL;
1455 gboolean changed = FALSE;
1457 g_return_val_if_fail (caps != NULL, FALSE);
1458 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1460 if (gst_caps_get_size (caps) < 2)
1463 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1465 start = caps->structs->len - 1;
1466 for (i = caps->structs->len - 1; i >= 0; i--) {
1467 simplify = gst_caps_get_structure (caps, i);
1468 if (gst_structure_get_name_id (simplify) !=
1469 gst_structure_get_name_id (gst_caps_get_structure (caps, start)))
1471 for (j = start; j >= 0; j--) {
1474 compare = gst_caps_get_structure (caps, j);
1475 if (gst_structure_get_name_id (simplify) !=
1476 gst_structure_get_name_id (compare)) {
1479 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1481 gst_caps_switch_structures (caps, simplify, result, i);
1484 gst_caps_remove_structure (caps, i);
1496 /* gst_caps_do_simplify (caps); */
1500 #ifndef GST_DISABLE_LOADSAVE
1502 * gst_caps_save_thyself:
1503 * @caps: a #GstCaps structure
1504 * @parent: a XML parent node
1506 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1508 * Returns: a XML node pointer
1511 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1513 char *s = gst_caps_to_string (caps);
1515 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1521 * gst_caps_load_thyself:
1522 * @parent: a XML node
1524 * Creates a #GstCaps from its XML serialization.
1526 * Returns: a new #GstCaps structure
1529 gst_caps_load_thyself (xmlNodePtr parent)
1531 if (strcmp ("caps", (char *) parent->name) == 0) {
1532 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1543 * @caps: a pointer to #GstCaps
1544 * @newcaps: a #GstCaps to replace *caps
1546 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1547 * pointed to by @caps, if applicable, then modifies @caps to point to
1548 * @newcaps. An additional ref on @newcaps is taken.
1551 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1555 #if 0 /* disable this, since too many plugins rely on undefined behavior */
1556 #ifdef USE_POISONING
1557 //if (newcaps) CAPS_POISON (newcaps);
1563 gst_caps_ref (newcaps);
1568 gst_caps_unref (oldcaps);
1572 * gst_caps_to_string:
1575 * Converts @caps to a string representation. This string representation
1576 * can be converted back to a #GstCaps by #gst_caps_from_string.
1578 * Returns: a newly allocated string representing @caps.
1581 gst_caps_to_string (const GstCaps * caps)
1586 /* NOTE: This function is potentially called by the debug system,
1587 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1588 * should be careful to avoid recursion. This includes any functions
1589 * called by gst_caps_to_string. In particular, calls should
1590 * not use the GST_PTR_FORMAT extension. */
1593 return g_strdup ("NULL");
1595 if (gst_caps_is_any (caps)) {
1596 return g_strdup ("ANY");
1598 if (gst_caps_is_empty (caps)) {
1599 return g_strdup ("EMPTY");
1602 s = g_string_new ("");
1603 for (i = 0; i < caps->structs->len; i++) {
1604 GstStructure *structure;
1608 g_string_append (s, "; ");
1610 structure = gst_caps_get_structure (caps, i);
1611 sstr = gst_structure_to_string (structure);
1612 g_string_append (s, sstr);
1616 return g_string_free (s, FALSE);
1620 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1622 GstStructure *structure;
1625 g_return_val_if_fail (string, FALSE);
1626 if (strcmp ("ANY", string) == 0) {
1627 caps->flags = GST_CAPS_FLAGS_ANY;
1630 if (strcmp ("EMPTY", string) == 0) {
1634 structure = gst_structure_from_string (string, &s);
1635 if (structure == NULL) {
1638 gst_caps_append_structure (caps, structure);
1642 while (g_ascii_isspace (*s))
1644 structure = gst_structure_from_string (s, &s);
1645 if (structure == NULL) {
1648 gst_caps_append_structure (caps, structure);
1649 while (g_ascii_isspace (*s))
1661 * gst_caps_from_string:
1662 * @string: a string to convert to #GstCaps
1664 * Converts @caps from a string representation.
1666 * Returns: a newly allocated #GstCaps
1669 gst_caps_from_string (const gchar * string)
1673 caps = gst_caps_new_empty ();
1674 if (gst_caps_from_string_inplace (caps, string)) {
1677 gst_caps_unref (caps);
1683 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1685 g_return_if_fail (G_IS_VALUE (src_value));
1686 g_return_if_fail (G_IS_VALUE (dest_value));
1687 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1688 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1689 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1691 dest_value->data[0].v_pointer =
1692 gst_caps_to_string (src_value->data[0].v_pointer);
1696 gst_caps_copy_conditional (GstCaps * src)
1699 return gst_caps_ref (src);