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, #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_get_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
83 #define GST_CAPS_SLICE_SIZE(c) (((GstCapsImpl *)(c))->slice_size)
84 #define GST_CAPS_ARRAY(c) (((GstCapsImpl *)(c))->array)
86 #define GST_CAPS_LEN(c) (GST_CAPS_ARRAY(c)->len)
88 #define IS_WRITABLE(caps) \
89 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
91 /* same as gst_caps_is_any () */
92 #define CAPS_IS_ANY(caps) \
93 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY)
95 /* same as gst_caps_is_empty () */
96 #define CAPS_IS_EMPTY(caps) \
97 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
99 #define CAPS_IS_EMPTY_SIMPLE(caps) \
100 ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
102 /* quick way to get a caps structure at an index without doing a type or array
104 #define gst_caps_get_structure_unchecked(caps, index) \
105 ((GstStructure *)g_ptr_array_index (GST_CAPS_ARRAY (caps), (index)))
106 /* quick way to append a structure without checking the args */
107 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
108 GstStructure *__s=structure; \
109 if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps))) \
110 g_ptr_array_add (GST_CAPS_ARRAY (caps), __s); \
113 /* lock to protect multiple invocations of static caps to caps conversion */
114 G_LOCK_DEFINE_STATIC (static_caps_lock);
116 static void gst_caps_transform_to_string (const GValue * src_value,
117 GValue * dest_value);
118 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
119 const gchar * string);
121 GType _gst_caps_type = 0;
122 GstCaps *_gst_caps_any;
123 GstCaps *_gst_caps_none;
125 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
128 _priv_gst_caps_initialize (void)
130 _gst_caps_type = gst_caps_get_type ();
132 _gst_caps_any = gst_caps_new_any ();
133 _gst_caps_none = gst_caps_new_empty ();
135 g_value_register_transform_func (_gst_caps_type,
136 G_TYPE_STRING, gst_caps_transform_to_string);
140 _gst_caps_copy (const GstCaps * caps)
143 GstStructure *structure;
146 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
148 newcaps = gst_caps_new_empty ();
149 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
150 n = GST_CAPS_LEN (caps);
152 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, caps, "doing copy %p -> %p",
155 for (i = 0; i < n; i++) {
156 structure = gst_caps_get_structure_unchecked (caps, i);
157 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
163 /* creation/deletion */
165 _gst_caps_free (GstCaps * caps)
167 GstStructure *structure;
170 /* The refcount must be 0, but since we're only called by gst_caps_unref,
171 * don't bother testing. */
172 len = GST_CAPS_LEN (caps);
173 /* This can be used to get statistics about caps sizes */
174 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
175 for (i = 0; i < len; i++) {
176 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
177 gst_structure_set_parent_refcount (structure, NULL);
178 gst_structure_free (structure);
180 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
182 #ifdef DEBUG_REFCOUNT
183 GST_CAT_TRACE (GST_CAT_CAPS, "freeing caps %p", caps);
185 g_slice_free1 (GST_CAPS_SLICE_SIZE (caps), caps);
189 gst_caps_init (GstCaps * caps, gsize size)
191 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type);
193 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
194 caps->mini_object.dispose = NULL;
195 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
197 GST_CAPS_SLICE_SIZE (caps) = size;
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 * The #GstCaps is guaranteed to be writable.
212 * Caller is responsible for unreffing the returned caps.
214 * Returns: (transfer full): the new #GstCaps
217 gst_caps_new_empty (void)
221 caps = (GstCaps *) g_slice_new (GstCapsImpl);
223 gst_caps_init (caps, sizeof (GstCapsImpl));
225 #ifdef DEBUG_REFCOUNT
226 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
235 * Creates a new #GstCaps that indicates that it is compatible with
238 * Returns: (transfer full): the new #GstCaps
241 gst_caps_new_any (void)
243 GstCaps *caps = gst_caps_new_empty ();
245 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
251 * gst_caps_new_empty_simple:
252 * @media_type: the media type of the structure
254 * Creates a new #GstCaps that contains one #GstStructure with name
256 * Caller is responsible for unreffing the returned caps.
258 * Returns: (transfer full): the new #GstCaps
261 gst_caps_new_empty_simple (const char *media_type)
264 GstStructure *structure;
266 caps = gst_caps_new_empty ();
267 structure = gst_structure_new_empty (media_type);
269 gst_caps_append_structure_unchecked (caps, structure);
275 * gst_caps_new_simple:
276 * @media_type: the media type of the structure
277 * @fieldname: first field to set
278 * @...: additional arguments
280 * Creates a new #GstCaps that contains one #GstStructure. The
281 * structure is defined by the arguments, which have the same format
282 * as gst_structure_new().
283 * Caller is responsible for unreffing the returned caps.
285 * Returns: (transfer full): the new #GstCaps
288 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
291 GstStructure *structure;
294 caps = gst_caps_new_empty ();
296 va_start (var_args, fieldname);
297 structure = gst_structure_new_valist (media_type, fieldname, var_args);
301 gst_caps_append_structure_unchecked (caps, structure);
303 gst_caps_replace (&caps, NULL);
310 * @struct1: the first structure to add
311 * @...: additional structures to add
313 * Creates a new #GstCaps and adds all the structures listed as
314 * arguments. The list must be NULL-terminated. The structures
315 * are not copied; the returned #GstCaps owns the structures.
317 * Returns: (transfer full): the new #GstCaps
320 gst_caps_new_full (GstStructure * struct1, ...)
325 va_start (var_args, struct1);
326 caps = gst_caps_new_full_valist (struct1, var_args);
333 * gst_caps_new_full_valist:
334 * @structure: the first structure to add
335 * @var_args: additional structures to add
337 * Creates a new #GstCaps and adds all the structures listed as
338 * arguments. The list must be NULL-terminated. The structures
339 * are not copied; the returned #GstCaps owns the structures.
341 * Returns: (transfer full): the new #GstCaps
344 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
348 caps = gst_caps_new_empty ();
351 gst_caps_append_structure_unchecked (caps, structure);
352 structure = va_arg (var_args, GstStructure *);
358 G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
361 * gst_static_caps_get:
362 * @static_caps: the #GstStaticCaps to convert
364 * Converts a #GstStaticCaps to a #GstCaps.
366 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
367 * Since the core holds an additional ref to the returned caps,
368 * use gst_caps_make_writable() on the returned caps to modify it.
371 gst_static_caps_get (GstStaticCaps * static_caps)
375 g_return_val_if_fail (static_caps != NULL, NULL);
377 caps = &static_caps->caps;
379 /* refcount is 0 when we need to convert */
380 if (G_UNLIKELY (*caps == NULL)) {
383 G_LOCK (static_caps_lock);
384 /* check if other thread already updated */
385 if (G_UNLIKELY (*caps != NULL))
388 string = static_caps->string;
390 if (G_UNLIKELY (string == NULL))
393 *caps = gst_caps_from_string (string);
395 /* convert to string */
396 if (G_UNLIKELY (*caps == NULL))
397 g_critical ("Could not convert static caps \"%s\"", string);
399 GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
402 G_UNLOCK (static_caps_lock);
404 /* ref the caps, makes it not writable */
405 if (G_LIKELY (*caps != NULL))
406 gst_caps_ref (*caps);
413 G_UNLOCK (static_caps_lock);
414 g_warning ("static caps %p string is NULL", static_caps);
420 * gst_static_caps_cleanup:
421 * @static_caps: the #GstStaticCaps to clean
423 * Clean up the cached caps contained in @static_caps.
426 gst_static_caps_cleanup (GstStaticCaps * static_caps)
428 G_LOCK (static_caps_lock);
429 gst_caps_replace (&static_caps->caps, NULL);
430 G_UNLOCK (static_caps_lock);
435 static GstStructure *
436 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
438 /* don't use index_fast, gst_caps_simplify relies on the order */
439 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
441 gst_structure_set_parent_refcount (s, NULL);
446 * gst_caps_steal_structure:
447 * @caps: the #GstCaps to retrieve from
448 * @index: Index of the structure to retrieve
450 * Retrieves the structure with the given index from the list of structures
451 * contained in @caps. The caller becomes the owner of the returned structure.
453 * Returns: (transfer full): a pointer to the #GstStructure corresponding
459 gst_caps_steal_structure (GstCaps * caps, guint index)
461 g_return_val_if_fail (caps != NULL, NULL);
462 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
464 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
467 return gst_caps_remove_and_get_structure (caps, index);
472 * @caps1: the #GstCaps that will be appended to
473 * @caps2: (transfer full): the #GstCaps to append
475 * Appends the structures contained in @caps2 to @caps1. The structures in
476 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
477 * freed. If either caps is ANY, the resulting caps will be ANY.
480 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
482 GstStructure *structure;
485 g_return_if_fail (GST_IS_CAPS (caps1));
486 g_return_if_fail (GST_IS_CAPS (caps2));
487 g_return_if_fail (IS_WRITABLE (caps1));
489 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
490 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
491 gst_caps_unref (caps2);
493 caps2 = gst_caps_make_writable (caps2);
495 for (i = GST_CAPS_LEN (caps2); i; i--) {
496 structure = gst_caps_remove_and_get_structure (caps2, 0);
497 gst_caps_append_structure_unchecked (caps1, structure);
499 gst_caps_unref (caps2); /* guaranteed to free it */
505 * @caps1: (transfer full): the #GstCaps that will take the new entries
506 * @caps2: (transfer full): the #GstCaps to merge in
508 * Appends the structures contained in @caps2 to @caps1 if they are not yet
509 * expressed by @caps1. The structures in @caps2 are not copied -- they are
510 * transferred to a writable copy of @caps1, and then @caps2 is freed.
511 * If either caps is ANY, the resulting caps will be ANY.
513 * Returns: (transfer full): the merged caps.
518 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
520 GstStructure *structure;
524 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
525 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
527 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
528 gst_caps_unref (caps2);
530 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
531 gst_caps_unref (caps1);
534 caps2 = gst_caps_make_writable (caps2);
536 for (i = GST_CAPS_LEN (caps2); i; i--) {
537 structure = gst_caps_remove_and_get_structure (caps2, 0);
538 caps1 = gst_caps_merge_structure (caps1, structure);
540 gst_caps_unref (caps2);
544 GstCaps *com = gst_caps_intersect (caps1, caps2);
545 GstCaps *add = gst_caps_subtract (caps2, com);
547 GST_DEBUG ("common : %d", gst_caps_get_size (com));
548 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
549 gst_caps_append (caps1, add);
550 gst_caps_unref (com);
558 * gst_caps_append_structure:
559 * @caps: the #GstCaps that will be appended to
560 * @structure: (transfer full): the #GstStructure to append
562 * Appends @structure to @caps. The structure is not copied; @caps
563 * becomes the owner of @structure.
566 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
568 g_return_if_fail (GST_IS_CAPS (caps));
569 g_return_if_fail (IS_WRITABLE (caps));
571 if (G_LIKELY (structure)) {
572 gst_caps_append_structure_unchecked (caps, structure);
577 * gst_caps_remove_structure:
578 * @caps: the #GstCaps to remove from
579 * @idx: Index of the structure to remove
581 * removes the stucture with the given index from the list of structures
582 * contained in @caps.
585 gst_caps_remove_structure (GstCaps * caps, guint idx)
587 GstStructure *structure;
589 g_return_if_fail (caps != NULL);
590 g_return_if_fail (idx <= gst_caps_get_size (caps));
591 g_return_if_fail (IS_WRITABLE (caps));
593 structure = gst_caps_remove_and_get_structure (caps, idx);
594 gst_structure_free (structure);
598 * gst_caps_merge_structure:
599 * @caps: (transfer full): the #GstCaps to merge into
600 * @structure: (transfer full): the #GstStructure to merge
602 * Appends @structure to @caps if its not already expressed by @caps.
604 * Returns: (transfer full): the merged caps.
607 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
609 GstStructure *structure1;
611 gboolean unique = TRUE;
613 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
615 if (G_UNLIKELY (structure == NULL))
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 caps = gst_caps_make_writable (caps);
629 gst_caps_append_structure_unchecked (caps, structure);
631 gst_structure_free (structure);
640 * Gets the number of structures contained in @caps.
642 * Returns: the number of structures that @caps contains
645 gst_caps_get_size (const GstCaps * caps)
647 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
649 return GST_CAPS_LEN (caps);
653 * gst_caps_get_structure:
655 * @index: the index of the structure
657 * Finds the structure in @caps that has the index @index, and
660 * WARNING: This function takes a const GstCaps *, but returns a
661 * non-const GstStructure *. This is for programming convenience --
662 * the caller should be aware that structures inside a constant
663 * #GstCaps should not be modified. However, if you know the caps
664 * are writable, either because you have just copied them or made
665 * them writable with gst_caps_make_writable(), you may modify the
666 * structure returned in the usual way, e.g. with functions like
667 * gst_structure_set().
669 * You do not need to free or unref the structure returned, it
670 * belongs to the #GstCaps.
672 * Returns: (transfer none): a pointer to the #GstStructure corresponding
676 gst_caps_get_structure (const GstCaps * caps, guint index)
678 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
679 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
681 return gst_caps_get_structure_unchecked (caps, index);
686 * @caps: the #GstCaps to copy
687 * @nth: the nth structure to copy
689 * Creates a new #GstCaps and appends a copy of the nth structure
690 * contained in @caps.
692 * Returns: (transfer full): the new #GstCaps
695 gst_caps_copy_nth (const GstCaps * caps, guint nth)
698 GstStructure *structure;
700 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
702 newcaps = gst_caps_new_empty ();
703 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
705 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
706 structure = gst_caps_get_structure_unchecked (caps, nth);
707 gst_caps_append_structure_unchecked (newcaps,
708 gst_structure_copy (structure));
716 * @caps: (transfer full): the #GstCaps to truncate
718 * Discard all but the first structure from @caps. Useful when
721 * Returns: (transfer full): truncated caps
724 gst_caps_truncate (GstCaps * caps)
728 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
730 i = GST_CAPS_LEN (caps) - 1;
734 caps = gst_caps_make_writable (caps);
736 gst_caps_remove_structure (caps, i--);
742 * gst_caps_set_value:
743 * @caps: a writable caps
744 * @field: name of the field to set
745 * @value: value to set the field to
747 * Sets the given @field on all structures of @caps to the given @value.
748 * This is a convenience function for calling gst_structure_set_value() on
749 * all structures of @caps.
754 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
758 g_return_if_fail (GST_IS_CAPS (caps));
759 g_return_if_fail (IS_WRITABLE (caps));
760 g_return_if_fail (field != NULL);
761 g_return_if_fail (G_IS_VALUE (value));
763 len = GST_CAPS_LEN (caps);
764 for (i = 0; i < len; i++) {
765 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
766 gst_structure_set_value (structure, field, value);
771 * gst_caps_set_simple_valist:
772 * @caps: the #GstCaps to set
773 * @field: first field to set
774 * @varargs: additional parameters
776 * Sets fields in a #GstCaps. The arguments must be passed in the same
777 * manner as gst_structure_set(), and be NULL-terminated.
778 * <note>Prior to GStreamer version 0.10.26, this function failed when
779 * @caps was not simple. If your code needs to work with those versions
780 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
781 * is %TRUE for @caps.</note>
784 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
786 GValue value = { 0, };
788 g_return_if_fail (GST_IS_CAPS (caps));
789 g_return_if_fail (IS_WRITABLE (caps));
795 type = va_arg (varargs, GType);
797 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
798 if (G_UNLIKELY (err)) {
799 g_critical ("%s", err);
803 gst_caps_set_value (caps, field, &value);
805 g_value_unset (&value);
807 field = va_arg (varargs, const gchar *);
812 * gst_caps_set_simple:
813 * @caps: the #GstCaps to set
814 * @field: first field to set
815 * @...: additional parameters
817 * Sets fields in a #GstCaps. The arguments must be passed in the same
818 * manner as gst_structure_set(), and be NULL-terminated.
819 * <note>Prior to GStreamer version 0.10.26, this function failed when
820 * @caps was not simple. If your code needs to work with those versions
821 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
822 * is %TRUE for @caps.</note>
825 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
829 g_return_if_fail (GST_IS_CAPS (caps));
830 g_return_if_fail (IS_WRITABLE (caps));
832 va_start (var_args, field);
833 gst_caps_set_simple_valist (caps, field, var_args);
841 * @caps: the #GstCaps to test
843 * Determines if @caps represents any media format.
845 * Returns: TRUE if @caps represents any format.
848 gst_caps_is_any (const GstCaps * caps)
850 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
852 return (CAPS_IS_ANY (caps));
857 * @caps: the #GstCaps to test
859 * Determines if @caps represents no media formats.
861 * Returns: TRUE if @caps represents no formats.
864 gst_caps_is_empty (const GstCaps * caps)
866 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
868 if (CAPS_IS_ANY (caps))
871 return CAPS_IS_EMPTY_SIMPLE (caps);
875 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
878 return gst_value_is_fixed (value);
883 * @caps: the #GstCaps to test
885 * Fixed #GstCaps describe exactly one format, that is, they have exactly
886 * one structure, and each field in the structure describes a fixed type.
887 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
889 * Returns: TRUE if @caps is fixed
892 gst_caps_is_fixed (const GstCaps * caps)
894 GstStructure *structure;
896 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
898 if (GST_CAPS_LEN (caps) != 1)
901 structure = gst_caps_get_structure_unchecked (caps, 0);
903 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
907 * gst_caps_is_equal_fixed:
908 * @caps1: the #GstCaps to test
909 * @caps2: the #GstCaps to test
911 * Tests if two #GstCaps are equal. This function only works on fixed
914 * Returns: TRUE if the arguments represent the same format
917 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
919 GstStructure *struct1, *struct2;
921 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
922 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
924 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
925 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
927 return gst_structure_is_equal (struct1, struct2);
931 * gst_caps_is_always_compatible:
932 * @caps1: the #GstCaps to test
933 * @caps2: the #GstCaps to test
935 * A given #GstCaps structure is always compatible with another if
936 * every media format that is in the first is also contained in the
937 * second. That is, @caps1 is a subset of @caps2.
939 * Returns: TRUE if @caps1 is a subset of @caps2.
942 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
944 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
945 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
947 return gst_caps_is_subset (caps1, caps2);
951 * gst_caps_is_subset:
952 * @subset: a #GstCaps
953 * @superset: a potentially greater #GstCaps
955 * Checks if all caps represented by @subset are also represented by @superset.
956 * <note>This function does not work reliably if optional properties for caps
957 * are included on one caps and omitted on the other.</note>
959 * Returns: %TRUE if @subset is a subset of @superset
962 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
964 GstStructure *s1, *s2;
968 g_return_val_if_fail (subset != NULL, FALSE);
969 g_return_val_if_fail (superset != NULL, FALSE);
971 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
973 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
976 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
977 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
978 s1 = gst_caps_get_structure_unchecked (subset, i);
979 s2 = gst_caps_get_structure_unchecked (superset, j);
980 if (gst_structure_is_subset (s1, s2)) {
981 /* If we found a superset, continue with the next
982 * subset structure */
986 /* If we found no superset for this subset structure
987 * we return FALSE immediately */
998 * gst_caps_is_subset_structure:
1000 * @structure: a potential #GstStructure subset of @caps
1002 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1003 * for more information.
1005 * Returns: %TRUE if @structure is a subset of @caps
1010 gst_caps_is_subset_structure (const GstCaps * caps,
1011 const GstStructure * structure)
1016 g_return_val_if_fail (caps != NULL, FALSE);
1017 g_return_val_if_fail (structure != NULL, FALSE);
1019 if (CAPS_IS_ANY (caps))
1021 if (CAPS_IS_EMPTY (caps))
1024 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1025 s = gst_caps_get_structure_unchecked (caps, i);
1026 if (gst_structure_is_subset (structure, s)) {
1027 /* If we found a superset return TRUE */
1036 * gst_caps_is_equal:
1037 * @caps1: a #GstCaps
1038 * @caps2: another #GstCaps
1040 * Checks if the given caps represent the same set of caps.
1041 * <note>This function does not work reliably if optional properties for caps
1042 * are included on one caps and omitted on the other.</note>
1044 * Returns: TRUE if both caps are equal.
1047 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1049 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1050 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1052 if (G_UNLIKELY (caps1 == caps2))
1055 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1056 return gst_caps_is_equal_fixed (caps1, caps2);
1058 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1062 * gst_caps_is_strictly_equal:
1063 * @caps1: a #GstCaps
1064 * @caps2: another #GstCaps
1066 * Checks if the given caps are exactly the same set of caps.
1068 * This function deals correctly with passing NULL for any of the caps.
1070 * Returns: TRUE if both caps are strictly equal.
1075 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1079 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1080 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1082 if (G_UNLIKELY (caps1 == caps2))
1085 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1088 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1089 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1090 gst_caps_get_structure_unchecked (caps2, i)))
1097 /* intersect operation */
1100 * gst_caps_can_intersect:
1101 * @caps1: a #GstCaps to intersect
1102 * @caps2: a #GstCaps to intersect
1104 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1107 * Returns: %TRUE if intersection would be not empty
1112 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1114 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1115 guint j, k, len1, len2;
1116 GstStructure *struct1;
1117 GstStructure *struct2;
1119 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1120 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1122 /* caps are exactly the same pointers */
1123 if (G_UNLIKELY (caps1 == caps2))
1126 /* empty caps on either side, return empty */
1127 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1130 /* one of the caps is any */
1131 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1134 /* run zigzag on top line then right line, this preserves the caps order
1135 * much better than a simple loop.
1137 * This algorithm zigzags over the caps structures as demonstrated in
1138 * the following matrix:
1141 * +------------- total distance: +-------------
1142 * | 1 2 4 7 0 | 0 1 2 3
1143 * caps2 | 3 5 8 10 1 | 1 2 3 4
1144 * | 6 9 11 12 2 | 2 3 4 5
1146 * First we iterate over the caps1 structures (top line) intersecting
1147 * the structures diagonally down, then we iterate over the caps2
1148 * structures. The result is that the intersections are ordered based on the
1149 * sum of the indexes in the list.
1151 len1 = GST_CAPS_LEN (caps1);
1152 len2 = GST_CAPS_LEN (caps2);
1153 for (i = 0; i < len1 + len2 - 1; i++) {
1154 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1155 j = MIN (i, len1 - 1);
1156 /* subset index stays 0 until i reaches superset->structs->len, then it
1157 * counts up from 1 to subset->structs->len - 1 */
1158 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1160 /* now run the diagonal line, end condition is the left or bottom
1163 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1164 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1166 if (gst_structure_can_intersect (struct1, struct2)) {
1169 /* move down left */
1171 if (G_UNLIKELY (j == 0))
1172 break; /* so we don't roll back to G_MAXUINT */
1180 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1182 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1183 guint j, k, len1, len2;
1185 GstStructure *struct1;
1186 GstStructure *struct2;
1188 GstStructure *istruct;
1190 /* caps are exactly the same pointers, just copy one caps */
1191 if (G_UNLIKELY (caps1 == caps2))
1192 return gst_caps_ref (caps1);
1194 /* empty caps on either side, return empty */
1195 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1196 return gst_caps_ref (GST_CAPS_NONE);
1198 /* one of the caps is any, just copy the other caps */
1199 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1200 return gst_caps_ref (caps2);
1201 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1202 return gst_caps_ref (caps1);
1204 dest = gst_caps_new_empty ();
1206 /* run zigzag on top line then right line, this preserves the caps order
1207 * much better than a simple loop.
1209 * This algorithm zigzags over the caps structures as demonstrated in
1210 * the following matrix:
1218 * First we iterate over the caps1 structures (top line) intersecting
1219 * the structures diagonally down, then we iterate over the caps2
1222 len1 = GST_CAPS_LEN (caps1);
1223 len2 = GST_CAPS_LEN (caps2);
1224 for (i = 0; i < len1 + len2 - 1; i++) {
1225 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1226 j = MIN (i, len1 - 1);
1227 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1228 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1229 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1231 /* now run the diagonal line, end condition is the left or bottom
1234 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1235 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1237 istruct = gst_structure_intersect (struct1, struct2);
1239 dest = gst_caps_merge_structure (dest, istruct);
1240 /* move down left */
1242 if (G_UNLIKELY (j == 0))
1243 break; /* so we don't roll back to G_MAXUINT */
1251 * gst_caps_intersect_first:
1252 * @caps1: a #GstCaps to intersect
1253 * @caps2: a #GstCaps to intersect
1255 * Creates a new #GstCaps that contains all the formats that are common
1256 * to both @caps1 and @caps2.
1258 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1259 * fashion as @caps1.
1261 * Returns: the new #GstCaps
1264 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1267 guint j, len1, len2;
1269 GstStructure *struct1;
1270 GstStructure *struct2;
1272 GstStructure *istruct;
1274 /* caps are exactly the same pointers, just copy one caps */
1275 if (G_UNLIKELY (caps1 == caps2))
1276 return gst_caps_ref (caps1);
1278 /* empty caps on either side, return empty */
1279 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1280 return gst_caps_ref (GST_CAPS_NONE);
1282 /* one of the caps is any, just copy the other caps */
1283 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1284 return gst_caps_ref (caps2);
1285 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1286 return gst_caps_ref (caps1);
1288 dest = gst_caps_new_empty ();
1290 len1 = GST_CAPS_LEN (caps1);
1291 len2 = GST_CAPS_LEN (caps2);
1292 for (i = 0; i < len1; i++) {
1293 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1294 for (j = 0; j < len2; j++) {
1295 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1296 istruct = gst_structure_intersect (struct1, struct2);
1298 dest = gst_caps_merge_structure (dest, istruct);
1306 * gst_caps_intersect_full:
1307 * @caps1: a #GstCaps to intersect
1308 * @caps2: a #GstCaps to intersect
1309 * @mode: The intersection algorithm/mode to use
1311 * Creates a new #GstCaps that contains all the formats that are common
1312 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1315 * Returns: the new #GstCaps
1319 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1320 GstCapsIntersectMode mode)
1322 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1323 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1326 case GST_CAPS_INTERSECT_FIRST:
1327 return gst_caps_intersect_first (caps1, caps2);
1329 g_warning ("Unknown caps intersect mode: %d", mode);
1331 case GST_CAPS_INTERSECT_ZIG_ZAG:
1332 return gst_caps_intersect_zig_zag (caps1, caps2);
1337 * gst_caps_intersect:
1338 * @caps1: a #GstCaps to intersect
1339 * @caps2: a #GstCaps to intersect
1341 * Creates a new #GstCaps that contains all the formats that are common
1342 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1344 * Returns: the new #GstCaps
1347 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1349 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1353 /* subtract operation */
1357 const GstStructure *subtract_from;
1363 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1366 SubtractionEntry *e = user_data;
1367 GValue subtraction = { 0, };
1368 const GValue *other;
1369 GstStructure *structure;
1371 other = gst_structure_id_get_value (e->subtract_from, field_id);
1375 if (!gst_value_subtract (&subtraction, other, value))
1377 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1378 g_value_unset (&subtraction);
1381 structure = gst_structure_copy (e->subtract_from);
1382 gst_structure_id_set_value (structure, field_id, &subtraction);
1383 g_value_unset (&subtraction);
1384 e->put_into = g_slist_prepend (e->put_into, structure);
1390 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1391 const GstStructure * subtrahend)
1396 e.subtract_from = minuend;
1399 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1400 gst_caps_structure_subtract_field, &e);
1406 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1407 gst_structure_free (walk->data);
1409 g_slist_free (e.put_into);
1415 * gst_caps_subtract:
1416 * @minuend: #GstCaps to subtract from
1417 * @subtrahend: #GstCaps to subtract
1419 * Subtracts the @subtrahend from the @minuend.
1420 * <note>This function does not work reliably if optional properties for caps
1421 * are included on one caps and omitted on the other.</note>
1423 * Returns: the resulting caps
1426 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1431 GstCaps *dest = NULL, *src;
1433 g_return_val_if_fail (minuend != NULL, NULL);
1434 g_return_val_if_fail (subtrahend != NULL, NULL);
1436 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1437 return gst_caps_new_empty ();
1439 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1440 return gst_caps_ref (minuend);
1442 /* FIXME: Do we want this here or above?
1443 The reason we need this is that there is no definition about what
1444 ANY means for specific types, so it's not possible to reduce ANY partially
1445 You can only remove everything or nothing and that is done above.
1446 Note: there's a test that checks this behaviour. */
1447 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1448 sublen = GST_CAPS_LEN (subtrahend);
1449 g_assert (sublen > 0);
1451 src = _gst_caps_copy (minuend);
1452 for (i = 0; i < sublen; i++) {
1455 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1457 gst_caps_unref (src);
1460 dest = gst_caps_new_empty ();
1461 srclen = GST_CAPS_LEN (src);
1462 for (j = 0; j < srclen; j++) {
1463 min = gst_caps_get_structure_unchecked (src, j);
1464 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1467 if (gst_caps_structure_subtract (&list, min, sub)) {
1470 for (walk = list; walk; walk = g_slist_next (walk)) {
1471 gst_caps_append_structure_unchecked (dest,
1472 (GstStructure *) walk->data);
1474 g_slist_free (list);
1476 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1479 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1482 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1483 gst_caps_unref (src);
1488 gst_caps_unref (src);
1489 dest = gst_caps_simplify (dest);
1493 /* normalize/simplify operations */
1495 typedef struct _NormalizeForeach
1498 GstStructure *structure;
1503 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1505 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1509 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1510 guint len = gst_value_list_get_size (value);
1511 for (i = 1; i < len; i++) {
1512 const GValue *v = gst_value_list_get_value (value, i);
1513 GstStructure *structure = gst_structure_copy (nf->structure);
1515 gst_structure_id_set_value (structure, field_id, v);
1516 gst_caps_append_structure_unchecked (nf->caps, structure);
1519 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1520 gst_structure_id_set_value (nf->structure, field_id, &val);
1521 g_value_unset (&val);
1529 * gst_caps_normalize:
1530 * @caps: (transfer full): a #GstCaps to normalize
1532 * Returns a #GstCaps that represents the same set of formats as
1533 * @caps, but contains no lists. Each list is expanded into separate
1536 * This function takes ownership of @caps.
1538 * Returns: (transfer full): the normalized #GstCaps
1541 gst_caps_normalize (GstCaps * caps)
1543 NormalizeForeach nf;
1546 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1548 caps = gst_caps_make_writable (caps);
1552 for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1553 nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1555 while (!gst_structure_foreach (nf.structure,
1556 gst_caps_normalize_foreach, &nf));
1563 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1566 const GstStructure *struct1 = *((const GstStructure **) one);
1567 const GstStructure *struct2 = *((const GstStructure **) two);
1569 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1570 So what's the best way? */
1571 ret = strcmp (gst_structure_get_name (struct1),
1572 gst_structure_get_name (struct2));
1576 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1583 GstStructure *compare;
1588 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1591 UnionField *u = user_data;
1592 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1596 g_value_unset (&u->value);
1599 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1602 g_value_unset (&u->value);
1606 gst_value_union (&u->value, val, value);
1611 gst_caps_structure_simplify (GstStructure ** result,
1612 GstStructure * simplify, GstStructure * compare)
1615 UnionField field = { 0, {0,}, NULL };
1617 /* try to subtract to get a real subset */
1618 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1619 if (list == NULL) { /* no result */
1622 } else if (list->next == NULL) { /* one result */
1623 *result = list->data;
1624 g_slist_free (list);
1626 } else { /* multiple results */
1627 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1628 g_slist_free (list);
1633 /* try to union both structs */
1634 field.compare = compare;
1635 if (gst_structure_foreach (simplify,
1636 gst_caps_structure_figure_out_union, &field)) {
1637 gboolean ret = FALSE;
1639 /* now we know all of simplify's fields are the same in compare
1640 * but at most one field: field.name */
1641 if (G_IS_VALUE (&field.value)) {
1642 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1643 gst_structure_id_set_value (compare, field.name, &field.value);
1647 g_value_unset (&field.value);
1648 } else if (gst_structure_n_fields (simplify) <=
1649 gst_structure_n_fields (compare)) {
1650 /* compare is just more specific, will be optimized away later */
1651 /* FIXME: do this here? */
1652 GST_LOG ("found a case that will be optimized later.");
1654 gchar *one = gst_structure_to_string (simplify);
1655 gchar *two = gst_structure_to_string (compare);
1658 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1670 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1671 GstStructure * new, gint i)
1673 gst_structure_set_parent_refcount (old, NULL);
1674 gst_structure_free (old);
1675 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1676 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1680 * gst_caps_simplify:
1681 * @caps: (transfer full): a #GstCaps to simplify
1683 * Converts the given @caps into a representation that represents the
1684 * same set of formats, but in a simpler form. Component structures that are
1685 * identical are merged. Component structures that have values that can be
1686 * merged are also merged.
1688 * This method does not preserve the original order of @caps.
1690 * Returns: The simplified caps.
1693 gst_caps_simplify (GstCaps * caps)
1695 GstStructure *simplify, *compare, *result = NULL;
1698 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1700 start = GST_CAPS_LEN (caps) - 1;
1701 /* one caps, already as simple as can be */
1705 caps = gst_caps_make_writable (caps);
1707 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1709 for (i = start; i >= 0; i--) {
1710 simplify = gst_caps_get_structure_unchecked (caps, i);
1711 compare = gst_caps_get_structure_unchecked (caps, start);
1712 if (gst_structure_get_name_id (simplify) !=
1713 gst_structure_get_name_id (compare))
1715 for (j = start; j >= 0; j--) {
1718 compare = gst_caps_get_structure_unchecked (caps, j);
1719 if (gst_structure_get_name_id (simplify) !=
1720 gst_structure_get_name_id (compare)) {
1723 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1725 gst_caps_switch_structures (caps, simplify, result, i);
1728 gst_caps_remove_structure (caps, i);
1740 * @caps: (transfer full): a #GstCaps to fixate
1742 * Modifies the given @caps into a representation with only fixed
1743 * values. First the caps will be truncated and then the first structure will be
1744 * fixated with gst_structure_fixate().
1746 * Returns: (transfer full): the fixated caps
1749 gst_caps_fixate (GstCaps * caps)
1753 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1755 /* default fixation */
1756 caps = gst_caps_truncate (caps);
1757 caps = gst_caps_make_writable (caps);
1758 s = gst_caps_get_structure (caps, 0);
1759 gst_structure_fixate (s);
1767 * gst_caps_to_string:
1770 * Converts @caps to a string representation. This string representation
1771 * can be converted back to a #GstCaps by gst_caps_from_string().
1773 * For debugging purposes its easier to do something like this:
1775 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1777 * This prints the caps in human readable form.
1779 * Returns: (transfer full): a newly allocated string representing @caps.
1782 gst_caps_to_string (const GstCaps * caps)
1784 guint i, slen, clen;
1787 /* NOTE: This function is potentially called by the debug system,
1788 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1789 * should be careful to avoid recursion. This includes any functions
1790 * called by gst_caps_to_string. In particular, calls should
1791 * not use the GST_PTR_FORMAT extension. */
1794 return g_strdup ("NULL");
1796 if (CAPS_IS_ANY (caps)) {
1797 return g_strdup ("ANY");
1799 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1800 return g_strdup ("EMPTY");
1803 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1805 clen = GST_CAPS_LEN (caps);
1806 for (i = 0; i < clen; i++) {
1808 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1812 s = g_string_sized_new (slen);
1813 for (i = 0; i < clen; i++) {
1814 GstStructure *structure;
1817 /* ';' is now added by gst_structure_to_string */
1818 g_string_append_c (s, ' ');
1821 structure = gst_caps_get_structure_unchecked (caps, i);
1822 priv_gst_structure_append_to_gstring (structure, s);
1824 if (s->len && s->str[s->len - 1] == ';') {
1825 /* remove latest ';' */
1826 s->str[--s->len] = '\0';
1828 return g_string_free (s, FALSE);
1832 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1834 GstStructure *structure;
1837 if (strcmp ("ANY", string) == 0) {
1838 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1841 if (strcmp ("EMPTY", string) == 0) {
1845 structure = gst_structure_from_string (string, &s);
1846 if (structure == NULL) {
1849 gst_caps_append_structure_unchecked (caps, structure);
1853 while (g_ascii_isspace (*s))
1858 structure = gst_structure_from_string (s, &s);
1859 if (structure == NULL) {
1862 gst_caps_append_structure_unchecked (caps, structure);
1870 * gst_caps_from_string:
1871 * @string: a string to convert to #GstCaps
1873 * Converts @caps from a string representation.
1875 * Returns: (transfer full): a newly allocated #GstCaps
1878 gst_caps_from_string (const gchar * string)
1882 g_return_val_if_fail (string, FALSE);
1884 caps = gst_caps_new_empty ();
1885 if (gst_caps_from_string_inplace (caps, string)) {
1888 gst_caps_unref (caps);
1894 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1896 g_return_if_fail (G_IS_VALUE (src_value));
1897 g_return_if_fail (G_IS_VALUE (dest_value));
1898 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1899 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1900 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1902 g_value_take_string (dest_value,
1903 gst_caps_to_string (gst_value_get_caps (src_value)));