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 (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
453 gst_caps_steal_structure (GstCaps * caps, guint index)
455 g_return_val_if_fail (caps != NULL, NULL);
456 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
458 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
461 return gst_caps_remove_and_get_structure (caps, index);
466 * @caps1: the #GstCaps that will be appended to
467 * @caps2: (transfer full): the #GstCaps to append
469 * Appends the structures contained in @caps2 to @caps1. The structures in
470 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
471 * freed. If either caps is ANY, the resulting caps will be ANY.
474 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
476 GstStructure *structure;
479 g_return_if_fail (GST_IS_CAPS (caps1));
480 g_return_if_fail (GST_IS_CAPS (caps2));
481 g_return_if_fail (IS_WRITABLE (caps1));
483 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
484 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
485 gst_caps_unref (caps2);
487 caps2 = gst_caps_make_writable (caps2);
489 for (i = GST_CAPS_LEN (caps2); i; i--) {
490 structure = gst_caps_remove_and_get_structure (caps2, 0);
491 gst_caps_append_structure_unchecked (caps1, structure);
493 gst_caps_unref (caps2); /* guaranteed to free it */
499 * @caps1: (transfer full): the #GstCaps that will take the new entries
500 * @caps2: (transfer full): the #GstCaps to merge in
502 * Appends the structures contained in @caps2 to @caps1 if they are not yet
503 * expressed by @caps1. The structures in @caps2 are not copied -- they are
504 * transferred to a writable copy of @caps1, and then @caps2 is freed.
505 * If either caps is ANY, the resulting caps will be ANY.
507 * Returns: (transfer full): the merged caps.
512 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
514 GstStructure *structure;
518 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
519 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
521 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
522 gst_caps_unref (caps2);
524 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
525 gst_caps_unref (caps1);
528 caps2 = gst_caps_make_writable (caps2);
530 for (i = GST_CAPS_LEN (caps2); i; i--) {
531 structure = gst_caps_remove_and_get_structure (caps2, 0);
532 caps1 = gst_caps_merge_structure (caps1, structure);
534 gst_caps_unref (caps2);
538 GstCaps *com = gst_caps_intersect (caps1, caps2);
539 GstCaps *add = gst_caps_subtract (caps2, com);
541 GST_DEBUG ("common : %d", gst_caps_get_size (com));
542 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
543 gst_caps_append (caps1, add);
544 gst_caps_unref (com);
552 * gst_caps_append_structure:
553 * @caps: the #GstCaps that will be appended to
554 * @structure: (transfer full): the #GstStructure to append
556 * Appends @structure to @caps. The structure is not copied; @caps
557 * becomes the owner of @structure.
560 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
562 g_return_if_fail (GST_IS_CAPS (caps));
563 g_return_if_fail (IS_WRITABLE (caps));
565 if (G_LIKELY (structure)) {
566 gst_caps_append_structure_unchecked (caps, structure);
571 * gst_caps_remove_structure:
572 * @caps: the #GstCaps to remove from
573 * @idx: Index of the structure to remove
575 * removes the stucture with the given index from the list of structures
576 * contained in @caps.
579 gst_caps_remove_structure (GstCaps * caps, guint idx)
581 GstStructure *structure;
583 g_return_if_fail (caps != NULL);
584 g_return_if_fail (idx <= gst_caps_get_size (caps));
585 g_return_if_fail (IS_WRITABLE (caps));
587 structure = gst_caps_remove_and_get_structure (caps, idx);
588 gst_structure_free (structure);
592 * gst_caps_merge_structure:
593 * @caps: (transfer full): the #GstCaps to merge into
594 * @structure: (transfer full): the #GstStructure to merge
596 * Appends @structure to @caps if its not already expressed by @caps.
598 * Returns: (transfer full): the merged caps.
601 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
603 GstStructure *structure1;
605 gboolean unique = TRUE;
607 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
609 if (G_UNLIKELY (structure == NULL))
612 /* check each structure */
613 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
614 structure1 = gst_caps_get_structure_unchecked (caps, i);
615 /* if structure is a subset of structure1, then skip it */
616 if (gst_structure_is_subset (structure, structure1)) {
622 caps = gst_caps_make_writable (caps);
623 gst_caps_append_structure_unchecked (caps, structure);
625 gst_structure_free (structure);
634 * Gets the number of structures contained in @caps.
636 * Returns: the number of structures that @caps contains
639 gst_caps_get_size (const GstCaps * caps)
641 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
643 return GST_CAPS_LEN (caps);
647 * gst_caps_get_structure:
649 * @index: the index of the structure
651 * Finds the structure in @caps that has the index @index, and
654 * WARNING: This function takes a const GstCaps *, but returns a
655 * non-const GstStructure *. This is for programming convenience --
656 * the caller should be aware that structures inside a constant
657 * #GstCaps should not be modified. However, if you know the caps
658 * are writable, either because you have just copied them or made
659 * them writable with gst_caps_make_writable(), you may modify the
660 * structure returned in the usual way, e.g. with functions like
661 * gst_structure_set().
663 * You do not need to free or unref the structure returned, it
664 * belongs to the #GstCaps.
666 * Returns: (transfer none): a pointer to the #GstStructure corresponding
670 gst_caps_get_structure (const GstCaps * caps, guint index)
672 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
673 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
675 return gst_caps_get_structure_unchecked (caps, index);
680 * @caps: the #GstCaps to copy
681 * @nth: the nth structure to copy
683 * Creates a new #GstCaps and appends a copy of the nth structure
684 * contained in @caps.
686 * Returns: (transfer full): the new #GstCaps
689 gst_caps_copy_nth (const GstCaps * caps, guint nth)
692 GstStructure *structure;
694 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
696 newcaps = gst_caps_new_empty ();
697 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
699 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
700 structure = gst_caps_get_structure_unchecked (caps, nth);
701 gst_caps_append_structure_unchecked (newcaps,
702 gst_structure_copy (structure));
710 * @caps: (transfer full): the #GstCaps to truncate
712 * Discard all but the first structure from @caps. Useful when
715 * Returns: (transfer full): truncated caps
718 gst_caps_truncate (GstCaps * caps)
722 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
724 i = GST_CAPS_LEN (caps) - 1;
728 caps = gst_caps_make_writable (caps);
730 gst_caps_remove_structure (caps, i--);
736 * gst_caps_set_value:
737 * @caps: a writable caps
738 * @field: name of the field to set
739 * @value: value to set the field to
741 * Sets the given @field on all structures of @caps to the given @value.
742 * This is a convenience function for calling gst_structure_set_value() on
743 * all structures of @caps.
748 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
752 g_return_if_fail (GST_IS_CAPS (caps));
753 g_return_if_fail (IS_WRITABLE (caps));
754 g_return_if_fail (field != NULL);
755 g_return_if_fail (G_IS_VALUE (value));
757 len = GST_CAPS_LEN (caps);
758 for (i = 0; i < len; i++) {
759 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
760 gst_structure_set_value (structure, field, value);
765 * gst_caps_set_simple_valist:
766 * @caps: the #GstCaps to set
767 * @field: first field to set
768 * @varargs: additional parameters
770 * Sets fields in a #GstCaps. The arguments must be passed in the same
771 * manner as gst_structure_set(), and be NULL-terminated.
772 * <note>Prior to GStreamer version 0.10.26, this function failed when
773 * @caps was not simple. If your code needs to work with those versions
774 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
775 * is %TRUE for @caps.</note>
778 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
780 GValue value = { 0, };
782 g_return_if_fail (GST_IS_CAPS (caps));
783 g_return_if_fail (IS_WRITABLE (caps));
789 type = va_arg (varargs, GType);
791 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
792 if (G_UNLIKELY (err)) {
793 g_critical ("%s", err);
797 gst_caps_set_value (caps, field, &value);
799 g_value_unset (&value);
801 field = va_arg (varargs, const gchar *);
806 * gst_caps_set_simple:
807 * @caps: the #GstCaps to set
808 * @field: first field to set
809 * @...: additional parameters
811 * Sets fields in a #GstCaps. The arguments must be passed in the same
812 * manner as gst_structure_set(), and be NULL-terminated.
813 * <note>Prior to GStreamer version 0.10.26, this function failed when
814 * @caps was not simple. If your code needs to work with those versions
815 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
816 * is %TRUE for @caps.</note>
819 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
823 g_return_if_fail (GST_IS_CAPS (caps));
824 g_return_if_fail (IS_WRITABLE (caps));
826 va_start (var_args, field);
827 gst_caps_set_simple_valist (caps, field, var_args);
835 * @caps: the #GstCaps to test
837 * Determines if @caps represents any media format.
839 * Returns: TRUE if @caps represents any format.
842 gst_caps_is_any (const GstCaps * caps)
844 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
846 return (CAPS_IS_ANY (caps));
851 * @caps: the #GstCaps to test
853 * Determines if @caps represents no media formats.
855 * Returns: TRUE if @caps represents no formats.
858 gst_caps_is_empty (const GstCaps * caps)
860 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
862 if (CAPS_IS_ANY (caps))
865 return CAPS_IS_EMPTY_SIMPLE (caps);
869 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
872 return gst_value_is_fixed (value);
877 * @caps: the #GstCaps to test
879 * Fixed #GstCaps describe exactly one format, that is, they have exactly
880 * one structure, and each field in the structure describes a fixed type.
881 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
883 * Returns: TRUE if @caps is fixed
886 gst_caps_is_fixed (const GstCaps * caps)
888 GstStructure *structure;
890 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
892 if (GST_CAPS_LEN (caps) != 1)
895 structure = gst_caps_get_structure_unchecked (caps, 0);
897 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
901 * gst_caps_is_equal_fixed:
902 * @caps1: the #GstCaps to test
903 * @caps2: the #GstCaps to test
905 * Tests if two #GstCaps are equal. This function only works on fixed
908 * Returns: TRUE if the arguments represent the same format
911 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
913 GstStructure *struct1, *struct2;
915 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
916 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
918 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
919 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
921 return gst_structure_is_equal (struct1, struct2);
925 * gst_caps_is_always_compatible:
926 * @caps1: the #GstCaps to test
927 * @caps2: the #GstCaps to test
929 * A given #GstCaps structure is always compatible with another if
930 * every media format that is in the first is also contained in the
931 * second. That is, @caps1 is a subset of @caps2.
933 * Returns: TRUE if @caps1 is a subset of @caps2.
936 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
938 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
939 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
941 return gst_caps_is_subset (caps1, caps2);
945 * gst_caps_is_subset:
946 * @subset: a #GstCaps
947 * @superset: a potentially greater #GstCaps
949 * Checks if all caps represented by @subset are also represented by @superset.
950 * <note>This function does not work reliably if optional properties for caps
951 * are included on one caps and omitted on the other.</note>
953 * Returns: %TRUE if @subset is a subset of @superset
956 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
958 GstStructure *s1, *s2;
962 g_return_val_if_fail (subset != NULL, FALSE);
963 g_return_val_if_fail (superset != NULL, FALSE);
965 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
967 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
970 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
971 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
972 s1 = gst_caps_get_structure_unchecked (subset, i);
973 s2 = gst_caps_get_structure_unchecked (superset, j);
974 if (gst_structure_is_subset (s1, s2)) {
975 /* If we found a superset, continue with the next
976 * subset structure */
980 /* If we found no superset for this subset structure
981 * we return FALSE immediately */
992 * gst_caps_is_subset_structure:
994 * @structure: a potential #GstStructure subset of @caps
996 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
997 * for more information.
999 * Returns: %TRUE if @structure is a subset of @caps
1004 gst_caps_is_subset_structure (const GstCaps * caps,
1005 const GstStructure * structure)
1010 g_return_val_if_fail (caps != NULL, FALSE);
1011 g_return_val_if_fail (structure != NULL, FALSE);
1013 if (CAPS_IS_ANY (caps))
1015 if (CAPS_IS_EMPTY (caps))
1018 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1019 s = gst_caps_get_structure_unchecked (caps, i);
1020 if (gst_structure_is_subset (structure, s)) {
1021 /* If we found a superset return TRUE */
1030 * gst_caps_is_equal:
1031 * @caps1: a #GstCaps
1032 * @caps2: another #GstCaps
1034 * Checks if the given caps represent the same set of caps.
1035 * <note>This function does not work reliably if optional properties for caps
1036 * are included on one caps and omitted on the other.</note>
1038 * Returns: TRUE if both caps are equal.
1041 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1043 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1044 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1046 if (G_UNLIKELY (caps1 == caps2))
1049 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1050 return gst_caps_is_equal_fixed (caps1, caps2);
1052 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1056 * gst_caps_is_strictly_equal:
1057 * @caps1: a #GstCaps
1058 * @caps2: another #GstCaps
1060 * Checks if the given caps are exactly the same set of caps.
1062 * Returns: TRUE if both caps are strictly equal.
1067 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1071 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1072 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1074 if (G_UNLIKELY (caps1 == caps2))
1077 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1080 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1081 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1082 gst_caps_get_structure_unchecked (caps2, i)))
1089 /* intersect operation */
1092 * gst_caps_can_intersect:
1093 * @caps1: a #GstCaps to intersect
1094 * @caps2: a #GstCaps to intersect
1096 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1099 * Returns: %TRUE if intersection would be not empty
1104 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1106 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1107 guint j, k, len1, len2;
1108 GstStructure *struct1;
1109 GstStructure *struct2;
1111 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1112 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1114 /* caps are exactly the same pointers */
1115 if (G_UNLIKELY (caps1 == caps2))
1118 /* empty caps on either side, return empty */
1119 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1122 /* one of the caps is any */
1123 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1126 /* run zigzag on top line then right line, this preserves the caps order
1127 * much better than a simple loop.
1129 * This algorithm zigzags over the caps structures as demonstrated in
1130 * the following matrix:
1133 * +------------- total distance: +-------------
1134 * | 1 2 4 7 0 | 0 1 2 3
1135 * caps2 | 3 5 8 10 1 | 1 2 3 4
1136 * | 6 9 11 12 2 | 2 3 4 5
1138 * First we iterate over the caps1 structures (top line) intersecting
1139 * the structures diagonally down, then we iterate over the caps2
1140 * structures. The result is that the intersections are ordered based on the
1141 * sum of the indexes in the list.
1143 len1 = GST_CAPS_LEN (caps1);
1144 len2 = GST_CAPS_LEN (caps2);
1145 for (i = 0; i < len1 + len2 - 1; i++) {
1146 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1147 j = MIN (i, len1 - 1);
1148 /* subset index stays 0 until i reaches superset->structs->len, then it
1149 * counts up from 1 to subset->structs->len - 1 */
1150 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1152 /* now run the diagonal line, end condition is the left or bottom
1155 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1156 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1158 if (gst_structure_can_intersect (struct1, struct2)) {
1161 /* move down left */
1163 if (G_UNLIKELY (j == 0))
1164 break; /* so we don't roll back to G_MAXUINT */
1172 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1174 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1175 guint j, k, len1, len2;
1177 GstStructure *struct1;
1178 GstStructure *struct2;
1180 GstStructure *istruct;
1182 /* caps are exactly the same pointers, just copy one caps */
1183 if (G_UNLIKELY (caps1 == caps2))
1184 return gst_caps_ref (caps1);
1186 /* empty caps on either side, return empty */
1187 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1188 return gst_caps_ref (GST_CAPS_NONE);
1190 /* one of the caps is any, just copy the other caps */
1191 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1192 return gst_caps_ref (caps2);
1193 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1194 return gst_caps_ref (caps1);
1196 dest = gst_caps_new_empty ();
1198 /* run zigzag on top line then right line, this preserves the caps order
1199 * much better than a simple loop.
1201 * This algorithm zigzags over the caps structures as demonstrated in
1202 * the following matrix:
1210 * First we iterate over the caps1 structures (top line) intersecting
1211 * the structures diagonally down, then we iterate over the caps2
1214 len1 = GST_CAPS_LEN (caps1);
1215 len2 = GST_CAPS_LEN (caps2);
1216 for (i = 0; i < len1 + len2 - 1; i++) {
1217 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1218 j = MIN (i, len1 - 1);
1219 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1220 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1221 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1223 /* now run the diagonal line, end condition is the left or bottom
1226 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1227 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1229 istruct = gst_structure_intersect (struct1, struct2);
1231 dest = gst_caps_merge_structure (dest, istruct);
1232 /* move down left */
1234 if (G_UNLIKELY (j == 0))
1235 break; /* so we don't roll back to G_MAXUINT */
1243 * gst_caps_intersect_first:
1244 * @caps1: a #GstCaps to intersect
1245 * @caps2: a #GstCaps to intersect
1247 * Creates a new #GstCaps that contains all the formats that are common
1248 * to both @caps1 and @caps2.
1250 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1251 * fashion as @caps1.
1253 * Returns: the new #GstCaps
1256 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1259 guint j, len1, len2;
1261 GstStructure *struct1;
1262 GstStructure *struct2;
1264 GstStructure *istruct;
1266 /* caps are exactly the same pointers, just copy one caps */
1267 if (G_UNLIKELY (caps1 == caps2))
1268 return gst_caps_ref (caps1);
1270 /* empty caps on either side, return empty */
1271 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1272 return gst_caps_ref (GST_CAPS_NONE);
1274 /* one of the caps is any, just copy the other caps */
1275 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1276 return gst_caps_ref (caps2);
1277 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1278 return gst_caps_ref (caps1);
1280 dest = gst_caps_new_empty ();
1282 len1 = GST_CAPS_LEN (caps1);
1283 len2 = GST_CAPS_LEN (caps2);
1284 for (i = 0; i < len1; i++) {
1285 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1286 for (j = 0; j < len2; j++) {
1287 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1288 istruct = gst_structure_intersect (struct1, struct2);
1290 dest = gst_caps_merge_structure (dest, istruct);
1298 * gst_caps_intersect_full:
1299 * @caps1: a #GstCaps to intersect
1300 * @caps2: a #GstCaps to intersect
1301 * @mode: The intersection algorithm/mode to use
1303 * Creates a new #GstCaps that contains all the formats that are common
1304 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1307 * Returns: the new #GstCaps
1311 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1312 GstCapsIntersectMode mode)
1314 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1315 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1318 case GST_CAPS_INTERSECT_FIRST:
1319 return gst_caps_intersect_first (caps1, caps2);
1321 g_warning ("Unknown caps intersect mode: %d", mode);
1323 case GST_CAPS_INTERSECT_ZIG_ZAG:
1324 return gst_caps_intersect_zig_zag (caps1, caps2);
1329 * gst_caps_intersect:
1330 * @caps1: a #GstCaps to intersect
1331 * @caps2: a #GstCaps to intersect
1333 * Creates a new #GstCaps that contains all the formats that are common
1334 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1336 * Returns: the new #GstCaps
1339 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1341 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1345 /* subtract operation */
1349 const GstStructure *subtract_from;
1355 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1358 SubtractionEntry *e = user_data;
1359 GValue subtraction = { 0, };
1360 const GValue *other;
1361 GstStructure *structure;
1363 other = gst_structure_id_get_value (e->subtract_from, field_id);
1367 if (!gst_value_subtract (&subtraction, other, value))
1369 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1370 g_value_unset (&subtraction);
1373 structure = gst_structure_copy (e->subtract_from);
1374 gst_structure_id_set_value (structure, field_id, &subtraction);
1375 g_value_unset (&subtraction);
1376 e->put_into = g_slist_prepend (e->put_into, structure);
1382 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1383 const GstStructure * subtrahend)
1388 e.subtract_from = minuend;
1391 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1392 gst_caps_structure_subtract_field, &e);
1398 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1399 gst_structure_free (walk->data);
1401 g_slist_free (e.put_into);
1407 * gst_caps_subtract:
1408 * @minuend: #GstCaps to subtract from
1409 * @subtrahend: #GstCaps to subtract
1411 * Subtracts the @subtrahend from the @minuend.
1412 * <note>This function does not work reliably if optional properties for caps
1413 * are included on one caps and omitted on the other.</note>
1415 * Returns: the resulting caps
1418 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1423 GstCaps *dest = NULL, *src;
1425 g_return_val_if_fail (minuend != NULL, NULL);
1426 g_return_val_if_fail (subtrahend != NULL, NULL);
1428 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1429 return gst_caps_new_empty ();
1431 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1432 return gst_caps_ref (minuend);
1434 /* FIXME: Do we want this here or above?
1435 The reason we need this is that there is no definition about what
1436 ANY means for specific types, so it's not possible to reduce ANY partially
1437 You can only remove everything or nothing and that is done above.
1438 Note: there's a test that checks this behaviour. */
1439 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1440 sublen = GST_CAPS_LEN (subtrahend);
1441 g_assert (sublen > 0);
1443 src = _gst_caps_copy (minuend);
1444 for (i = 0; i < sublen; i++) {
1447 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1449 gst_caps_unref (src);
1452 dest = gst_caps_new_empty ();
1453 srclen = GST_CAPS_LEN (src);
1454 for (j = 0; j < srclen; j++) {
1455 min = gst_caps_get_structure_unchecked (src, j);
1456 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1459 if (gst_caps_structure_subtract (&list, min, sub)) {
1462 for (walk = list; walk; walk = g_slist_next (walk)) {
1463 gst_caps_append_structure_unchecked (dest,
1464 (GstStructure *) walk->data);
1466 g_slist_free (list);
1468 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1471 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1474 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1475 gst_caps_unref (src);
1480 gst_caps_unref (src);
1481 dest = gst_caps_simplify (dest);
1485 /* normalize/simplify operations */
1487 typedef struct _NormalizeForeach
1490 GstStructure *structure;
1495 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1497 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1501 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1502 guint len = gst_value_list_get_size (value);
1503 for (i = 1; i < len; i++) {
1504 const GValue *v = gst_value_list_get_value (value, i);
1505 GstStructure *structure = gst_structure_copy (nf->structure);
1507 gst_structure_id_set_value (structure, field_id, v);
1508 gst_caps_append_structure_unchecked (nf->caps, structure);
1511 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1512 gst_structure_id_set_value (nf->structure, field_id, &val);
1513 g_value_unset (&val);
1521 * gst_caps_normalize:
1522 * @caps: (transfer full): a #GstCaps to normalize
1524 * Returns a #GstCaps that represents the same set of formats as
1525 * @caps, but contains no lists. Each list is expanded into separate
1528 * This function takes ownership of @caps.
1530 * Returns: (transfer full): the normalized #GstCaps
1533 gst_caps_normalize (GstCaps * caps)
1535 NormalizeForeach nf;
1538 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1540 caps = gst_caps_make_writable (caps);
1544 for (i = 0; i < gst_caps_get_size (nf.caps); i++) {
1545 nf.structure = gst_caps_get_structure_unchecked (nf.caps, i);
1547 while (!gst_structure_foreach (nf.structure,
1548 gst_caps_normalize_foreach, &nf));
1555 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1558 const GstStructure *struct1 = *((const GstStructure **) one);
1559 const GstStructure *struct2 = *((const GstStructure **) two);
1561 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1562 So what's the best way? */
1563 ret = strcmp (gst_structure_get_name (struct1),
1564 gst_structure_get_name (struct2));
1568 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1575 GstStructure *compare;
1580 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1583 UnionField *u = user_data;
1584 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1588 g_value_unset (&u->value);
1591 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1594 g_value_unset (&u->value);
1598 gst_value_union (&u->value, val, value);
1603 gst_caps_structure_simplify (GstStructure ** result,
1604 GstStructure * simplify, GstStructure * compare)
1607 UnionField field = { 0, {0,}, NULL };
1609 /* try to subtract to get a real subset */
1610 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1611 if (list == NULL) { /* no result */
1614 } else if (list->next == NULL) { /* one result */
1615 *result = list->data;
1616 g_slist_free (list);
1618 } else { /* multiple results */
1619 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1620 g_slist_free (list);
1625 /* try to union both structs */
1626 field.compare = compare;
1627 if (gst_structure_foreach (simplify,
1628 gst_caps_structure_figure_out_union, &field)) {
1629 gboolean ret = FALSE;
1631 /* now we know all of simplify's fields are the same in compare
1632 * but at most one field: field.name */
1633 if (G_IS_VALUE (&field.value)) {
1634 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1635 gst_structure_id_set_value (compare, field.name, &field.value);
1639 g_value_unset (&field.value);
1640 } else if (gst_structure_n_fields (simplify) <=
1641 gst_structure_n_fields (compare)) {
1642 /* compare is just more specific, will be optimized away later */
1643 /* FIXME: do this here? */
1644 GST_LOG ("found a case that will be optimized later.");
1646 gchar *one = gst_structure_to_string (simplify);
1647 gchar *two = gst_structure_to_string (compare);
1650 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1662 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1663 GstStructure * new, gint i)
1665 gst_structure_set_parent_refcount (old, NULL);
1666 gst_structure_free (old);
1667 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1668 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1672 * gst_caps_simplify:
1673 * @caps: (transfer full): a #GstCaps to simplify
1675 * Converts the given @caps into a representation that represents the
1676 * same set of formats, but in a simpler form. Component structures that are
1677 * identical are merged. Component structures that have values that can be
1678 * merged are also merged.
1680 * This method does not preserve the original order of @caps.
1682 * Returns: The simplified caps.
1685 gst_caps_simplify (GstCaps * caps)
1687 GstStructure *simplify, *compare, *result = NULL;
1690 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1692 start = GST_CAPS_LEN (caps) - 1;
1693 /* one caps, already as simple as can be */
1697 caps = gst_caps_make_writable (caps);
1699 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1701 for (i = start; i >= 0; i--) {
1702 simplify = gst_caps_get_structure_unchecked (caps, i);
1703 compare = gst_caps_get_structure_unchecked (caps, start);
1704 if (gst_structure_get_name_id (simplify) !=
1705 gst_structure_get_name_id (compare))
1707 for (j = start; j >= 0; j--) {
1710 compare = gst_caps_get_structure_unchecked (caps, j);
1711 if (gst_structure_get_name_id (simplify) !=
1712 gst_structure_get_name_id (compare)) {
1715 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1717 gst_caps_switch_structures (caps, simplify, result, i);
1720 gst_caps_remove_structure (caps, i);
1732 * @caps: (transfer full): a #GstCaps to fixate
1734 * Modifies the given @caps into a representation with only fixed
1735 * values. First the caps will be truncated and then the first structure will be
1736 * fixated with gst_structure_fixate().
1738 * Returns: (transfer full): the fixated caps
1741 gst_caps_fixate (GstCaps * caps)
1745 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1747 /* default fixation */
1748 caps = gst_caps_truncate (caps);
1749 caps = gst_caps_make_writable (caps);
1750 s = gst_caps_get_structure (caps, 0);
1751 gst_structure_fixate (s);
1759 * gst_caps_to_string:
1762 * Converts @caps to a string representation. This string representation
1763 * can be converted back to a #GstCaps by gst_caps_from_string().
1765 * For debugging purposes its easier to do something like this:
1767 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1769 * This prints the caps in human readable form.
1771 * Returns: (transfer full): a newly allocated string representing @caps.
1774 gst_caps_to_string (const GstCaps * caps)
1776 guint i, slen, clen;
1779 /* NOTE: This function is potentially called by the debug system,
1780 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1781 * should be careful to avoid recursion. This includes any functions
1782 * called by gst_caps_to_string. In particular, calls should
1783 * not use the GST_PTR_FORMAT extension. */
1786 return g_strdup ("NULL");
1788 if (CAPS_IS_ANY (caps)) {
1789 return g_strdup ("ANY");
1791 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1792 return g_strdup ("EMPTY");
1795 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1797 clen = GST_CAPS_LEN (caps);
1798 for (i = 0; i < clen; i++) {
1800 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1804 s = g_string_sized_new (slen);
1805 for (i = 0; i < clen; i++) {
1806 GstStructure *structure;
1809 /* ';' is now added by gst_structure_to_string */
1810 g_string_append_c (s, ' ');
1813 structure = gst_caps_get_structure_unchecked (caps, i);
1814 priv_gst_structure_append_to_gstring (structure, s);
1816 if (s->len && s->str[s->len - 1] == ';') {
1817 /* remove latest ';' */
1818 s->str[--s->len] = '\0';
1820 return g_string_free (s, FALSE);
1824 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1826 GstStructure *structure;
1829 if (strcmp ("ANY", string) == 0) {
1830 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1833 if (strcmp ("EMPTY", string) == 0) {
1837 structure = gst_structure_from_string (string, &s);
1838 if (structure == NULL) {
1841 gst_caps_append_structure_unchecked (caps, structure);
1845 while (g_ascii_isspace (*s))
1850 structure = gst_structure_from_string (s, &s);
1851 if (structure == NULL) {
1854 gst_caps_append_structure_unchecked (caps, structure);
1862 * gst_caps_from_string:
1863 * @string: a string to convert to #GstCaps
1865 * Converts @caps from a string representation.
1867 * Returns: (transfer full): a newly allocated #GstCaps
1870 gst_caps_from_string (const gchar * string)
1874 g_return_val_if_fail (string, FALSE);
1876 caps = gst_caps_new_empty ();
1877 if (gst_caps_from_string_inplace (caps, string)) {
1880 gst_caps_unref (caps);
1886 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1888 g_return_if_fail (G_IS_VALUE (src_value));
1889 g_return_if_fail (G_IS_VALUE (dest_value));
1890 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1891 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1892 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1894 g_value_take_string (dest_value,
1895 gst_caps_to_string (gst_value_get_caps (src_value)));