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
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 (GST_MINI_OBJECT_SIZE (caps), caps);
186 gst_caps_init (GstCaps * caps, gsize size)
188 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
190 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
191 caps->mini_object.dispose = NULL;
192 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
194 /* the 32 has been determined by logging caps sizes in _gst_caps_free
195 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
197 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
199 GST_CAPS_ARRAY (caps) = g_ptr_array_new ();
203 * gst_caps_new_empty:
205 * Creates a new #GstCaps that is empty. That is, the returned
206 * #GstCaps contains no media formats.
207 * The #GstCaps is guaranteed to be writable.
208 * Caller is responsible for unreffing the returned caps.
210 * Returns: (transfer full): the new #GstCaps
213 gst_caps_new_empty (void)
217 caps = (GstCaps *) g_slice_new (GstCapsImpl);
219 gst_caps_init (caps, sizeof (GstCapsImpl));
221 #ifdef DEBUG_REFCOUNT
222 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
231 * Creates a new #GstCaps that indicates that it is compatible with
234 * Returns: (transfer full): the new #GstCaps
237 gst_caps_new_any (void)
239 GstCaps *caps = gst_caps_new_empty ();
241 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
247 * gst_caps_new_empty_simple:
248 * @media_type: the media type of the structure
250 * Creates a new #GstCaps that contains one #GstStructure with name
252 * Caller is responsible for unreffing the returned caps.
254 * Returns: (transfer full): the new #GstCaps
257 gst_caps_new_empty_simple (const char *media_type)
260 GstStructure *structure;
262 caps = gst_caps_new_empty ();
263 structure = gst_structure_new_empty (media_type);
265 gst_caps_append_structure_unchecked (caps, structure);
271 * gst_caps_new_simple:
272 * @media_type: the media type of the structure
273 * @fieldname: first field to set
274 * @...: additional arguments
276 * Creates a new #GstCaps that contains one #GstStructure. The
277 * structure is defined by the arguments, which have the same format
278 * as gst_structure_new().
279 * Caller is responsible for unreffing the returned caps.
281 * Returns: (transfer full): the new #GstCaps
284 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
287 GstStructure *structure;
290 caps = gst_caps_new_empty ();
292 va_start (var_args, fieldname);
293 structure = gst_structure_new_valist (media_type, fieldname, var_args);
297 gst_caps_append_structure_unchecked (caps, structure);
299 gst_caps_replace (&caps, NULL);
306 * @struct1: the first structure to add
307 * @...: additional structures to add
309 * Creates a new #GstCaps and adds all the structures listed as
310 * arguments. The list must be NULL-terminated. The structures
311 * are not copied; the returned #GstCaps owns the structures.
313 * Returns: (transfer full): the new #GstCaps
316 gst_caps_new_full (GstStructure * struct1, ...)
321 va_start (var_args, struct1);
322 caps = gst_caps_new_full_valist (struct1, var_args);
329 * gst_caps_new_full_valist:
330 * @structure: the first structure to add
331 * @var_args: additional structures to add
333 * Creates a new #GstCaps and adds all the structures listed as
334 * arguments. The list must be NULL-terminated. The structures
335 * are not copied; the returned #GstCaps owns the structures.
337 * Returns: (transfer full): the new #GstCaps
340 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
344 caps = gst_caps_new_empty ();
347 gst_caps_append_structure_unchecked (caps, structure);
348 structure = va_arg (var_args, GstStructure *);
354 G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
357 * gst_static_caps_get:
358 * @static_caps: the #GstStaticCaps to convert
360 * Converts a #GstStaticCaps to a #GstCaps.
362 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
363 * Since the core holds an additional ref to the returned caps,
364 * use gst_caps_make_writable() on the returned caps to modify it.
367 gst_static_caps_get (GstStaticCaps * static_caps)
371 g_return_val_if_fail (static_caps != NULL, NULL);
373 caps = &static_caps->caps;
375 /* refcount is 0 when we need to convert */
376 if (G_UNLIKELY (*caps == NULL)) {
379 G_LOCK (static_caps_lock);
380 /* check if other thread already updated */
381 if (G_UNLIKELY (*caps != NULL))
384 string = static_caps->string;
386 if (G_UNLIKELY (string == NULL))
389 *caps = gst_caps_from_string (string);
391 /* convert to string */
392 if (G_UNLIKELY (*caps == NULL))
393 g_critical ("Could not convert static caps \"%s\"", string);
395 GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
398 G_UNLOCK (static_caps_lock);
400 /* ref the caps, makes it not writable */
401 if (G_LIKELY (*caps != NULL))
402 gst_caps_ref (*caps);
409 G_UNLOCK (static_caps_lock);
410 g_warning ("static caps %p string is NULL", static_caps);
416 * gst_static_caps_cleanup:
417 * @static_caps: the #GstStaticCaps to clean
419 * Clean up the cached caps contained in @static_caps.
422 gst_static_caps_cleanup (GstStaticCaps * static_caps)
424 G_LOCK (static_caps_lock);
425 gst_caps_replace (&static_caps->caps, NULL);
426 G_UNLOCK (static_caps_lock);
431 static GstStructure *
432 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
434 /* don't use index_fast, gst_caps_simplify relies on the order */
435 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
437 gst_structure_set_parent_refcount (s, NULL);
442 * gst_caps_steal_structure:
443 * @caps: the #GstCaps to retrieve from
444 * @index: Index of the structure to retrieve
446 * Retrieves the structure with the given index from the list of structures
447 * contained in @caps. The caller becomes the owner of the returned structure.
449 * Returns: (transfer full): a pointer to the #GstStructure corresponding
455 gst_caps_steal_structure (GstCaps * caps, guint index)
457 g_return_val_if_fail (caps != NULL, NULL);
458 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
460 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
463 return gst_caps_remove_and_get_structure (caps, index);
468 * @caps1: the #GstCaps that will be appended to
469 * @caps2: (transfer full): the #GstCaps to append
471 * Appends the structures contained in @caps2 to @caps1. The structures in
472 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
473 * freed. If either caps is ANY, the resulting caps will be ANY.
476 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
478 GstStructure *structure;
481 g_return_if_fail (GST_IS_CAPS (caps1));
482 g_return_if_fail (GST_IS_CAPS (caps2));
483 g_return_if_fail (IS_WRITABLE (caps1));
485 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
486 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
487 gst_caps_unref (caps2);
489 caps2 = gst_caps_make_writable (caps2);
491 for (i = GST_CAPS_LEN (caps2); i; i--) {
492 structure = gst_caps_remove_and_get_structure (caps2, 0);
493 gst_caps_append_structure_unchecked (caps1, structure);
495 gst_caps_unref (caps2); /* guaranteed to free it */
501 * @caps1: (transfer full): the #GstCaps that will take the new entries
502 * @caps2: (transfer full): the #GstCaps to merge in
504 * Appends the structures contained in @caps2 to @caps1 if they are not yet
505 * expressed by @caps1. The structures in @caps2 are not copied -- they are
506 * transferred to a writable copy of @caps1, and then @caps2 is freed.
507 * If either caps is ANY, the resulting caps will be ANY.
509 * Returns: (transfer full): the merged caps.
514 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
516 GstStructure *structure;
520 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
521 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
523 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
524 gst_caps_unref (caps2);
526 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
527 gst_caps_unref (caps1);
530 caps2 = gst_caps_make_writable (caps2);
532 for (i = GST_CAPS_LEN (caps2); i; i--) {
533 structure = gst_caps_remove_and_get_structure (caps2, 0);
534 caps1 = gst_caps_merge_structure (caps1, structure);
536 gst_caps_unref (caps2);
540 GstCaps *com = gst_caps_intersect (caps1, caps2);
541 GstCaps *add = gst_caps_subtract (caps2, com);
543 GST_DEBUG ("common : %d", gst_caps_get_size (com));
544 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
545 gst_caps_append (caps1, add);
546 gst_caps_unref (com);
554 * gst_caps_append_structure:
555 * @caps: the #GstCaps that will be appended to
556 * @structure: (transfer full): the #GstStructure to append
558 * Appends @structure to @caps. The structure is not copied; @caps
559 * becomes the owner of @structure.
562 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
564 g_return_if_fail (GST_IS_CAPS (caps));
565 g_return_if_fail (IS_WRITABLE (caps));
567 if (G_LIKELY (structure)) {
568 gst_caps_append_structure_unchecked (caps, structure);
573 * gst_caps_remove_structure:
574 * @caps: the #GstCaps to remove from
575 * @idx: Index of the structure to remove
577 * removes the stucture with the given index from the list of structures
578 * contained in @caps.
581 gst_caps_remove_structure (GstCaps * caps, guint idx)
583 GstStructure *structure;
585 g_return_if_fail (caps != NULL);
586 g_return_if_fail (idx <= gst_caps_get_size (caps));
587 g_return_if_fail (IS_WRITABLE (caps));
589 structure = gst_caps_remove_and_get_structure (caps, idx);
590 gst_structure_free (structure);
594 * gst_caps_merge_structure:
595 * @caps: (transfer full): the #GstCaps to merge into
596 * @structure: (transfer full): the #GstStructure to merge
598 * Appends @structure to @caps if its not already expressed by @caps.
600 * Returns: (transfer full): the merged caps.
603 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
605 GstStructure *structure1;
607 gboolean unique = TRUE;
609 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
611 if (G_UNLIKELY (structure == NULL))
614 /* check each structure */
615 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
616 structure1 = gst_caps_get_structure_unchecked (caps, i);
617 /* if structure is a subset of structure1, then skip it */
618 if (gst_structure_is_subset (structure, structure1)) {
624 caps = gst_caps_make_writable (caps);
625 gst_caps_append_structure_unchecked (caps, structure);
627 gst_structure_free (structure);
636 * Gets the number of structures contained in @caps.
638 * Returns: the number of structures that @caps contains
641 gst_caps_get_size (const GstCaps * caps)
643 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
645 return GST_CAPS_LEN (caps);
649 * gst_caps_get_structure:
651 * @index: the index of the structure
653 * Finds the structure in @caps that has the index @index, and
656 * WARNING: This function takes a const GstCaps *, but returns a
657 * non-const GstStructure *. This is for programming convenience --
658 * the caller should be aware that structures inside a constant
659 * #GstCaps should not be modified. However, if you know the caps
660 * are writable, either because you have just copied them or made
661 * them writable with gst_caps_make_writable(), you may modify the
662 * structure returned in the usual way, e.g. with functions like
663 * gst_structure_set().
665 * You do not need to free or unref the structure returned, it
666 * belongs to the #GstCaps.
668 * Returns: (transfer none): a pointer to the #GstStructure corresponding
672 gst_caps_get_structure (const GstCaps * caps, guint index)
674 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
675 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
677 return gst_caps_get_structure_unchecked (caps, index);
682 * @caps: the #GstCaps to copy
683 * @nth: the nth structure to copy
685 * Creates a new #GstCaps and appends a copy of the nth structure
686 * contained in @caps.
688 * Returns: (transfer full): the new #GstCaps
691 gst_caps_copy_nth (const GstCaps * caps, guint nth)
694 GstStructure *structure;
696 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
698 newcaps = gst_caps_new_empty ();
699 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
701 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
702 structure = gst_caps_get_structure_unchecked (caps, nth);
703 gst_caps_append_structure_unchecked (newcaps,
704 gst_structure_copy (structure));
712 * @caps: (transfer full): the #GstCaps to truncate
714 * Discard all but the first structure from @caps. Useful when
717 * Returns: (transfer full): truncated caps
720 gst_caps_truncate (GstCaps * caps)
724 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
726 i = GST_CAPS_LEN (caps) - 1;
730 caps = gst_caps_make_writable (caps);
732 gst_caps_remove_structure (caps, i--);
738 * gst_caps_set_value:
739 * @caps: a writable caps
740 * @field: name of the field to set
741 * @value: value to set the field to
743 * Sets the given @field on all structures of @caps to the given @value.
744 * This is a convenience function for calling gst_structure_set_value() on
745 * all structures of @caps.
750 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
754 g_return_if_fail (GST_IS_CAPS (caps));
755 g_return_if_fail (IS_WRITABLE (caps));
756 g_return_if_fail (field != NULL);
757 g_return_if_fail (G_IS_VALUE (value));
759 len = GST_CAPS_LEN (caps);
760 for (i = 0; i < len; i++) {
761 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
762 gst_structure_set_value (structure, field, value);
767 * gst_caps_set_simple_valist:
768 * @caps: the #GstCaps to set
769 * @field: first field to set
770 * @varargs: additional parameters
772 * Sets fields in a #GstCaps. The arguments must be passed in the same
773 * manner as gst_structure_set(), and be NULL-terminated.
774 * <note>Prior to GStreamer version 0.10.26, this function failed when
775 * @caps was not simple. If your code needs to work with those versions
776 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
777 * is %TRUE for @caps.</note>
780 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
782 GValue value = { 0, };
784 g_return_if_fail (GST_IS_CAPS (caps));
785 g_return_if_fail (IS_WRITABLE (caps));
791 type = va_arg (varargs, GType);
793 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
794 if (G_UNLIKELY (err)) {
795 g_critical ("%s", err);
799 gst_caps_set_value (caps, field, &value);
801 g_value_unset (&value);
803 field = va_arg (varargs, const gchar *);
808 * gst_caps_set_simple:
809 * @caps: the #GstCaps to set
810 * @field: first field to set
811 * @...: additional parameters
813 * Sets fields in a #GstCaps. The arguments must be passed in the same
814 * manner as gst_structure_set(), and be NULL-terminated.
815 * <note>Prior to GStreamer version 0.10.26, this function failed when
816 * @caps was not simple. If your code needs to work with those versions
817 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
818 * is %TRUE for @caps.</note>
821 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
825 g_return_if_fail (GST_IS_CAPS (caps));
826 g_return_if_fail (IS_WRITABLE (caps));
828 va_start (var_args, field);
829 gst_caps_set_simple_valist (caps, field, var_args);
837 * @caps: the #GstCaps to test
839 * Determines if @caps represents any media format.
841 * Returns: TRUE if @caps represents any format.
844 gst_caps_is_any (const GstCaps * caps)
846 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
848 return (CAPS_IS_ANY (caps));
853 * @caps: the #GstCaps to test
855 * Determines if @caps represents no media formats.
857 * Returns: TRUE if @caps represents no formats.
860 gst_caps_is_empty (const GstCaps * caps)
862 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
864 if (CAPS_IS_ANY (caps))
867 return CAPS_IS_EMPTY_SIMPLE (caps);
871 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
874 return gst_value_is_fixed (value);
879 * @caps: the #GstCaps to test
881 * Fixed #GstCaps describe exactly one format, that is, they have exactly
882 * one structure, and each field in the structure describes a fixed type.
883 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
885 * Returns: TRUE if @caps is fixed
888 gst_caps_is_fixed (const GstCaps * caps)
890 GstStructure *structure;
892 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
894 if (GST_CAPS_LEN (caps) != 1)
897 structure = gst_caps_get_structure_unchecked (caps, 0);
899 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
903 * gst_caps_is_equal_fixed:
904 * @caps1: the #GstCaps to test
905 * @caps2: the #GstCaps to test
907 * Tests if two #GstCaps are equal. This function only works on fixed
910 * Returns: TRUE if the arguments represent the same format
913 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
915 GstStructure *struct1, *struct2;
917 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
918 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
920 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
921 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
923 return gst_structure_is_equal (struct1, struct2);
927 * gst_caps_is_always_compatible:
928 * @caps1: the #GstCaps to test
929 * @caps2: the #GstCaps to test
931 * A given #GstCaps structure is always compatible with another if
932 * every media format that is in the first is also contained in the
933 * second. That is, @caps1 is a subset of @caps2.
935 * Returns: TRUE if @caps1 is a subset of @caps2.
938 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
940 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
941 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
943 return gst_caps_is_subset (caps1, caps2);
947 * gst_caps_is_subset:
948 * @subset: a #GstCaps
949 * @superset: a potentially greater #GstCaps
951 * Checks if all caps represented by @subset are also represented by @superset.
952 * <note>This function does not work reliably if optional properties for caps
953 * are included on one caps and omitted on the other.</note>
955 * Returns: %TRUE if @subset is a subset of @superset
958 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
960 GstStructure *s1, *s2;
964 g_return_val_if_fail (subset != NULL, FALSE);
965 g_return_val_if_fail (superset != NULL, FALSE);
967 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
969 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
972 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
973 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
974 s1 = gst_caps_get_structure_unchecked (subset, i);
975 s2 = gst_caps_get_structure_unchecked (superset, j);
976 if (gst_structure_is_subset (s1, s2)) {
977 /* If we found a superset, continue with the next
978 * subset structure */
982 /* If we found no superset for this subset structure
983 * we return FALSE immediately */
994 * gst_caps_is_subset_structure:
996 * @structure: a potential #GstStructure subset of @caps
998 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
999 * for more information.
1001 * Returns: %TRUE if @structure is a subset of @caps
1006 gst_caps_is_subset_structure (const GstCaps * caps,
1007 const GstStructure * structure)
1012 g_return_val_if_fail (caps != NULL, FALSE);
1013 g_return_val_if_fail (structure != NULL, FALSE);
1015 if (CAPS_IS_ANY (caps))
1017 if (CAPS_IS_EMPTY (caps))
1020 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1021 s = gst_caps_get_structure_unchecked (caps, i);
1022 if (gst_structure_is_subset (structure, s)) {
1023 /* If we found a superset return TRUE */
1032 * gst_caps_is_equal:
1033 * @caps1: a #GstCaps
1034 * @caps2: another #GstCaps
1036 * Checks if the given caps represent the same set of caps.
1037 * <note>This function does not work reliably if optional properties for caps
1038 * are included on one caps and omitted on the other.</note>
1040 * Returns: TRUE if both caps are equal.
1043 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1045 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1046 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1048 if (G_UNLIKELY (caps1 == caps2))
1051 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1052 return gst_caps_is_equal_fixed (caps1, caps2);
1054 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1058 * gst_caps_is_strictly_equal:
1059 * @caps1: a #GstCaps
1060 * @caps2: another #GstCaps
1062 * Checks if the given caps are exactly the same set of caps.
1064 * This function deals correctly with passing NULL for any of the caps.
1066 * Returns: TRUE if both caps are strictly equal.
1071 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1075 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1076 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1078 if (G_UNLIKELY (caps1 == caps2))
1081 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1084 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1085 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1086 gst_caps_get_structure_unchecked (caps2, i)))
1093 /* intersect operation */
1096 * gst_caps_can_intersect:
1097 * @caps1: a #GstCaps to intersect
1098 * @caps2: a #GstCaps to intersect
1100 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1103 * Returns: %TRUE if intersection would be not empty
1108 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1110 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1111 guint j, k, len1, len2;
1112 GstStructure *struct1;
1113 GstStructure *struct2;
1115 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1116 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1118 /* caps are exactly the same pointers */
1119 if (G_UNLIKELY (caps1 == caps2))
1122 /* empty caps on either side, return empty */
1123 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1126 /* one of the caps is any */
1127 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1130 /* run zigzag on top line then right line, this preserves the caps order
1131 * much better than a simple loop.
1133 * This algorithm zigzags over the caps structures as demonstrated in
1134 * the following matrix:
1137 * +------------- total distance: +-------------
1138 * | 1 2 4 7 0 | 0 1 2 3
1139 * caps2 | 3 5 8 10 1 | 1 2 3 4
1140 * | 6 9 11 12 2 | 2 3 4 5
1142 * First we iterate over the caps1 structures (top line) intersecting
1143 * the structures diagonally down, then we iterate over the caps2
1144 * structures. The result is that the intersections are ordered based on the
1145 * sum of the indexes in the list.
1147 len1 = GST_CAPS_LEN (caps1);
1148 len2 = GST_CAPS_LEN (caps2);
1149 for (i = 0; i < len1 + len2 - 1; i++) {
1150 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1151 j = MIN (i, len1 - 1);
1152 /* subset index stays 0 until i reaches superset->structs->len, then it
1153 * counts up from 1 to subset->structs->len - 1 */
1154 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1156 /* now run the diagonal line, end condition is the left or bottom
1159 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1160 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1162 if (gst_structure_can_intersect (struct1, struct2)) {
1165 /* move down left */
1167 if (G_UNLIKELY (j == 0))
1168 break; /* so we don't roll back to G_MAXUINT */
1176 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1178 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1179 guint j, k, len1, len2;
1181 GstStructure *struct1;
1182 GstStructure *struct2;
1184 GstStructure *istruct;
1186 /* caps are exactly the same pointers, just copy one caps */
1187 if (G_UNLIKELY (caps1 == caps2))
1188 return gst_caps_ref (caps1);
1190 /* empty caps on either side, return empty */
1191 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1192 return gst_caps_ref (GST_CAPS_NONE);
1194 /* one of the caps is any, just copy the other caps */
1195 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1196 return gst_caps_ref (caps2);
1197 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1198 return gst_caps_ref (caps1);
1200 dest = gst_caps_new_empty ();
1202 /* run zigzag on top line then right line, this preserves the caps order
1203 * much better than a simple loop.
1205 * This algorithm zigzags over the caps structures as demonstrated in
1206 * the following matrix:
1214 * First we iterate over the caps1 structures (top line) intersecting
1215 * the structures diagonally down, then we iterate over the caps2
1218 len1 = GST_CAPS_LEN (caps1);
1219 len2 = GST_CAPS_LEN (caps2);
1220 for (i = 0; i < len1 + len2 - 1; i++) {
1221 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1222 j = MIN (i, len1 - 1);
1223 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1224 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1225 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1227 /* now run the diagonal line, end condition is the left or bottom
1230 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1231 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1233 istruct = gst_structure_intersect (struct1, struct2);
1235 dest = gst_caps_merge_structure (dest, istruct);
1236 /* move down left */
1238 if (G_UNLIKELY (j == 0))
1239 break; /* so we don't roll back to G_MAXUINT */
1247 * gst_caps_intersect_first:
1248 * @caps1: a #GstCaps to intersect
1249 * @caps2: a #GstCaps to intersect
1251 * Creates a new #GstCaps that contains all the formats that are common
1252 * to both @caps1 and @caps2.
1254 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1255 * fashion as @caps1.
1257 * Returns: the new #GstCaps
1260 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1263 guint j, len1, len2;
1265 GstStructure *struct1;
1266 GstStructure *struct2;
1268 GstStructure *istruct;
1270 /* caps are exactly the same pointers, just copy one caps */
1271 if (G_UNLIKELY (caps1 == caps2))
1272 return gst_caps_ref (caps1);
1274 /* empty caps on either side, return empty */
1275 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1276 return gst_caps_ref (GST_CAPS_NONE);
1278 /* one of the caps is any, just copy the other caps */
1279 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1280 return gst_caps_ref (caps2);
1281 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1282 return gst_caps_ref (caps1);
1284 dest = gst_caps_new_empty ();
1286 len1 = GST_CAPS_LEN (caps1);
1287 len2 = GST_CAPS_LEN (caps2);
1288 for (i = 0; i < len1; i++) {
1289 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1290 for (j = 0; j < len2; j++) {
1291 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1292 istruct = gst_structure_intersect (struct1, struct2);
1294 dest = gst_caps_merge_structure (dest, istruct);
1302 * gst_caps_intersect_full:
1303 * @caps1: a #GstCaps to intersect
1304 * @caps2: a #GstCaps to intersect
1305 * @mode: The intersection algorithm/mode to use
1307 * Creates a new #GstCaps that contains all the formats that are common
1308 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1311 * Returns: the new #GstCaps
1315 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1316 GstCapsIntersectMode mode)
1318 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1319 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1322 case GST_CAPS_INTERSECT_FIRST:
1323 return gst_caps_intersect_first (caps1, caps2);
1325 g_warning ("Unknown caps intersect mode: %d", mode);
1327 case GST_CAPS_INTERSECT_ZIG_ZAG:
1328 return gst_caps_intersect_zig_zag (caps1, caps2);
1333 * gst_caps_intersect:
1334 * @caps1: a #GstCaps to intersect
1335 * @caps2: a #GstCaps to intersect
1337 * Creates a new #GstCaps that contains all the formats that are common
1338 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1340 * Returns: the new #GstCaps
1343 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1345 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1349 /* subtract operation */
1353 const GstStructure *subtract_from;
1359 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1362 SubtractionEntry *e = user_data;
1363 GValue subtraction = { 0, };
1364 const GValue *other;
1365 GstStructure *structure;
1367 other = gst_structure_id_get_value (e->subtract_from, field_id);
1371 if (!gst_value_subtract (&subtraction, other, value))
1373 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1374 g_value_unset (&subtraction);
1377 structure = gst_structure_copy (e->subtract_from);
1378 gst_structure_id_set_value (structure, field_id, &subtraction);
1379 g_value_unset (&subtraction);
1380 e->put_into = g_slist_prepend (e->put_into, structure);
1386 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1387 const GstStructure * subtrahend)
1392 e.subtract_from = minuend;
1395 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1396 gst_caps_structure_subtract_field, &e);
1402 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1403 gst_structure_free (walk->data);
1405 g_slist_free (e.put_into);
1411 * gst_caps_subtract:
1412 * @minuend: #GstCaps to subtract from
1413 * @subtrahend: #GstCaps to subtract
1415 * Subtracts the @subtrahend from the @minuend.
1416 * <note>This function does not work reliably if optional properties for caps
1417 * are included on one caps and omitted on the other.</note>
1419 * Returns: the resulting caps
1422 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1427 GstCaps *dest = NULL, *src;
1429 g_return_val_if_fail (minuend != NULL, NULL);
1430 g_return_val_if_fail (subtrahend != NULL, NULL);
1432 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1433 return gst_caps_new_empty ();
1435 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1436 return gst_caps_ref (minuend);
1438 /* FIXME: Do we want this here or above?
1439 The reason we need this is that there is no definition about what
1440 ANY means for specific types, so it's not possible to reduce ANY partially
1441 You can only remove everything or nothing and that is done above.
1442 Note: there's a test that checks this behaviour. */
1443 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1444 sublen = GST_CAPS_LEN (subtrahend);
1445 g_assert (sublen > 0);
1447 src = _gst_caps_copy (minuend);
1448 for (i = 0; i < sublen; i++) {
1451 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1453 gst_caps_unref (src);
1456 dest = gst_caps_new_empty ();
1457 srclen = GST_CAPS_LEN (src);
1458 for (j = 0; j < srclen; j++) {
1459 min = gst_caps_get_structure_unchecked (src, j);
1460 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1463 if (gst_caps_structure_subtract (&list, min, sub)) {
1466 for (walk = list; walk; walk = g_slist_next (walk)) {
1467 gst_caps_append_structure_unchecked (dest,
1468 (GstStructure *) walk->data);
1470 g_slist_free (list);
1472 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1475 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1478 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1479 gst_caps_unref (src);
1484 gst_caps_unref (src);
1485 dest = gst_caps_simplify (dest);
1489 /* normalize/simplify operations */
1491 typedef struct _NormalizeForeach
1494 GstStructure *structure;
1499 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1501 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1505 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1506 guint len = gst_value_list_get_size (value);
1507 for (i = 1; i < len; i++) {
1508 const GValue *v = gst_value_list_get_value (value, i);
1509 GstStructure *structure = gst_structure_copy (nf->structure);
1511 gst_structure_id_set_value (structure, field_id, v);
1512 gst_caps_append_structure_unchecked (nf->caps, structure);
1515 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1516 gst_structure_id_set_value (nf->structure, field_id, &val);
1517 g_value_unset (&val);
1525 * gst_caps_normalize:
1526 * @caps: (transfer full): a #GstCaps to normalize
1528 * Returns a #GstCaps that represents the same set of formats as
1529 * @caps, but contains no lists. Each list is expanded into separate
1532 * This function takes ownership of @caps.
1534 * Returns: (transfer full): the normalized #GstCaps
1537 gst_caps_normalize (GstCaps * caps)
1539 NormalizeForeach nf;
1542 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1544 caps = gst_caps_make_writable (caps);
1548 for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1549 nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1551 while (!gst_structure_foreach (nf.structure,
1552 gst_caps_normalize_foreach, &nf));
1559 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1562 const GstStructure *struct1 = *((const GstStructure **) one);
1563 const GstStructure *struct2 = *((const GstStructure **) two);
1565 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1566 So what's the best way? */
1567 ret = strcmp (gst_structure_get_name (struct1),
1568 gst_structure_get_name (struct2));
1572 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1579 GstStructure *compare;
1584 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1587 UnionField *u = user_data;
1588 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1592 g_value_unset (&u->value);
1595 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1598 g_value_unset (&u->value);
1602 gst_value_union (&u->value, val, value);
1607 gst_caps_structure_simplify (GstStructure ** result,
1608 GstStructure * simplify, GstStructure * compare)
1611 UnionField field = { 0, {0,}, NULL };
1613 /* try to subtract to get a real subset */
1614 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1615 if (list == NULL) { /* no result */
1618 } else if (list->next == NULL) { /* one result */
1619 *result = list->data;
1620 g_slist_free (list);
1622 } else { /* multiple results */
1623 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1624 g_slist_free (list);
1629 /* try to union both structs */
1630 field.compare = compare;
1631 if (gst_structure_foreach (simplify,
1632 gst_caps_structure_figure_out_union, &field)) {
1633 gboolean ret = FALSE;
1635 /* now we know all of simplify's fields are the same in compare
1636 * but at most one field: field.name */
1637 if (G_IS_VALUE (&field.value)) {
1638 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1639 gst_structure_id_set_value (compare, field.name, &field.value);
1643 g_value_unset (&field.value);
1644 } else if (gst_structure_n_fields (simplify) <=
1645 gst_structure_n_fields (compare)) {
1646 /* compare is just more specific, will be optimized away later */
1647 /* FIXME: do this here? */
1648 GST_LOG ("found a case that will be optimized later.");
1650 gchar *one = gst_structure_to_string (simplify);
1651 gchar *two = gst_structure_to_string (compare);
1654 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1666 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1667 GstStructure * new, gint i)
1669 gst_structure_set_parent_refcount (old, NULL);
1670 gst_structure_free (old);
1671 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1672 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1676 * gst_caps_simplify:
1677 * @caps: (transfer full): a #GstCaps to simplify
1679 * Converts the given @caps into a representation that represents the
1680 * same set of formats, but in a simpler form. Component structures that are
1681 * identical are merged. Component structures that have values that can be
1682 * merged are also merged.
1684 * This method does not preserve the original order of @caps.
1686 * Returns: The simplified caps.
1689 gst_caps_simplify (GstCaps * caps)
1691 GstStructure *simplify, *compare, *result = NULL;
1694 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1696 start = GST_CAPS_LEN (caps) - 1;
1697 /* one caps, already as simple as can be */
1701 caps = gst_caps_make_writable (caps);
1703 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1705 for (i = start; i >= 0; i--) {
1706 simplify = gst_caps_get_structure_unchecked (caps, i);
1707 compare = gst_caps_get_structure_unchecked (caps, start);
1708 if (gst_structure_get_name_id (simplify) !=
1709 gst_structure_get_name_id (compare))
1711 for (j = start; j >= 0; j--) {
1714 compare = gst_caps_get_structure_unchecked (caps, j);
1715 if (gst_structure_get_name_id (simplify) !=
1716 gst_structure_get_name_id (compare)) {
1719 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1721 gst_caps_switch_structures (caps, simplify, result, i);
1724 gst_caps_remove_structure (caps, i);
1736 * @caps: (transfer full): a #GstCaps to fixate
1738 * Modifies the given @caps into a representation with only fixed
1739 * values. First the caps will be truncated and then the first structure will be
1740 * fixated with gst_structure_fixate().
1742 * Returns: (transfer full): the fixated caps
1745 gst_caps_fixate (GstCaps * caps)
1749 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1751 /* default fixation */
1752 caps = gst_caps_truncate (caps);
1753 caps = gst_caps_make_writable (caps);
1754 s = gst_caps_get_structure (caps, 0);
1755 gst_structure_fixate (s);
1763 * gst_caps_to_string:
1766 * Converts @caps to a string representation. This string representation
1767 * can be converted back to a #GstCaps by gst_caps_from_string().
1769 * For debugging purposes its easier to do something like this:
1771 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1773 * This prints the caps in human readable form.
1775 * Returns: (transfer full): a newly allocated string representing @caps.
1778 gst_caps_to_string (const GstCaps * caps)
1780 guint i, slen, clen;
1783 /* NOTE: This function is potentially called by the debug system,
1784 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1785 * should be careful to avoid recursion. This includes any functions
1786 * called by gst_caps_to_string. In particular, calls should
1787 * not use the GST_PTR_FORMAT extension. */
1790 return g_strdup ("NULL");
1792 if (CAPS_IS_ANY (caps)) {
1793 return g_strdup ("ANY");
1795 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1796 return g_strdup ("EMPTY");
1799 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1801 clen = GST_CAPS_LEN (caps);
1802 for (i = 0; i < clen; i++) {
1804 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1808 s = g_string_sized_new (slen);
1809 for (i = 0; i < clen; i++) {
1810 GstStructure *structure;
1813 /* ';' is now added by gst_structure_to_string */
1814 g_string_append_c (s, ' ');
1817 structure = gst_caps_get_structure_unchecked (caps, i);
1818 priv_gst_structure_append_to_gstring (structure, s);
1820 if (s->len && s->str[s->len - 1] == ';') {
1821 /* remove latest ';' */
1822 s->str[--s->len] = '\0';
1824 return g_string_free (s, FALSE);
1828 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1830 GstStructure *structure;
1833 if (strcmp ("ANY", string) == 0) {
1834 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1837 if (strcmp ("EMPTY", string) == 0) {
1841 structure = gst_structure_from_string (string, &s);
1842 if (structure == NULL) {
1845 gst_caps_append_structure_unchecked (caps, structure);
1849 while (g_ascii_isspace (*s))
1854 structure = gst_structure_from_string (s, &s);
1855 if (structure == NULL) {
1858 gst_caps_append_structure_unchecked (caps, structure);
1866 * gst_caps_from_string:
1867 * @string: a string to convert to #GstCaps
1869 * Converts @caps from a string representation.
1871 * Returns: (transfer full): a newly allocated #GstCaps
1874 gst_caps_from_string (const gchar * string)
1878 g_return_val_if_fail (string, FALSE);
1880 caps = gst_caps_new_empty ();
1881 if (gst_caps_from_string_inplace (caps, string)) {
1884 gst_caps_unref (caps);
1890 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1892 g_return_if_fail (G_IS_VALUE (src_value));
1893 g_return_if_fail (G_IS_VALUE (dest_value));
1894 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1895 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1896 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1898 g_value_take_string (dest_value,
1899 gst_caps_to_string (gst_value_get_caps (src_value)));