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., 51 Franklin St, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
22 * @short_description: Structure describing sets of media formats
23 * @see_also: #GstStructure, #GstMiniObject
25 * Caps (capabilities) are lightweight 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_query_caps() pad
33 * function. This function describes the possible types that the pad can
34 * handle or produce at runtime.
36 * A #GstCaps can be constructed with the following code fragment:
39 * <title>Creating caps</title>
42 * caps = gst_caps_new_simple ("video/x-raw",
43 * "format", G_TYPE_STRING, "I420",
44 * "framerate", GST_TYPE_FRACTION, 25, 1,
45 * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
46 * "width", G_TYPE_INT, 320,
47 * "height", G_TYPE_INT, 240,
52 * A #GstCaps is fixed when it has no properties with ranges or lists. Use
53 * gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a
54 * caps event to notify downstream elements of the current media type.
56 * Various methods exist to work with the media types such as subtracting
59 * Last reviewed on 2011-03-28 (0.11.3)
68 #include "gst_private.h"
70 #include <gobject/gvaluecollector.h>
72 #define DEBUG_REFCOUNT
74 typedef struct _GstCapsImpl
81 #define GST_CAPS_ARRAY(c) (((GstCapsImpl *)(c))->array)
83 #define GST_CAPS_LEN(c) (GST_CAPS_ARRAY(c)->len)
85 #define IS_WRITABLE(caps) \
86 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
88 /* same as gst_caps_is_any () */
89 #define CAPS_IS_ANY(caps) \
90 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY)
92 /* same as gst_caps_is_empty () */
93 #define CAPS_IS_EMPTY(caps) \
94 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
96 #define CAPS_IS_EMPTY_SIMPLE(caps) \
97 ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
99 /* quick way to get a caps structure at an index without doing a type or array
101 #define gst_caps_get_structure_unchecked(caps, index) \
102 ((GstStructure *)g_ptr_array_index (GST_CAPS_ARRAY (caps), (index)))
103 /* quick way to append a structure without checking the args */
104 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
105 GstStructure *__s=structure; \
106 if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps))) \
107 g_ptr_array_add (GST_CAPS_ARRAY (caps), __s); \
110 /* lock to protect multiple invocations of static caps to caps conversion */
111 G_LOCK_DEFINE_STATIC (static_caps_lock);
113 static void gst_caps_transform_to_string (const GValue * src_value,
114 GValue * dest_value);
115 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
116 const gchar * string);
118 GType _gst_caps_type = 0;
119 GstCaps *_gst_caps_any;
120 GstCaps *_gst_caps_none;
122 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
125 _priv_gst_caps_initialize (void)
127 _gst_caps_type = gst_caps_get_type ();
129 _gst_caps_any = gst_caps_new_any ();
130 _gst_caps_none = gst_caps_new_empty ();
132 g_value_register_transform_func (_gst_caps_type,
133 G_TYPE_STRING, gst_caps_transform_to_string);
137 _gst_caps_copy (const GstCaps * caps)
140 GstStructure *structure;
143 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
145 newcaps = gst_caps_new_empty ();
146 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
147 n = GST_CAPS_LEN (caps);
149 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, caps, "doing copy %p -> %p",
152 for (i = 0; i < n; i++) {
153 structure = gst_caps_get_structure_unchecked (caps, i);
154 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
160 /* creation/deletion */
162 _gst_caps_free (GstCaps * caps)
164 GstStructure *structure;
167 /* The refcount must be 0, but since we're only called by gst_caps_unref,
168 * don't bother testing. */
169 len = GST_CAPS_LEN (caps);
170 /* This can be used to get statistics about caps sizes */
171 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
172 for (i = 0; i < len; i++) {
173 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
174 gst_structure_set_parent_refcount (structure, NULL);
175 gst_structure_free (structure);
177 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
179 #ifdef DEBUG_REFCOUNT
180 GST_CAT_TRACE (GST_CAT_CAPS, "freeing caps %p", caps);
182 g_slice_free1 (sizeof (GstCapsImpl), caps);
186 gst_caps_init (GstCaps * caps)
188 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), 0, _gst_caps_type,
189 (GstMiniObjectCopyFunction) _gst_caps_copy, NULL,
190 (GstMiniObjectFreeFunction) _gst_caps_free);
192 /* the 32 has been determined by logging caps sizes in _gst_caps_free
193 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
195 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
197 GST_CAPS_ARRAY (caps) = g_ptr_array_new ();
201 * gst_caps_new_empty:
203 * Creates a new #GstCaps that is empty. That is, the returned
204 * #GstCaps contains no media formats.
205 * The #GstCaps is guaranteed to be writable.
206 * Caller is responsible for unreffing the returned caps.
208 * Returns: (transfer full): the new #GstCaps
211 gst_caps_new_empty (void)
215 caps = (GstCaps *) g_slice_new (GstCapsImpl);
217 gst_caps_init (caps);
219 #ifdef DEBUG_REFCOUNT
220 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
229 * Creates a new #GstCaps that indicates that it is compatible with
232 * Returns: (transfer full): the new #GstCaps
235 gst_caps_new_any (void)
237 GstCaps *caps = gst_caps_new_empty ();
239 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
245 * gst_caps_new_empty_simple:
246 * @media_type: the media type of the structure
248 * Creates a new #GstCaps that contains one #GstStructure with name
250 * Caller is responsible for unreffing the returned caps.
252 * Returns: (transfer full): the new #GstCaps
255 gst_caps_new_empty_simple (const char *media_type)
258 GstStructure *structure;
260 caps = gst_caps_new_empty ();
261 structure = gst_structure_new_empty (media_type);
263 gst_caps_append_structure_unchecked (caps, structure);
269 * gst_caps_new_simple:
270 * @media_type: the media type of the structure
271 * @fieldname: first field to set
272 * @...: additional arguments
274 * Creates a new #GstCaps that contains one #GstStructure. The
275 * structure is defined by the arguments, which have the same format
276 * as gst_structure_new().
277 * Caller is responsible for unreffing the returned caps.
279 * Returns: (transfer full): the new #GstCaps
282 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
285 GstStructure *structure;
288 caps = gst_caps_new_empty ();
290 va_start (var_args, fieldname);
291 structure = gst_structure_new_valist (media_type, fieldname, var_args);
295 gst_caps_append_structure_unchecked (caps, structure);
297 gst_caps_replace (&caps, NULL);
304 * @struct1: the first structure to add
305 * @...: additional structures to add
307 * Creates a new #GstCaps and adds all the structures listed as
308 * arguments. The list must be NULL-terminated. The structures
309 * are not copied; the returned #GstCaps owns the structures.
311 * Returns: (transfer full): the new #GstCaps
314 gst_caps_new_full (GstStructure * struct1, ...)
319 va_start (var_args, struct1);
320 caps = gst_caps_new_full_valist (struct1, var_args);
327 * gst_caps_new_full_valist:
328 * @structure: the first structure to add
329 * @var_args: additional structures to add
331 * Creates a new #GstCaps and adds all the structures listed as
332 * arguments. The list must be NULL-terminated. The structures
333 * are not copied; the returned #GstCaps owns the structures.
335 * Returns: (transfer full): the new #GstCaps
338 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
342 caps = gst_caps_new_empty ();
345 gst_caps_append_structure_unchecked (caps, structure);
346 structure = va_arg (var_args, GstStructure *);
352 G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
355 * gst_static_caps_get:
356 * @static_caps: the #GstStaticCaps to convert
358 * Converts a #GstStaticCaps to a #GstCaps.
360 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
361 * Since the core holds an additional ref to the returned caps,
362 * use gst_caps_make_writable() on the returned caps to modify it.
365 gst_static_caps_get (GstStaticCaps * static_caps)
369 g_return_val_if_fail (static_caps != NULL, NULL);
371 caps = &static_caps->caps;
373 /* refcount is 0 when we need to convert */
374 if (G_UNLIKELY (*caps == NULL)) {
377 G_LOCK (static_caps_lock);
378 /* check if other thread already updated */
379 if (G_UNLIKELY (*caps != NULL))
382 string = static_caps->string;
384 if (G_UNLIKELY (string == NULL))
387 *caps = gst_caps_from_string (string);
389 /* convert to string */
390 if (G_UNLIKELY (*caps == NULL))
391 g_critical ("Could not convert static caps \"%s\"", string);
393 GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
396 G_UNLOCK (static_caps_lock);
398 /* ref the caps, makes it not writable */
399 if (G_LIKELY (*caps != NULL))
400 gst_caps_ref (*caps);
407 G_UNLOCK (static_caps_lock);
408 g_warning ("static caps %p string is NULL", static_caps);
414 * gst_static_caps_cleanup:
415 * @static_caps: the #GstStaticCaps to clean
417 * Clean up the cached caps contained in @static_caps.
420 gst_static_caps_cleanup (GstStaticCaps * static_caps)
422 G_LOCK (static_caps_lock);
423 gst_caps_replace (&static_caps->caps, NULL);
424 G_UNLOCK (static_caps_lock);
429 static GstStructure *
430 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
432 /* don't use index_fast, gst_caps_simplify relies on the order */
433 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
435 gst_structure_set_parent_refcount (s, NULL);
440 * gst_caps_steal_structure:
441 * @caps: the #GstCaps to retrieve from
442 * @index: Index of the structure to retrieve
444 * Retrieves the structure with the given index from the list of structures
445 * contained in @caps. The caller becomes the owner of the returned structure.
447 * Returns: (transfer full): a pointer to the #GstStructure corresponding
451 gst_caps_steal_structure (GstCaps * caps, guint index)
453 g_return_val_if_fail (caps != NULL, NULL);
454 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
456 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
459 return gst_caps_remove_and_get_structure (caps, index);
464 * @caps1: the #GstCaps that will be appended to
465 * @caps2: (transfer full): the #GstCaps to append
467 * Appends the structures contained in @caps2 to @caps1. The structures in
468 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
469 * freed. If either caps is ANY, the resulting caps will be ANY.
472 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
474 GstStructure *structure;
477 g_return_if_fail (GST_IS_CAPS (caps1));
478 g_return_if_fail (GST_IS_CAPS (caps2));
479 g_return_if_fail (IS_WRITABLE (caps1));
481 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
482 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
483 gst_caps_unref (caps2);
485 caps2 = gst_caps_make_writable (caps2);
487 for (i = GST_CAPS_LEN (caps2); i; i--) {
488 structure = gst_caps_remove_and_get_structure (caps2, 0);
489 gst_caps_append_structure_unchecked (caps1, structure);
491 gst_caps_unref (caps2); /* guaranteed to free it */
497 * @caps1: (transfer full): the #GstCaps that will take the new entries
498 * @caps2: (transfer full): the #GstCaps to merge in
500 * Appends the structures contained in @caps2 to @caps1 if they are not yet
501 * expressed by @caps1. The structures in @caps2 are not copied -- they are
502 * transferred to a writable copy of @caps1, and then @caps2 is freed.
503 * If either caps is ANY, the resulting caps will be ANY.
505 * Returns: (transfer full): the merged caps.
508 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
510 GstStructure *structure;
514 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
515 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
517 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
518 gst_caps_unref (caps2);
520 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
521 gst_caps_unref (caps1);
524 caps2 = gst_caps_make_writable (caps2);
526 for (i = GST_CAPS_LEN (caps2); i; i--) {
527 structure = gst_caps_remove_and_get_structure (caps2, 0);
528 caps1 = gst_caps_merge_structure (caps1, structure);
530 gst_caps_unref (caps2);
534 GstCaps *com = gst_caps_intersect (caps1, caps2);
535 GstCaps *add = gst_caps_subtract (caps2, com);
537 GST_DEBUG ("common : %d", gst_caps_get_size (com));
538 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
539 gst_caps_append (caps1, add);
540 gst_caps_unref (com);
548 * gst_caps_append_structure:
549 * @caps: the #GstCaps that will be appended to
550 * @structure: (transfer full): the #GstStructure to append
552 * Appends @structure to @caps. The structure is not copied; @caps
553 * becomes the owner of @structure.
556 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
558 g_return_if_fail (GST_IS_CAPS (caps));
559 g_return_if_fail (IS_WRITABLE (caps));
561 if (G_LIKELY (structure)) {
562 gst_caps_append_structure_unchecked (caps, structure);
567 * gst_caps_remove_structure:
568 * @caps: the #GstCaps to remove from
569 * @idx: Index of the structure to remove
571 * removes the stucture with the given index from the list of structures
572 * contained in @caps.
575 gst_caps_remove_structure (GstCaps * caps, guint idx)
577 GstStructure *structure;
579 g_return_if_fail (caps != NULL);
580 g_return_if_fail (idx <= gst_caps_get_size (caps));
581 g_return_if_fail (IS_WRITABLE (caps));
583 structure = gst_caps_remove_and_get_structure (caps, idx);
584 gst_structure_free (structure);
588 * gst_caps_merge_structure:
589 * @caps: (transfer full): the #GstCaps to merge into
590 * @structure: (transfer full): the #GstStructure to merge
592 * Appends @structure to @caps if its not already expressed by @caps.
594 * Returns: (transfer full): the merged caps.
597 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
599 GstStructure *structure1;
601 gboolean unique = TRUE;
603 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
605 if (G_UNLIKELY (structure == NULL))
608 /* check each structure */
609 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
610 structure1 = gst_caps_get_structure_unchecked (caps, i);
611 /* if structure is a subset of structure1, then skip it */
612 if (gst_structure_is_subset (structure, structure1)) {
618 caps = gst_caps_make_writable (caps);
619 gst_caps_append_structure_unchecked (caps, structure);
621 gst_structure_free (structure);
630 * Gets the number of structures contained in @caps.
632 * Returns: the number of structures that @caps contains
635 gst_caps_get_size (const GstCaps * caps)
637 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
639 return GST_CAPS_LEN (caps);
643 * gst_caps_get_structure:
645 * @index: the index of the structure
647 * Finds the structure in @caps that has the index @index, and
650 * WARNING: This function takes a const GstCaps *, but returns a
651 * non-const GstStructure *. This is for programming convenience --
652 * the caller should be aware that structures inside a constant
653 * #GstCaps should not be modified. However, if you know the caps
654 * are writable, either because you have just copied them or made
655 * them writable with gst_caps_make_writable(), you may modify the
656 * structure returned in the usual way, e.g. with functions like
657 * gst_structure_set().
659 * You do not need to free or unref the structure returned, it
660 * belongs to the #GstCaps.
662 * Returns: (transfer none): a pointer to the #GstStructure corresponding
666 gst_caps_get_structure (const GstCaps * caps, guint index)
668 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
669 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
671 return gst_caps_get_structure_unchecked (caps, index);
676 * @caps: the #GstCaps to copy
677 * @nth: the nth structure to copy
679 * Creates a new #GstCaps and appends a copy of the nth structure
680 * contained in @caps.
682 * Returns: (transfer full): the new #GstCaps
685 gst_caps_copy_nth (const GstCaps * caps, guint nth)
688 GstStructure *structure;
690 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
692 newcaps = gst_caps_new_empty ();
693 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
695 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
696 structure = gst_caps_get_structure_unchecked (caps, nth);
697 gst_caps_append_structure_unchecked (newcaps,
698 gst_structure_copy (structure));
706 * @caps: (transfer full): the #GstCaps to truncate
708 * Discard all but the first structure from @caps. Useful when
711 * Returns: (transfer full): truncated caps
714 gst_caps_truncate (GstCaps * caps)
718 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
720 i = GST_CAPS_LEN (caps) - 1;
724 caps = gst_caps_make_writable (caps);
726 gst_caps_remove_structure (caps, i--);
732 * gst_caps_set_value:
733 * @caps: a writable caps
734 * @field: name of the field to set
735 * @value: value to set the field to
737 * Sets the given @field on all structures of @caps to the given @value.
738 * This is a convenience function for calling gst_structure_set_value() on
739 * all structures of @caps.
742 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
746 g_return_if_fail (GST_IS_CAPS (caps));
747 g_return_if_fail (IS_WRITABLE (caps));
748 g_return_if_fail (field != NULL);
749 g_return_if_fail (G_IS_VALUE (value));
751 len = GST_CAPS_LEN (caps);
752 for (i = 0; i < len; i++) {
753 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
754 gst_structure_set_value (structure, field, value);
759 * gst_caps_set_simple_valist:
760 * @caps: the #GstCaps to set
761 * @field: first field to set
762 * @varargs: additional parameters
764 * Sets fields in a #GstCaps. The arguments must be passed in the same
765 * manner as gst_structure_set(), and be NULL-terminated.
768 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
770 GValue value = { 0, };
772 g_return_if_fail (GST_IS_CAPS (caps));
773 g_return_if_fail (IS_WRITABLE (caps));
779 type = va_arg (varargs, GType);
781 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
782 if (G_UNLIKELY (err)) {
783 g_critical ("%s", err);
787 gst_caps_set_value (caps, field, &value);
789 g_value_unset (&value);
791 field = va_arg (varargs, const gchar *);
796 * gst_caps_set_simple:
797 * @caps: the #GstCaps to set
798 * @field: first field to set
799 * @...: additional parameters
801 * Sets fields in a #GstCaps. The arguments must be passed in the same
802 * manner as gst_structure_set(), and be NULL-terminated.
805 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
809 g_return_if_fail (GST_IS_CAPS (caps));
810 g_return_if_fail (IS_WRITABLE (caps));
812 va_start (var_args, field);
813 gst_caps_set_simple_valist (caps, field, var_args);
821 * @caps: the #GstCaps to test
823 * Determines if @caps represents any media format.
825 * Returns: TRUE if @caps represents any format.
828 gst_caps_is_any (const GstCaps * caps)
830 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
832 return (CAPS_IS_ANY (caps));
837 * @caps: the #GstCaps to test
839 * Determines if @caps represents no media formats.
841 * Returns: TRUE if @caps represents no formats.
844 gst_caps_is_empty (const GstCaps * caps)
846 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
848 if (CAPS_IS_ANY (caps))
851 return CAPS_IS_EMPTY_SIMPLE (caps);
855 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
858 return gst_value_is_fixed (value);
863 * @caps: the #GstCaps to test
865 * Fixed #GstCaps describe exactly one format, that is, they have exactly
866 * one structure, and each field in the structure describes a fixed type.
867 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
869 * Returns: TRUE if @caps is fixed
872 gst_caps_is_fixed (const GstCaps * caps)
874 GstStructure *structure;
876 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
878 if (GST_CAPS_LEN (caps) != 1)
881 structure = gst_caps_get_structure_unchecked (caps, 0);
883 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
887 * gst_caps_is_equal_fixed:
888 * @caps1: the #GstCaps to test
889 * @caps2: the #GstCaps to test
891 * Tests if two #GstCaps are equal. This function only works on fixed
894 * Returns: TRUE if the arguments represent the same format
897 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
899 GstStructure *struct1, *struct2;
901 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
902 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
904 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
905 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
907 return gst_structure_is_equal (struct1, struct2);
911 * gst_caps_is_always_compatible:
912 * @caps1: the #GstCaps to test
913 * @caps2: the #GstCaps to test
915 * A given #GstCaps structure is always compatible with another if
916 * every media format that is in the first is also contained in the
917 * second. That is, @caps1 is a subset of @caps2.
919 * Returns: TRUE if @caps1 is a subset of @caps2.
922 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
924 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
925 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
927 return gst_caps_is_subset (caps1, caps2);
931 * gst_caps_is_subset:
932 * @subset: a #GstCaps
933 * @superset: a potentially greater #GstCaps
935 * Checks if all caps represented by @subset are also represented by @superset.
936 * <note>This function does not work reliably if optional properties for caps
937 * are included on one caps and omitted on the other.</note>
939 * Returns: %TRUE if @subset is a subset of @superset
942 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
944 GstStructure *s1, *s2;
948 g_return_val_if_fail (subset != NULL, FALSE);
949 g_return_val_if_fail (superset != NULL, FALSE);
951 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
953 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
956 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
957 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
958 s1 = gst_caps_get_structure_unchecked (subset, i);
959 s2 = gst_caps_get_structure_unchecked (superset, j);
960 if (gst_structure_is_subset (s1, s2)) {
961 /* If we found a superset, continue with the next
962 * subset structure */
966 /* If we found no superset for this subset structure
967 * we return FALSE immediately */
978 * gst_caps_is_subset_structure:
980 * @structure: a potential #GstStructure subset of @caps
982 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
983 * for more information.
985 * Returns: %TRUE if @structure is a subset of @caps
988 gst_caps_is_subset_structure (const GstCaps * caps,
989 const GstStructure * structure)
994 g_return_val_if_fail (caps != NULL, FALSE);
995 g_return_val_if_fail (structure != NULL, FALSE);
997 if (CAPS_IS_ANY (caps))
999 if (CAPS_IS_EMPTY (caps))
1002 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1003 s = gst_caps_get_structure_unchecked (caps, i);
1004 if (gst_structure_is_subset (structure, s)) {
1005 /* If we found a superset return TRUE */
1014 * gst_caps_is_equal:
1015 * @caps1: a #GstCaps
1016 * @caps2: another #GstCaps
1018 * Checks if the given caps represent the same set of caps.
1019 * <note>This function does not work reliably if optional properties for caps
1020 * are included on one caps and omitted on the other.</note>
1022 * Returns: TRUE if both caps are equal.
1025 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1027 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1028 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1030 if (G_UNLIKELY (caps1 == caps2))
1033 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1034 return gst_caps_is_equal_fixed (caps1, caps2);
1036 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1040 * gst_caps_is_strictly_equal:
1041 * @caps1: a #GstCaps
1042 * @caps2: another #GstCaps
1044 * Checks if the given caps are exactly the same set of caps.
1046 * Returns: TRUE if both caps are strictly equal.
1049 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1053 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1054 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1056 if (G_UNLIKELY (caps1 == caps2))
1059 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1062 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1063 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1064 gst_caps_get_structure_unchecked (caps2, i)))
1071 /* intersect operation */
1074 * gst_caps_can_intersect:
1075 * @caps1: a #GstCaps to intersect
1076 * @caps2: a #GstCaps to intersect
1078 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1081 * Returns: %TRUE if intersection would be not empty
1084 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1086 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1087 guint j, k, len1, len2;
1088 GstStructure *struct1;
1089 GstStructure *struct2;
1091 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1092 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1094 /* caps are exactly the same pointers */
1095 if (G_UNLIKELY (caps1 == caps2))
1098 /* empty caps on either side, return empty */
1099 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1102 /* one of the caps is any */
1103 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1106 /* run zigzag on top line then right line, this preserves the caps order
1107 * much better than a simple loop.
1109 * This algorithm zigzags over the caps structures as demonstrated in
1110 * the following matrix:
1113 * +------------- total distance: +-------------
1114 * | 1 2 4 7 0 | 0 1 2 3
1115 * caps2 | 3 5 8 10 1 | 1 2 3 4
1116 * | 6 9 11 12 2 | 2 3 4 5
1118 * First we iterate over the caps1 structures (top line) intersecting
1119 * the structures diagonally down, then we iterate over the caps2
1120 * structures. The result is that the intersections are ordered based on the
1121 * sum of the indexes in the list.
1123 len1 = GST_CAPS_LEN (caps1);
1124 len2 = GST_CAPS_LEN (caps2);
1125 for (i = 0; i < len1 + len2 - 1; i++) {
1126 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1127 j = MIN (i, len1 - 1);
1128 /* subset index stays 0 until i reaches superset->structs->len, then it
1129 * counts up from 1 to subset->structs->len - 1 */
1130 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1132 /* now run the diagonal line, end condition is the left or bottom
1135 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1136 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1138 if (gst_structure_can_intersect (struct1, struct2)) {
1141 /* move down left */
1143 if (G_UNLIKELY (j == 0))
1144 break; /* so we don't roll back to G_MAXUINT */
1152 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1154 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1155 guint j, k, len1, len2;
1157 GstStructure *struct1;
1158 GstStructure *struct2;
1160 GstStructure *istruct;
1162 /* caps are exactly the same pointers, just copy one caps */
1163 if (G_UNLIKELY (caps1 == caps2))
1164 return gst_caps_ref (caps1);
1166 /* empty caps on either side, return empty */
1167 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1168 return gst_caps_ref (GST_CAPS_NONE);
1170 /* one of the caps is any, just copy the other caps */
1171 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1172 return gst_caps_ref (caps2);
1173 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1174 return gst_caps_ref (caps1);
1176 dest = gst_caps_new_empty ();
1178 /* run zigzag on top line then right line, this preserves the caps order
1179 * much better than a simple loop.
1181 * This algorithm zigzags over the caps structures as demonstrated in
1182 * the following matrix:
1190 * First we iterate over the caps1 structures (top line) intersecting
1191 * the structures diagonally down, then we iterate over the caps2
1194 len1 = GST_CAPS_LEN (caps1);
1195 len2 = GST_CAPS_LEN (caps2);
1196 for (i = 0; i < len1 + len2 - 1; i++) {
1197 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1198 j = MIN (i, len1 - 1);
1199 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1200 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1201 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1203 /* now run the diagonal line, end condition is the left or bottom
1206 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1207 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1209 istruct = gst_structure_intersect (struct1, struct2);
1211 dest = gst_caps_merge_structure (dest, istruct);
1212 /* move down left */
1214 if (G_UNLIKELY (j == 0))
1215 break; /* so we don't roll back to G_MAXUINT */
1223 * gst_caps_intersect_first:
1224 * @caps1: a #GstCaps to intersect
1225 * @caps2: a #GstCaps to intersect
1227 * Creates a new #GstCaps that contains all the formats that are common
1228 * to both @caps1 and @caps2.
1230 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1231 * fashion as @caps1.
1233 * Returns: the new #GstCaps
1236 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1239 guint j, len1, len2;
1241 GstStructure *struct1;
1242 GstStructure *struct2;
1244 GstStructure *istruct;
1246 /* caps are exactly the same pointers, just copy one caps */
1247 if (G_UNLIKELY (caps1 == caps2))
1248 return gst_caps_ref (caps1);
1250 /* empty caps on either side, return empty */
1251 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1252 return gst_caps_ref (GST_CAPS_NONE);
1254 /* one of the caps is any, just copy the other caps */
1255 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1256 return gst_caps_ref (caps2);
1257 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1258 return gst_caps_ref (caps1);
1260 dest = gst_caps_new_empty ();
1262 len1 = GST_CAPS_LEN (caps1);
1263 len2 = GST_CAPS_LEN (caps2);
1264 for (i = 0; i < len1; i++) {
1265 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1266 for (j = 0; j < len2; j++) {
1267 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1268 istruct = gst_structure_intersect (struct1, struct2);
1270 dest = gst_caps_merge_structure (dest, istruct);
1278 * gst_caps_intersect_full:
1279 * @caps1: a #GstCaps to intersect
1280 * @caps2: a #GstCaps to intersect
1281 * @mode: The intersection algorithm/mode to use
1283 * Creates a new #GstCaps that contains all the formats that are common
1284 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1287 * Returns: the new #GstCaps
1290 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1291 GstCapsIntersectMode mode)
1293 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1294 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1297 case GST_CAPS_INTERSECT_FIRST:
1298 return gst_caps_intersect_first (caps1, caps2);
1300 g_warning ("Unknown caps intersect mode: %d", mode);
1302 case GST_CAPS_INTERSECT_ZIG_ZAG:
1303 return gst_caps_intersect_zig_zag (caps1, caps2);
1308 * gst_caps_intersect:
1309 * @caps1: a #GstCaps to intersect
1310 * @caps2: a #GstCaps to intersect
1312 * Creates a new #GstCaps that contains all the formats that are common
1313 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1315 * Returns: the new #GstCaps
1318 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1320 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1324 /* subtract operation */
1328 const GstStructure *subtract_from;
1334 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1337 SubtractionEntry *e = user_data;
1338 GValue subtraction = { 0, };
1339 const GValue *other;
1340 GstStructure *structure;
1342 other = gst_structure_id_get_value (e->subtract_from, field_id);
1346 if (!gst_value_subtract (&subtraction, other, value))
1348 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1349 g_value_unset (&subtraction);
1352 structure = gst_structure_copy (e->subtract_from);
1353 gst_structure_id_take_value (structure, field_id, &subtraction);
1354 e->put_into = g_slist_prepend (e->put_into, structure);
1360 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1361 const GstStructure * subtrahend)
1366 e.subtract_from = minuend;
1369 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1370 gst_caps_structure_subtract_field, &e);
1376 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1377 gst_structure_free (walk->data);
1379 g_slist_free (e.put_into);
1385 * gst_caps_subtract:
1386 * @minuend: #GstCaps to subtract from
1387 * @subtrahend: #GstCaps to subtract
1389 * Subtracts the @subtrahend from the @minuend.
1390 * <note>This function does not work reliably if optional properties for caps
1391 * are included on one caps and omitted on the other.</note>
1393 * Returns: the resulting caps
1396 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1401 GstCaps *dest = NULL, *src;
1403 g_return_val_if_fail (minuend != NULL, NULL);
1404 g_return_val_if_fail (subtrahend != NULL, NULL);
1406 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1407 return gst_caps_new_empty ();
1409 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1410 return gst_caps_ref (minuend);
1412 /* FIXME: Do we want this here or above?
1413 The reason we need this is that there is no definition about what
1414 ANY means for specific types, so it's not possible to reduce ANY partially
1415 You can only remove everything or nothing and that is done above.
1416 Note: there's a test that checks this behaviour. */
1417 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1418 sublen = GST_CAPS_LEN (subtrahend);
1419 g_assert (sublen > 0);
1421 src = _gst_caps_copy (minuend);
1422 for (i = 0; i < sublen; i++) {
1425 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1427 gst_caps_unref (src);
1430 dest = gst_caps_new_empty ();
1431 srclen = GST_CAPS_LEN (src);
1432 for (j = 0; j < srclen; j++) {
1433 min = gst_caps_get_structure_unchecked (src, j);
1434 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1437 if (gst_caps_structure_subtract (&list, min, sub)) {
1440 for (walk = list; walk; walk = g_slist_next (walk)) {
1441 gst_caps_append_structure_unchecked (dest,
1442 (GstStructure *) walk->data);
1444 g_slist_free (list);
1446 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1449 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1452 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1453 gst_caps_unref (src);
1458 gst_caps_unref (src);
1459 dest = gst_caps_simplify (dest);
1463 /* normalize/simplify operations */
1465 typedef struct _NormalizeForeach
1468 GstStructure *structure;
1473 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1475 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1479 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1480 guint len = gst_value_list_get_size (value);
1481 for (i = 1; i < len; i++) {
1482 const GValue *v = gst_value_list_get_value (value, i);
1483 GstStructure *structure = gst_structure_copy (nf->structure);
1485 gst_structure_id_set_value (structure, field_id, v);
1486 gst_caps_append_structure_unchecked (nf->caps, structure);
1489 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1490 gst_structure_id_take_value (nf->structure, field_id, &val);
1497 * gst_caps_normalize:
1498 * @caps: (transfer full): a #GstCaps to normalize
1500 * Returns a #GstCaps that represents the same set of formats as
1501 * @caps, but contains no lists. Each list is expanded into separate
1504 * This function takes ownership of @caps.
1506 * Returns: (transfer full): the normalized #GstCaps
1509 gst_caps_normalize (GstCaps * caps)
1511 NormalizeForeach nf;
1514 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1516 caps = gst_caps_make_writable (caps);
1520 for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1521 nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1523 while (!gst_structure_foreach (nf.structure,
1524 gst_caps_normalize_foreach, &nf));
1531 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1534 const GstStructure *struct1 = *((const GstStructure **) one);
1535 const GstStructure *struct2 = *((const GstStructure **) two);
1537 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1538 So what's the best way? */
1539 ret = strcmp (gst_structure_get_name (struct1),
1540 gst_structure_get_name (struct2));
1544 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1551 GstStructure *compare;
1556 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1559 UnionField *u = user_data;
1560 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1564 g_value_unset (&u->value);
1567 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1570 g_value_unset (&u->value);
1574 gst_value_union (&u->value, val, value);
1579 gst_caps_structure_simplify (GstStructure ** result,
1580 GstStructure * simplify, GstStructure * compare)
1583 UnionField field = { 0, {0,}, NULL };
1585 /* try to subtract to get a real subset */
1586 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1587 if (list == NULL) { /* no result */
1590 } else if (list->next == NULL) { /* one result */
1591 *result = list->data;
1592 g_slist_free (list);
1594 } else { /* multiple results */
1595 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1596 g_slist_free (list);
1601 /* try to union both structs */
1602 field.compare = compare;
1603 if (gst_structure_foreach (simplify,
1604 gst_caps_structure_figure_out_union, &field)) {
1605 gboolean ret = FALSE;
1607 /* now we know all of simplify's fields are the same in compare
1608 * but at most one field: field.name */
1609 if (G_IS_VALUE (&field.value)) {
1610 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1611 gst_structure_id_take_value (compare, field.name, &field.value);
1615 g_value_unset (&field.value);
1617 } else if (gst_structure_n_fields (simplify) <=
1618 gst_structure_n_fields (compare)) {
1619 /* compare is just more specific, will be optimized away later */
1620 /* FIXME: do this here? */
1621 GST_LOG ("found a case that will be optimized later.");
1623 gchar *one = gst_structure_to_string (simplify);
1624 gchar *two = gst_structure_to_string (compare);
1627 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1639 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1640 GstStructure * new, gint i)
1642 gst_structure_set_parent_refcount (old, NULL);
1643 gst_structure_free (old);
1644 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1645 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1649 * gst_caps_simplify:
1650 * @caps: (transfer full): a #GstCaps to simplify
1652 * Converts the given @caps into a representation that represents the
1653 * same set of formats, but in a simpler form. Component structures that are
1654 * identical are merged. Component structures that have values that can be
1655 * merged are also merged.
1657 * This method does not preserve the original order of @caps.
1659 * Returns: The simplified caps.
1662 gst_caps_simplify (GstCaps * caps)
1664 GstStructure *simplify, *compare, *result = NULL;
1667 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1669 start = GST_CAPS_LEN (caps) - 1;
1670 /* one caps, already as simple as can be */
1674 caps = gst_caps_make_writable (caps);
1676 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1678 for (i = start; i >= 0; i--) {
1679 simplify = gst_caps_get_structure_unchecked (caps, i);
1680 compare = gst_caps_get_structure_unchecked (caps, start);
1681 if (gst_structure_get_name_id (simplify) !=
1682 gst_structure_get_name_id (compare))
1684 for (j = start; j >= 0; j--) {
1687 compare = gst_caps_get_structure_unchecked (caps, j);
1688 if (gst_structure_get_name_id (simplify) !=
1689 gst_structure_get_name_id (compare)) {
1692 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1694 gst_caps_switch_structures (caps, simplify, result, i);
1697 gst_caps_remove_structure (caps, i);
1709 * @caps: (transfer full): a #GstCaps to fixate
1711 * Modifies the given @caps into a representation with only fixed
1712 * values. First the caps will be truncated and then the first structure will be
1713 * fixated with gst_structure_fixate().
1715 * Returns: (transfer full): the fixated caps
1718 gst_caps_fixate (GstCaps * caps)
1722 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1724 /* default fixation */
1725 caps = gst_caps_truncate (caps);
1726 caps = gst_caps_make_writable (caps);
1727 s = gst_caps_get_structure (caps, 0);
1728 gst_structure_fixate (s);
1736 * gst_caps_to_string:
1739 * Converts @caps to a string representation. This string representation
1740 * can be converted back to a #GstCaps by gst_caps_from_string().
1742 * For debugging purposes its easier to do something like this:
1744 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1746 * This prints the caps in human readable form.
1748 * Returns: (transfer full): a newly allocated string representing @caps.
1751 gst_caps_to_string (const GstCaps * caps)
1753 guint i, slen, clen;
1756 /* NOTE: This function is potentially called by the debug system,
1757 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1758 * should be careful to avoid recursion. This includes any functions
1759 * called by gst_caps_to_string. In particular, calls should
1760 * not use the GST_PTR_FORMAT extension. */
1763 return g_strdup ("NULL");
1765 if (CAPS_IS_ANY (caps)) {
1766 return g_strdup ("ANY");
1768 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1769 return g_strdup ("EMPTY");
1772 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1774 clen = GST_CAPS_LEN (caps);
1775 for (i = 0; i < clen; i++) {
1777 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1781 s = g_string_sized_new (slen);
1782 for (i = 0; i < clen; i++) {
1783 GstStructure *structure;
1786 /* ';' is now added by gst_structure_to_string */
1787 g_string_append_c (s, ' ');
1790 structure = gst_caps_get_structure_unchecked (caps, i);
1791 priv_gst_structure_append_to_gstring (structure, s);
1793 if (s->len && s->str[s->len - 1] == ';') {
1794 /* remove latest ';' */
1795 s->str[--s->len] = '\0';
1797 return g_string_free (s, FALSE);
1801 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1803 GstStructure *structure;
1806 if (strcmp ("ANY", string) == 0) {
1807 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1810 if (strcmp ("EMPTY", string) == 0 || strcmp ("NONE", string) == 0) {
1814 structure = gst_structure_from_string (string, &s);
1815 if (structure == NULL) {
1818 gst_caps_append_structure_unchecked (caps, structure);
1822 while (g_ascii_isspace (*s))
1827 structure = gst_structure_from_string (s, &s);
1828 if (structure == NULL) {
1831 gst_caps_append_structure_unchecked (caps, structure);
1839 * gst_caps_from_string:
1840 * @string: a string to convert to #GstCaps
1842 * Converts @caps from a string representation.
1844 * Returns: (transfer full): a newly allocated #GstCaps
1847 gst_caps_from_string (const gchar * string)
1851 g_return_val_if_fail (string, FALSE);
1853 caps = gst_caps_new_empty ();
1854 if (gst_caps_from_string_inplace (caps, string)) {
1857 gst_caps_unref (caps);
1863 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1865 g_return_if_fail (G_IS_VALUE (src_value));
1866 g_return_if_fail (G_IS_VALUE (dest_value));
1867 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1868 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1869 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1871 g_value_take_string (dest_value,
1872 gst_caps_to_string (gst_value_get_caps (src_value)));