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 #define DEBUG_REFCOUNT
78 #define CAPS_POISON(caps) G_STMT_START{ \
80 GstCaps *_newcaps = gst_caps_copy (caps); \
81 gst_caps_unref(caps); \
85 #define STRUCTURE_POISON(structure) G_STMT_START{ \
87 GstStructure *_newstruct = gst_structure_copy (structure); \
88 gst_structure_free(structure); \
89 structure = _newstruct; \
92 #define IS_WRITABLE(caps) \
93 (g_atomic_int_get (&(caps)->refcount) == 1)
95 /* same as gst_caps_is_any () */
96 #define CAPS_IS_ANY(caps) \
97 ((caps)->flags & GST_CAPS_FLAGS_ANY)
99 /* same as gst_caps_is_empty () */
100 #define CAPS_IS_EMPTY(caps) \
101 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
103 #define CAPS_IS_EMPTY_SIMPLE(caps) \
104 (((caps)->structs == NULL) || ((caps)->structs->len == 0))
106 /* quick way to get a caps structure at an index without doing a type or array
108 #define gst_caps_get_structure_unchecked(caps, index) \
109 ((GstStructure *)g_ptr_array_index ((caps)->structs, (index)))
110 /* quick way to append a structure without checking the args */
111 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
112 GstStructure *__s=structure; \
113 gst_structure_set_parent_refcount (__s, &caps->refcount); \
114 g_ptr_array_add (caps->structs, __s); \
117 /* lock to protect multiple invocations of static caps to caps conversion */
118 G_LOCK_DEFINE_STATIC (static_caps_lock);
120 static void gst_caps_transform_to_string (const GValue * src_value,
121 GValue * dest_value);
122 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
123 const gchar * string);
124 static GstCaps *gst_caps_copy_conditional (GstCaps * src);
127 gst_caps_get_type (void)
129 static GType gst_caps_type = 0;
131 if (G_UNLIKELY (gst_caps_type == 0)) {
132 gst_caps_type = g_boxed_type_register_static ("GstCaps",
133 (GBoxedCopyFunc) gst_caps_copy_conditional,
134 (GBoxedFreeFunc) gst_caps_unref);
136 g_value_register_transform_func (gst_caps_type,
137 G_TYPE_STRING, gst_caps_transform_to_string);
140 return gst_caps_type;
143 /* creation/deletion */
146 * gst_caps_new_empty:
148 * Creates a new #GstCaps that is empty. That is, the returned
149 * #GstCaps contains no media formats.
150 * Caller is responsible for unreffing the returned caps.
152 * Returns: (transfer full): the new #GstCaps
155 gst_caps_new_empty (void)
157 GstCaps *caps = g_slice_new (GstCaps);
159 caps->type = GST_TYPE_CAPS;
162 caps->structs = g_ptr_array_new ();
163 /* the 32 has been determined by logging caps sizes in _gst_caps_free
164 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
166 * caps->structs = g_ptr_array_sized_new (32);
169 #ifdef DEBUG_REFCOUNT
170 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
179 * Creates a new #GstCaps that indicates that it is compatible with
182 * Returns: (transfer full): the new #GstCaps
185 gst_caps_new_any (void)
187 GstCaps *caps = gst_caps_new_empty ();
189 caps->flags = GST_CAPS_FLAGS_ANY;
195 * gst_caps_new_simple:
196 * @media_type: the media type of the structure
197 * @fieldname: first field to set
198 * @...: additional arguments
200 * Creates a new #GstCaps that contains one #GstStructure. The
201 * structure is defined by the arguments, which have the same format
202 * as gst_structure_new().
203 * Caller is responsible for unreffing the returned caps.
205 * Returns: (transfer full): the new #GstCaps
208 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
211 GstStructure *structure;
214 caps = gst_caps_new_empty ();
216 va_start (var_args, fieldname);
217 structure = gst_structure_new_valist (media_type, fieldname, var_args);
220 gst_caps_append_structure_unchecked (caps, structure);
227 * @struct1: the first structure to add
228 * @...: additional structures to add
230 * Creates a new #GstCaps and adds all the structures listed as
231 * arguments. The list must be NULL-terminated. The structures
232 * are not copied; the returned #GstCaps owns the structures.
234 * Returns: (transfer full): the new #GstCaps
237 gst_caps_new_full (GstStructure * struct1, ...)
242 va_start (var_args, struct1);
243 caps = gst_caps_new_full_valist (struct1, var_args);
250 * gst_caps_new_full_valist:
251 * @structure: the first structure to add
252 * @var_args: additional structures to add
254 * Creates a new #GstCaps and adds all the structures listed as
255 * arguments. The list must be NULL-terminated. The structures
256 * are not copied; the returned #GstCaps owns the structures.
258 * Returns: (transfer full): the new #GstCaps
261 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
265 caps = gst_caps_new_empty ();
268 gst_caps_append_structure_unchecked (caps, structure);
269 structure = va_arg (var_args, GstStructure *);
277 * @caps: the #GstCaps to copy
279 * Creates a new #GstCaps as a copy of the old @caps. The new caps will have a
280 * refcount of 1, owned by the caller. The structures are copied as well.
282 * Note that this function is the semantic equivalent of a gst_caps_ref()
283 * followed by a gst_caps_make_writable(). If you only want to hold on to a
284 * reference to the data, you should use gst_caps_ref().
286 * When you are finished with the caps, call gst_caps_unref() on it.
288 * Returns: (transfer full): the new #GstCaps
291 gst_caps_copy (const GstCaps * caps)
294 GstStructure *structure;
297 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
299 newcaps = gst_caps_new_empty ();
300 newcaps->flags = caps->flags;
301 n = caps->structs->len;
303 for (i = 0; i < n; i++) {
304 structure = gst_caps_get_structure_unchecked (caps, i);
305 gst_caps_append_structure_unchecked (newcaps,
306 gst_structure_copy (structure));
313 _gst_caps_free (GstCaps * caps)
315 GstStructure *structure;
318 /* The refcount must be 0, but since we're only called by gst_caps_unref,
319 * don't bother testing. */
320 len = caps->structs->len;
321 /* This can be used to get statistics about caps sizes */
322 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
323 for (i = 0; i < len; i++) {
324 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
325 gst_structure_set_parent_refcount (structure, NULL);
326 gst_structure_free (structure);
328 g_ptr_array_free (caps->structs, TRUE);
330 memset (caps, 0xff, sizeof (GstCaps));
333 #ifdef DEBUG_REFCOUNT
334 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
336 g_slice_free (GstCaps, caps);
340 * gst_caps_make_writable:
341 * @caps: (transfer full): the #GstCaps to make writable
343 * Returns a writable copy of @caps.
345 * If there is only one reference count on @caps, the caller must be the owner,
346 * and so this function will return the caps object unchanged. If on the other
347 * hand there is more than one reference on the object, a new caps object will
348 * be returned. The caller's reference on @caps will be removed, and instead the
349 * caller will own a reference to the returned object.
351 * In short, this function unrefs the caps in the argument and refs the caps
352 * that it returns. Don't access the argument after calling this function. See
353 * also: gst_caps_ref().
355 * Returns: (transfer full): the same #GstCaps object.
358 gst_caps_make_writable (GstCaps * caps)
362 g_return_val_if_fail (caps != NULL, NULL);
364 /* we are the only instance reffing this caps */
365 if (IS_WRITABLE (caps))
369 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy caps");
370 copy = gst_caps_copy (caps);
371 gst_caps_unref (caps);
378 * @caps: the #GstCaps to reference
380 * Add a reference to a #GstCaps object.
382 * From this point on, until the caller calls gst_caps_unref() or
383 * gst_caps_make_writable(), it is guaranteed that the caps object will not
384 * change. This means its structures won't change, etc. To use a #GstCaps
385 * object, you must always have a refcount on it -- either the one made
386 * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
389 * Returns: (transfer full): the same #GstCaps object.
392 gst_caps_ref (GstCaps * caps)
394 g_return_val_if_fail (caps != NULL, NULL);
396 #ifdef DEBUG_REFCOUNT
397 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
398 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) + 1);
400 g_return_val_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0, NULL);
402 g_atomic_int_inc (&caps->refcount);
409 * @caps: (transfer full): the #GstCaps to unref
411 * Unref a #GstCaps and and free all its structures and the
412 * structures' values when the refcount reaches 0.
415 gst_caps_unref (GstCaps * caps)
417 g_return_if_fail (caps != NULL);
419 #ifdef DEBUG_REFCOUNT
420 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p %d->%d", caps,
421 GST_CAPS_REFCOUNT_VALUE (caps), GST_CAPS_REFCOUNT_VALUE (caps) - 1);
424 g_return_if_fail (GST_CAPS_REFCOUNT_VALUE (caps) > 0);
426 /* if we ended up with the refcount at zero, free the caps */
427 if (G_UNLIKELY (g_atomic_int_dec_and_test (&caps->refcount)))
428 _gst_caps_free (caps);
432 gst_static_caps_get_type (void)
434 static GType staticcaps_type = 0;
436 if (G_UNLIKELY (staticcaps_type == 0)) {
437 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
439 return staticcaps_type;
444 * gst_static_caps_get:
445 * @static_caps: the #GstStaticCaps to convert
447 * Converts a #GstStaticCaps to a #GstCaps.
449 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
450 * Since the core holds an additional ref to the returned caps,
451 * use gst_caps_make_writable() on the returned caps to modify it.
454 gst_static_caps_get (GstStaticCaps * static_caps)
458 g_return_val_if_fail (static_caps != NULL, NULL);
460 caps = (GstCaps *) static_caps;
462 /* refcount is 0 when we need to convert */
463 if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) == 0)) {
467 G_LOCK (static_caps_lock);
468 /* check if other thread already updated */
469 if (G_UNLIKELY (g_atomic_int_get (&caps->refcount) > 0))
472 string = static_caps->string;
474 if (G_UNLIKELY (string == NULL))
477 GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);
479 /* we construct the caps on the stack, then copy over the struct into our
480 * real caps, refcount last. We do this because we must leave the refcount
481 * of the result caps to 0 so that other threads don't run away with the
482 * caps while we are constructing it. */
483 temp.type = GST_TYPE_CAPS;
485 temp.structs = g_ptr_array_new ();
487 /* initialize the caps to a refcount of 1 so the caps can be writable for
488 * the next statement */
491 /* convert to string */
492 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
493 g_critical ("Could not convert static caps \"%s\"", string);
495 /* now copy stuff over to the real caps. */
496 caps->type = temp.type;
497 caps->flags = temp.flags;
498 caps->structs = temp.structs;
499 /* and bump the refcount so other threads can now read */
500 g_atomic_int_set (&caps->refcount, 1);
502 GST_CAT_LOG (GST_CAT_CAPS, "created %p", static_caps);
504 G_UNLOCK (static_caps_lock);
506 /* ref the caps, makes it not writable */
514 G_UNLOCK (static_caps_lock);
515 g_warning ("static caps %p string is NULL", static_caps);
522 static GstStructure *
523 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
525 /* don't use index_fast, gst_caps_do_simplify relies on the order */
526 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
528 gst_structure_set_parent_refcount (s, NULL);
533 * gst_caps_steal_structure:
534 * @caps: the #GstCaps to retrieve from
535 * @index: Index of the structure to retrieve
537 * Retrieves the stucture with the given index from the list of structures
538 * contained in @caps. The caller becomes the owner of the returned structure.
540 * Returns: (transfer full): a pointer to the #GstStructure corresponding
546 gst_caps_steal_structure (GstCaps * caps, guint index)
548 g_return_val_if_fail (caps != NULL, NULL);
549 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
551 if (G_UNLIKELY (index >= caps->structs->len))
554 return gst_caps_remove_and_get_structure (caps, index);
558 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
561 GstStructure *struct1 = (GstStructure *) data;
562 const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
564 if (G_UNLIKELY (val1 == NULL))
566 if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
574 gst_caps_structure_is_subset_field (GQuark field_id, const GValue * value,
577 GstStructure *subtract_from = user_data;
578 GValue subtraction = { 0, };
581 if (!(other = gst_structure_id_get_value (subtract_from, field_id)))
582 /* field is missing in one set */
585 /* equal values are subset */
586 if (gst_value_compare (other, value) == GST_VALUE_EQUAL)
594 * -> 1 - [1,2] = empty
598 * -> [1,2] - [1,3] = empty
602 * -> {1,3} - {1,2} = 3
605 * First caps subtraction needs to return a non-empty set, second
606 * subtractions needs to give en empty set.
608 if (gst_value_subtract (&subtraction, other, value)) {
609 g_value_unset (&subtraction);
610 /* !empty result, swapping must be empty */
611 if (!gst_value_subtract (&subtraction, value, other))
614 g_value_unset (&subtraction);
620 gst_caps_structure_is_subset (const GstStructure * minuend,
621 const GstStructure * subtrahend)
623 if ((minuend->name != subtrahend->name) ||
624 (gst_structure_n_fields (minuend) !=
625 gst_structure_n_fields (subtrahend))) {
629 return gst_structure_foreach ((GstStructure *) subtrahend,
630 gst_caps_structure_is_subset_field, (gpointer) minuend);
635 * @caps1: the #GstCaps that will be appended to
636 * @caps2: (transfer full): the #GstCaps to append
638 * Appends the structures contained in @caps2 to @caps1. The structures in
639 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
640 * freed. If either caps is ANY, the resulting caps will be ANY.
643 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
645 GstStructure *structure;
648 g_return_if_fail (GST_IS_CAPS (caps1));
649 g_return_if_fail (GST_IS_CAPS (caps2));
650 g_return_if_fail (IS_WRITABLE (caps1));
651 g_return_if_fail (IS_WRITABLE (caps2));
656 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
657 /* FIXME: this leaks */
658 caps1->flags |= GST_CAPS_FLAGS_ANY;
659 for (i = caps2->structs->len - 1; i >= 0; i--) {
660 structure = gst_caps_remove_and_get_structure (caps2, i);
661 gst_structure_free (structure);
664 for (i = caps2->structs->len; i; i--) {
665 structure = gst_caps_remove_and_get_structure (caps2, 0);
666 gst_caps_append_structure_unchecked (caps1, structure);
669 gst_caps_unref (caps2); /* guaranteed to free it */
674 * @caps1: the #GstCaps that will take the new entries
675 * @caps2: (transfer full): the #GstCaps to merge in
677 * Appends the structures contained in @caps2 to @caps1 if they are not yet
678 * expressed by @caps1. The structures in @caps2 are not copied -- they are
679 * transferred to @caps1, and then @caps2 is freed.
680 * If either caps is ANY, the resulting caps will be ANY.
685 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
687 GstStructure *structure;
690 g_return_if_fail (GST_IS_CAPS (caps1));
691 g_return_if_fail (GST_IS_CAPS (caps2));
692 g_return_if_fail (IS_WRITABLE (caps1));
693 g_return_if_fail (IS_WRITABLE (caps2));
698 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
699 for (i = caps2->structs->len - 1; i >= 0; i--) {
700 structure = gst_caps_remove_and_get_structure (caps2, i);
701 gst_structure_free (structure);
703 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
704 caps1->flags |= GST_CAPS_FLAGS_ANY;
705 for (i = caps1->structs->len - 1; i >= 0; i--) {
706 structure = gst_caps_remove_and_get_structure (caps1, i);
707 gst_structure_free (structure);
710 for (i = caps2->structs->len; i; i--) {
711 structure = gst_caps_remove_and_get_structure (caps2, 0);
712 gst_caps_merge_structure (caps1, structure);
715 GstCaps *com = gst_caps_intersect (caps1, caps2);
716 GstCaps *add = gst_caps_subtract (caps2, com);
718 GST_DEBUG ("common : %d", gst_caps_get_size (com));
719 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
720 gst_caps_append (caps1, add);
721 gst_caps_unref (com);
724 gst_caps_unref (caps2); /* guaranteed to free it */
728 * gst_caps_append_structure:
729 * @caps: the #GstCaps that will be appended to
730 * @structure: (transfer full): the #GstStructure to append
732 * Appends @structure to @caps. The structure is not copied; @caps
733 * becomes the owner of @structure.
736 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
738 g_return_if_fail (GST_IS_CAPS (caps));
739 g_return_if_fail (IS_WRITABLE (caps));
741 if (G_LIKELY (structure)) {
742 g_return_if_fail (structure->parent_refcount == NULL);
745 STRUCTURE_POISON (structure);
748 gst_caps_append_structure_unchecked (caps, structure);
753 * gst_caps_remove_structure:
754 * @caps: the #GstCaps to remove from
755 * @idx: Index of the structure to remove
757 * removes the stucture with the given index from the list of structures
758 * contained in @caps.
761 gst_caps_remove_structure (GstCaps * caps, guint idx)
763 GstStructure *structure;
765 g_return_if_fail (caps != NULL);
766 g_return_if_fail (idx <= gst_caps_get_size (caps));
767 g_return_if_fail (IS_WRITABLE (caps));
769 structure = gst_caps_remove_and_get_structure (caps, idx);
770 gst_structure_free (structure);
774 * gst_caps_merge_structure:
775 * @caps: the #GstCaps that will the the new structure
776 * @structure: (transfer full): the #GstStructure to merge
778 * Appends @structure to @caps if its not already expressed by @caps. The
779 * structure is not copied; @caps becomes the owner of @structure.
782 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
784 g_return_if_fail (GST_IS_CAPS (caps));
785 g_return_if_fail (IS_WRITABLE (caps));
787 if (G_LIKELY (structure)) {
788 GstStructure *structure1;
790 gboolean unique = TRUE;
792 g_return_if_fail (structure->parent_refcount == NULL);
795 STRUCTURE_POISON (structure);
798 /* check each structure */
799 for (i = caps->structs->len - 1; i >= 0; i--) {
800 structure1 = gst_caps_get_structure_unchecked (caps, i);
801 /* if structure is a subset of structure1, then skip it */
802 if (gst_caps_structure_is_subset (structure1, structure)) {
808 gst_caps_append_structure_unchecked (caps, structure);
810 gst_structure_free (structure);
819 * Gets the number of structures contained in @caps.
821 * Returns: the number of structures that @caps contains
824 gst_caps_get_size (const GstCaps * caps)
826 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
828 return caps->structs->len;
832 * gst_caps_get_structure:
834 * @index: the index of the structure
836 * Finds the structure in @caps that has the index @index, and
839 * WARNING: This function takes a const GstCaps *, but returns a
840 * non-const GstStructure *. This is for programming convenience --
841 * the caller should be aware that structures inside a constant
842 * #GstCaps should not be modified. However, if you know the caps
843 * are writable, either because you have just copied them or made
844 * them writable with gst_caps_make_writable(), you may modify the
845 * structure returned in the usual way, e.g. with functions like
846 * gst_structure_set().
848 * You do not need to free or unref the structure returned, it
849 * belongs to the #GstCaps.
851 * Returns: (transfer none): a pointer to the #GstStructure corresponding
855 gst_caps_get_structure (const GstCaps * caps, guint index)
857 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
858 g_return_val_if_fail (index < caps->structs->len, NULL);
860 return gst_caps_get_structure_unchecked (caps, index);
865 * @caps: the #GstCaps to copy
866 * @nth: the nth structure to copy
868 * Creates a new #GstCaps and appends a copy of the nth structure
869 * contained in @caps.
871 * Returns: (transfer full): the new #GstCaps
874 gst_caps_copy_nth (const GstCaps * caps, guint nth)
877 GstStructure *structure;
879 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
881 newcaps = gst_caps_new_empty ();
882 newcaps->flags = caps->flags;
884 if (G_LIKELY (caps->structs->len > nth)) {
885 structure = gst_caps_get_structure_unchecked (caps, nth);
886 gst_caps_append_structure_unchecked (newcaps,
887 gst_structure_copy (structure));
895 * @caps: the #GstCaps to truncate
897 * Destructively discard all but the first structure from @caps. Useful when
898 * fixating. @caps must be writable.
901 gst_caps_truncate (GstCaps * caps)
905 g_return_if_fail (GST_IS_CAPS (caps));
906 g_return_if_fail (IS_WRITABLE (caps));
908 i = caps->structs->len - 1;
911 gst_caps_remove_structure (caps, i--);
915 * gst_caps_set_value:
916 * @caps: a writable caps
917 * @field: name of the field to set
918 * @value: value to set the field to
920 * Sets the given @field on all structures of @caps to the given @value.
921 * This is a convenience function for calling gst_structure_set_value() on
922 * all structures of @caps.
927 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
931 g_return_if_fail (GST_IS_CAPS (caps));
932 g_return_if_fail (IS_WRITABLE (caps));
933 g_return_if_fail (field != NULL);
934 g_return_if_fail (G_IS_VALUE (value));
936 len = caps->structs->len;
937 for (i = 0; i < len; i++) {
938 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
939 gst_structure_set_value (structure, field, value);
944 * gst_caps_set_simple_valist:
945 * @caps: the #GstCaps to set
946 * @field: first field to set
947 * @varargs: additional parameters
949 * Sets fields in a #GstCaps. The arguments must be passed in the same
950 * manner as gst_structure_set(), and be NULL-terminated.
951 * <note>Prior to GStreamer version 0.10.26, this function failed when
952 * @caps was not simple. If your code needs to work with those versions
953 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
954 * is %TRUE for @caps.</note>
957 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
959 GValue value = { 0, };
961 g_return_if_fail (GST_IS_CAPS (caps));
962 g_return_if_fail (IS_WRITABLE (caps));
968 type = va_arg (varargs, GType);
970 if (G_UNLIKELY (type == G_TYPE_DATE)) {
971 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
972 type = GST_TYPE_DATE;
974 #if GLIB_CHECK_VERSION(2,23,3)
975 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
977 g_value_init (&value, type);
978 G_VALUE_COLLECT (&value, varargs, 0, &err);
980 if (G_UNLIKELY (err)) {
981 g_critical ("%s", err);
985 gst_caps_set_value (caps, field, &value);
987 g_value_unset (&value);
989 field = va_arg (varargs, const gchar *);
994 * gst_caps_set_simple:
995 * @caps: the #GstCaps to set
996 * @field: first field to set
997 * @...: additional parameters
999 * Sets fields in a #GstCaps. The arguments must be passed in the same
1000 * manner as gst_structure_set(), and be NULL-terminated.
1001 * <note>Prior to GStreamer version 0.10.26, this function failed when
1002 * @caps was not simple. If your code needs to work with those versions
1003 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
1004 * is %TRUE for @caps.</note>
1007 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
1011 g_return_if_fail (GST_IS_CAPS (caps));
1012 g_return_if_fail (IS_WRITABLE (caps));
1014 va_start (var_args, field);
1015 gst_caps_set_simple_valist (caps, field, var_args);
1023 * @caps: the #GstCaps to test
1025 * Determines if @caps represents any media format.
1027 * Returns: TRUE if @caps represents any format.
1030 gst_caps_is_any (const GstCaps * caps)
1032 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1034 return (CAPS_IS_ANY (caps));
1038 * gst_caps_is_empty:
1039 * @caps: the #GstCaps to test
1041 * Determines if @caps represents no media formats.
1043 * Returns: TRUE if @caps represents no formats.
1046 gst_caps_is_empty (const GstCaps * caps)
1048 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1050 if (CAPS_IS_ANY (caps))
1053 return CAPS_IS_EMPTY_SIMPLE (caps);
1057 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
1060 return gst_value_is_fixed (value);
1064 * gst_caps_is_fixed:
1065 * @caps: the #GstCaps to test
1067 * Fixed #GstCaps describe exactly one format, that is, they have exactly
1068 * one structure, and each field in the structure describes a fixed type.
1069 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
1071 * Returns: TRUE if @caps is fixed
1074 gst_caps_is_fixed (const GstCaps * caps)
1076 GstStructure *structure;
1078 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
1080 if (caps->structs->len != 1)
1083 structure = gst_caps_get_structure_unchecked (caps, 0);
1085 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
1089 * gst_caps_is_equal_fixed:
1090 * @caps1: the #GstCaps to test
1091 * @caps2: the #GstCaps to test
1093 * Tests if two #GstCaps are equal. This function only works on fixed
1096 * Returns: TRUE if the arguments represent the same format
1099 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
1101 GstStructure *struct1, *struct2;
1103 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1104 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1106 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1107 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1109 if (struct1->name != struct2->name) {
1112 if (struct1->fields->len != struct2->fields->len) {
1116 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
1121 * gst_caps_is_always_compatible:
1122 * @caps1: the #GstCaps to test
1123 * @caps2: the #GstCaps to test
1125 * A given #GstCaps structure is always compatible with another if
1126 * every media format that is in the first is also contained in the
1127 * second. That is, @caps1 is a subset of @caps2.
1129 * Returns: TRUE if @caps1 is a subset of @caps2.
1132 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1134 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1135 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1137 return gst_caps_is_subset (caps1, caps2);
1141 * gst_caps_is_subset:
1142 * @subset: a #GstCaps
1143 * @superset: a potentially greater #GstCaps
1145 * Checks if all caps represented by @subset are also represented by @superset.
1146 * <note>This function does not work reliably if optional properties for caps
1147 * are included on one caps and omitted on the other.</note>
1149 * Returns: %TRUE if @subset is a subset of @superset
1152 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1157 g_return_val_if_fail (subset != NULL, FALSE);
1158 g_return_val_if_fail (superset != NULL, FALSE);
1160 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1162 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1165 caps = gst_caps_subtract (subset, superset);
1166 ret = CAPS_IS_EMPTY_SIMPLE (caps);
1167 gst_caps_unref (caps);
1172 * gst_caps_is_equal:
1173 * @caps1: a #GstCaps
1174 * @caps2: another #GstCaps
1176 * Checks if the given caps represent the same set of caps.
1177 * <note>This function does not work reliably if optional properties for caps
1178 * are included on one caps and omitted on the other.</note>
1180 * This function deals correctly with passing NULL for any of the caps.
1182 * Returns: TRUE if both caps are equal.
1185 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1187 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1188 * So there should be an assertion that caps1 and caps2 != NULL */
1190 /* NULL <-> NULL is allowed here */
1191 if (G_UNLIKELY (caps1 == caps2))
1194 /* one of them NULL => they are different (can't be both NULL because
1195 * we checked that above) */
1196 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1199 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1200 return gst_caps_is_equal_fixed (caps1, caps2);
1202 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1205 /* intersect operation */
1210 const GstStructure *intersect;
1215 gst_caps_structure_intersect_field1 (GQuark id, const GValue * val1,
1218 IntersectData *idata = (IntersectData *) data;
1219 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1221 if (G_UNLIKELY (val2 == NULL)) {
1222 gst_structure_id_set_value (idata->dest, id, val1);
1224 GValue dest_value = { 0 };
1225 if (gst_value_intersect (&dest_value, val1, val2)) {
1226 gst_structure_id_set_value (idata->dest, id, &dest_value);
1227 g_value_unset (&dest_value);
1236 gst_caps_structure_intersect_field2 (GQuark id, const GValue * val1,
1239 IntersectData *idata = (IntersectData *) data;
1240 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1242 if (G_UNLIKELY (val2 == NULL)) {
1243 gst_structure_id_set_value (idata->dest, id, val1);
1248 static GstStructure *
1249 gst_caps_structure_intersect (const GstStructure * struct1,
1250 const GstStructure * struct2)
1254 g_assert (struct1 != NULL);
1255 g_assert (struct2 != NULL);
1257 if (G_UNLIKELY (struct1->name != struct2->name))
1260 /* copy fields from struct1 which we have not in struct2 to target
1261 * intersect if we have the field in both */
1262 data.dest = gst_structure_id_empty_new (struct1->name);
1263 data.intersect = struct2;
1264 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1265 gst_caps_structure_intersect_field1, &data)))
1268 /* copy fields from struct2 which we have not in struct1 to target */
1269 data.intersect = struct1;
1270 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
1271 gst_caps_structure_intersect_field2, &data)))
1277 gst_structure_free (data.dest);
1282 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
1285 GstStructure *other = (GstStructure *) data;
1286 const GValue *val2 = gst_structure_id_get_value (other, id);
1288 if (G_LIKELY (val2)) {
1289 if (!gst_value_can_intersect (val1, val2)) {
1292 gint eq = gst_value_compare (val1, val2);
1294 if (eq == GST_VALUE_UNORDERED) {
1295 /* we need to try interseting */
1296 GValue dest_value = { 0 };
1297 if (gst_value_intersect (&dest_value, val1, val2)) {
1298 g_value_unset (&dest_value);
1302 } else if (eq != GST_VALUE_EQUAL) {
1311 gst_caps_structure_can_intersect (const GstStructure * struct1,
1312 const GstStructure * struct2)
1314 g_assert (struct1 != NULL);
1315 g_assert (struct2 != NULL);
1317 if (G_UNLIKELY (struct1->name != struct2->name))
1320 /* tries to intersect if we have the field in both */
1321 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1322 gst_caps_structure_can_intersect_field, (gpointer) struct2)))
1329 * gst_caps_can_intersect:
1330 * @caps1: a #GstCaps to intersect
1331 * @caps2: a #GstCaps to intersect
1333 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1336 * Returns: %TRUE if intersection would be not empty
1341 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1343 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1344 guint j, k, len1, len2;
1345 GstStructure *struct1;
1346 GstStructure *struct2;
1348 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1349 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1351 /* caps are exactly the same pointers */
1352 if (G_UNLIKELY (caps1 == caps2))
1355 /* empty caps on either side, return empty */
1356 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1359 /* one of the caps is any */
1360 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1363 /* run zigzag on top line then right line, this preserves the caps order
1364 * much better than a simple loop.
1366 * This algorithm zigzags over the caps structures as demonstrated in
1367 * the folowing matrix:
1370 * +------------- total distance: +-------------
1371 * | 1 2 4 7 0 | 0 1 2 3
1372 * caps2 | 3 5 8 10 1 | 1 2 3 4
1373 * | 6 9 11 12 2 | 2 3 4 5
1375 * First we iterate over the caps1 structures (top line) intersecting
1376 * the structures diagonally down, then we iterate over the caps2
1377 * structures. The result is that the intersections are ordered based on the
1378 * sum of the indexes in the list.
1380 len1 = caps1->structs->len;
1381 len2 = caps2->structs->len;
1382 for (i = 0; i < len1 + len2 - 1; i++) {
1383 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1384 j = MIN (i, len1 - 1);
1385 /* subset index stays 0 until i reaches superset->structs->len, then it
1386 * counts up from 1 to subset->structs->len - 1 */
1389 /* now run the diagonal line, end condition is the left or bottom
1392 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1393 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1395 if (gst_caps_structure_can_intersect (struct1, struct2)) {
1398 /* move down left */
1400 if (G_UNLIKELY (j == 0))
1401 break; /* so we don't roll back to G_MAXUINT */
1409 * gst_caps_intersect:
1410 * @caps1: a #GstCaps to intersect
1411 * @caps2: a #GstCaps to intersect
1413 * Creates a new #GstCaps that contains all the formats that are common
1414 * to both @caps1 and @caps2.
1416 * Returns: the new #GstCaps
1419 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1421 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1422 guint j, k, len1, len2;
1424 GstStructure *struct1;
1425 GstStructure *struct2;
1427 GstStructure *istruct;
1429 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1430 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1432 /* caps are exactly the same pointers, just copy one caps */
1433 if (G_UNLIKELY (caps1 == caps2))
1434 return gst_caps_copy (caps1);
1436 /* empty caps on either side, return empty */
1437 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1438 return gst_caps_new_empty ();
1440 /* one of the caps is any, just copy the other caps */
1441 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1442 return gst_caps_copy (caps2);
1443 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1444 return gst_caps_copy (caps1);
1446 dest = gst_caps_new_empty ();
1448 /* run zigzag on top line then right line, this preserves the caps order
1449 * much better than a simple loop.
1451 * This algorithm zigzags over the caps structures as demonstrated in
1452 * the folowing matrix:
1460 * First we iterate over the caps1 structures (top line) intersecting
1461 * the structures diagonally down, then we iterate over the caps2
1464 len1 = caps1->structs->len;
1465 len2 = caps2->structs->len;
1466 for (i = 0; i < len1 + len2 - 1; i++) {
1467 /* caps1 index goes from 0 to caps1->structs->len-1 */
1468 j = MIN (i, len1 - 1);
1469 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1470 * up from 1 to caps2->structs->len - 1 */
1473 /* now run the diagonal line, end condition is the left or bottom
1476 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1477 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1479 istruct = gst_caps_structure_intersect (struct1, struct2);
1481 gst_caps_append_structure (dest, istruct);
1482 /* move down left */
1484 if (G_UNLIKELY (j == 0))
1485 break; /* so we don't roll back to G_MAXUINT */
1492 /* subtract operation */
1496 const GstStructure *subtract_from;
1502 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1505 SubtractionEntry *e = user_data;
1506 GValue subtraction = { 0, };
1507 const GValue *other;
1508 GstStructure *structure;
1510 other = gst_structure_id_get_value (e->subtract_from, field_id);
1514 if (!gst_value_subtract (&subtraction, other, value))
1516 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1517 g_value_unset (&subtraction);
1520 structure = gst_structure_copy (e->subtract_from);
1521 gst_structure_id_set_value (structure, field_id, &subtraction);
1522 g_value_unset (&subtraction);
1523 e->put_into = g_slist_prepend (e->put_into, structure);
1529 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1530 const GstStructure * subtrahend)
1535 e.subtract_from = minuend;
1538 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1539 gst_caps_structure_subtract_field, &e);
1545 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1546 gst_structure_free (walk->data);
1548 g_slist_free (e.put_into);
1554 * gst_caps_subtract:
1555 * @minuend: #GstCaps to substract from
1556 * @subtrahend: #GstCaps to substract
1558 * Subtracts the @subtrahend from the @minuend.
1559 * <note>This function does not work reliably if optional properties for caps
1560 * are included on one caps and omitted on the other.</note>
1562 * Returns: the resulting caps
1565 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1570 GstCaps *dest = NULL, *src;
1572 g_return_val_if_fail (minuend != NULL, NULL);
1573 g_return_val_if_fail (subtrahend != NULL, NULL);
1575 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1576 return gst_caps_new_empty ();
1578 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1579 return gst_caps_copy (minuend);
1581 /* FIXME: Do we want this here or above?
1582 The reason we need this is that there is no definition about what
1583 ANY means for specific types, so it's not possible to reduce ANY partially
1584 You can only remove everything or nothing and that is done above.
1585 Note: there's a test that checks this behaviour. */
1586 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1587 sublen = subtrahend->structs->len;
1588 g_assert (sublen > 0);
1590 src = gst_caps_copy (minuend);
1591 for (i = 0; i < sublen; i++) {
1594 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1596 gst_caps_unref (src);
1599 dest = gst_caps_new_empty ();
1600 srclen = src->structs->len;
1601 for (j = 0; j < srclen; j++) {
1602 min = gst_caps_get_structure_unchecked (src, j);
1603 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1606 if (gst_caps_structure_subtract (&list, min, sub)) {
1609 for (walk = list; walk; walk = g_slist_next (walk)) {
1610 gst_caps_append_structure_unchecked (dest,
1611 (GstStructure *) walk->data);
1613 g_slist_free (list);
1615 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1618 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1621 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1622 gst_caps_unref (src);
1627 gst_caps_unref (src);
1628 gst_caps_do_simplify (dest);
1632 /* union operation */
1635 static GstStructure *
1636 gst_caps_structure_union (const GstStructure * struct1,
1637 const GstStructure * struct2)
1641 const GstStructureField *field1;
1642 const GstStructureField *field2;
1645 /* FIXME this doesn't actually work */
1647 if (struct1->name != struct2->name)
1650 dest = gst_structure_id_empty_new (struct1->name);
1652 for (i = 0; i < struct1->fields->len; i++) {
1653 GValue dest_value = { 0 };
1655 field1 = GST_STRUCTURE_FIELD (struct1, i);
1656 field2 = gst_structure_id_get_field (struct2, field1->name);
1658 if (field2 == NULL) {
1661 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1662 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1665 ret = gst_value_compare (&field1->value, &field2->value);
1676 * @caps1: a #GstCaps to union
1677 * @caps2: a #GstCaps to union
1679 * Creates a new #GstCaps that contains all the formats that are in
1680 * either @caps1 and @caps2.
1682 * Returns: the new #GstCaps
1685 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1690 /* NULL pointers are no correct GstCaps */
1691 g_return_val_if_fail (caps1 != NULL, NULL);
1692 g_return_val_if_fail (caps2 != NULL, NULL);
1694 if (CAPS_IS_EMPTY (caps1))
1695 return gst_caps_copy (caps2);
1697 if (CAPS_IS_EMPTY (caps2))
1698 return gst_caps_copy (caps1);
1700 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1701 return gst_caps_new_any ();
1703 dest1 = gst_caps_copy (caps1);
1704 dest2 = gst_caps_copy (caps2);
1705 gst_caps_append (dest1, dest2);
1707 gst_caps_do_simplify (dest1);
1711 /* normalize/simplify operations */
1713 typedef struct _NormalizeForeach
1716 GstStructure *structure;
1721 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1723 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1727 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1728 guint len = gst_value_list_get_size (value);
1729 for (i = 1; i < len; i++) {
1730 const GValue *v = gst_value_list_get_value (value, i);
1731 GstStructure *structure = gst_structure_copy (nf->structure);
1733 gst_structure_id_set_value (structure, field_id, v);
1734 gst_caps_append_structure_unchecked (nf->caps, structure);
1737 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1738 gst_structure_id_set_value (nf->structure, field_id, &val);
1739 g_value_unset (&val);
1747 * gst_caps_normalize:
1748 * @caps: a #GstCaps to normalize
1750 * Creates a new #GstCaps that represents the same set of formats as
1751 * @caps, but contains no lists. Each list is expanded into separate
1754 * Returns: the new #GstCaps
1757 gst_caps_normalize (const GstCaps * caps)
1759 NormalizeForeach nf;
1763 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1765 newcaps = gst_caps_copy (caps);
1768 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1769 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1771 while (!gst_structure_foreach (nf.structure,
1772 gst_caps_normalize_foreach, &nf));
1779 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1782 const GstStructure *struct1 = *((const GstStructure **) one);
1783 const GstStructure *struct2 = *((const GstStructure **) two);
1785 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1786 So what's the best way? */
1787 ret = strcmp (gst_structure_get_name (struct1),
1788 gst_structure_get_name (struct2));
1792 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1799 GstStructure *compare;
1804 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1807 UnionField *u = user_data;
1808 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1812 g_value_unset (&u->value);
1815 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1818 g_value_unset (&u->value);
1822 gst_value_union (&u->value, val, value);
1827 gst_caps_structure_simplify (GstStructure ** result,
1828 const GstStructure * simplify, GstStructure * compare)
1831 UnionField field = { 0, {0,}, NULL };
1833 /* try to subtract to get a real subset */
1834 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1835 if (list == NULL) { /* no result */
1838 } else if (list->next == NULL) { /* one result */
1839 *result = list->data;
1840 g_slist_free (list);
1842 } else { /* multiple results */
1843 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1844 g_slist_free (list);
1849 /* try to union both structs */
1850 field.compare = compare;
1851 if (gst_structure_foreach ((GstStructure *) simplify,
1852 gst_caps_structure_figure_out_union, &field)) {
1853 gboolean ret = FALSE;
1855 /* now we know all of simplify's fields are the same in compare
1856 * but at most one field: field.name */
1857 if (G_IS_VALUE (&field.value)) {
1858 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1859 gst_structure_id_set_value (compare, field.name, &field.value);
1863 g_value_unset (&field.value);
1864 } else if (gst_structure_n_fields (simplify) <=
1865 gst_structure_n_fields (compare)) {
1866 /* compare is just more specific, will be optimized away later */
1867 /* FIXME: do this here? */
1868 GST_LOG ("found a case that will be optimized later.");
1870 gchar *one = gst_structure_to_string (simplify);
1871 gchar *two = gst_structure_to_string (compare);
1874 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1886 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1887 GstStructure * new, gint i)
1889 gst_structure_set_parent_refcount (old, NULL);
1890 gst_structure_free (old);
1891 gst_structure_set_parent_refcount (new, &caps->refcount);
1892 g_ptr_array_index (caps->structs, i) = new;
1896 * gst_caps_do_simplify:
1897 * @caps: a #GstCaps to simplify
1899 * Modifies the given @caps inplace into a representation that represents the
1900 * same set of formats, but in a simpler form. Component structures that are
1901 * identical are merged. Component structures that have values that can be
1902 * merged are also merged.
1904 * Returns: TRUE, if the caps could be simplified
1907 gst_caps_do_simplify (GstCaps * caps)
1909 GstStructure *simplify, *compare, *result = NULL;
1911 gboolean changed = FALSE;
1913 g_return_val_if_fail (caps != NULL, FALSE);
1914 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1916 if (gst_caps_get_size (caps) < 2)
1919 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1921 start = caps->structs->len - 1;
1922 for (i = caps->structs->len - 1; i >= 0; i--) {
1923 simplify = gst_caps_get_structure_unchecked (caps, i);
1924 if (gst_structure_get_name_id (simplify) !=
1925 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1928 for (j = start; j >= 0; j--) {
1931 compare = gst_caps_get_structure_unchecked (caps, j);
1932 if (gst_structure_get_name_id (simplify) !=
1933 gst_structure_get_name_id (compare)) {
1936 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1938 gst_caps_switch_structures (caps, simplify, result, i);
1941 gst_caps_remove_structure (caps, i);
1953 /* gst_caps_do_simplify (caps); */
1961 * @caps: (inout) (transfer full): a pointer to #GstCaps
1962 * @newcaps: a #GstCaps to replace *caps
1964 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1965 * pointed to by @caps, if applicable, then modifies @caps to point to
1966 * @newcaps. An additional ref on @newcaps is taken.
1968 * This function does not take any locks so you might want to lock
1969 * the object owning @caps pointer.
1972 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1976 g_return_if_fail (caps != NULL);
1980 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1982 if (newcaps != oldcaps) {
1984 gst_caps_ref (newcaps);
1989 gst_caps_unref (oldcaps);
1994 * gst_caps_to_string:
1997 * Converts @caps to a string representation. This string representation
1998 * can be converted back to a #GstCaps by gst_caps_from_string().
2000 * For debugging purposes its easier to do something like this:
2002 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
2004 * This prints the caps in human readble form.
2006 * Returns: (transfer full): a newly allocated string representing @caps.
2009 gst_caps_to_string (const GstCaps * caps)
2011 guint i, slen, clen;
2014 /* NOTE: This function is potentially called by the debug system,
2015 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2016 * should be careful to avoid recursion. This includes any functions
2017 * called by gst_caps_to_string. In particular, calls should
2018 * not use the GST_PTR_FORMAT extension. */
2021 return g_strdup ("NULL");
2023 if (CAPS_IS_ANY (caps)) {
2024 return g_strdup ("ANY");
2026 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2027 return g_strdup ("EMPTY");
2030 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2032 clen = caps->structs->len;
2033 for (i = 0; i < clen; i++) {
2035 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
2039 s = g_string_sized_new (slen);
2040 for (i = 0; i < clen; i++) {
2041 GstStructure *structure;
2044 /* ';' is now added by gst_structure_to_string */
2045 g_string_append_c (s, ' ');
2048 structure = gst_caps_get_structure_unchecked (caps, i);
2049 priv_gst_structure_append_to_gstring (structure, s);
2051 if (s->len && s->str[s->len - 1] == ';') {
2052 /* remove latest ';' */
2053 s->str[--s->len] = '\0';
2055 return g_string_free (s, FALSE);
2059 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2061 GstStructure *structure;
2064 if (strcmp ("ANY", string) == 0) {
2065 caps->flags = GST_CAPS_FLAGS_ANY;
2068 if (strcmp ("EMPTY", string) == 0) {
2072 structure = gst_structure_from_string (string, &s);
2073 if (structure == NULL) {
2076 gst_caps_append_structure_unchecked (caps, structure);
2080 while (g_ascii_isspace (*s))
2085 structure = gst_structure_from_string (s, &s);
2086 if (structure == NULL) {
2089 gst_caps_append_structure_unchecked (caps, structure);
2097 * gst_caps_from_string:
2098 * @string: a string to convert to #GstCaps
2100 * Converts @caps from a string representation.
2102 * Returns: (transfer full): a newly allocated #GstCaps
2105 gst_caps_from_string (const gchar * string)
2109 g_return_val_if_fail (string, FALSE);
2111 caps = gst_caps_new_empty ();
2112 if (gst_caps_from_string_inplace (caps, string)) {
2115 gst_caps_unref (caps);
2121 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2123 g_return_if_fail (G_IS_VALUE (src_value));
2124 g_return_if_fail (G_IS_VALUE (dest_value));
2125 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2126 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2127 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2129 dest_value->data[0].v_pointer =
2130 gst_caps_to_string (src_value->data[0].v_pointer);
2134 gst_caps_copy_conditional (GstCaps * src)
2137 return gst_caps_ref (src);