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",
47 * "format", G_TYPE_STRING, "I420",
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 typedef struct _GstCapsImpl
85 #define GST_CAPS_ARRAY(c) (((GstCapsImpl *)(c))->array)
87 #define GST_CAPS_LEN(c) (GST_CAPS_ARRAY(c)->len)
89 #define IS_WRITABLE(caps) \
90 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
92 /* same as gst_caps_is_any () */
93 #define CAPS_IS_ANY(caps) \
94 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY)
96 /* same as gst_caps_is_empty () */
97 #define CAPS_IS_EMPTY(caps) \
98 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
100 #define CAPS_IS_EMPTY_SIMPLE(caps) \
101 ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
103 /* quick way to get a caps structure at an index without doing a type or array
105 #define gst_caps_get_structure_unchecked(caps, index) \
106 ((GstStructure *)g_ptr_array_index (GST_CAPS_ARRAY (caps), (index)))
107 /* quick way to append a structure without checking the args */
108 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
109 GstStructure *__s=structure; \
110 if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps))) \
111 g_ptr_array_add (GST_CAPS_ARRAY (caps), __s); \
114 /* lock to protect multiple invocations of static caps to caps conversion */
115 G_LOCK_DEFINE_STATIC (static_caps_lock);
117 static void gst_caps_transform_to_string (const GValue * src_value,
118 GValue * dest_value);
119 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
120 const gchar * string);
122 GType _gst_caps_type = 0;
123 GstCaps *_gst_caps_any;
124 GstCaps *_gst_caps_none;
126 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
129 _priv_gst_caps_initialize (void)
131 _gst_caps_type = gst_caps_get_type ();
133 _gst_caps_any = gst_caps_new_any ();
134 _gst_caps_none = gst_caps_new_empty ();
136 g_value_register_transform_func (_gst_caps_type,
137 G_TYPE_STRING, gst_caps_transform_to_string);
141 _gst_caps_copy (const GstCaps * caps)
144 GstStructure *structure;
147 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
149 newcaps = gst_caps_new_empty ();
150 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
151 n = GST_CAPS_LEN (caps);
153 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, caps, "doing copy %p -> %p",
156 for (i = 0; i < n; i++) {
157 structure = gst_caps_get_structure_unchecked (caps, i);
158 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
164 /* creation/deletion */
166 _gst_caps_free (GstCaps * caps)
168 GstStructure *structure;
171 /* The refcount must be 0, but since we're only called by gst_caps_unref,
172 * don't bother testing. */
173 len = GST_CAPS_LEN (caps);
174 /* This can be used to get statistics about caps sizes */
175 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
176 for (i = 0; i < len; i++) {
177 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
178 gst_structure_set_parent_refcount (structure, NULL);
179 gst_structure_free (structure);
181 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
183 #ifdef DEBUG_REFCOUNT
184 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
186 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
190 gst_caps_init (GstCaps * caps, gsize size)
192 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
194 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
195 caps->mini_object.dispose = NULL;
196 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
198 /* the 32 has been determined by logging caps sizes in _gst_caps_free
199 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
201 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
203 GST_CAPS_ARRAY (caps) = g_ptr_array_new ();
207 * gst_caps_new_empty:
209 * Creates a new #GstCaps that is empty. That is, the returned
210 * #GstCaps contains no media formats.
211 * Caller is responsible for unreffing the returned caps.
213 * Returns: (transfer full): the new #GstCaps
216 gst_caps_new_empty (void)
220 caps = (GstCaps *) g_slice_new (GstCapsImpl);
222 gst_caps_init (caps, sizeof (GstCapsImpl));
224 #ifdef DEBUG_REFCOUNT
225 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
234 * Creates a new #GstCaps that indicates that it is compatible with
237 * Returns: (transfer full): the new #GstCaps
240 gst_caps_new_any (void)
242 GstCaps *caps = gst_caps_new_empty ();
244 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
250 * gst_caps_new_empty_simple:
251 * @media_type: the media type of the structure
253 * Creates a new #GstCaps that contains one #GstStructure with name
255 * Caller is responsible for unreffing the returned caps.
257 * Returns: (transfer full): the new #GstCaps
260 gst_caps_new_empty_simple (const char *media_type)
263 GstStructure *structure;
265 caps = gst_caps_new_empty ();
266 structure = gst_structure_new_empty (media_type);
268 gst_caps_append_structure_unchecked (caps, structure);
274 * gst_caps_new_simple:
275 * @media_type: the media type of the structure
276 * @fieldname: first field to set
277 * @...: additional arguments
279 * Creates a new #GstCaps that contains one #GstStructure. The
280 * structure is defined by the arguments, which have the same format
281 * as gst_structure_new().
282 * Caller is responsible for unreffing the returned caps.
284 * Returns: (transfer full): the new #GstCaps
287 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
290 GstStructure *structure;
293 caps = gst_caps_new_empty ();
295 va_start (var_args, fieldname);
296 structure = gst_structure_new_valist (media_type, fieldname, var_args);
300 gst_caps_append_structure_unchecked (caps, structure);
302 gst_caps_replace (&caps, NULL);
309 * @struct1: the first structure to add
310 * @...: additional structures to add
312 * Creates a new #GstCaps and adds all the structures listed as
313 * arguments. The list must be NULL-terminated. The structures
314 * are not copied; the returned #GstCaps owns the structures.
316 * Returns: (transfer full): the new #GstCaps
319 gst_caps_new_full (GstStructure * struct1, ...)
324 va_start (var_args, struct1);
325 caps = gst_caps_new_full_valist (struct1, var_args);
332 * gst_caps_new_full_valist:
333 * @structure: the first structure to add
334 * @var_args: additional structures to add
336 * Creates a new #GstCaps and adds all the structures listed as
337 * arguments. The list must be NULL-terminated. The structures
338 * are not copied; the returned #GstCaps owns the structures.
340 * Returns: (transfer full): the new #GstCaps
343 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
347 caps = gst_caps_new_empty ();
350 gst_caps_append_structure_unchecked (caps, structure);
351 structure = va_arg (var_args, GstStructure *);
357 G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
360 * gst_static_caps_get:
361 * @static_caps: the #GstStaticCaps to convert
363 * Converts a #GstStaticCaps to a #GstCaps.
365 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
366 * Since the core holds an additional ref to the returned caps,
367 * use gst_caps_make_writable() on the returned caps to modify it.
370 gst_static_caps_get (GstStaticCaps * static_caps)
374 g_return_val_if_fail (static_caps != NULL, NULL);
376 caps = &static_caps->caps;
378 /* refcount is 0 when we need to convert */
379 if (G_UNLIKELY (*caps == NULL)) {
382 G_LOCK (static_caps_lock);
383 /* check if other thread already updated */
384 if (G_UNLIKELY (*caps != NULL))
387 string = static_caps->string;
389 if (G_UNLIKELY (string == NULL))
392 *caps = gst_caps_from_string (string);
394 /* convert to string */
395 if (G_UNLIKELY (*caps == NULL))
396 g_critical ("Could not convert static caps \"%s\"", string);
398 GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
401 G_UNLOCK (static_caps_lock);
403 /* ref the caps, makes it not writable */
404 if (G_LIKELY (*caps != NULL))
405 gst_caps_ref (*caps);
412 G_UNLOCK (static_caps_lock);
413 g_warning ("static caps %p string is NULL", static_caps);
419 * gst_static_caps_cleanup:
420 * @static_caps: the #GstStaticCaps to clean
422 * Clean up the cached caps contained in @static_caps.
425 gst_static_caps_cleanup (GstStaticCaps * static_caps)
427 G_LOCK (static_caps_lock);
428 gst_caps_replace (&static_caps->caps, NULL);
429 G_UNLOCK (static_caps_lock);
434 static GstStructure *
435 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
437 /* don't use index_fast, gst_caps_do_simplify relies on the order */
438 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
440 gst_structure_set_parent_refcount (s, NULL);
445 * gst_caps_steal_structure:
446 * @caps: the #GstCaps to retrieve from
447 * @index: Index of the structure to retrieve
449 * Retrieves the stucture with the given index from the list of structures
450 * contained in @caps. The caller becomes the owner of the returned structure.
452 * Returns: (transfer full): a pointer to the #GstStructure corresponding
458 gst_caps_steal_structure (GstCaps * caps, guint index)
460 g_return_val_if_fail (caps != NULL, NULL);
461 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
463 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
466 return gst_caps_remove_and_get_structure (caps, index);
471 * @caps1: the #GstCaps that will be appended to
472 * @caps2: (transfer full): the #GstCaps to append
474 * Appends the structures contained in @caps2 to @caps1. The structures in
475 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
476 * freed. If either caps is ANY, the resulting caps will be ANY.
479 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
481 GstStructure *structure;
484 g_return_if_fail (GST_IS_CAPS (caps1));
485 g_return_if_fail (GST_IS_CAPS (caps2));
486 g_return_if_fail (IS_WRITABLE (caps1));
488 caps2 = gst_caps_make_writable (caps2);
490 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
491 /* FIXME: this leaks */
492 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
493 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
494 structure = gst_caps_remove_and_get_structure (caps2, i);
495 gst_structure_free (structure);
498 for (i = GST_CAPS_LEN (caps2); i; i--) {
499 structure = gst_caps_remove_and_get_structure (caps2, 0);
500 gst_caps_append_structure_unchecked (caps1, structure);
503 gst_caps_unref (caps2); /* guaranteed to free it */
508 * @caps1: the #GstCaps that will take the new entries
509 * @caps2: (transfer full): the #GstCaps to merge in
511 * Appends the structures contained in @caps2 to @caps1 if they are not yet
512 * expressed by @caps1. The structures in @caps2 are not copied -- they are
513 * transferred to @caps1, and then @caps2 is freed.
514 * If either caps is ANY, the resulting caps will be ANY.
519 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
521 GstStructure *structure;
524 g_return_if_fail (GST_IS_CAPS (caps1));
525 g_return_if_fail (GST_IS_CAPS (caps2));
526 g_return_if_fail (IS_WRITABLE (caps1));
528 caps2 = gst_caps_make_writable (caps2);
530 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
531 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
532 structure = gst_caps_remove_and_get_structure (caps2, i);
533 gst_structure_free (structure);
535 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
536 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
537 for (i = GST_CAPS_LEN (caps1) - 1; i >= 0; i--) {
538 structure = gst_caps_remove_and_get_structure (caps1, i);
539 gst_structure_free (structure);
542 for (i = GST_CAPS_LEN (caps2); i; i--) {
543 structure = gst_caps_remove_and_get_structure (caps2, 0);
544 gst_caps_merge_structure (caps1, structure);
547 GstCaps *com = gst_caps_intersect (caps1, caps2);
548 GstCaps *add = gst_caps_subtract (caps2, com);
550 GST_DEBUG ("common : %d", gst_caps_get_size (com));
551 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
552 gst_caps_append (caps1, add);
553 gst_caps_unref (com);
556 gst_caps_unref (caps2); /* guaranteed to free it */
560 * gst_caps_append_structure:
561 * @caps: the #GstCaps that will be appended to
562 * @structure: (transfer full): the #GstStructure to append
564 * Appends @structure to @caps. The structure is not copied; @caps
565 * becomes the owner of @structure.
568 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
570 g_return_if_fail (GST_IS_CAPS (caps));
571 g_return_if_fail (IS_WRITABLE (caps));
573 if (G_LIKELY (structure)) {
574 gst_caps_append_structure_unchecked (caps, structure);
579 * gst_caps_remove_structure:
580 * @caps: the #GstCaps to remove from
581 * @idx: Index of the structure to remove
583 * removes the stucture with the given index from the list of structures
584 * contained in @caps.
587 gst_caps_remove_structure (GstCaps * caps, guint idx)
589 GstStructure *structure;
591 g_return_if_fail (caps != NULL);
592 g_return_if_fail (idx <= gst_caps_get_size (caps));
593 g_return_if_fail (IS_WRITABLE (caps));
595 structure = gst_caps_remove_and_get_structure (caps, idx);
596 gst_structure_free (structure);
600 * gst_caps_merge_structure:
601 * @caps: the #GstCaps that will the new structure
602 * @structure: (transfer full): the #GstStructure to merge
604 * Appends @structure to @caps if its not already expressed by @caps. The
605 * structure is not copied; @caps becomes the owner of @structure.
608 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
610 g_return_if_fail (GST_IS_CAPS (caps));
611 g_return_if_fail (IS_WRITABLE (caps));
613 if (G_LIKELY (structure)) {
614 GstStructure *structure1;
616 gboolean unique = TRUE;
618 /* check each structure */
619 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
620 structure1 = gst_caps_get_structure_unchecked (caps, i);
621 /* if structure is a subset of structure1, then skip it */
622 if (gst_structure_is_subset (structure, structure1)) {
628 gst_caps_append_structure_unchecked (caps, structure);
630 gst_structure_free (structure);
639 * Gets the number of structures contained in @caps.
641 * Returns: the number of structures that @caps contains
644 gst_caps_get_size (const GstCaps * caps)
646 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
648 return GST_CAPS_LEN (caps);
652 * gst_caps_get_structure:
654 * @index: the index of the structure
656 * Finds the structure in @caps that has the index @index, and
659 * WARNING: This function takes a const GstCaps *, but returns a
660 * non-const GstStructure *. This is for programming convenience --
661 * the caller should be aware that structures inside a constant
662 * #GstCaps should not be modified. However, if you know the caps
663 * are writable, either because you have just copied them or made
664 * them writable with gst_caps_make_writable(), you may modify the
665 * structure returned in the usual way, e.g. with functions like
666 * gst_structure_set().
668 * You do not need to free or unref the structure returned, it
669 * belongs to the #GstCaps.
671 * Returns: (transfer none): a pointer to the #GstStructure corresponding
675 gst_caps_get_structure (const GstCaps * caps, guint index)
677 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
678 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
680 return gst_caps_get_structure_unchecked (caps, index);
685 * @caps: the #GstCaps to copy
686 * @nth: the nth structure to copy
688 * Creates a new #GstCaps and appends a copy of the nth structure
689 * contained in @caps.
691 * Returns: (transfer full): the new #GstCaps
694 gst_caps_copy_nth (const GstCaps * caps, guint nth)
697 GstStructure *structure;
699 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
701 newcaps = gst_caps_new_empty ();
702 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
704 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
705 structure = gst_caps_get_structure_unchecked (caps, nth);
706 gst_caps_append_structure_unchecked (newcaps,
707 gst_structure_copy (structure));
715 * @caps: the #GstCaps to truncate
717 * Destructively discard all but the first structure from @caps. Useful when
718 * fixating. @caps must be writable.
721 gst_caps_truncate (GstCaps * caps)
725 g_return_if_fail (GST_IS_CAPS (caps));
726 g_return_if_fail (IS_WRITABLE (caps));
728 i = GST_CAPS_LEN (caps) - 1;
731 gst_caps_remove_structure (caps, i--);
735 * gst_caps_set_value:
736 * @caps: a writable caps
737 * @field: name of the field to set
738 * @value: value to set the field to
740 * Sets the given @field on all structures of @caps to the given @value.
741 * This is a convenience function for calling gst_structure_set_value() on
742 * all structures of @caps.
747 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
751 g_return_if_fail (GST_IS_CAPS (caps));
752 g_return_if_fail (IS_WRITABLE (caps));
753 g_return_if_fail (field != NULL);
754 g_return_if_fail (G_IS_VALUE (value));
756 len = GST_CAPS_LEN (caps);
757 for (i = 0; i < len; i++) {
758 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
759 gst_structure_set_value (structure, field, value);
764 * gst_caps_set_simple_valist:
765 * @caps: the #GstCaps to set
766 * @field: first field to set
767 * @varargs: additional parameters
769 * Sets fields in a #GstCaps. The arguments must be passed in the same
770 * manner as gst_structure_set(), and be NULL-terminated.
771 * <note>Prior to GStreamer version 0.10.26, this function failed when
772 * @caps was not simple. If your code needs to work with those versions
773 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
774 * is %TRUE for @caps.</note>
777 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
779 GValue value = { 0, };
781 g_return_if_fail (GST_IS_CAPS (caps));
782 g_return_if_fail (IS_WRITABLE (caps));
788 type = va_arg (varargs, GType);
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 (GST_CAPS_LEN (caps) != 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 = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
970 for (j = GST_CAPS_LEN (superset) - 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 = GST_CAPS_LEN (caps) - 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);
1063 * gst_caps_is_strictly_equal:
1064 * @caps1: a #GstCaps
1065 * @caps2: another #GstCaps
1067 * Checks if the given caps are exactly the same set of caps.
1069 * This function deals correctly with passing NULL for any of the caps.
1071 * Returns: TRUE if both caps are strictly equal.
1076 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1079 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1080 * So there should be an assertion that caps1 and caps2 != NULL */
1082 /* NULL <-> NULL is allowed here */
1083 if (G_UNLIKELY (caps1 == caps2))
1086 /* one of them NULL => they are different (can't be both NULL because
1087 * we checked that above) */
1088 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1091 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1094 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1095 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1096 gst_caps_get_structure_unchecked (caps2, i)))
1103 /* intersect operation */
1106 * gst_caps_can_intersect:
1107 * @caps1: a #GstCaps to intersect
1108 * @caps2: a #GstCaps to intersect
1110 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1113 * Returns: %TRUE if intersection would be not empty
1118 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1120 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1121 guint j, k, len1, len2;
1122 GstStructure *struct1;
1123 GstStructure *struct2;
1125 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1126 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1128 /* caps are exactly the same pointers */
1129 if (G_UNLIKELY (caps1 == caps2))
1132 /* empty caps on either side, return empty */
1133 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1136 /* one of the caps is any */
1137 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1140 /* run zigzag on top line then right line, this preserves the caps order
1141 * much better than a simple loop.
1143 * This algorithm zigzags over the caps structures as demonstrated in
1144 * the folowing matrix:
1147 * +------------- total distance: +-------------
1148 * | 1 2 4 7 0 | 0 1 2 3
1149 * caps2 | 3 5 8 10 1 | 1 2 3 4
1150 * | 6 9 11 12 2 | 2 3 4 5
1152 * First we iterate over the caps1 structures (top line) intersecting
1153 * the structures diagonally down, then we iterate over the caps2
1154 * structures. The result is that the intersections are ordered based on the
1155 * sum of the indexes in the list.
1157 len1 = GST_CAPS_LEN (caps1);
1158 len2 = GST_CAPS_LEN (caps2);
1159 for (i = 0; i < len1 + len2 - 1; i++) {
1160 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1161 j = MIN (i, len1 - 1);
1162 /* subset index stays 0 until i reaches superset->structs->len, then it
1163 * counts up from 1 to subset->structs->len - 1 */
1164 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1166 /* now run the diagonal line, end condition is the left or bottom
1169 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1170 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1172 if (gst_structure_can_intersect (struct1, struct2)) {
1175 /* move down left */
1177 if (G_UNLIKELY (j == 0))
1178 break; /* so we don't roll back to G_MAXUINT */
1186 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1188 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1189 guint j, k, len1, len2;
1191 GstStructure *struct1;
1192 GstStructure *struct2;
1194 GstStructure *istruct;
1196 /* caps are exactly the same pointers, just copy one caps */
1197 if (G_UNLIKELY (caps1 == caps2))
1198 return _gst_caps_copy (caps1);
1200 /* empty caps on either side, return empty */
1201 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1202 return gst_caps_new_empty ();
1204 /* one of the caps is any, just copy the other caps */
1205 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1206 return _gst_caps_copy (caps2);
1207 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1208 return _gst_caps_copy (caps1);
1210 dest = gst_caps_new_empty ();
1212 /* run zigzag on top line then right line, this preserves the caps order
1213 * much better than a simple loop.
1215 * This algorithm zigzags over the caps structures as demonstrated in
1216 * the folowing matrix:
1224 * First we iterate over the caps1 structures (top line) intersecting
1225 * the structures diagonally down, then we iterate over the caps2
1228 len1 = GST_CAPS_LEN (caps1);
1229 len2 = GST_CAPS_LEN (caps2);
1230 for (i = 0; i < len1 + len2 - 1; i++) {
1231 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1232 j = MIN (i, len1 - 1);
1233 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1234 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1235 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1237 /* now run the diagonal line, end condition is the left or bottom
1240 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1241 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1243 istruct = gst_structure_intersect (struct1, struct2);
1245 gst_caps_merge_structure (dest, istruct);
1246 /* move down left */
1248 if (G_UNLIKELY (j == 0))
1249 break; /* so we don't roll back to G_MAXUINT */
1257 * gst_caps_intersect_first:
1258 * @caps1: a #GstCaps to intersect
1259 * @caps2: a #GstCaps to intersect
1261 * Creates a new #GstCaps that contains all the formats that are common
1262 * to both @caps1 and @caps2.
1264 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1265 * fashion as @caps1.
1267 * Returns: the new #GstCaps
1270 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1273 guint j, len1, len2;
1275 GstStructure *struct1;
1276 GstStructure *struct2;
1278 GstStructure *istruct;
1280 /* caps are exactly the same pointers, just copy one caps */
1281 if (G_UNLIKELY (caps1 == caps2))
1282 return gst_caps_copy (caps1);
1284 /* empty caps on either side, return empty */
1285 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1286 return gst_caps_new_empty ();
1288 /* one of the caps is any, just copy the other caps */
1289 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1290 return gst_caps_copy (caps2);
1291 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1292 return gst_caps_copy (caps1);
1294 dest = gst_caps_new_empty ();
1296 len1 = GST_CAPS_LEN (caps1);
1297 len2 = GST_CAPS_LEN (caps2);
1298 for (i = 0; i < len1; i++) {
1299 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1300 for (j = 0; j < len2; j++) {
1301 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1302 istruct = gst_structure_intersect (struct1, struct2);
1304 gst_caps_merge_structure (dest, istruct);
1312 * gst_caps_intersect_full:
1313 * @caps1: a #GstCaps to intersect
1314 * @caps2: a #GstCaps to intersect
1315 * @mode: The intersection algorithm/mode to use
1317 * Creates a new #GstCaps that contains all the formats that are common
1318 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1321 * Returns: the new #GstCaps
1325 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1326 GstCapsIntersectMode mode)
1328 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1329 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1332 case GST_CAPS_INTERSECT_FIRST:
1333 return gst_caps_intersect_first (caps1, caps2);
1335 g_warning ("Unknown caps intersect mode: %d", mode);
1337 case GST_CAPS_INTERSECT_ZIG_ZAG:
1338 return gst_caps_intersect_zig_zag (caps1, caps2);
1343 * gst_caps_intersect:
1344 * @caps1: a #GstCaps to intersect
1345 * @caps2: a #GstCaps to intersect
1347 * Creates a new #GstCaps that contains all the formats that are common
1348 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1350 * Returns: the new #GstCaps
1353 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1355 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1359 /* subtract operation */
1363 const GstStructure *subtract_from;
1369 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1372 SubtractionEntry *e = user_data;
1373 GValue subtraction = { 0, };
1374 const GValue *other;
1375 GstStructure *structure;
1377 other = gst_structure_id_get_value (e->subtract_from, field_id);
1381 if (!gst_value_subtract (&subtraction, other, value))
1383 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1384 g_value_unset (&subtraction);
1387 structure = gst_structure_copy (e->subtract_from);
1388 gst_structure_id_set_value (structure, field_id, &subtraction);
1389 g_value_unset (&subtraction);
1390 e->put_into = g_slist_prepend (e->put_into, structure);
1396 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1397 const GstStructure * subtrahend)
1402 e.subtract_from = minuend;
1405 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1406 gst_caps_structure_subtract_field, &e);
1412 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1413 gst_structure_free (walk->data);
1415 g_slist_free (e.put_into);
1421 * gst_caps_subtract:
1422 * @minuend: #GstCaps to subtract from
1423 * @subtrahend: #GstCaps to subtract
1425 * Subtracts the @subtrahend from the @minuend.
1426 * <note>This function does not work reliably if optional properties for caps
1427 * are included on one caps and omitted on the other.</note>
1429 * Returns: the resulting caps
1432 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1437 GstCaps *dest = NULL, *src;
1439 g_return_val_if_fail (minuend != NULL, NULL);
1440 g_return_val_if_fail (subtrahend != NULL, NULL);
1442 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1443 return gst_caps_new_empty ();
1445 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1446 return _gst_caps_copy (minuend);
1448 /* FIXME: Do we want this here or above?
1449 The reason we need this is that there is no definition about what
1450 ANY means for specific types, so it's not possible to reduce ANY partially
1451 You can only remove everything or nothing and that is done above.
1452 Note: there's a test that checks this behaviour. */
1453 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1454 sublen = GST_CAPS_LEN (subtrahend);
1455 g_assert (sublen > 0);
1457 src = _gst_caps_copy (minuend);
1458 for (i = 0; i < sublen; i++) {
1461 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1463 gst_caps_unref (src);
1466 dest = gst_caps_new_empty ();
1467 srclen = GST_CAPS_LEN (src);
1468 for (j = 0; j < srclen; j++) {
1469 min = gst_caps_get_structure_unchecked (src, j);
1470 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1473 if (gst_caps_structure_subtract (&list, min, sub)) {
1476 for (walk = list; walk; walk = g_slist_next (walk)) {
1477 gst_caps_append_structure_unchecked (dest,
1478 (GstStructure *) walk->data);
1480 g_slist_free (list);
1482 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1485 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1488 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1489 gst_caps_unref (src);
1494 gst_caps_unref (src);
1495 gst_caps_do_simplify (dest);
1499 /* union operation */
1502 static GstStructure *
1503 gst_caps_structure_union (const GstStructure * struct1,
1504 const GstStructure * struct2)
1508 const GstStructureField *field1;
1509 const GstStructureField *field2;
1512 /* FIXME this doesn't actually work */
1514 if (struct1->name != struct2->name)
1517 dest = gst_structure_new_id_empty (struct1->name);
1519 for (i = 0; i < struct1->fields->len; i++) {
1520 GValue dest_value = { 0 };
1522 field1 = GST_STRUCTURE_FIELD (struct1, i);
1523 field2 = gst_structure_id_get_field (struct2, field1->name);
1525 if (field2 == NULL) {
1528 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1529 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1532 ret = gst_value_compare (&field1->value, &field2->value);
1543 * @caps1: a #GstCaps to union
1544 * @caps2: a #GstCaps to union
1546 * Creates a new #GstCaps that contains all the formats that are in
1547 * either @caps1 and @caps2.
1549 * Returns: the new #GstCaps
1552 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1557 /* NULL pointers are no correct GstCaps */
1558 g_return_val_if_fail (caps1 != NULL, NULL);
1559 g_return_val_if_fail (caps2 != NULL, NULL);
1561 if (CAPS_IS_EMPTY (caps1))
1562 return _gst_caps_copy (caps2);
1564 if (CAPS_IS_EMPTY (caps2))
1565 return _gst_caps_copy (caps1);
1567 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1568 return gst_caps_new_any ();
1570 dest1 = _gst_caps_copy (caps1);
1571 dest2 = _gst_caps_copy (caps2);
1572 gst_caps_append (dest1, dest2);
1574 gst_caps_do_simplify (dest1);
1578 /* normalize/simplify operations */
1580 typedef struct _NormalizeForeach
1583 GstStructure *structure;
1588 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1590 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1594 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1595 guint len = gst_value_list_get_size (value);
1596 for (i = 1; i < len; i++) {
1597 const GValue *v = gst_value_list_get_value (value, i);
1598 GstStructure *structure = gst_structure_copy (nf->structure);
1600 gst_structure_id_set_value (structure, field_id, v);
1601 gst_caps_append_structure_unchecked (nf->caps, structure);
1604 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1605 gst_structure_id_set_value (nf->structure, field_id, &val);
1606 g_value_unset (&val);
1614 * gst_caps_normalize:
1615 * @caps: a #GstCaps to normalize
1617 * Creates a new #GstCaps that represents the same set of formats as
1618 * @caps, but contains no lists. Each list is expanded into separate
1621 * Returns: the new #GstCaps
1624 gst_caps_normalize (const GstCaps * caps)
1626 NormalizeForeach nf;
1630 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1632 newcaps = _gst_caps_copy (caps);
1635 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1636 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1638 while (!gst_structure_foreach (nf.structure,
1639 gst_caps_normalize_foreach, &nf));
1646 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1649 const GstStructure *struct1 = *((const GstStructure **) one);
1650 const GstStructure *struct2 = *((const GstStructure **) two);
1652 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1653 So what's the best way? */
1654 ret = strcmp (gst_structure_get_name (struct1),
1655 gst_structure_get_name (struct2));
1659 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1666 GstStructure *compare;
1671 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1674 UnionField *u = user_data;
1675 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1679 g_value_unset (&u->value);
1682 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1685 g_value_unset (&u->value);
1689 gst_value_union (&u->value, val, value);
1694 gst_caps_structure_simplify (GstStructure ** result,
1695 const GstStructure * simplify, GstStructure * compare)
1698 UnionField field = { 0, {0,}, NULL };
1700 /* try to subtract to get a real subset */
1701 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1702 if (list == NULL) { /* no result */
1705 } else if (list->next == NULL) { /* one result */
1706 *result = list->data;
1707 g_slist_free (list);
1709 } else { /* multiple results */
1710 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1711 g_slist_free (list);
1716 /* try to union both structs */
1717 field.compare = compare;
1718 if (gst_structure_foreach ((GstStructure *) simplify,
1719 gst_caps_structure_figure_out_union, &field)) {
1720 gboolean ret = FALSE;
1722 /* now we know all of simplify's fields are the same in compare
1723 * but at most one field: field.name */
1724 if (G_IS_VALUE (&field.value)) {
1725 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1726 gst_structure_id_set_value (compare, field.name, &field.value);
1730 g_value_unset (&field.value);
1731 } else if (gst_structure_n_fields (simplify) <=
1732 gst_structure_n_fields (compare)) {
1733 /* compare is just more specific, will be optimized away later */
1734 /* FIXME: do this here? */
1735 GST_LOG ("found a case that will be optimized later.");
1737 gchar *one = gst_structure_to_string (simplify);
1738 gchar *two = gst_structure_to_string (compare);
1741 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1753 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1754 GstStructure * new, gint i)
1756 gst_structure_set_parent_refcount (old, NULL);
1757 gst_structure_free (old);
1758 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1759 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1763 * gst_caps_do_simplify:
1764 * @caps: a #GstCaps to simplify
1766 * Modifies the given @caps inplace into a representation that represents the
1767 * same set of formats, but in a simpler form. Component structures that are
1768 * identical are merged. Component structures that have values that can be
1769 * merged are also merged.
1771 * Returns: TRUE, if the caps could be simplified
1774 gst_caps_do_simplify (GstCaps * caps)
1776 GstStructure *simplify, *compare, *result = NULL;
1778 gboolean changed = FALSE;
1780 g_return_val_if_fail (caps != NULL, FALSE);
1781 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1783 if (gst_caps_get_size (caps) < 2)
1786 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1788 start = GST_CAPS_LEN (caps) - 1;
1789 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1790 simplify = gst_caps_get_structure_unchecked (caps, i);
1791 if (gst_structure_get_name_id (simplify) !=
1792 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1795 for (j = start; j >= 0; j--) {
1798 compare = gst_caps_get_structure_unchecked (caps, j);
1799 if (gst_structure_get_name_id (simplify) !=
1800 gst_structure_get_name_id (compare)) {
1803 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1805 gst_caps_switch_structures (caps, simplify, result, i);
1808 gst_caps_remove_structure (caps, i);
1820 /* gst_caps_do_simplify (caps); */
1826 * @caps: a #GstCaps to fixate
1828 * Modifies the given @caps inplace into a representation with only fixed
1829 * values. First the caps will be truncated and then the first structure will be
1830 * fixated with gst_structure_fixate(). @caps should be writable.
1833 gst_caps_fixate (GstCaps * caps)
1837 g_return_if_fail (GST_IS_CAPS (caps));
1838 g_return_if_fail (IS_WRITABLE (caps));
1840 /* default fixation */
1841 gst_caps_truncate (caps);
1842 s = gst_caps_get_structure (caps, 0);
1843 gst_structure_fixate (s);
1849 * gst_caps_to_string:
1852 * Converts @caps to a string representation. This string representation
1853 * can be converted back to a #GstCaps by gst_caps_from_string().
1855 * For debugging purposes its easier to do something like this:
1857 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1859 * This prints the caps in human readble form.
1861 * Returns: (transfer full): a newly allocated string representing @caps.
1864 gst_caps_to_string (const GstCaps * caps)
1866 guint i, slen, clen;
1869 /* NOTE: This function is potentially called by the debug system,
1870 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1871 * should be careful to avoid recursion. This includes any functions
1872 * called by gst_caps_to_string. In particular, calls should
1873 * not use the GST_PTR_FORMAT extension. */
1876 return g_strdup ("NULL");
1878 if (CAPS_IS_ANY (caps)) {
1879 return g_strdup ("ANY");
1881 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1882 return g_strdup ("EMPTY");
1885 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1887 clen = GST_CAPS_LEN (caps);
1888 for (i = 0; i < clen; i++) {
1890 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1894 s = g_string_sized_new (slen);
1895 for (i = 0; i < clen; i++) {
1896 GstStructure *structure;
1899 /* ';' is now added by gst_structure_to_string */
1900 g_string_append_c (s, ' ');
1903 structure = gst_caps_get_structure_unchecked (caps, i);
1904 priv_gst_structure_append_to_gstring (structure, s);
1906 if (s->len && s->str[s->len - 1] == ';') {
1907 /* remove latest ';' */
1908 s->str[--s->len] = '\0';
1910 return g_string_free (s, FALSE);
1914 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1916 GstStructure *structure;
1919 if (strcmp ("ANY", string) == 0) {
1920 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1923 if (strcmp ("EMPTY", string) == 0) {
1927 structure = gst_structure_from_string (string, &s);
1928 if (structure == NULL) {
1931 gst_caps_append_structure_unchecked (caps, structure);
1935 while (g_ascii_isspace (*s))
1940 structure = gst_structure_from_string (s, &s);
1941 if (structure == NULL) {
1944 gst_caps_append_structure_unchecked (caps, structure);
1952 * gst_caps_from_string:
1953 * @string: a string to convert to #GstCaps
1955 * Converts @caps from a string representation.
1957 * Returns: (transfer full): a newly allocated #GstCaps
1960 gst_caps_from_string (const gchar * string)
1964 g_return_val_if_fail (string, FALSE);
1966 caps = gst_caps_new_empty ();
1967 if (gst_caps_from_string_inplace (caps, string)) {
1970 gst_caps_unref (caps);
1976 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1978 g_return_if_fail (G_IS_VALUE (src_value));
1979 g_return_if_fail (G_IS_VALUE (dest_value));
1980 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1981 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1982 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1984 g_value_take_string (dest_value,
1985 gst_caps_to_string (gst_value_get_caps (src_value)));