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 #GstRegistry along with
30 * a description of the #GstElement.
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", GST_TYPE_FRACTION, 25, 1,
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 2007-02-13 (0.10.10)
72 #include "gst_private.h"
74 #include <gobject/gvaluecollector.h>
76 #ifdef GST_DISABLE_DEPRECATED
77 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
78 #include <libxml/parser.h>
79 xmlNodePtr gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent);
80 GstCaps *gst_caps_load_thyself (xmlNodePtr parent);
84 #define DEBUG_REFCOUNT
86 #define CAPS_POISON(caps) G_STMT_START{ \
88 GstCaps *_newcaps = gst_caps_copy (caps); \
89 gst_caps_unref(caps); \
93 #define STRUCTURE_POISON(structure) G_STMT_START{ \
95 GstStructure *_newstruct = gst_structure_copy (structure); \
96 gst_structure_free(structure); \
97 structure = _newstruct; \
100 #define IS_WRITABLE(caps) \
101 (g_atomic_int_get (&(caps)->refcount) == 1)
103 /* same as gst_caps_is_any () */
104 #define CAPS_IS_ANY(caps) \
105 ((caps)->flags & GST_CAPS_FLAGS_ANY)
107 /* same as gst_caps_is_empty () */
108 #define CAPS_IS_EMPTY(caps) \
109 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
111 #define CAPS_IS_EMPTY_SIMPLE(caps) \
112 (((caps)->structs == NULL) || ((caps)->structs->len == 0))
114 /* quick way to get a caps structure at an index without doing a type or array
116 #define gst_caps_get_structure_unchecked(caps, index) \
117 ((GstStructure *)g_ptr_array_index ((caps)->structs, (index)))
118 /* quick way to append a structure without checking the args */
119 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
120 GstStructure *__s=structure; \
121 gst_structure_set_parent_refcount (__s, &caps->refcount); \
122 g_ptr_array_add (caps->structs, __s); \
125 /* lock to protect multiple invocations of static caps to caps conversion */
126 G_LOCK_DEFINE_STATIC (static_caps_lock);
128 static void gst_caps_transform_to_string (const GValue * src_value,
129 GValue * dest_value);
130 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
131 const gchar * string);
132 static GstCaps *gst_caps_copy_conditional (GstCaps * src);
135 gst_caps_get_type (void)
137 static GType gst_caps_type = 0;
139 if (G_UNLIKELY (gst_caps_type == 0)) {
140 gst_caps_type = g_boxed_type_register_static ("GstCaps",
141 (GBoxedCopyFunc) gst_caps_copy_conditional,
142 (GBoxedFreeFunc) gst_caps_unref);
144 g_value_register_transform_func (gst_caps_type,
145 G_TYPE_STRING, gst_caps_transform_to_string);
148 return gst_caps_type;
151 /* creation/deletion */
154 * gst_caps_new_empty:
156 * Creates a new #GstCaps that is empty. That is, the returned
157 * #GstCaps contains no media formats.
158 * Caller is responsible for unreffing the returned caps.
160 * Returns: (transfer full): the new #GstCaps
163 gst_caps_new_empty (void)
165 GstCaps *caps = g_slice_new (GstCaps);
167 caps->type = GST_TYPE_CAPS;
170 caps->structs = g_ptr_array_new ();
171 /* the 32 has been determined by logging caps sizes in _gst_caps_free
172 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
174 * caps->structs = g_ptr_array_sized_new (32);
177 #ifdef DEBUG_REFCOUNT
178 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
187 * Creates a new #GstCaps that indicates that it is compatible with
190 * Returns: (transfer full): the new #GstCaps
193 gst_caps_new_any (void)
195 GstCaps *caps = gst_caps_new_empty ();
197 caps->flags = GST_CAPS_FLAGS_ANY;
203 * gst_caps_new_simple:
204 * @media_type: the media type of the structure
205 * @fieldname: first field to set
206 * @...: additional arguments
208 * Creates a new #GstCaps that contains one #GstStructure. The
209 * structure is defined by the arguments, which have the same format
210 * as gst_structure_new().
211 * Caller is responsible for unreffing the returned caps.
213 * Returns: (transfer full): the new #GstCaps
216 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
219 GstStructure *structure;
222 caps = gst_caps_new_empty ();
224 va_start (var_args, fieldname);
225 structure = gst_structure_new_valist (media_type, fieldname, var_args);
229 gst_caps_append_structure_unchecked (caps, structure);
231 gst_caps_replace (&caps, NULL);
238 * @struct1: the first structure to add
239 * @...: additional structures to add
241 * Creates a new #GstCaps and adds all the structures listed as
242 * arguments. The list must be NULL-terminated. The structures
243 * are not copied; the returned #GstCaps owns the structures.
245 * Returns: (transfer full): the new #GstCaps
248 gst_caps_new_full (GstStructure * struct1, ...)
253 va_start (var_args, struct1);
254 caps = gst_caps_new_full_valist (struct1, var_args);
261 * gst_caps_new_full_valist:
262 * @structure: the first structure to add
263 * @var_args: additional structures to add
265 * Creates a new #GstCaps and adds all the structures listed as
266 * arguments. The list must be NULL-terminated. The structures
267 * are not copied; the returned #GstCaps owns the structures.
269 * Returns: (transfer full): the new #GstCaps
272 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
276 caps = gst_caps_new_empty ();
279 gst_caps_append_structure_unchecked (caps, structure);
280 structure = va_arg (var_args, GstStructure *);
288 * @caps: the #GstCaps to copy
290 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
291 * refcount of 1, owned by the caller. The structures are copied as well.
293 * Note that this function is the semantic equivalent of a gst_caps_ref()
294 * followed by a gst_caps_make_writable(). If you only want to hold on to a
295 * reference to the data, you should use gst_caps_ref().
297 * When you are finished with the caps, call gst_caps_unref() on it.
299 * Returns: (transfer full): the new #GstCaps
302 gst_caps_copy (const GstCaps * caps)
305 GstStructure *structure;
308 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
310 newcaps = gst_caps_new_empty ();
311 newcaps->flags = caps->flags;
312 n = caps->structs->len;
314 for (i = 0; i < n; i++) {
315 structure = gst_caps_get_structure_unchecked (caps, i);
316 gst_caps_append_structure_unchecked (newcaps,
317 gst_structure_copy (structure));
324 _gst_caps_free (GstCaps * caps)
326 GstStructure *structure;
329 /* The refcount must be 0, but since we're only called by gst_caps_unref,
330 * don't bother testing. */
331 len = caps->structs->len;
332 /* This can be used to get statistics about caps sizes */
333 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
334 for (i = 0; i < len; i++) {
335 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
336 gst_structure_set_parent_refcount (structure, NULL);
337 gst_structure_free (structure);
339 g_ptr_array_free (caps->structs, TRUE);
341 memset (caps, 0xff, sizeof (GstCaps));
344 #ifdef DEBUG_REFCOUNT
345 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
347 g_slice_free (GstCaps, caps);
351 * gst_caps_make_writable:
352 * @caps: (transfer full): the #GstCaps to make writable
354 * Returns a writable copy of @caps.
356 * If there is only one reference count on @caps, the caller must be the owner,
357 * and so this function will return the caps object unchanged. If on the other
358 * hand there is more than one reference on the object, a new caps object will
359 * be returned. The caller's reference on @caps will be removed, and instead the
360 * caller will own a reference to the returned object.
362 * In short, this function unrefs the caps in the argument and refs the caps
363 * that it returns. Don't access the argument after calling this function. See
364 * also: gst_caps_ref().
366 * Returns: (transfer full): the same #GstCaps object.
369 gst_caps_make_writable (GstCaps * caps)
373 g_return_val_if_fail (caps != NULL, NULL);
375 /* we are the only instance reffing this caps */
376 if (IS_WRITABLE (caps))
380 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy caps");
381 copy = gst_caps_copy (caps);
382 gst_caps_unref (caps);
389 * @caps: the #GstCaps to reference
391 * Add a reference to a #GstCaps object.
393 * From this point on, until the caller calls gst_caps_unref() or
394 * gst_caps_make_writable(), it is guaranteed that the caps object will not
395 * change. This means its structures won't change, etc. To use a #GstCaps
396 * object, you must always have a refcount on it -- either the one made
397 * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
400 * Returns: (transfer full): the same #GstCaps object.
403 gst_caps_ref (GstCaps * caps)
405 g_return_val_if_fail (caps != NULL, NULL);
407 #ifdef DEBUG_REFCOUNT
408 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
409 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) + 1);
411 g_return_val_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0, NULL);
413 g_atomic_int_inc (&caps->refcount);
420 * @caps: (transfer full): the #GstCaps to unref
422 * Unref a #GstCaps and and free all its structures and the
423 * structures' values when the refcount reaches 0.
426 gst_caps_unref (GstCaps * caps)
428 g_return_if_fail (caps != NULL);
430 #ifdef DEBUG_REFCOUNT
431 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
432 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) - 1);
435 g_return_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0);
437 /* if we ended up with the refcount at zero, free the caps */
438 if (G_UNLIKELY (g_atomic_int_dec_and_test (&caps->refcount)))
439 _gst_caps_free (caps);
443 gst_static_caps_get_type (void)
445 static GType staticcaps_type = 0;
447 if (G_UNLIKELY (staticcaps_type == 0)) {
448 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
450 return staticcaps_type;
455 * gst_static_caps_get:
456 * @static_caps: the #GstStaticCaps to convert
458 * Converts a #GstStaticCaps to a #GstCaps.
460 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
461 * Since the core holds an additional ref to the returned caps,
462 * use gst_caps_make_writable() on the returned caps to modify it.
465 gst_static_caps_get (GstStaticCaps * static_caps)
469 g_return_val_if_fail (static_caps != NULL, NULL);
471 caps = (GstCaps *) static_caps;
473 /* refcount is 0 when we need to convert */
474 if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) == 0)) {
478 G_LOCK (static_caps_lock);
479 /* check if other thread already updated */
480 if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) > 0))
483 string = static_caps->string;
485 if (G_UNLIKELY (string == NULL))
488 GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);
490 /* we construct the caps on the stack, then copy over the struct into our
491 * real caps, refcount last. We do this because we must leave the refcount
492 * of the result caps to 0 so that other threads don't run away with the
493 * caps while we are constructing it. */
494 temp.type = GST_TYPE_CAPS;
496 temp.structs = g_ptr_array_new ();
498 /* initialize the caps to a refcount of 1 so the caps can be writable for
499 * the next statement */
502 /* convert to string */
503 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
504 g_critical ("Could not convert static caps \"%s\"", string);
506 /* now copy stuff over to the real caps. */
507 caps->type = temp.type;
508 caps->flags = temp.flags;
509 caps->structs = temp.structs;
510 /* and bump the refcount so other threads can now read */
511 g_atomic_int_set (&caps->refcount, 1);
513 GST_CAT_LOG (GST_CAT_CAPS, "created %p", static_caps);
515 G_UNLOCK (static_caps_lock);
517 /* ref the caps, makes it not writable */
525 G_UNLOCK (static_caps_lock);
526 g_warning ("static caps %p string is NULL", static_caps);
533 static GstStructure *
534 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
536 /* don't use index_fast, gst_caps_do_simplify relies on the order */
537 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
539 gst_structure_set_parent_refcount (s, NULL);
544 * gst_caps_steal_structure:
545 * @caps: the #GstCaps to retrieve from
546 * @index: Index of the structure to retrieve
548 * Retrieves the stucture with the given index from the list of structures
549 * contained in @caps. The caller becomes the owner of the returned structure.
551 * Returns: (transfer full): a pointer to the #GstStructure corresponding
557 gst_caps_steal_structure (GstCaps * caps, guint index)
559 g_return_val_if_fail (caps != NULL, NULL);
560 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
562 if (G_UNLIKELY (index >= caps->structs->len))
565 return gst_caps_remove_and_get_structure (caps, index);
570 * @caps1: the #GstCaps that will be appended to
571 * @caps2: (transfer full): the #GstCaps to append
573 * Appends the structures contained in @caps2 to @caps1. The structures in
574 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
575 * freed. If either caps is ANY, the resulting caps will be ANY.
578 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
580 GstStructure *structure;
583 g_return_if_fail (GST_IS_CAPS (caps1));
584 g_return_if_fail (GST_IS_CAPS (caps2));
585 g_return_if_fail (IS_WRITABLE (caps1));
586 g_return_if_fail (IS_WRITABLE (caps2));
591 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
592 /* FIXME: this leaks */
593 caps1->flags |= GST_CAPS_FLAGS_ANY;
594 for (i = caps2->structs->len - 1; i >= 0; i--) {
595 structure = gst_caps_remove_and_get_structure (caps2, i);
596 gst_structure_free (structure);
599 for (i = caps2->structs->len; i; i--) {
600 structure = gst_caps_remove_and_get_structure (caps2, 0);
601 gst_caps_append_structure_unchecked (caps1, structure);
604 gst_caps_unref (caps2); /* guaranteed to free it */
609 * @caps1: the #GstCaps that will take the new entries
610 * @caps2: (transfer full): the #GstCaps to merge in
612 * Appends the structures contained in @caps2 to @caps1 if they are not yet
613 * expressed by @caps1. The structures in @caps2 are not copied -- they are
614 * transferred to @caps1, and then @caps2 is freed.
615 * If either caps is ANY, the resulting caps will be ANY.
620 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
622 GstStructure *structure;
625 g_return_if_fail (GST_IS_CAPS (caps1));
626 g_return_if_fail (GST_IS_CAPS (caps2));
627 g_return_if_fail (IS_WRITABLE (caps1));
628 g_return_if_fail (IS_WRITABLE (caps2));
633 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
634 for (i = caps2->structs->len - 1; i >= 0; i--) {
635 structure = gst_caps_remove_and_get_structure (caps2, i);
636 gst_structure_free (structure);
638 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
639 caps1->flags |= GST_CAPS_FLAGS_ANY;
640 for (i = caps1->structs->len - 1; i >= 0; i--) {
641 structure = gst_caps_remove_and_get_structure (caps1, i);
642 gst_structure_free (structure);
645 for (i = caps2->structs->len; i; i--) {
646 structure = gst_caps_remove_and_get_structure (caps2, 0);
647 gst_caps_merge_structure (caps1, structure);
650 GstCaps *com = gst_caps_intersect (caps1, caps2);
651 GstCaps *add = gst_caps_subtract (caps2, com);
653 GST_DEBUG ("common : %d", gst_caps_get_size (com));
654 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
655 gst_caps_append (caps1, add);
656 gst_caps_unref (com);
659 gst_caps_unref (caps2); /* guaranteed to free it */
663 * gst_caps_append_structure:
664 * @caps: the #GstCaps that will be appended to
665 * @structure: (transfer full): the #GstStructure to append
667 * Appends @structure to @caps. The structure is not copied; @caps
668 * becomes the owner of @structure.
671 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
673 g_return_if_fail (GST_IS_CAPS (caps));
674 g_return_if_fail (IS_WRITABLE (caps));
676 if (G_LIKELY (structure)) {
677 g_return_if_fail (structure->parent_refcount == NULL);
680 STRUCTURE_POISON (structure);
683 gst_caps_append_structure_unchecked (caps, structure);
688 * gst_caps_remove_structure:
689 * @caps: the #GstCaps to remove from
690 * @idx: Index of the structure to remove
692 * removes the stucture with the given index from the list of structures
693 * contained in @caps.
696 gst_caps_remove_structure (GstCaps * caps, guint idx)
698 GstStructure *structure;
700 g_return_if_fail (caps != NULL);
701 g_return_if_fail (idx <= gst_caps_get_size (caps));
702 g_return_if_fail (IS_WRITABLE (caps));
704 structure = gst_caps_remove_and_get_structure (caps, idx);
705 gst_structure_free (structure);
709 * gst_caps_merge_structure:
710 * @caps: the #GstCaps that will the the new structure
711 * @structure: (transfer full): the #GstStructure to merge
713 * Appends @structure to @caps if its not already expressed by @caps. The
714 * structure is not copied; @caps becomes the owner of @structure.
717 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
719 g_return_if_fail (GST_IS_CAPS (caps));
720 g_return_if_fail (IS_WRITABLE (caps));
722 if (G_LIKELY (structure)) {
723 GstStructure *structure1;
725 gboolean unique = TRUE;
727 g_return_if_fail (structure->parent_refcount == NULL);
730 STRUCTURE_POISON (structure);
733 /* check each structure */
734 for (i = caps->structs->len - 1; i >= 0; i--) {
735 structure1 = gst_caps_get_structure_unchecked (caps, i);
736 /* if structure is a subset of structure1, then skip it */
737 if (gst_structure_is_subset (structure, structure1)) {
743 gst_caps_append_structure_unchecked (caps, structure);
745 gst_structure_free (structure);
754 * Gets the number of structures contained in @caps.
756 * Returns: the number of structures that @caps contains
759 gst_caps_get_size (const GstCaps * caps)
761 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
763 return caps->structs->len;
767 * gst_caps_get_structure:
769 * @index: the index of the structure
771 * Finds the structure in @caps that has the index @index, and
774 * WARNING: This function takes a const GstCaps *, but returns a
775 * non-const GstStructure *. This is for programming convenience --
776 * the caller should be aware that structures inside a constant
777 * #GstCaps should not be modified. However, if you know the caps
778 * are writable, either because you have just copied them or made
779 * them writable with gst_caps_make_writable(), you may modify the
780 * structure returned in the usual way, e.g. with functions like
781 * gst_structure_set().
783 * You do not need to free or unref the structure returned, it
784 * belongs to the #GstCaps.
786 * Returns: (transfer none): a pointer to the #GstStructure corresponding
790 gst_caps_get_structure (const GstCaps * caps, guint index)
792 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
793 g_return_val_if_fail (index < caps->structs->len, NULL);
795 return gst_caps_get_structure_unchecked (caps, index);
800 * @caps: the #GstCaps to copy
801 * @nth: the nth structure to copy
803 * Creates a new #GstCaps and appends a copy of the nth structure
804 * contained in @caps.
806 * Returns: (transfer full): the new #GstCaps
809 gst_caps_copy_nth (const GstCaps * caps, guint nth)
812 GstStructure *structure;
814 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
816 newcaps = gst_caps_new_empty ();
817 newcaps->flags = caps->flags;
819 if (G_LIKELY (caps->structs->len > nth)) {
820 structure = gst_caps_get_structure_unchecked (caps, nth);
821 gst_caps_append_structure_unchecked (newcaps,
822 gst_structure_copy (structure));
830 * @caps: the #GstCaps to truncate
832 * Destructively discard all but the first structure from @caps. Useful when
833 * fixating. @caps must be writable.
836 gst_caps_truncate (GstCaps * caps)
840 g_return_if_fail (GST_IS_CAPS (caps));
841 g_return_if_fail (IS_WRITABLE (caps));
843 i = caps->structs->len - 1;
846 gst_caps_remove_structure (caps, i--);
850 * gst_caps_set_value:
851 * @caps: a writable caps
852 * @field: name of the field to set
853 * @value: value to set the field to
855 * Sets the given @field on all structures of @caps to the given @value.
856 * This is a convenience function for calling gst_structure_set_value() on
857 * all structures of @caps.
862 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
866 g_return_if_fail (GST_IS_CAPS (caps));
867 g_return_if_fail (IS_WRITABLE (caps));
868 g_return_if_fail (field != NULL);
869 g_return_if_fail (G_IS_VALUE (value));
871 len = caps->structs->len;
872 for (i = 0; i < len; i++) {
873 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
874 gst_structure_set_value (structure, field, value);
879 * gst_caps_set_simple_valist:
880 * @caps: the #GstCaps to set
881 * @field: first field to set
882 * @varargs: additional parameters
884 * Sets fields in a #GstCaps. The arguments must be passed in the same
885 * manner as gst_structure_set(), and be NULL-terminated.
886 * <note>Prior to GStreamer version 0.10.26, this function failed when
887 * @caps was not simple. If your code needs to work with those versions
888 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
889 * is %TRUE for @caps.</note>
892 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
894 GValue value = { 0, };
896 g_return_if_fail (GST_IS_CAPS (caps));
897 g_return_if_fail (IS_WRITABLE (caps));
903 type = va_arg (varargs, GType);
905 if (G_UNLIKELY (type == G_TYPE_DATE)) {
906 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
907 type = GST_TYPE_DATE;
909 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
910 if (G_UNLIKELY (err)) {
911 g_critical ("%s", err);
915 gst_caps_set_value (caps, field, &value);
917 g_value_unset (&value);
919 field = va_arg (varargs, const gchar *);
924 * gst_caps_set_simple:
925 * @caps: the #GstCaps to set
926 * @field: first field to set
927 * @...: additional parameters
929 * Sets fields in a #GstCaps. The arguments must be passed in the same
930 * manner as gst_structure_set(), and be NULL-terminated.
931 * <note>Prior to GStreamer version 0.10.26, this function failed when
932 * @caps was not simple. If your code needs to work with those versions
933 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
934 * is %TRUE for @caps.</note>
937 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
941 g_return_if_fail (GST_IS_CAPS (caps));
942 g_return_if_fail (IS_WRITABLE (caps));
944 va_start (var_args, field);
945 gst_caps_set_simple_valist (caps, field, var_args);
953 * @caps: the #GstCaps to test
955 * Determines if @caps represents any media format.
957 * Returns: TRUE if @caps represents any format.
960 gst_caps_is_any (const GstCaps * caps)
962 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
964 return (CAPS_IS_ANY (caps));
969 * @caps: the #GstCaps to test
971 * Determines if @caps represents no media formats.
973 * Returns: TRUE if @caps represents no formats.
976 gst_caps_is_empty (const GstCaps * caps)
978 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
980 if (CAPS_IS_ANY (caps))
983 return CAPS_IS_EMPTY_SIMPLE (caps);
987 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
990 return gst_value_is_fixed (value);
995 * @caps: the #GstCaps to test
997 * Fixed #GstCaps describe exactly one format, that is, they have exactly
998 * one structure, and each field in the structure describes a fixed type.
999 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
1001 * Returns: TRUE if @caps is fixed
1004 gst_caps_is_fixed (const GstCaps * caps)
1006 GstStructure *structure;
1008 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1010 if (caps->structs->len != 1)
1013 structure = gst_caps_get_structure_unchecked (caps, 0);
1015 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
1019 * gst_caps_is_equal_fixed:
1020 * @caps1: the #GstCaps to test
1021 * @caps2: the #GstCaps to test
1023 * Tests if two #GstCaps are equal. This function only works on fixed
1026 * Returns: TRUE if the arguments represent the same format
1029 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
1031 GstStructure *struct1, *struct2;
1033 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1034 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1036 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1037 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1039 return gst_structure_is_equal (struct1, struct2);
1043 * gst_caps_is_always_compatible:
1044 * @caps1: the #GstCaps to test
1045 * @caps2: the #GstCaps to test
1047 * A given #GstCaps structure is always compatible with another if
1048 * every media format that is in the first is also contained in the
1049 * second. That is, @caps1 is a subset of @caps2.
1051 * Returns: TRUE if @caps1 is a subset of @caps2.
1054 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1056 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1057 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1059 return gst_caps_is_subset (caps1, caps2);
1063 * gst_caps_is_subset:
1064 * @subset: a #GstCaps
1065 * @superset: a potentially greater #GstCaps
1067 * Checks if all caps represented by @subset are also represented by @superset.
1068 * <note>This function does not work reliably if optional properties for caps
1069 * are included on one caps and omitted on the other.</note>
1071 * Returns: %TRUE if @subset is a subset of @superset
1074 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1076 GstStructure *s1, *s2;
1077 gboolean ret = TRUE;
1080 g_return_val_if_fail (subset != NULL, FALSE);
1081 g_return_val_if_fail (superset != NULL, FALSE);
1083 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1085 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1088 for (i = subset->structs->len - 1; i >= 0; i--) {
1089 for (j = superset->structs->len - 1; j >= 0; j--) {
1090 s1 = gst_caps_get_structure_unchecked (subset, i);
1091 s2 = gst_caps_get_structure_unchecked (superset, j);
1092 if (gst_structure_is_subset (s1, s2)) {
1093 /* If we found a superset, continue with the next
1094 * subset structure */
1098 /* If we found no superset for this subset structure
1099 * we return FALSE immediately */
1110 * gst_caps_is_equal:
1111 * @caps1: a #GstCaps
1112 * @caps2: another #GstCaps
1114 * Checks if the given caps represent the same set of caps.
1115 * <note>This function does not work reliably if optional properties for caps
1116 * are included on one caps and omitted on the other.</note>
1118 * This function deals correctly with passing NULL for any of the caps.
1120 * Returns: TRUE if both caps are equal.
1123 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1125 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1126 * So there should be an assertion that caps1 and caps2 != NULL */
1128 /* NULL <-> NULL is allowed here */
1129 if (G_UNLIKELY (caps1 == caps2))
1132 /* one of them NULL => they are different (can't be both NULL because
1133 * we checked that above) */
1134 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1137 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1138 return gst_caps_is_equal_fixed (caps1, caps2);
1140 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1143 /* intersect operation */
1146 * gst_caps_can_intersect:
1147 * @caps1: a #GstCaps to intersect
1148 * @caps2: a #GstCaps to intersect
1150 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1153 * Returns: %TRUE if intersection would be not empty
1158 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1160 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1161 guint j, k, len1, len2;
1162 GstStructure *struct1;
1163 GstStructure *struct2;
1165 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1166 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1168 /* caps are exactly the same pointers */
1169 if (G_UNLIKELY (caps1 == caps2))
1172 /* empty caps on either side, return empty */
1173 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1176 /* one of the caps is any */
1177 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1180 /* run zigzag on top line then right line, this preserves the caps order
1181 * much better than a simple loop.
1183 * This algorithm zigzags over the caps structures as demonstrated in
1184 * the folowing matrix:
1187 * +------------- total distance: +-------------
1188 * | 1 2 4 7 0 | 0 1 2 3
1189 * caps2 | 3 5 8 10 1 | 1 2 3 4
1190 * | 6 9 11 12 2 | 2 3 4 5
1192 * First we iterate over the caps1 structures (top line) intersecting
1193 * the structures diagonally down, then we iterate over the caps2
1194 * structures. The result is that the intersections are ordered based on the
1195 * sum of the indexes in the list.
1197 len1 = caps1->structs->len;
1198 len2 = caps2->structs->len;
1199 for (i = 0; i < len1 + len2 - 1; i++) {
1200 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1201 j = MIN (i, len1 - 1);
1202 /* subset index stays 0 until i reaches superset->structs->len, then it
1203 * counts up from 1 to subset->structs->len - 1 */
1206 /* now run the diagonal line, end condition is the left or bottom
1209 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1210 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1212 if (gst_structure_can_intersect (struct1, struct2)) {
1215 /* move down left */
1217 if (G_UNLIKELY (j == 0))
1218 break; /* so we don't roll back to G_MAXUINT */
1226 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1228 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1229 guint j, k, len1, len2;
1231 GstStructure *struct1;
1232 GstStructure *struct2;
1234 GstStructure *istruct;
1236 /* caps are exactly the same pointers, just copy one caps */
1237 if (G_UNLIKELY (caps1 == caps2))
1238 return gst_caps_copy (caps1);
1240 /* empty caps on either side, return empty */
1241 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1242 return gst_caps_new_empty ();
1244 /* one of the caps is any, just copy the other caps */
1245 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1246 return gst_caps_copy (caps2);
1247 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1248 return gst_caps_copy (caps1);
1250 dest = gst_caps_new_empty ();
1252 /* run zigzag on top line then right line, this preserves the caps order
1253 * much better than a simple loop.
1255 * This algorithm zigzags over the caps structures as demonstrated in
1256 * the folowing matrix:
1264 * First we iterate over the caps1 structures (top line) intersecting
1265 * the structures diagonally down, then we iterate over the caps2
1268 len1 = caps1->structs->len;
1269 len2 = caps2->structs->len;
1270 for (i = 0; i < len1 + len2 - 1; i++) {
1271 /* caps1 index goes from 0 to caps1->structs->len-1 */
1272 j = MIN (i, len1 - 1);
1273 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1274 * up from 1 to caps2->structs->len - 1 */
1277 /* now run the diagonal line, end condition is the left or bottom
1280 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1281 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1283 istruct = gst_structure_intersect (struct1, struct2);
1285 gst_caps_merge_structure (dest, istruct);
1286 /* move down left */
1288 if (G_UNLIKELY (j == 0))
1289 break; /* so we don't roll back to G_MAXUINT */
1297 * gst_caps_intersect_first:
1298 * @caps1: a #GstCaps to intersect
1299 * @caps2: a #GstCaps to intersect
1301 * Creates a new #GstCaps that contains all the formats that are common
1302 * to both @caps1 and @caps2.
1304 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1305 * fashion as @caps1.
1307 * Returns: the new #GstCaps
1310 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1312 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1313 guint j, len1, len2;
1315 GstStructure *struct1;
1316 GstStructure *struct2;
1318 GstStructure *istruct;
1320 /* caps are exactly the same pointers, just copy one caps */
1321 if (G_UNLIKELY (caps1 == caps2))
1322 return gst_caps_copy (caps1);
1324 /* empty caps on either side, return empty */
1325 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1326 return gst_caps_new_empty ();
1328 /* one of the caps is any, just copy the other caps */
1329 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1330 return gst_caps_copy (caps2);
1331 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1332 return gst_caps_copy (caps1);
1334 dest = gst_caps_new_empty ();
1336 len1 = caps1->structs->len;
1337 len2 = caps2->structs->len;
1338 for (i = 0; i < len1; i++) {
1339 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1340 for (j = 0; j < len2; j++) {
1341 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1342 istruct = gst_structure_intersect (struct1, struct2);
1344 gst_caps_merge_structure (dest, istruct);
1352 * gst_caps_intersect_full:
1353 * @caps1: a #GstCaps to intersect
1354 * @caps2: a #GstCaps to intersect
1355 * @mode: The intersection algorithm/mode to use
1357 * Creates a new #GstCaps that contains all the formats that are common
1358 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1361 * Returns: the new #GstCaps
1365 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1366 GstCapsIntersectMode mode)
1368 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1369 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1372 case GST_CAPS_INTERSECT_FIRST:
1373 return gst_caps_intersect_first (caps1, caps2);
1375 g_warning ("Unknown caps intersect mode: %d", mode);
1377 case GST_CAPS_INTERSECT_ZIG_ZAG:
1378 return gst_caps_intersect_zig_zag (caps1, caps2);
1383 * gst_caps_intersect:
1384 * @caps1: a #GstCaps to intersect
1385 * @caps2: a #GstCaps to intersect
1387 * Creates a new #GstCaps that contains all the formats that are common
1388 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1390 * Returns: the new #GstCaps
1393 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1395 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1399 /* subtract operation */
1403 const GstStructure *subtract_from;
1409 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1412 SubtractionEntry *e = user_data;
1413 GValue subtraction = { 0, };
1414 const GValue *other;
1415 GstStructure *structure;
1417 other = gst_structure_id_get_value (e->subtract_from, field_id);
1421 if (!gst_value_subtract (&subtraction, other, value))
1423 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1424 g_value_unset (&subtraction);
1427 structure = gst_structure_copy (e->subtract_from);
1428 gst_structure_id_set_value (structure, field_id, &subtraction);
1429 g_value_unset (&subtraction);
1430 e->put_into = g_slist_prepend (e->put_into, structure);
1436 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1437 const GstStructure * subtrahend)
1442 e.subtract_from = minuend;
1445 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1446 gst_caps_structure_subtract_field, &e);
1452 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1453 gst_structure_free (walk->data);
1455 g_slist_free (e.put_into);
1461 * gst_caps_subtract:
1462 * @minuend: #GstCaps to substract from
1463 * @subtrahend: #GstCaps to substract
1465 * Subtracts the @subtrahend from the @minuend.
1466 * <note>This function does not work reliably if optional properties for caps
1467 * are included on one caps and omitted on the other.</note>
1469 * Returns: the resulting caps
1472 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1477 GstCaps *dest = NULL, *src;
1479 g_return_val_if_fail (minuend != NULL, NULL);
1480 g_return_val_if_fail (subtrahend != NULL, NULL);
1482 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1483 return gst_caps_new_empty ();
1485 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1486 return gst_caps_copy (minuend);
1488 /* FIXME: Do we want this here or above?
1489 The reason we need this is that there is no definition about what
1490 ANY means for specific types, so it's not possible to reduce ANY partially
1491 You can only remove everything or nothing and that is done above.
1492 Note: there's a test that checks this behaviour. */
1493 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1494 sublen = subtrahend->structs->len;
1495 g_assert (sublen > 0);
1497 src = gst_caps_copy (minuend);
1498 for (i = 0; i < sublen; i++) {
1501 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1503 gst_caps_unref (src);
1506 dest = gst_caps_new_empty ();
1507 srclen = src->structs->len;
1508 for (j = 0; j < srclen; j++) {
1509 min = gst_caps_get_structure_unchecked (src, j);
1510 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1513 if (gst_caps_structure_subtract (&list, min, sub)) {
1516 for (walk = list; walk; walk = g_slist_next (walk)) {
1517 gst_caps_append_structure_unchecked (dest,
1518 (GstStructure *) walk->data);
1520 g_slist_free (list);
1522 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1525 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1528 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1529 gst_caps_unref (src);
1534 gst_caps_unref (src);
1535 gst_caps_do_simplify (dest);
1539 /* union operation */
1542 static GstStructure *
1543 gst_caps_structure_union (const GstStructure * struct1,
1544 const GstStructure * struct2)
1548 const GstStructureField *field1;
1549 const GstStructureField *field2;
1552 /* FIXME this doesn't actually work */
1554 if (struct1->name != struct2->name)
1557 dest = gst_structure_id_empty_new (struct1->name);
1559 for (i = 0; i < struct1->fields->len; i++) {
1560 GValue dest_value = { 0 };
1562 field1 = GST_STRUCTURE_FIELD (struct1, i);
1563 field2 = gst_structure_id_get_field (struct2, field1->name);
1565 if (field2 == NULL) {
1568 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1569 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1572 ret = gst_value_compare (&field1->value, &field2->value);
1583 * @caps1: a #GstCaps to union
1584 * @caps2: a #GstCaps to union
1586 * Creates a new #GstCaps that contains all the formats that are in
1587 * either @caps1 and @caps2.
1589 * Returns: the new #GstCaps
1592 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1597 /* NULL pointers are no correct GstCaps */
1598 g_return_val_if_fail (caps1 != NULL, NULL);
1599 g_return_val_if_fail (caps2 != NULL, NULL);
1601 if (CAPS_IS_EMPTY (caps1))
1602 return gst_caps_copy (caps2);
1604 if (CAPS_IS_EMPTY (caps2))
1605 return gst_caps_copy (caps1);
1607 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1608 return gst_caps_new_any ();
1610 dest1 = gst_caps_copy (caps1);
1611 dest2 = gst_caps_copy (caps2);
1612 gst_caps_append (dest1, dest2);
1614 gst_caps_do_simplify (dest1);
1618 /* normalize/simplify operations */
1620 typedef struct _NormalizeForeach
1623 GstStructure *structure;
1628 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1630 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1634 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1635 guint len = gst_value_list_get_size (value);
1636 for (i = 1; i < len; i++) {
1637 const GValue *v = gst_value_list_get_value (value, i);
1638 GstStructure *structure = gst_structure_copy (nf->structure);
1640 gst_structure_id_set_value (structure, field_id, v);
1641 gst_caps_append_structure_unchecked (nf->caps, structure);
1644 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1645 gst_structure_id_set_value (nf->structure, field_id, &val);
1646 g_value_unset (&val);
1654 * gst_caps_normalize:
1655 * @caps: a #GstCaps to normalize
1657 * Creates a new #GstCaps that represents the same set of formats as
1658 * @caps, but contains no lists. Each list is expanded into separate
1661 * Returns: the new #GstCaps
1664 gst_caps_normalize (const GstCaps * caps)
1666 NormalizeForeach nf;
1670 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1672 newcaps = gst_caps_copy (caps);
1675 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1676 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1678 while (!gst_structure_foreach (nf.structure,
1679 gst_caps_normalize_foreach, &nf));
1686 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1689 const GstStructure *struct1 = *((const GstStructure **) one);
1690 const GstStructure *struct2 = *((const GstStructure **) two);
1692 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1693 So what's the best way? */
1694 ret = strcmp (gst_structure_get_name (struct1),
1695 gst_structure_get_name (struct2));
1699 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1706 GstStructure *compare;
1711 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1714 UnionField *u = user_data;
1715 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1719 g_value_unset (&u->value);
1722 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1725 g_value_unset (&u->value);
1729 gst_value_union (&u->value, val, value);
1734 gst_caps_structure_simplify (GstStructure ** result,
1735 const GstStructure * simplify, GstStructure * compare)
1738 UnionField field = { 0, {0,}, NULL };
1740 /* try to subtract to get a real subset */
1741 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1742 if (list == NULL) { /* no result */
1745 } else if (list->next == NULL) { /* one result */
1746 *result = list->data;
1747 g_slist_free (list);
1749 } else { /* multiple results */
1750 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1751 g_slist_free (list);
1756 /* try to union both structs */
1757 field.compare = compare;
1758 if (gst_structure_foreach ((GstStructure *) simplify,
1759 gst_caps_structure_figure_out_union, &field)) {
1760 gboolean ret = FALSE;
1762 /* now we know all of simplify's fields are the same in compare
1763 * but at most one field: field.name */
1764 if (G_IS_VALUE (&field.value)) {
1765 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1766 gst_structure_id_set_value (compare, field.name, &field.value);
1770 g_value_unset (&field.value);
1771 } else if (gst_structure_n_fields (simplify) <=
1772 gst_structure_n_fields (compare)) {
1773 /* compare is just more specific, will be optimized away later */
1774 /* FIXME: do this here? */
1775 GST_LOG ("found a case that will be optimized later.");
1777 gchar *one = gst_structure_to_string (simplify);
1778 gchar *two = gst_structure_to_string (compare);
1781 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1793 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1794 GstStructure * new, gint i)
1796 gst_structure_set_parent_refcount (old, NULL);
1797 gst_structure_free (old);
1798 gst_structure_set_parent_refcount (new, &caps->refcount);
1799 g_ptr_array_index (caps->structs, i) = new;
1803 * gst_caps_do_simplify:
1804 * @caps: a #GstCaps to simplify
1806 * Modifies the given @caps inplace into a representation that represents the
1807 * same set of formats, but in a simpler form. Component structures that are
1808 * identical are merged. Component structures that have values that can be
1809 * merged are also merged.
1811 * Returns: TRUE, if the caps could be simplified
1814 gst_caps_do_simplify (GstCaps * caps)
1816 GstStructure *simplify, *compare, *result = NULL;
1818 gboolean changed = FALSE;
1820 g_return_val_if_fail (caps != NULL, FALSE);
1821 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1823 if (gst_caps_get_size (caps) < 2)
1826 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1828 start = caps->structs->len - 1;
1829 for (i = caps->structs->len - 1; i >= 0; i--) {
1830 simplify = gst_caps_get_structure_unchecked (caps, i);
1831 if (gst_structure_get_name_id (simplify) !=
1832 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1835 for (j = start; j >= 0; j--) {
1838 compare = gst_caps_get_structure_unchecked (caps, j);
1839 if (gst_structure_get_name_id (simplify) !=
1840 gst_structure_get_name_id (compare)) {
1843 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1845 gst_caps_switch_structures (caps, simplify, result, i);
1848 gst_caps_remove_structure (caps, i);
1860 /* gst_caps_do_simplify (caps); */
1866 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
1868 * gst_caps_save_thyself:
1869 * @caps: a #GstCaps structure
1870 * @parent: a XML parent node
1872 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1874 * Returns: a XML node pointer
1877 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1879 char *s = gst_caps_to_string (caps);
1881 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1887 * gst_caps_load_thyself:
1888 * @parent: a XML node
1890 * Creates a #GstCaps from its XML serialization.
1892 * Returns: a new #GstCaps structure
1895 gst_caps_load_thyself (xmlNodePtr parent)
1897 if (strcmp ("caps", (char *) parent->name) == 0) {
1898 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1909 * @caps: (inout) (transfer full): a pointer to #GstCaps
1910 * @newcaps: a #GstCaps to replace *caps
1912 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1913 * pointed to by @caps, if applicable, then modifies @caps to point to
1914 * @newcaps. An additional ref on @newcaps is taken.
1916 * This function does not take any locks so you might want to lock
1917 * the object owning @caps pointer.
1920 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1924 g_return_if_fail (caps != NULL);
1928 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1930 if (newcaps != oldcaps) {
1932 gst_caps_ref (newcaps);
1937 gst_caps_unref (oldcaps);
1942 * gst_caps_to_string:
1945 * Converts @caps to a string representation. This string representation
1946 * can be converted back to a #GstCaps by gst_caps_from_string().
1948 * For debugging purposes its easier to do something like this:
1950 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1952 * This prints the caps in human readble form.
1954 * Returns: (transfer full): a newly allocated string representing @caps.
1957 gst_caps_to_string (const GstCaps * caps)
1959 guint i, slen, clen;
1962 /* NOTE: This function is potentially called by the debug system,
1963 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1964 * should be careful to avoid recursion. This includes any functions
1965 * called by gst_caps_to_string. In particular, calls should
1966 * not use the GST_PTR_FORMAT extension. */
1969 return g_strdup ("NULL");
1971 if (CAPS_IS_ANY (caps)) {
1972 return g_strdup ("ANY");
1974 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1975 return g_strdup ("EMPTY");
1978 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1980 clen = caps->structs->len;
1981 for (i = 0; i < clen; i++) {
1983 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1987 s = g_string_sized_new (slen);
1988 for (i = 0; i < clen; i++) {
1989 GstStructure *structure;
1992 /* ';' is now added by gst_structure_to_string */
1993 g_string_append_c (s, ' ');
1996 structure = gst_caps_get_structure_unchecked (caps, i);
1997 priv_gst_structure_append_to_gstring (structure, s);
1999 if (s->len && s->str[s->len - 1] == ';') {
2000 /* remove latest ';' */
2001 s->str[--s->len] = '\0';
2003 return g_string_free (s, FALSE);
2007 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2009 GstStructure *structure;
2012 if (strcmp ("ANY", string) == 0) {
2013 caps->flags = GST_CAPS_FLAGS_ANY;
2016 if (strcmp ("EMPTY", string) == 0) {
2020 structure = gst_structure_from_string (string, &s);
2021 if (structure == NULL) {
2024 gst_caps_append_structure_unchecked (caps, structure);
2028 while (g_ascii_isspace (*s))
2033 structure = gst_structure_from_string (s, &s);
2034 if (structure == NULL) {
2037 gst_caps_append_structure_unchecked (caps, structure);
2045 * gst_caps_from_string:
2046 * @string: a string to convert to #GstCaps
2048 * Converts @caps from a string representation.
2050 * Returns: (transfer full): a newly allocated #GstCaps
2053 gst_caps_from_string (const gchar * string)
2057 g_return_val_if_fail (string, FALSE);
2059 caps = gst_caps_new_empty ();
2060 if (gst_caps_from_string_inplace (caps, string)) {
2063 gst_caps_unref (caps);
2069 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2071 g_return_if_fail (G_IS_VALUE (src_value));
2072 g_return_if_fail (G_IS_VALUE (dest_value));
2073 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2074 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2075 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2077 dest_value->data[0].v_pointer =
2078 gst_caps_to_string (src_value->data[0].v_pointer);
2082 gst_caps_copy_conditional (GstCaps * src)
2085 return gst_caps_ref (src);