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 IS_WRITABLE(caps) \
79 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
81 /* same as gst_caps_is_any () */
82 #define CAPS_IS_ANY(caps) \
83 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAGS_ANY)
85 /* same as gst_caps_is_empty () */
86 #define CAPS_IS_EMPTY(caps) \
87 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
89 #define CAPS_IS_EMPTY_SIMPLE(caps) \
90 (((caps)->structs == NULL) || ((caps)->structs->len == 0))
92 /* quick way to get a caps structure at an index without doing a type or array
94 #define gst_caps_get_structure_unchecked(caps, index) \
95 ((GstStructure *)g_ptr_array_index ((caps)->structs, (index)))
96 /* quick way to append a structure without checking the args */
97 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
98 GstStructure *__s=structure; \
99 if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps))) \
100 g_ptr_array_add (caps->structs, __s); \
103 /* lock to protect multiple invocations of static caps to caps conversion */
104 G_LOCK_DEFINE_STATIC (static_caps_lock);
106 static void gst_caps_transform_to_string (const GValue * src_value,
107 GValue * dest_value);
108 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
109 const gchar * string);
111 GType _gst_caps_type = 0;
114 _gst_caps_initialize (void)
116 _gst_caps_type = gst_mini_object_register ("GstCaps");
118 g_value_register_transform_func (_gst_caps_type,
119 G_TYPE_STRING, gst_caps_transform_to_string);
123 _gst_caps_copy (const GstCaps * caps)
126 GstStructure *structure;
129 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
131 newcaps = gst_caps_new_empty ();
132 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
133 n = caps->structs->len;
135 for (i = 0; i < n; i++) {
136 structure = gst_caps_get_structure_unchecked (caps, i);
137 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
143 /* creation/deletion */
145 _gst_caps_free (GstCaps * caps)
147 GstStructure *structure;
150 /* The refcount must be 0, but since we're only called by gst_caps_unref,
151 * don't bother testing. */
152 len = caps->structs->len;
153 /* This can be used to get statistics about caps sizes */
154 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
155 for (i = 0; i < len; i++) {
156 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
157 gst_structure_set_parent_refcount (structure, NULL);
158 gst_structure_free (structure);
160 g_ptr_array_free (caps->structs, TRUE);
162 #ifdef DEBUG_REFCOUNT
163 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
165 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
169 gst_caps_init (GstCaps * caps, gsize size)
171 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
173 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
174 caps->mini_object.dispose = NULL;
175 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
177 /* the 32 has been determined by logging caps sizes in _gst_caps_free
178 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
180 * caps->structs = g_ptr_array_sized_new (32);
182 caps->structs = g_ptr_array_new ();
186 * gst_caps_new_empty:
188 * Creates a new #GstCaps that is empty. That is, the returned
189 * #GstCaps contains no media formats.
190 * Caller is responsible for unreffing the returned caps.
192 * Returns: (transfer full): the new #GstCaps
195 gst_caps_new_empty (void)
199 caps = g_slice_new (GstCaps);
201 gst_caps_init (caps, sizeof (GstCaps));
203 #ifdef DEBUG_REFCOUNT
204 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
213 * Creates a new #GstCaps that indicates that it is compatible with
216 * Returns: (transfer full): the new #GstCaps
219 gst_caps_new_any (void)
221 GstCaps *caps = gst_caps_new_empty ();
223 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAGS_ANY);
229 * gst_caps_new_simple:
230 * @media_type: the media type of the structure
231 * @fieldname: first field to set
232 * @...: additional arguments
234 * Creates a new #GstCaps that contains one #GstStructure. The
235 * structure is defined by the arguments, which have the same format
236 * as gst_structure_new().
237 * Caller is responsible for unreffing the returned caps.
239 * Returns: (transfer full): the new #GstCaps
242 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
245 GstStructure *structure;
248 caps = gst_caps_new_empty ();
250 va_start (var_args, fieldname);
251 structure = gst_structure_new_valist (media_type, fieldname, var_args);
255 gst_caps_append_structure_unchecked (caps, structure);
257 gst_caps_replace (&caps, NULL);
264 * @struct1: the first structure to add
265 * @...: additional structures to add
267 * Creates a new #GstCaps and adds all the structures listed as
268 * arguments. The list must be NULL-terminated. The structures
269 * are not copied; the returned #GstCaps owns the structures.
271 * Returns: (transfer full): the new #GstCaps
274 gst_caps_new_full (GstStructure * struct1, ...)
279 va_start (var_args, struct1);
280 caps = gst_caps_new_full_valist (struct1, var_args);
287 * gst_caps_new_full_valist:
288 * @structure: the first structure to add
289 * @var_args: additional structures to add
291 * Creates a new #GstCaps and adds all the structures listed as
292 * arguments. The list must be NULL-terminated. The structures
293 * are not copied; the returned #GstCaps owns the structures.
295 * Returns: (transfer full): the new #GstCaps
298 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
302 caps = gst_caps_new_empty ();
305 gst_caps_append_structure_unchecked (caps, structure);
306 structure = va_arg (var_args, GstStructure *);
313 * gst_caps_make_writable:
314 * @caps: (transfer full): the #GstCaps to make writable
316 * Returns a writable copy of @caps.
318 * If there is only one reference count on @caps, the caller must be the owner,
319 * and so this function will return the caps object unchanged. If on the other
320 * hand there is more than one reference on the object, a new caps object will
321 * be returned. The caller's reference on @caps will be removed, and instead the
322 * caller will own a reference to the returned object.
324 * In short, this function unrefs the caps in the argument and refs the caps
325 * that it returns. Don't access the argument after calling this function. See
326 * also: gst_caps_ref().
328 * Returns: (transfer full): the same #GstCaps object.
331 gst_caps_make_writable (GstCaps * caps)
335 g_return_val_if_fail (caps != NULL, NULL);
337 /* we are the only instance reffing this caps */
338 if (IS_WRITABLE (caps))
342 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy caps");
343 copy = _gst_caps_copy (caps);
344 gst_caps_unref (caps);
350 gst_static_caps_get_type (void)
352 static GType staticcaps_type = 0;
354 if (G_UNLIKELY (staticcaps_type == 0)) {
355 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
357 return staticcaps_type;
362 * gst_static_caps_get:
363 * @static_caps: the #GstStaticCaps to convert
365 * Converts a #GstStaticCaps to a #GstCaps.
367 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
368 * Since the core holds an additional ref to the returned caps,
369 * use gst_caps_make_writable() on the returned caps to modify it.
372 gst_static_caps_get (GstStaticCaps * static_caps)
376 g_return_val_if_fail (static_caps != NULL, NULL);
378 caps = (GstCaps *) static_caps;
380 /* refcount is 0 when we need to convert */
381 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) == 0)) {
385 G_LOCK (static_caps_lock);
386 /* check if other thread already updated */
387 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) > 0))
390 string = static_caps->string;
392 if (G_UNLIKELY (string == NULL))
395 GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);
397 /* we construct the caps on the stack, then copy over the struct into our
398 * real caps, refcount last. We do this because we must leave the refcount
399 * of the result caps to 0 so that other threads don't run away with the
400 * caps while we are constructing it. */
401 gst_caps_init (&temp, sizeof (GstCaps));
403 /* convert to string */
404 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
405 g_critical ("Could not convert static caps \"%s\"", string);
407 gst_caps_init (caps, sizeof (GstCaps));
408 /* now copy stuff over to the real caps. */
409 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS (&temp);
410 caps->structs = temp.structs;
412 GST_CAT_LOG (GST_CAT_CAPS, "created %p", static_caps);
414 G_UNLOCK (static_caps_lock);
416 /* ref the caps, makes it not writable */
424 G_UNLOCK (static_caps_lock);
425 g_warning ("static caps %p string is NULL", static_caps);
432 static GstStructure *
433 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
435 /* don't use index_fast, gst_caps_do_simplify relies on the order */
436 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
438 gst_structure_set_parent_refcount (s, NULL);
443 * gst_caps_steal_structure:
444 * @caps: the #GstCaps to retrieve from
445 * @index: Index of the structure to retrieve
447 * Retrieves the stucture with the given index from the list of structures
448 * contained in @caps. The caller becomes the owner of the returned structure.
450 * Returns: (transfer full): a pointer to the #GstStructure corresponding
456 gst_caps_steal_structure (GstCaps * caps, guint index)
458 g_return_val_if_fail (caps != NULL, NULL);
459 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
461 if (G_UNLIKELY (index >= caps->structs->len))
464 return gst_caps_remove_and_get_structure (caps, index);
469 * @caps1: the #GstCaps that will be appended to
470 * @caps2: (transfer full): the #GstCaps to append
472 * Appends the structures contained in @caps2 to @caps1. The structures in
473 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
474 * freed. If either caps is ANY, the resulting caps will be ANY.
477 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
479 GstStructure *structure;
482 g_return_if_fail (GST_IS_CAPS (caps1));
483 g_return_if_fail (GST_IS_CAPS (caps2));
484 g_return_if_fail (IS_WRITABLE (caps1));
485 g_return_if_fail (IS_WRITABLE (caps2));
487 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
488 /* FIXME: this leaks */
489 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
490 for (i = caps2->structs->len - 1; i >= 0; i--) {
491 structure = gst_caps_remove_and_get_structure (caps2, i);
492 gst_structure_free (structure);
495 for (i = caps2->structs->len; i; i--) {
496 structure = gst_caps_remove_and_get_structure (caps2, 0);
497 gst_caps_append_structure_unchecked (caps1, structure);
500 gst_caps_unref (caps2); /* guaranteed to free it */
505 * @caps1: the #GstCaps that will take the new entries
506 * @caps2: (transfer full): the #GstCaps to merge in
508 * Appends the structures contained in @caps2 to @caps1 if they are not yet
509 * expressed by @caps1. The structures in @caps2 are not copied -- they are
510 * transferred to @caps1, and then @caps2 is freed.
511 * If either caps is ANY, the resulting caps will be ANY.
516 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
518 GstStructure *structure;
521 g_return_if_fail (GST_IS_CAPS (caps1));
522 g_return_if_fail (GST_IS_CAPS (caps2));
523 g_return_if_fail (IS_WRITABLE (caps1));
524 g_return_if_fail (IS_WRITABLE (caps2));
526 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
527 for (i = caps2->structs->len - 1; i >= 0; i--) {
528 structure = gst_caps_remove_and_get_structure (caps2, i);
529 gst_structure_free (structure);
531 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
532 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
533 for (i = caps1->structs->len - 1; i >= 0; i--) {
534 structure = gst_caps_remove_and_get_structure (caps1, i);
535 gst_structure_free (structure);
538 for (i = caps2->structs->len; i; i--) {
539 structure = gst_caps_remove_and_get_structure (caps2, 0);
540 gst_caps_merge_structure (caps1, structure);
543 GstCaps *com = gst_caps_intersect (caps1, caps2);
544 GstCaps *add = gst_caps_subtract (caps2, com);
546 GST_DEBUG ("common : %d", gst_caps_get_size (com));
547 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
548 gst_caps_append (caps1, add);
549 gst_caps_unref (com);
552 gst_caps_unref (caps2); /* guaranteed to free it */
556 * gst_caps_append_structure:
557 * @caps: the #GstCaps that will be appended to
558 * @structure: (transfer full): the #GstStructure to append
560 * Appends @structure to @caps. The structure is not copied; @caps
561 * becomes the owner of @structure.
564 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
566 g_return_if_fail (GST_IS_CAPS (caps));
567 g_return_if_fail (IS_WRITABLE (caps));
569 if (G_LIKELY (structure)) {
570 gst_caps_append_structure_unchecked (caps, structure);
575 * gst_caps_remove_structure:
576 * @caps: the #GstCaps to remove from
577 * @idx: Index of the structure to remove
579 * removes the stucture with the given index from the list of structures
580 * contained in @caps.
583 gst_caps_remove_structure (GstCaps * caps, guint idx)
585 GstStructure *structure;
587 g_return_if_fail (caps != NULL);
588 g_return_if_fail (idx <= gst_caps_get_size (caps));
589 g_return_if_fail (IS_WRITABLE (caps));
591 structure = gst_caps_remove_and_get_structure (caps, idx);
592 gst_structure_free (structure);
596 * gst_caps_merge_structure:
597 * @caps: the #GstCaps that will the the new structure
598 * @structure: (transfer full): the #GstStructure to merge
600 * Appends @structure to @caps if its not already expressed by @caps. The
601 * structure is not copied; @caps becomes the owner of @structure.
604 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
606 g_return_if_fail (GST_IS_CAPS (caps));
607 g_return_if_fail (IS_WRITABLE (caps));
609 if (G_LIKELY (structure)) {
610 GstStructure *structure1;
612 gboolean unique = TRUE;
614 /* check each structure */
615 for (i = caps->structs->len - 1; i >= 0; i--) {
616 structure1 = gst_caps_get_structure_unchecked (caps, i);
617 /* if structure is a subset of structure1, then skip it */
618 if (gst_structure_is_subset (structure, structure1)) {
624 gst_caps_append_structure_unchecked (caps, structure);
626 gst_structure_free (structure);
635 * Gets the number of structures contained in @caps.
637 * Returns: the number of structures that @caps contains
640 gst_caps_get_size (const GstCaps * caps)
642 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
644 return caps->structs->len;
648 * gst_caps_get_structure:
650 * @index: the index of the structure
652 * Finds the structure in @caps that has the index @index, and
655 * WARNING: This function takes a const GstCaps *, but returns a
656 * non-const GstStructure *. This is for programming convenience --
657 * the caller should be aware that structures inside a constant
658 * #GstCaps should not be modified. However, if you know the caps
659 * are writable, either because you have just copied them or made
660 * them writable with gst_caps_make_writable(), you may modify the
661 * structure returned in the usual way, e.g. with functions like
662 * gst_structure_set().
664 * You do not need to free or unref the structure returned, it
665 * belongs to the #GstCaps.
667 * Returns: (transfer none): a pointer to the #GstStructure corresponding
671 gst_caps_get_structure (const GstCaps * caps, guint index)
673 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
674 g_return_val_if_fail (index < caps->structs->len, NULL);
676 return gst_caps_get_structure_unchecked (caps, index);
681 * @caps: the #GstCaps to copy
682 * @nth: the nth structure to copy
684 * Creates a new #GstCaps and appends a copy of the nth structure
685 * contained in @caps.
687 * Returns: (transfer full): the new #GstCaps
690 gst_caps_copy_nth (const GstCaps * caps, guint nth)
693 GstStructure *structure;
695 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
697 newcaps = gst_caps_new_empty ();
698 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
700 if (G_LIKELY (caps->structs->len > nth)) {
701 structure = gst_caps_get_structure_unchecked (caps, nth);
702 gst_caps_append_structure_unchecked (newcaps,
703 gst_structure_copy (structure));
711 * @caps: the #GstCaps to truncate
713 * Destructively discard all but the first structure from @caps. Useful when
714 * fixating. @caps must be writable.
717 gst_caps_truncate (GstCaps * caps)
721 g_return_if_fail (GST_IS_CAPS (caps));
722 g_return_if_fail (IS_WRITABLE (caps));
724 i = caps->structs->len - 1;
727 gst_caps_remove_structure (caps, i--);
731 * gst_caps_set_value:
732 * @caps: a writable caps
733 * @field: name of the field to set
734 * @value: value to set the field to
736 * Sets the given @field on all structures of @caps to the given @value.
737 * This is a convenience function for calling gst_structure_set_value() on
738 * all structures of @caps.
743 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
747 g_return_if_fail (GST_IS_CAPS (caps));
748 g_return_if_fail (IS_WRITABLE (caps));
749 g_return_if_fail (field != NULL);
750 g_return_if_fail (G_IS_VALUE (value));
752 len = caps->structs->len;
753 for (i = 0; i < len; i++) {
754 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
755 gst_structure_set_value (structure, field, value);
760 * gst_caps_set_simple_valist:
761 * @caps: the #GstCaps to set
762 * @field: first field to set
763 * @varargs: additional parameters
765 * Sets fields in a #GstCaps. The arguments must be passed in the same
766 * manner as gst_structure_set(), and be NULL-terminated.
767 * <note>Prior to GStreamer version 0.10.26, this function failed when
768 * @caps was not simple. If your code needs to work with those versions
769 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
770 * is %TRUE for @caps.</note>
773 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
775 GValue value = { 0, };
777 g_return_if_fail (GST_IS_CAPS (caps));
778 g_return_if_fail (IS_WRITABLE (caps));
784 type = va_arg (varargs, GType);
786 if (G_UNLIKELY (type == G_TYPE_DATE)) {
787 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
788 type = GST_TYPE_DATE;
790 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
791 if (G_UNLIKELY (err)) {
792 g_critical ("%s", err);
796 gst_caps_set_value (caps, field, &value);
798 g_value_unset (&value);
800 field = va_arg (varargs, const gchar *);
805 * gst_caps_set_simple:
806 * @caps: the #GstCaps to set
807 * @field: first field to set
808 * @...: additional parameters
810 * Sets fields in a #GstCaps. The arguments must be passed in the same
811 * manner as gst_structure_set(), and be NULL-terminated.
812 * <note>Prior to GStreamer version 0.10.26, this function failed when
813 * @caps was not simple. If your code needs to work with those versions
814 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
815 * is %TRUE for @caps.</note>
818 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
822 g_return_if_fail (GST_IS_CAPS (caps));
823 g_return_if_fail (IS_WRITABLE (caps));
825 va_start (var_args, field);
826 gst_caps_set_simple_valist (caps, field, var_args);
834 * @caps: the #GstCaps to test
836 * Determines if @caps represents any media format.
838 * Returns: TRUE if @caps represents any format.
841 gst_caps_is_any (const GstCaps * caps)
843 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
845 return (CAPS_IS_ANY (caps));
850 * @caps: the #GstCaps to test
852 * Determines if @caps represents no media formats.
854 * Returns: TRUE if @caps represents no formats.
857 gst_caps_is_empty (const GstCaps * caps)
859 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
861 if (CAPS_IS_ANY (caps))
864 return CAPS_IS_EMPTY_SIMPLE (caps);
868 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
871 return gst_value_is_fixed (value);
876 * @caps: the #GstCaps to test
878 * Fixed #GstCaps describe exactly one format, that is, they have exactly
879 * one structure, and each field in the structure describes a fixed type.
880 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
882 * Returns: TRUE if @caps is fixed
885 gst_caps_is_fixed (const GstCaps * caps)
887 GstStructure *structure;
889 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
891 if (caps->structs->len != 1)
894 structure = gst_caps_get_structure_unchecked (caps, 0);
896 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
900 * gst_caps_is_equal_fixed:
901 * @caps1: the #GstCaps to test
902 * @caps2: the #GstCaps to test
904 * Tests if two #GstCaps are equal. This function only works on fixed
907 * Returns: TRUE if the arguments represent the same format
910 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
912 GstStructure *struct1, *struct2;
914 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
915 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
917 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
918 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
920 return gst_structure_is_equal (struct1, struct2);
924 * gst_caps_is_always_compatible:
925 * @caps1: the #GstCaps to test
926 * @caps2: the #GstCaps to test
928 * A given #GstCaps structure is always compatible with another if
929 * every media format that is in the first is also contained in the
930 * second. That is, @caps1 is a subset of @caps2.
932 * Returns: TRUE if @caps1 is a subset of @caps2.
935 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
937 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
938 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
940 return gst_caps_is_subset (caps1, caps2);
944 * gst_caps_is_subset:
945 * @subset: a #GstCaps
946 * @superset: a potentially greater #GstCaps
948 * Checks if all caps represented by @subset are also represented by @superset.
949 * <note>This function does not work reliably if optional properties for caps
950 * are included on one caps and omitted on the other.</note>
952 * Returns: %TRUE if @subset is a subset of @superset
955 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
957 GstStructure *s1, *s2;
961 g_return_val_if_fail (subset != NULL, FALSE);
962 g_return_val_if_fail (superset != NULL, FALSE);
964 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
966 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
969 for (i = subset->structs->len - 1; i >= 0; i--) {
970 for (j = superset->structs->len - 1; j >= 0; j--) {
971 s1 = gst_caps_get_structure_unchecked (subset, i);
972 s2 = gst_caps_get_structure_unchecked (superset, j);
973 if (gst_structure_is_subset (s1, s2)) {
974 /* If we found a superset, continue with the next
975 * subset structure */
979 /* If we found no superset for this subset structure
980 * we return FALSE immediately */
991 * gst_caps_is_subset_structure:
993 * @structure: a potential #GstStructure subset of @caps
995 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
996 * for more information.
998 * Returns: %TRUE if @structure is a subset of @caps
1003 gst_caps_is_subset_structure (const GstCaps * caps,
1004 const GstStructure * structure)
1009 g_return_val_if_fail (caps != NULL, FALSE);
1010 g_return_val_if_fail (structure != NULL, FALSE);
1012 if (CAPS_IS_ANY (caps))
1014 if (CAPS_IS_EMPTY (caps))
1017 for (i = caps->structs->len - 1; i >= 0; i--) {
1018 s = gst_caps_get_structure_unchecked (caps, i);
1019 if (gst_structure_is_subset (structure, s)) {
1020 /* If we found a superset return TRUE */
1029 * gst_caps_is_equal:
1030 * @caps1: a #GstCaps
1031 * @caps2: another #GstCaps
1033 * Checks if the given caps represent the same set of caps.
1034 * <note>This function does not work reliably if optional properties for caps
1035 * are included on one caps and omitted on the other.</note>
1037 * This function deals correctly with passing NULL for any of the caps.
1039 * Returns: TRUE if both caps are equal.
1042 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1044 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1045 * So there should be an assertion that caps1 and caps2 != NULL */
1047 /* NULL <-> NULL is allowed here */
1048 if (G_UNLIKELY (caps1 == caps2))
1051 /* one of them NULL => they are different (can't be both NULL because
1052 * we checked that above) */
1053 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1056 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1057 return gst_caps_is_equal_fixed (caps1, caps2);
1059 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1062 /* intersect operation */
1065 * gst_caps_can_intersect:
1066 * @caps1: a #GstCaps to intersect
1067 * @caps2: a #GstCaps to intersect
1069 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1072 * Returns: %TRUE if intersection would be not empty
1077 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1079 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1080 guint j, k, len1, len2;
1081 GstStructure *struct1;
1082 GstStructure *struct2;
1084 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1085 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1087 /* caps are exactly the same pointers */
1088 if (G_UNLIKELY (caps1 == caps2))
1091 /* empty caps on either side, return empty */
1092 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1095 /* one of the caps is any */
1096 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1099 /* run zigzag on top line then right line, this preserves the caps order
1100 * much better than a simple loop.
1102 * This algorithm zigzags over the caps structures as demonstrated in
1103 * the folowing matrix:
1106 * +------------- total distance: +-------------
1107 * | 1 2 4 7 0 | 0 1 2 3
1108 * caps2 | 3 5 8 10 1 | 1 2 3 4
1109 * | 6 9 11 12 2 | 2 3 4 5
1111 * First we iterate over the caps1 structures (top line) intersecting
1112 * the structures diagonally down, then we iterate over the caps2
1113 * structures. The result is that the intersections are ordered based on the
1114 * sum of the indexes in the list.
1116 len1 = caps1->structs->len;
1117 len2 = caps2->structs->len;
1118 for (i = 0; i < len1 + len2 - 1; i++) {
1119 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1120 j = MIN (i, len1 - 1);
1121 /* subset index stays 0 until i reaches superset->structs->len, then it
1122 * counts up from 1 to subset->structs->len - 1 */
1125 /* now run the diagonal line, end condition is the left or bottom
1128 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1129 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1131 if (gst_structure_can_intersect (struct1, struct2)) {
1134 /* move down left */
1136 if (G_UNLIKELY (j == 0))
1137 break; /* so we don't roll back to G_MAXUINT */
1145 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1147 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1148 guint j, k, len1, len2;
1150 GstStructure *struct1;
1151 GstStructure *struct2;
1153 GstStructure *istruct;
1155 /* caps are exactly the same pointers, just copy one caps */
1156 if (G_UNLIKELY (caps1 == caps2))
1157 return _gst_caps_copy (caps1);
1159 /* empty caps on either side, return empty */
1160 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1161 return gst_caps_new_empty ();
1163 /* one of the caps is any, just copy the other caps */
1164 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1165 return _gst_caps_copy (caps2);
1166 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1167 return _gst_caps_copy (caps1);
1169 dest = gst_caps_new_empty ();
1171 /* run zigzag on top line then right line, this preserves the caps order
1172 * much better than a simple loop.
1174 * This algorithm zigzags over the caps structures as demonstrated in
1175 * the folowing matrix:
1183 * First we iterate over the caps1 structures (top line) intersecting
1184 * the structures diagonally down, then we iterate over the caps2
1187 len1 = caps1->structs->len;
1188 len2 = caps2->structs->len;
1189 for (i = 0; i < len1 + len2 - 1; i++) {
1190 /* caps1 index goes from 0 to caps1->structs->len-1 */
1191 j = MIN (i, len1 - 1);
1192 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1193 * up from 1 to caps2->structs->len - 1 */
1196 /* now run the diagonal line, end condition is the left or bottom
1199 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1200 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1202 istruct = gst_structure_intersect (struct1, struct2);
1204 gst_caps_merge_structure (dest, istruct);
1205 /* move down left */
1207 if (G_UNLIKELY (j == 0))
1208 break; /* so we don't roll back to G_MAXUINT */
1216 * gst_caps_intersect_first:
1217 * @caps1: a #GstCaps to intersect
1218 * @caps2: a #GstCaps to intersect
1220 * Creates a new #GstCaps that contains all the formats that are common
1221 * to both @caps1 and @caps2.
1223 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1224 * fashion as @caps1.
1226 * Returns: the new #GstCaps
1229 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1231 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1232 guint j, len1, len2;
1234 GstStructure *struct1;
1235 GstStructure *struct2;
1237 GstStructure *istruct;
1239 /* caps are exactly the same pointers, just copy one caps */
1240 if (G_UNLIKELY (caps1 == caps2))
1241 return gst_caps_copy (caps1);
1243 /* empty caps on either side, return empty */
1244 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1245 return gst_caps_new_empty ();
1247 /* one of the caps is any, just copy the other caps */
1248 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1249 return gst_caps_copy (caps2);
1250 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1251 return gst_caps_copy (caps1);
1253 dest = gst_caps_new_empty ();
1255 len1 = caps1->structs->len;
1256 len2 = caps2->structs->len;
1257 for (i = 0; i < len1; i++) {
1258 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1259 for (j = 0; j < len2; j++) {
1260 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1261 istruct = gst_structure_intersect (struct1, struct2);
1263 gst_caps_merge_structure (dest, istruct);
1271 * gst_caps_intersect_full:
1272 * @caps1: a #GstCaps to intersect
1273 * @caps2: a #GstCaps to intersect
1274 * @mode: The intersection algorithm/mode to use
1276 * Creates a new #GstCaps that contains all the formats that are common
1277 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1280 * Returns: the new #GstCaps
1284 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1285 GstCapsIntersectMode mode)
1287 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1288 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1291 case GST_CAPS_INTERSECT_FIRST:
1292 return gst_caps_intersect_first (caps1, caps2);
1294 g_warning ("Unknown caps intersect mode: %d", mode);
1296 case GST_CAPS_INTERSECT_ZIG_ZAG:
1297 return gst_caps_intersect_zig_zag (caps1, caps2);
1302 * gst_caps_intersect:
1303 * @caps1: a #GstCaps to intersect
1304 * @caps2: a #GstCaps to intersect
1306 * Creates a new #GstCaps that contains all the formats that are common
1307 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1309 * Returns: the new #GstCaps
1312 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1314 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1318 /* subtract operation */
1322 const GstStructure *subtract_from;
1328 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1331 SubtractionEntry *e = user_data;
1332 GValue subtraction = { 0, };
1333 const GValue *other;
1334 GstStructure *structure;
1336 other = gst_structure_id_get_value (e->subtract_from, field_id);
1340 if (!gst_value_subtract (&subtraction, other, value))
1342 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1343 g_value_unset (&subtraction);
1346 structure = gst_structure_copy (e->subtract_from);
1347 gst_structure_id_set_value (structure, field_id, &subtraction);
1348 g_value_unset (&subtraction);
1349 e->put_into = g_slist_prepend (e->put_into, structure);
1355 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1356 const GstStructure * subtrahend)
1361 e.subtract_from = minuend;
1364 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1365 gst_caps_structure_subtract_field, &e);
1371 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1372 gst_structure_free (walk->data);
1374 g_slist_free (e.put_into);
1380 * gst_caps_subtract:
1381 * @minuend: #GstCaps to substract from
1382 * @subtrahend: #GstCaps to substract
1384 * Subtracts the @subtrahend from the @minuend.
1385 * <note>This function does not work reliably if optional properties for caps
1386 * are included on one caps and omitted on the other.</note>
1388 * Returns: the resulting caps
1391 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1396 GstCaps *dest = NULL, *src;
1398 g_return_val_if_fail (minuend != NULL, NULL);
1399 g_return_val_if_fail (subtrahend != NULL, NULL);
1401 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1402 return gst_caps_new_empty ();
1404 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1405 return _gst_caps_copy (minuend);
1407 /* FIXME: Do we want this here or above?
1408 The reason we need this is that there is no definition about what
1409 ANY means for specific types, so it's not possible to reduce ANY partially
1410 You can only remove everything or nothing and that is done above.
1411 Note: there's a test that checks this behaviour. */
1412 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1413 sublen = subtrahend->structs->len;
1414 g_assert (sublen > 0);
1416 src = _gst_caps_copy (minuend);
1417 for (i = 0; i < sublen; i++) {
1420 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1422 gst_caps_unref (src);
1425 dest = gst_caps_new_empty ();
1426 srclen = src->structs->len;
1427 for (j = 0; j < srclen; j++) {
1428 min = gst_caps_get_structure_unchecked (src, j);
1429 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1432 if (gst_caps_structure_subtract (&list, min, sub)) {
1435 for (walk = list; walk; walk = g_slist_next (walk)) {
1436 gst_caps_append_structure_unchecked (dest,
1437 (GstStructure *) walk->data);
1439 g_slist_free (list);
1441 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1444 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1447 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1448 gst_caps_unref (src);
1453 gst_caps_unref (src);
1454 gst_caps_do_simplify (dest);
1458 /* union operation */
1461 static GstStructure *
1462 gst_caps_structure_union (const GstStructure * struct1,
1463 const GstStructure * struct2)
1467 const GstStructureField *field1;
1468 const GstStructureField *field2;
1471 /* FIXME this doesn't actually work */
1473 if (struct1->name != struct2->name)
1476 dest = gst_structure_id_empty_new (struct1->name);
1478 for (i = 0; i < struct1->fields->len; i++) {
1479 GValue dest_value = { 0 };
1481 field1 = GST_STRUCTURE_FIELD (struct1, i);
1482 field2 = gst_structure_id_get_field (struct2, field1->name);
1484 if (field2 == NULL) {
1487 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1488 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1491 ret = gst_value_compare (&field1->value, &field2->value);
1502 * @caps1: a #GstCaps to union
1503 * @caps2: a #GstCaps to union
1505 * Creates a new #GstCaps that contains all the formats that are in
1506 * either @caps1 and @caps2.
1508 * Returns: the new #GstCaps
1511 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1516 /* NULL pointers are no correct GstCaps */
1517 g_return_val_if_fail (caps1 != NULL, NULL);
1518 g_return_val_if_fail (caps2 != NULL, NULL);
1520 if (CAPS_IS_EMPTY (caps1))
1521 return _gst_caps_copy (caps2);
1523 if (CAPS_IS_EMPTY (caps2))
1524 return _gst_caps_copy (caps1);
1526 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1527 return gst_caps_new_any ();
1529 dest1 = _gst_caps_copy (caps1);
1530 dest2 = _gst_caps_copy (caps2);
1531 gst_caps_append (dest1, dest2);
1533 gst_caps_do_simplify (dest1);
1537 /* normalize/simplify operations */
1539 typedef struct _NormalizeForeach
1542 GstStructure *structure;
1547 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1549 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1553 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1554 guint len = gst_value_list_get_size (value);
1555 for (i = 1; i < len; i++) {
1556 const GValue *v = gst_value_list_get_value (value, i);
1557 GstStructure *structure = gst_structure_copy (nf->structure);
1559 gst_structure_id_set_value (structure, field_id, v);
1560 gst_caps_append_structure_unchecked (nf->caps, structure);
1563 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1564 gst_structure_id_set_value (nf->structure, field_id, &val);
1565 g_value_unset (&val);
1573 * gst_caps_normalize:
1574 * @caps: a #GstCaps to normalize
1576 * Creates a new #GstCaps that represents the same set of formats as
1577 * @caps, but contains no lists. Each list is expanded into separate
1580 * Returns: the new #GstCaps
1583 gst_caps_normalize (const GstCaps * caps)
1585 NormalizeForeach nf;
1589 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1591 newcaps = _gst_caps_copy (caps);
1594 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1595 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1597 while (!gst_structure_foreach (nf.structure,
1598 gst_caps_normalize_foreach, &nf));
1605 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1608 const GstStructure *struct1 = *((const GstStructure **) one);
1609 const GstStructure *struct2 = *((const GstStructure **) two);
1611 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1612 So what's the best way? */
1613 ret = strcmp (gst_structure_get_name (struct1),
1614 gst_structure_get_name (struct2));
1618 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1625 GstStructure *compare;
1630 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1633 UnionField *u = user_data;
1634 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1638 g_value_unset (&u->value);
1641 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1644 g_value_unset (&u->value);
1648 gst_value_union (&u->value, val, value);
1653 gst_caps_structure_simplify (GstStructure ** result,
1654 const GstStructure * simplify, GstStructure * compare)
1657 UnionField field = { 0, {0,}, NULL };
1659 /* try to subtract to get a real subset */
1660 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1661 if (list == NULL) { /* no result */
1664 } else if (list->next == NULL) { /* one result */
1665 *result = list->data;
1666 g_slist_free (list);
1668 } else { /* multiple results */
1669 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1670 g_slist_free (list);
1675 /* try to union both structs */
1676 field.compare = compare;
1677 if (gst_structure_foreach ((GstStructure *) simplify,
1678 gst_caps_structure_figure_out_union, &field)) {
1679 gboolean ret = FALSE;
1681 /* now we know all of simplify's fields are the same in compare
1682 * but at most one field: field.name */
1683 if (G_IS_VALUE (&field.value)) {
1684 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1685 gst_structure_id_set_value (compare, field.name, &field.value);
1689 g_value_unset (&field.value);
1690 } else if (gst_structure_n_fields (simplify) <=
1691 gst_structure_n_fields (compare)) {
1692 /* compare is just more specific, will be optimized away later */
1693 /* FIXME: do this here? */
1694 GST_LOG ("found a case that will be optimized later.");
1696 gchar *one = gst_structure_to_string (simplify);
1697 gchar *two = gst_structure_to_string (compare);
1700 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1712 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1713 GstStructure * new, gint i)
1715 gst_structure_set_parent_refcount (old, NULL);
1716 gst_structure_free (old);
1717 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1718 g_ptr_array_index (caps->structs, i) = new;
1722 * gst_caps_do_simplify:
1723 * @caps: a #GstCaps to simplify
1725 * Modifies the given @caps inplace into a representation that represents the
1726 * same set of formats, but in a simpler form. Component structures that are
1727 * identical are merged. Component structures that have values that can be
1728 * merged are also merged.
1730 * Returns: TRUE, if the caps could be simplified
1733 gst_caps_do_simplify (GstCaps * caps)
1735 GstStructure *simplify, *compare, *result = NULL;
1737 gboolean changed = FALSE;
1739 g_return_val_if_fail (caps != NULL, FALSE);
1740 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1742 if (gst_caps_get_size (caps) < 2)
1745 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1747 start = caps->structs->len - 1;
1748 for (i = caps->structs->len - 1; i >= 0; i--) {
1749 simplify = gst_caps_get_structure_unchecked (caps, i);
1750 if (gst_structure_get_name_id (simplify) !=
1751 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1754 for (j = start; j >= 0; j--) {
1757 compare = gst_caps_get_structure_unchecked (caps, j);
1758 if (gst_structure_get_name_id (simplify) !=
1759 gst_structure_get_name_id (compare)) {
1762 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1764 gst_caps_switch_structures (caps, simplify, result, i);
1767 gst_caps_remove_structure (caps, i);
1779 /* gst_caps_do_simplify (caps); */
1787 * @caps: (inout) (transfer full): a pointer to #GstCaps
1788 * @newcaps: a #GstCaps to replace *caps
1790 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1791 * pointed to by @caps, if applicable, then modifies @caps to point to
1792 * @newcaps. An additional ref on @newcaps is taken.
1794 * This function does not take any locks so you might want to lock
1795 * the object owning @caps pointer.
1798 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1802 g_return_if_fail (caps != NULL);
1806 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1808 if (newcaps != oldcaps) {
1810 gst_caps_ref (newcaps);
1815 gst_caps_unref (oldcaps);
1820 * gst_caps_to_string:
1823 * Converts @caps to a string representation. This string representation
1824 * can be converted back to a #GstCaps by gst_caps_from_string().
1826 * For debugging purposes its easier to do something like this:
1828 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1830 * This prints the caps in human readble form.
1832 * Returns: (transfer full): a newly allocated string representing @caps.
1835 gst_caps_to_string (const GstCaps * caps)
1837 guint i, slen, clen;
1840 /* NOTE: This function is potentially called by the debug system,
1841 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1842 * should be careful to avoid recursion. This includes any functions
1843 * called by gst_caps_to_string. In particular, calls should
1844 * not use the GST_PTR_FORMAT extension. */
1847 return g_strdup ("NULL");
1849 if (CAPS_IS_ANY (caps)) {
1850 return g_strdup ("ANY");
1852 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1853 return g_strdup ("EMPTY");
1856 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1858 clen = caps->structs->len;
1859 for (i = 0; i < clen; i++) {
1861 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1865 s = g_string_sized_new (slen);
1866 for (i = 0; i < clen; i++) {
1867 GstStructure *structure;
1870 /* ';' is now added by gst_structure_to_string */
1871 g_string_append_c (s, ' ');
1874 structure = gst_caps_get_structure_unchecked (caps, i);
1875 priv_gst_structure_append_to_gstring (structure, s);
1877 if (s->len && s->str[s->len - 1] == ';') {
1878 /* remove latest ';' */
1879 s->str[--s->len] = '\0';
1881 return g_string_free (s, FALSE);
1885 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1887 GstStructure *structure;
1890 if (strcmp ("ANY", string) == 0) {
1891 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
1894 if (strcmp ("EMPTY", string) == 0) {
1898 structure = gst_structure_from_string (string, &s);
1899 if (structure == NULL) {
1902 gst_caps_append_structure_unchecked (caps, structure);
1906 while (g_ascii_isspace (*s))
1911 structure = gst_structure_from_string (s, &s);
1912 if (structure == NULL) {
1915 gst_caps_append_structure_unchecked (caps, structure);
1923 * gst_caps_from_string:
1924 * @string: a string to convert to #GstCaps
1926 * Converts @caps from a string representation.
1928 * Returns: (transfer full): a newly allocated #GstCaps
1931 gst_caps_from_string (const gchar * string)
1935 g_return_val_if_fail (string, FALSE);
1937 caps = gst_caps_new_empty ();
1938 if (gst_caps_from_string_inplace (caps, string)) {
1941 gst_caps_unref (caps);
1947 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1949 g_return_if_fail (G_IS_VALUE (src_value));
1950 g_return_if_fail (G_IS_VALUE (dest_value));
1951 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1952 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1953 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1955 dest_value->data[0].v_pointer =
1956 gst_caps_to_string (src_value->data[0].v_pointer);