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;
169 caps->flags = GST_CAPS_FLAGS_NONE;
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_TRACE (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_TRACE (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 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_TRACE (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;
495 temp.flags = GST_CAPS_FLAGS_NONE;
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_TRACE (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 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_subset_structure:
1112 * @structure: a potential #GstStructure subset of @caps
1114 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1115 * for more information.
1117 * Returns: %TRUE if @structure is a subset of @caps
1122 gst_caps_is_subset_structure (const GstCaps * caps,
1123 const GstStructure * structure)
1128 g_return_val_if_fail (caps != NULL, FALSE);
1129 g_return_val_if_fail (structure != NULL, FALSE);
1131 if (CAPS_IS_ANY (caps))
1133 if (CAPS_IS_EMPTY (caps))
1136 for (i = caps->structs->len - 1; i >= 0; i--) {
1137 s = gst_caps_get_structure_unchecked (caps, i);
1138 if (gst_structure_is_subset (structure, s)) {
1139 /* If we found a superset return TRUE */
1148 * gst_caps_is_equal:
1149 * @caps1: a #GstCaps
1150 * @caps2: another #GstCaps
1152 * Checks if the given caps represent the same set of caps.
1153 * <note>This function does not work reliably if optional properties for caps
1154 * are included on one caps and omitted on the other.</note>
1156 * This function deals correctly with passing NULL for any of the caps.
1158 * Returns: TRUE if both caps are equal.
1161 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1163 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1164 * So there should be an assertion that caps1 and caps2 != NULL */
1166 /* NULL <-> NULL is allowed here */
1167 if (G_UNLIKELY (caps1 == caps2))
1170 /* one of them NULL => they are different (can't be both NULL because
1171 * we checked that above) */
1172 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1175 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1176 return gst_caps_is_equal_fixed (caps1, caps2);
1178 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1181 /* intersect operation */
1184 * gst_caps_can_intersect:
1185 * @caps1: a #GstCaps to intersect
1186 * @caps2: a #GstCaps to intersect
1188 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1191 * Returns: %TRUE if intersection would be not empty
1196 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1198 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1199 guint j, k, len1, len2;
1200 GstStructure *struct1;
1201 GstStructure *struct2;
1203 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1204 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1206 /* caps are exactly the same pointers */
1207 if (G_UNLIKELY (caps1 == caps2))
1210 /* empty caps on either side, return empty */
1211 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1214 /* one of the caps is any */
1215 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1218 /* run zigzag on top line then right line, this preserves the caps order
1219 * much better than a simple loop.
1221 * This algorithm zigzags over the caps structures as demonstrated in
1222 * the folowing matrix:
1225 * +------------- total distance: +-------------
1226 * | 1 2 4 7 0 | 0 1 2 3
1227 * caps2 | 3 5 8 10 1 | 1 2 3 4
1228 * | 6 9 11 12 2 | 2 3 4 5
1230 * First we iterate over the caps1 structures (top line) intersecting
1231 * the structures diagonally down, then we iterate over the caps2
1232 * structures. The result is that the intersections are ordered based on the
1233 * sum of the indexes in the list.
1235 len1 = caps1->structs->len;
1236 len2 = caps2->structs->len;
1237 for (i = 0; i < len1 + len2 - 1; i++) {
1238 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1239 j = MIN (i, len1 - 1);
1240 /* subset index stays 0 until i reaches superset->structs->len, then it
1241 * counts up from 1 to subset->structs->len - 1 */
1242 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1244 /* now run the diagonal line, end condition is the left or bottom
1247 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1248 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1250 if (gst_structure_can_intersect (struct1, struct2)) {
1253 /* move down left */
1255 if (G_UNLIKELY (j == 0))
1256 break; /* so we don't roll back to G_MAXUINT */
1264 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1266 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1267 guint j, k, len1, len2;
1269 GstStructure *struct1;
1270 GstStructure *struct2;
1272 GstStructure *istruct;
1274 /* caps are exactly the same pointers, just copy one caps */
1275 if (G_UNLIKELY (caps1 == caps2))
1276 return gst_caps_copy (caps1);
1278 /* empty caps on either side, return empty */
1279 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1280 return gst_caps_new_empty ();
1282 /* one of the caps is any, just copy the other caps */
1283 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1284 return gst_caps_copy (caps2);
1285 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1286 return gst_caps_copy (caps1);
1288 dest = gst_caps_new_empty ();
1290 /* run zigzag on top line then right line, this preserves the caps order
1291 * much better than a simple loop.
1293 * This algorithm zigzags over the caps structures as demonstrated in
1294 * the folowing matrix:
1302 * First we iterate over the caps1 structures (top line) intersecting
1303 * the structures diagonally down, then we iterate over the caps2
1306 len1 = caps1->structs->len;
1307 len2 = caps2->structs->len;
1308 for (i = 0; i < len1 + len2 - 1; i++) {
1309 /* caps1 index goes from 0 to caps1->structs->len-1 */
1310 j = MIN (i, len1 - 1);
1311 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1312 * up from 1 to caps2->structs->len - 1 */
1313 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1315 /* now run the diagonal line, end condition is the left or bottom
1318 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1319 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1321 istruct = gst_structure_intersect (struct1, struct2);
1323 gst_caps_merge_structure (dest, istruct);
1324 /* move down left */
1326 if (G_UNLIKELY (j == 0))
1327 break; /* so we don't roll back to G_MAXUINT */
1335 * gst_caps_intersect_first:
1336 * @caps1: a #GstCaps to intersect
1337 * @caps2: a #GstCaps to intersect
1339 * Creates a new #GstCaps that contains all the formats that are common
1340 * to both @caps1 and @caps2.
1342 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1343 * fashion as @caps1.
1345 * Returns: the new #GstCaps
1348 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1350 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1351 guint j, len1, len2;
1353 GstStructure *struct1;
1354 GstStructure *struct2;
1356 GstStructure *istruct;
1358 /* caps are exactly the same pointers, just copy one caps */
1359 if (G_UNLIKELY (caps1 == caps2))
1360 return gst_caps_copy (caps1);
1362 /* empty caps on either side, return empty */
1363 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1364 return gst_caps_new_empty ();
1366 /* one of the caps is any, just copy the other caps */
1367 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1368 return gst_caps_copy (caps2);
1369 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1370 return gst_caps_copy (caps1);
1372 dest = gst_caps_new_empty ();
1374 len1 = caps1->structs->len;
1375 len2 = caps2->structs->len;
1376 for (i = 0; i < len1; i++) {
1377 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1378 for (j = 0; j < len2; j++) {
1379 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1380 istruct = gst_structure_intersect (struct1, struct2);
1382 gst_caps_merge_structure (dest, istruct);
1390 * gst_caps_intersect_full:
1391 * @caps1: a #GstCaps to intersect
1392 * @caps2: a #GstCaps to intersect
1393 * @mode: The intersection algorithm/mode to use
1395 * Creates a new #GstCaps that contains all the formats that are common
1396 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1399 * Returns: the new #GstCaps
1403 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1404 GstCapsIntersectMode mode)
1406 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1407 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1410 case GST_CAPS_INTERSECT_FIRST:
1411 return gst_caps_intersect_first (caps1, caps2);
1413 g_warning ("Unknown caps intersect mode: %d", mode);
1415 case GST_CAPS_INTERSECT_ZIG_ZAG:
1416 return gst_caps_intersect_zig_zag (caps1, caps2);
1421 * gst_caps_intersect:
1422 * @caps1: a #GstCaps to intersect
1423 * @caps2: a #GstCaps to intersect
1425 * Creates a new #GstCaps that contains all the formats that are common
1426 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1428 * Returns: the new #GstCaps
1431 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1433 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1437 /* subtract operation */
1441 const GstStructure *subtract_from;
1447 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1450 SubtractionEntry *e = user_data;
1451 GValue subtraction = { 0, };
1452 const GValue *other;
1453 GstStructure *structure;
1455 other = gst_structure_id_get_value (e->subtract_from, field_id);
1459 if (!gst_value_subtract (&subtraction, other, value))
1461 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1462 g_value_unset (&subtraction);
1465 structure = gst_structure_copy (e->subtract_from);
1466 gst_structure_id_set_value (structure, field_id, &subtraction);
1467 g_value_unset (&subtraction);
1468 e->put_into = g_slist_prepend (e->put_into, structure);
1474 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1475 const GstStructure * subtrahend)
1480 e.subtract_from = minuend;
1483 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1484 gst_caps_structure_subtract_field, &e);
1490 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1491 gst_structure_free (walk->data);
1493 g_slist_free (e.put_into);
1499 * gst_caps_subtract:
1500 * @minuend: #GstCaps to subtract from
1501 * @subtrahend: #GstCaps to subtract
1503 * Subtracts the @subtrahend from the @minuend.
1504 * <note>This function does not work reliably if optional properties for caps
1505 * are included on one caps and omitted on the other.</note>
1507 * Returns: the resulting caps
1510 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1515 GstCaps *dest = NULL, *src;
1517 g_return_val_if_fail (minuend != NULL, NULL);
1518 g_return_val_if_fail (subtrahend != NULL, NULL);
1520 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1521 return gst_caps_new_empty ();
1523 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1524 return gst_caps_copy (minuend);
1526 /* FIXME: Do we want this here or above?
1527 The reason we need this is that there is no definition about what
1528 ANY means for specific types, so it's not possible to reduce ANY partially
1529 You can only remove everything or nothing and that is done above.
1530 Note: there's a test that checks this behaviour. */
1531 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1532 sublen = subtrahend->structs->len;
1533 g_assert (sublen > 0);
1535 src = gst_caps_copy (minuend);
1536 for (i = 0; i < sublen; i++) {
1539 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1541 gst_caps_unref (src);
1544 dest = gst_caps_new_empty ();
1545 srclen = src->structs->len;
1546 for (j = 0; j < srclen; j++) {
1547 min = gst_caps_get_structure_unchecked (src, j);
1548 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1551 if (gst_caps_structure_subtract (&list, min, sub)) {
1554 for (walk = list; walk; walk = g_slist_next (walk)) {
1555 gst_caps_append_structure_unchecked (dest,
1556 (GstStructure *) walk->data);
1558 g_slist_free (list);
1560 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1563 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1566 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1567 gst_caps_unref (src);
1572 gst_caps_unref (src);
1573 gst_caps_do_simplify (dest);
1577 /* union operation */
1580 static GstStructure *
1581 gst_caps_structure_union (const GstStructure * struct1,
1582 const GstStructure * struct2)
1586 const GstStructureField *field1;
1587 const GstStructureField *field2;
1590 /* FIXME this doesn't actually work */
1592 if (struct1->name != struct2->name)
1595 dest = gst_structure_id_empty_new (struct1->name);
1597 for (i = 0; i < struct1->fields->len; i++) {
1598 GValue dest_value = { 0 };
1600 field1 = GST_STRUCTURE_FIELD (struct1, i);
1601 field2 = gst_structure_id_get_field (struct2, field1->name);
1603 if (field2 == NULL) {
1606 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1607 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1610 ret = gst_value_compare (&field1->value, &field2->value);
1621 * @caps1: a #GstCaps to union
1622 * @caps2: a #GstCaps to union
1624 * Creates a new #GstCaps that contains all the formats that are in
1625 * either @caps1 and @caps2.
1627 * Returns: the new #GstCaps
1630 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1635 /* NULL pointers are no correct GstCaps */
1636 g_return_val_if_fail (caps1 != NULL, NULL);
1637 g_return_val_if_fail (caps2 != NULL, NULL);
1639 if (CAPS_IS_EMPTY (caps1))
1640 return gst_caps_copy (caps2);
1642 if (CAPS_IS_EMPTY (caps2))
1643 return gst_caps_copy (caps1);
1645 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1646 return gst_caps_new_any ();
1648 dest1 = gst_caps_copy (caps1);
1649 dest2 = gst_caps_copy (caps2);
1650 gst_caps_append (dest1, dest2);
1652 gst_caps_do_simplify (dest1);
1656 /* normalize/simplify operations */
1658 typedef struct _NormalizeForeach
1661 GstStructure *structure;
1666 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1668 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1672 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1673 guint len = gst_value_list_get_size (value);
1674 for (i = 1; i < len; i++) {
1675 const GValue *v = gst_value_list_get_value (value, i);
1676 GstStructure *structure = gst_structure_copy (nf->structure);
1678 gst_structure_id_set_value (structure, field_id, v);
1679 gst_caps_append_structure_unchecked (nf->caps, structure);
1682 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1683 gst_structure_id_set_value (nf->structure, field_id, &val);
1684 g_value_unset (&val);
1692 * gst_caps_normalize:
1693 * @caps: a #GstCaps to normalize
1695 * Creates a new #GstCaps that represents the same set of formats as
1696 * @caps, but contains no lists. Each list is expanded into separate
1699 * Returns: the new #GstCaps
1702 gst_caps_normalize (const GstCaps * caps)
1704 NormalizeForeach nf;
1708 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1710 newcaps = gst_caps_copy (caps);
1713 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1714 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1716 while (!gst_structure_foreach (nf.structure,
1717 gst_caps_normalize_foreach, &nf));
1724 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1727 const GstStructure *struct1 = *((const GstStructure **) one);
1728 const GstStructure *struct2 = *((const GstStructure **) two);
1730 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1731 So what's the best way? */
1732 ret = strcmp (gst_structure_get_name (struct1),
1733 gst_structure_get_name (struct2));
1737 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1744 GstStructure *compare;
1749 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1752 UnionField *u = user_data;
1753 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1757 g_value_unset (&u->value);
1760 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1763 g_value_unset (&u->value);
1767 gst_value_union (&u->value, val, value);
1772 gst_caps_structure_simplify (GstStructure ** result,
1773 const GstStructure * simplify, GstStructure * compare)
1776 UnionField field = { 0, {0,}, NULL };
1778 /* try to subtract to get a real subset */
1779 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1780 if (list == NULL) { /* no result */
1783 } else if (list->next == NULL) { /* one result */
1784 *result = list->data;
1785 g_slist_free (list);
1787 } else { /* multiple results */
1788 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1789 g_slist_free (list);
1794 /* try to union both structs */
1795 field.compare = compare;
1796 if (gst_structure_foreach ((GstStructure *) simplify,
1797 gst_caps_structure_figure_out_union, &field)) {
1798 gboolean ret = FALSE;
1800 /* now we know all of simplify's fields are the same in compare
1801 * but at most one field: field.name */
1802 if (G_IS_VALUE (&field.value)) {
1803 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1804 gst_structure_id_set_value (compare, field.name, &field.value);
1808 g_value_unset (&field.value);
1809 } else if (gst_structure_n_fields (simplify) <=
1810 gst_structure_n_fields (compare)) {
1811 /* compare is just more specific, will be optimized away later */
1812 /* FIXME: do this here? */
1813 GST_LOG ("found a case that will be optimized later.");
1815 gchar *one = gst_structure_to_string (simplify);
1816 gchar *two = gst_structure_to_string (compare);
1819 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1831 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1832 GstStructure * new, gint i)
1834 gst_structure_set_parent_refcount (old, NULL);
1835 gst_structure_free (old);
1836 gst_structure_set_parent_refcount (new, &caps->refcount);
1837 g_ptr_array_index (caps->structs, i) = new;
1841 * gst_caps_do_simplify:
1842 * @caps: a #GstCaps to simplify
1844 * Modifies the given @caps inplace into a representation that represents the
1845 * same set of formats, but in a simpler form. Component structures that are
1846 * identical are merged. Component structures that have values that can be
1847 * merged are also merged.
1849 * Returns: TRUE, if the caps could be simplified
1852 gst_caps_do_simplify (GstCaps * caps)
1854 GstStructure *simplify, *compare, *result = NULL;
1856 gboolean changed = FALSE;
1858 g_return_val_if_fail (caps != NULL, FALSE);
1859 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1861 if (gst_caps_get_size (caps) < 2)
1864 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1866 start = caps->structs->len - 1;
1867 for (i = caps->structs->len - 1; i >= 0; i--) {
1868 simplify = gst_caps_get_structure_unchecked (caps, i);
1869 if (gst_structure_get_name_id (simplify) !=
1870 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1873 for (j = start; j >= 0; j--) {
1876 compare = gst_caps_get_structure_unchecked (caps, j);
1877 if (gst_structure_get_name_id (simplify) !=
1878 gst_structure_get_name_id (compare)) {
1881 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1883 gst_caps_switch_structures (caps, simplify, result, i);
1886 gst_caps_remove_structure (caps, i);
1898 /* gst_caps_do_simplify (caps); */
1904 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
1906 * gst_caps_save_thyself:
1907 * @caps: a #GstCaps structure
1908 * @parent: a XML parent node
1910 * Serializes a #GstCaps to XML and adds it as a child node of @parent.
1912 * Returns: a XML node pointer
1915 gst_caps_save_thyself (const GstCaps * caps, xmlNodePtr parent)
1917 char *s = gst_caps_to_string (caps);
1919 xmlNewChild (parent, NULL, (xmlChar *) "caps", (xmlChar *) s);
1925 * gst_caps_load_thyself:
1926 * @parent: a XML node
1928 * Creates a #GstCaps from its XML serialization.
1930 * Returns: a new #GstCaps structure
1933 gst_caps_load_thyself (xmlNodePtr parent)
1935 if (strcmp ("caps", (char *) parent->name) == 0) {
1936 return gst_caps_from_string ((gchar *) xmlNodeGetContent (parent));
1947 * @caps: (inout) (transfer full): a pointer to #GstCaps
1948 * @newcaps: a #GstCaps to replace *caps
1950 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1951 * pointed to by @caps, if applicable, then modifies @caps to point to
1952 * @newcaps. An additional ref on @newcaps is taken.
1954 * This function does not take any locks so you might want to lock
1955 * the object owning @caps pointer.
1958 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1962 g_return_if_fail (caps != NULL);
1966 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1968 if (newcaps != oldcaps) {
1970 gst_caps_ref (newcaps);
1975 gst_caps_unref (oldcaps);
1980 * gst_caps_to_string:
1983 * Converts @caps to a string representation. This string representation
1984 * can be converted back to a #GstCaps by gst_caps_from_string().
1986 * For debugging purposes its easier to do something like this:
1988 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1990 * This prints the caps in human readble form.
1992 * Returns: (transfer full): a newly allocated string representing @caps.
1995 gst_caps_to_string (const GstCaps * caps)
1997 guint i, slen, clen;
2000 /* NOTE: This function is potentially called by the debug system,
2001 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2002 * should be careful to avoid recursion. This includes any functions
2003 * called by gst_caps_to_string. In particular, calls should
2004 * not use the GST_PTR_FORMAT extension. */
2007 return g_strdup ("NULL");
2009 if (CAPS_IS_ANY (caps)) {
2010 return g_strdup ("ANY");
2012 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2013 return g_strdup ("EMPTY");
2016 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2018 clen = caps->structs->len;
2019 for (i = 0; i < clen; i++) {
2021 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
2025 s = g_string_sized_new (slen);
2026 for (i = 0; i < clen; i++) {
2027 GstStructure *structure;
2030 /* ';' is now added by gst_structure_to_string */
2031 g_string_append_c (s, ' ');
2034 structure = gst_caps_get_structure_unchecked (caps, i);
2035 priv_gst_structure_append_to_gstring (structure, s);
2037 if (s->len && s->str[s->len - 1] == ';') {
2038 /* remove latest ';' */
2039 s->str[--s->len] = '\0';
2041 return g_string_free (s, FALSE);
2045 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2047 GstStructure *structure;
2050 if (strcmp ("ANY", string) == 0) {
2051 caps->flags = GST_CAPS_FLAGS_ANY;
2054 if (strcmp ("EMPTY", string) == 0) {
2058 structure = gst_structure_from_string (string, &s);
2059 if (structure == NULL) {
2062 gst_caps_append_structure_unchecked (caps, structure);
2066 while (g_ascii_isspace (*s))
2071 structure = gst_structure_from_string (s, &s);
2072 if (structure == NULL) {
2075 gst_caps_append_structure_unchecked (caps, structure);
2083 * gst_caps_from_string:
2084 * @string: a string to convert to #GstCaps
2086 * Converts @caps from a string representation.
2088 * Returns: (transfer full): a newly allocated #GstCaps
2091 gst_caps_from_string (const gchar * string)
2095 g_return_val_if_fail (string, FALSE);
2097 caps = gst_caps_new_empty ();
2098 if (gst_caps_from_string_inplace (caps, string)) {
2101 gst_caps_unref (caps);
2107 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2109 g_return_if_fail (G_IS_VALUE (src_value));
2110 g_return_if_fail (G_IS_VALUE (dest_value));
2111 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2112 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2113 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2115 dest_value->data[0].v_pointer =
2116 gst_caps_to_string (src_value->data[0].v_pointer);
2120 gst_caps_copy_conditional (GstCaps * src)
2123 return gst_caps_ref (src);