2 * Copyright (C) <2003> David A. Schleef <ds@schleef.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
22 * @short_description: Structure describing sets of media formats
23 * @see_also: #GstStructure
25 * Caps (capabilities) are lighweight refcounted objects describing media types.
26 * They are composed of an array of #GstStructure.
28 * Caps are exposed on #GstPadTemplate to describe all possible types a
29 * given pad can handle. They are also stored in the #GstRegistry along with
30 * a description of the #GstElement.
32 * Caps are exposed on the element pads using the gst_pad_get_caps() pad
33 * function. This function describes the possible types that the pad can
34 * handle or produce at runtime.
36 * Caps are also attached to buffers to describe to content of the data
37 * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
38 * a #GstBuffer allow for format negotiation upstream and downstream.
40 * A #GstCaps can be constructed with the following code fragment:
43 * <title>Creating caps</title>
46 * caps = gst_caps_new_simple ("video/x-raw",
47 * "format", G_TYPE_STRING, "I420",
48 * "framerate", GST_TYPE_FRACTION, 25, 1,
49 * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
50 * "width", G_TYPE_INT, 320,
51 * "height", G_TYPE_INT, 240,
56 * A #GstCaps is fixed when it has no properties with ranges or lists. Use
57 * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
58 * set on a #GstPad or #GstBuffer.
60 * Various methods exist to work with the media types such as subtracting
63 * Last reviewed on 2007-02-13 (0.10.10)
72 #include "gst_private.h"
74 #include <gobject/gvaluecollector.h>
76 #define DEBUG_REFCOUNT
78 typedef struct _GstCapsImpl
85 #define GST_CAPS_ARRAY(c) (((GstCapsImpl *)(c))->array)
87 #define GST_CAPS_LEN(c) (GST_CAPS_ARRAY(c)->len)
89 #define IS_WRITABLE(caps) \
90 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
92 /* same as gst_caps_is_any () */
93 #define CAPS_IS_ANY(caps) \
94 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY)
96 /* same as gst_caps_is_empty () */
97 #define CAPS_IS_EMPTY(caps) \
98 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
100 #define CAPS_IS_EMPTY_SIMPLE(caps) \
101 ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
103 /* quick way to get a caps structure at an index without doing a type or array
105 #define gst_caps_get_structure_unchecked(caps, index) \
106 ((GstStructure *)g_ptr_array_index (GST_CAPS_ARRAY (caps), (index)))
107 /* quick way to append a structure without checking the args */
108 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
109 GstStructure *__s=structure; \
110 if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps))) \
111 g_ptr_array_add (GST_CAPS_ARRAY (caps), __s); \
114 /* lock to protect multiple invocations of static caps to caps conversion */
115 G_LOCK_DEFINE_STATIC (static_caps_lock);
117 static void gst_caps_transform_to_string (const GValue * src_value,
118 GValue * dest_value);
119 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
120 const gchar * string);
122 GType _gst_caps_type = 0;
123 GstCaps *_gst_caps_any;
124 GstCaps *_gst_caps_none;
126 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
129 _priv_gst_caps_initialize (void)
131 _gst_caps_type = gst_caps_get_type ();
133 _gst_caps_any = gst_caps_new_any ();
134 _gst_caps_none = gst_caps_new_empty ();
136 g_value_register_transform_func (_gst_caps_type,
137 G_TYPE_STRING, gst_caps_transform_to_string);
141 _gst_caps_copy (const GstCaps * caps)
144 GstStructure *structure;
147 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
149 newcaps = gst_caps_new_empty ();
150 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
151 n = GST_CAPS_LEN (caps);
153 GST_CAT_DEBUG_OBJECT (GST_CAT_PERFORMANCE, caps, "doing copy %p -> %p",
156 for (i = 0; i < n; i++) {
157 structure = gst_caps_get_structure_unchecked (caps, i);
158 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
164 /* creation/deletion */
166 _gst_caps_free (GstCaps * caps)
168 GstStructure *structure;
171 /* The refcount must be 0, but since we're only called by gst_caps_unref,
172 * don't bother testing. */
173 len = GST_CAPS_LEN (caps);
174 /* This can be used to get statistics about caps sizes */
175 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
176 for (i = 0; i < len; i++) {
177 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
178 gst_structure_set_parent_refcount (structure, NULL);
179 gst_structure_free (structure);
181 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
183 #ifdef DEBUG_REFCOUNT
184 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
186 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
190 gst_caps_init (GstCaps * caps, gsize size)
192 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
194 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
195 caps->mini_object.dispose = NULL;
196 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
198 /* the 32 has been determined by logging caps sizes in _gst_caps_free
199 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
201 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
203 GST_CAPS_ARRAY (caps) = g_ptr_array_new ();
207 * gst_caps_new_empty:
209 * Creates a new #GstCaps that is empty. That is, the returned
210 * #GstCaps contains no media formats.
211 * 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 stucture 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 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
611 if (G_LIKELY (structure)) {
612 GstStructure *structure1;
614 gboolean unique = TRUE;
616 /* check each structure */
617 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
618 structure1 = gst_caps_get_structure_unchecked (caps, i);
619 /* if structure is a subset of structure1, then skip it */
620 if (gst_structure_is_subset (structure, structure1)) {
626 caps = gst_caps_make_writable (caps);
627 gst_caps_append_structure_unchecked (caps, structure);
629 gst_structure_free (structure);
639 * Gets the number of structures contained in @caps.
641 * Returns: the number of structures that @caps contains
644 gst_caps_get_size (const GstCaps * caps)
646 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
648 return GST_CAPS_LEN (caps);
652 * gst_caps_get_structure:
654 * @index: the index of the structure
656 * Finds the structure in @caps that has the index @index, and
659 * WARNING: This function takes a const GstCaps *, but returns a
660 * non-const GstStructure *. This is for programming convenience --
661 * the caller should be aware that structures inside a constant
662 * #GstCaps should not be modified. However, if you know the caps
663 * are writable, either because you have just copied them or made
664 * them writable with gst_caps_make_writable(), you may modify the
665 * structure returned in the usual way, e.g. with functions like
666 * gst_structure_set().
668 * You do not need to free or unref the structure returned, it
669 * belongs to the #GstCaps.
671 * Returns: (transfer none): a pointer to the #GstStructure corresponding
675 gst_caps_get_structure (const GstCaps * caps, guint index)
677 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
678 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
680 return gst_caps_get_structure_unchecked (caps, index);
685 * @caps: the #GstCaps to copy
686 * @nth: the nth structure to copy
688 * Creates a new #GstCaps and appends a copy of the nth structure
689 * contained in @caps.
691 * Returns: (transfer full): the new #GstCaps
694 gst_caps_copy_nth (const GstCaps * caps, guint nth)
697 GstStructure *structure;
699 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
701 newcaps = gst_caps_new_empty ();
702 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
704 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
705 structure = gst_caps_get_structure_unchecked (caps, nth);
706 gst_caps_append_structure_unchecked (newcaps,
707 gst_structure_copy (structure));
715 * @caps: (transfer full): the #GstCaps to truncate
717 * Discard all but the first structure from @caps. Useful when
720 * Returns: (transfer full): truncated caps
723 gst_caps_truncate (GstCaps * caps)
727 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
729 i = GST_CAPS_LEN (caps) - 1;
733 caps = gst_caps_make_writable (caps);
735 gst_caps_remove_structure (caps, i--);
741 * gst_caps_set_value:
742 * @caps: a writable caps
743 * @field: name of the field to set
744 * @value: value to set the field to
746 * Sets the given @field on all structures of @caps to the given @value.
747 * This is a convenience function for calling gst_structure_set_value() on
748 * all structures of @caps.
753 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
757 g_return_if_fail (GST_IS_CAPS (caps));
758 g_return_if_fail (IS_WRITABLE (caps));
759 g_return_if_fail (field != NULL);
760 g_return_if_fail (G_IS_VALUE (value));
762 len = GST_CAPS_LEN (caps);
763 for (i = 0; i < len; i++) {
764 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
765 gst_structure_set_value (structure, field, value);
770 * gst_caps_set_simple_valist:
771 * @caps: the #GstCaps to set
772 * @field: first field to set
773 * @varargs: additional parameters
775 * Sets fields in a #GstCaps. The arguments must be passed in the same
776 * manner as gst_structure_set(), and be NULL-terminated.
777 * <note>Prior to GStreamer version 0.10.26, this function failed when
778 * @caps was not simple. If your code needs to work with those versions
779 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
780 * is %TRUE for @caps.</note>
783 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
785 GValue value = { 0, };
787 g_return_if_fail (GST_IS_CAPS (caps));
788 g_return_if_fail (IS_WRITABLE (caps));
794 type = va_arg (varargs, GType);
796 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
797 if (G_UNLIKELY (err)) {
798 g_critical ("%s", err);
802 gst_caps_set_value (caps, field, &value);
804 g_value_unset (&value);
806 field = va_arg (varargs, const gchar *);
811 * gst_caps_set_simple:
812 * @caps: the #GstCaps to set
813 * @field: first field to set
814 * @...: additional parameters
816 * Sets fields in a #GstCaps. The arguments must be passed in the same
817 * manner as gst_structure_set(), and be NULL-terminated.
818 * <note>Prior to GStreamer version 0.10.26, this function failed when
819 * @caps was not simple. If your code needs to work with those versions
820 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
821 * is %TRUE for @caps.</note>
824 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
828 g_return_if_fail (GST_IS_CAPS (caps));
829 g_return_if_fail (IS_WRITABLE (caps));
831 va_start (var_args, field);
832 gst_caps_set_simple_valist (caps, field, var_args);
840 * @caps: the #GstCaps to test
842 * Determines if @caps represents any media format.
844 * Returns: TRUE if @caps represents any format.
847 gst_caps_is_any (const GstCaps * caps)
849 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
851 return (CAPS_IS_ANY (caps));
856 * @caps: the #GstCaps to test
858 * Determines if @caps represents no media formats.
860 * Returns: TRUE if @caps represents no formats.
863 gst_caps_is_empty (const GstCaps * caps)
865 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
867 if (CAPS_IS_ANY (caps))
870 return CAPS_IS_EMPTY_SIMPLE (caps);
874 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
877 return gst_value_is_fixed (value);
882 * @caps: the #GstCaps to test
884 * Fixed #GstCaps describe exactly one format, that is, they have exactly
885 * one structure, and each field in the structure describes a fixed type.
886 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
888 * Returns: TRUE if @caps is fixed
891 gst_caps_is_fixed (const GstCaps * caps)
893 GstStructure *structure;
895 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
897 if (GST_CAPS_LEN (caps) != 1)
900 structure = gst_caps_get_structure_unchecked (caps, 0);
902 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
906 * gst_caps_is_equal_fixed:
907 * @caps1: the #GstCaps to test
908 * @caps2: the #GstCaps to test
910 * Tests if two #GstCaps are equal. This function only works on fixed
913 * Returns: TRUE if the arguments represent the same format
916 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
918 GstStructure *struct1, *struct2;
920 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
921 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
923 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
924 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
926 return gst_structure_is_equal (struct1, struct2);
930 * gst_caps_is_always_compatible:
931 * @caps1: the #GstCaps to test
932 * @caps2: the #GstCaps to test
934 * A given #GstCaps structure is always compatible with another if
935 * every media format that is in the first is also contained in the
936 * second. That is, @caps1 is a subset of @caps2.
938 * Returns: TRUE if @caps1 is a subset of @caps2.
941 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
943 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
944 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
946 return gst_caps_is_subset (caps1, caps2);
950 * gst_caps_is_subset:
951 * @subset: a #GstCaps
952 * @superset: a potentially greater #GstCaps
954 * Checks if all caps represented by @subset are also represented by @superset.
955 * <note>This function does not work reliably if optional properties for caps
956 * are included on one caps and omitted on the other.</note>
958 * Returns: %TRUE if @subset is a subset of @superset
961 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
963 GstStructure *s1, *s2;
967 g_return_val_if_fail (subset != NULL, FALSE);
968 g_return_val_if_fail (superset != NULL, FALSE);
970 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
972 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
975 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
976 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
977 s1 = gst_caps_get_structure_unchecked (subset, i);
978 s2 = gst_caps_get_structure_unchecked (superset, j);
979 if (gst_structure_is_subset (s1, s2)) {
980 /* If we found a superset, continue with the next
981 * subset structure */
985 /* If we found no superset for this subset structure
986 * we return FALSE immediately */
997 * gst_caps_is_subset_structure:
999 * @structure: a potential #GstStructure subset of @caps
1001 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1002 * for more information.
1004 * Returns: %TRUE if @structure is a subset of @caps
1009 gst_caps_is_subset_structure (const GstCaps * caps,
1010 const GstStructure * structure)
1015 g_return_val_if_fail (caps != NULL, FALSE);
1016 g_return_val_if_fail (structure != NULL, FALSE);
1018 if (CAPS_IS_ANY (caps))
1020 if (CAPS_IS_EMPTY (caps))
1023 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1024 s = gst_caps_get_structure_unchecked (caps, i);
1025 if (gst_structure_is_subset (structure, s)) {
1026 /* If we found a superset return TRUE */
1035 * gst_caps_is_equal:
1036 * @caps1: a #GstCaps
1037 * @caps2: another #GstCaps
1039 * Checks if the given caps represent the same set of caps.
1040 * <note>This function does not work reliably if optional properties for caps
1041 * are included on one caps and omitted on the other.</note>
1043 * This function deals correctly with passing NULL for any of the caps.
1045 * Returns: TRUE if both caps are equal.
1048 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1050 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1051 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1053 if (G_UNLIKELY (caps1 == caps2))
1056 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1057 return gst_caps_is_equal_fixed (caps1, caps2);
1059 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1063 * gst_caps_is_strictly_equal:
1064 * @caps1: a #GstCaps
1065 * @caps2: another #GstCaps
1067 * Checks if the given caps are exactly the same set of caps.
1069 * This function deals correctly with passing NULL for any of the caps.
1071 * Returns: TRUE if both caps are strictly equal.
1076 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1080 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1081 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1083 if (G_UNLIKELY (caps1 == caps2))
1086 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1089 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1090 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1091 gst_caps_get_structure_unchecked (caps2, i)))
1098 /* intersect operation */
1101 * gst_caps_can_intersect:
1102 * @caps1: a #GstCaps to intersect
1103 * @caps2: a #GstCaps to intersect
1105 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1108 * Returns: %TRUE if intersection would be not empty
1113 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1115 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1116 guint j, k, len1, len2;
1117 GstStructure *struct1;
1118 GstStructure *struct2;
1120 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1121 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1123 /* caps are exactly the same pointers */
1124 if (G_UNLIKELY (caps1 == caps2))
1127 /* empty caps on either side, return empty */
1128 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1131 /* one of the caps is any */
1132 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1135 /* run zigzag on top line then right line, this preserves the caps order
1136 * much better than a simple loop.
1138 * This algorithm zigzags over the caps structures as demonstrated in
1139 * the folowing matrix:
1142 * +------------- total distance: +-------------
1143 * | 1 2 4 7 0 | 0 1 2 3
1144 * caps2 | 3 5 8 10 1 | 1 2 3 4
1145 * | 6 9 11 12 2 | 2 3 4 5
1147 * First we iterate over the caps1 structures (top line) intersecting
1148 * the structures diagonally down, then we iterate over the caps2
1149 * structures. The result is that the intersections are ordered based on the
1150 * sum of the indexes in the list.
1152 len1 = GST_CAPS_LEN (caps1);
1153 len2 = GST_CAPS_LEN (caps2);
1154 for (i = 0; i < len1 + len2 - 1; i++) {
1155 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1156 j = MIN (i, len1 - 1);
1157 /* subset index stays 0 until i reaches superset->structs->len, then it
1158 * counts up from 1 to subset->structs->len - 1 */
1159 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1161 /* now run the diagonal line, end condition is the left or bottom
1164 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1165 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1167 if (gst_structure_can_intersect (struct1, struct2)) {
1170 /* move down left */
1172 if (G_UNLIKELY (j == 0))
1173 break; /* so we don't roll back to G_MAXUINT */
1181 gst_caps_intersect_zig_zag (GstCaps * caps1, GstCaps * caps2)
1183 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1184 guint j, k, len1, len2;
1186 GstStructure *struct1;
1187 GstStructure *struct2;
1189 GstStructure *istruct;
1191 /* caps are exactly the same pointers, just copy one caps */
1192 if (G_UNLIKELY (caps1 == caps2))
1193 return gst_caps_ref (caps1);
1195 /* empty caps on either side, return empty */
1196 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1197 return gst_caps_ref (GST_CAPS_NONE);
1199 /* one of the caps is any, just copy the other caps */
1200 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1201 return gst_caps_ref (caps2);
1202 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1203 return gst_caps_ref (caps1);
1205 dest = gst_caps_new_empty ();
1207 /* run zigzag on top line then right line, this preserves the caps order
1208 * much better than a simple loop.
1210 * This algorithm zigzags over the caps structures as demonstrated in
1211 * the folowing matrix:
1219 * First we iterate over the caps1 structures (top line) intersecting
1220 * the structures diagonally down, then we iterate over the caps2
1223 len1 = GST_CAPS_LEN (caps1);
1224 len2 = GST_CAPS_LEN (caps2);
1225 for (i = 0; i < len1 + len2 - 1; i++) {
1226 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1227 j = MIN (i, len1 - 1);
1228 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1229 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1230 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1232 /* now run the diagonal line, end condition is the left or bottom
1235 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1236 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1238 istruct = gst_structure_intersect (struct1, struct2);
1240 dest = gst_caps_merge_structure (dest, istruct);
1241 /* move down left */
1243 if (G_UNLIKELY (j == 0))
1244 break; /* so we don't roll back to G_MAXUINT */
1252 * gst_caps_intersect_first:
1253 * @caps1: a #GstCaps to intersect
1254 * @caps2: a #GstCaps to intersect
1256 * Creates a new #GstCaps that contains all the formats that are common
1257 * to both @caps1 and @caps2.
1259 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1260 * fashion as @caps1.
1262 * Returns: the new #GstCaps
1265 gst_caps_intersect_first (GstCaps * caps1, GstCaps * caps2)
1268 guint j, len1, len2;
1270 GstStructure *struct1;
1271 GstStructure *struct2;
1273 GstStructure *istruct;
1275 /* caps are exactly the same pointers, just copy one caps */
1276 if (G_UNLIKELY (caps1 == caps2))
1277 return gst_caps_ref (caps1);
1279 /* empty caps on either side, return empty */
1280 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1281 return gst_caps_ref (GST_CAPS_NONE);
1283 /* one of the caps is any, just copy the other caps */
1284 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1285 return gst_caps_ref (caps2);
1286 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1287 return gst_caps_ref (caps1);
1289 dest = gst_caps_new_empty ();
1291 len1 = GST_CAPS_LEN (caps1);
1292 len2 = GST_CAPS_LEN (caps2);
1293 for (i = 0; i < len1; i++) {
1294 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1295 for (j = 0; j < len2; j++) {
1296 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1297 istruct = gst_structure_intersect (struct1, struct2);
1299 dest = gst_caps_merge_structure (dest, istruct);
1307 * gst_caps_intersect_full:
1308 * @caps1: a #GstCaps to intersect
1309 * @caps2: a #GstCaps to intersect
1310 * @mode: The intersection algorithm/mode to use
1312 * Creates a new #GstCaps that contains all the formats that are common
1313 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1316 * Returns: the new #GstCaps
1320 gst_caps_intersect_full (GstCaps * caps1, GstCaps * caps2,
1321 GstCapsIntersectMode mode)
1323 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1324 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1327 case GST_CAPS_INTERSECT_FIRST:
1328 return gst_caps_intersect_first (caps1, caps2);
1330 g_warning ("Unknown caps intersect mode: %d", mode);
1332 case GST_CAPS_INTERSECT_ZIG_ZAG:
1333 return gst_caps_intersect_zig_zag (caps1, caps2);
1338 * gst_caps_intersect:
1339 * @caps1: a #GstCaps to intersect
1340 * @caps2: a #GstCaps to intersect
1342 * Creates a new #GstCaps that contains all the formats that are common
1343 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1345 * Returns: the new #GstCaps
1348 gst_caps_intersect (GstCaps * caps1, GstCaps * caps2)
1350 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1354 /* subtract operation */
1358 const GstStructure *subtract_from;
1364 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1367 SubtractionEntry *e = user_data;
1368 GValue subtraction = { 0, };
1369 const GValue *other;
1370 GstStructure *structure;
1372 other = gst_structure_id_get_value (e->subtract_from, field_id);
1376 if (!gst_value_subtract (&subtraction, other, value))
1378 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1379 g_value_unset (&subtraction);
1382 structure = gst_structure_copy (e->subtract_from);
1383 gst_structure_id_set_value (structure, field_id, &subtraction);
1384 g_value_unset (&subtraction);
1385 e->put_into = g_slist_prepend (e->put_into, structure);
1391 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1392 const GstStructure * subtrahend)
1397 e.subtract_from = minuend;
1400 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1401 gst_caps_structure_subtract_field, &e);
1407 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1408 gst_structure_free (walk->data);
1410 g_slist_free (e.put_into);
1416 * gst_caps_subtract:
1417 * @minuend: #GstCaps to subtract from
1418 * @subtrahend: #GstCaps to subtract
1420 * Subtracts the @subtrahend from the @minuend.
1421 * <note>This function does not work reliably if optional properties for caps
1422 * are included on one caps and omitted on the other.</note>
1424 * Returns: the resulting caps
1427 gst_caps_subtract (GstCaps * minuend, GstCaps * subtrahend)
1432 GstCaps *dest = NULL, *src;
1434 g_return_val_if_fail (minuend != NULL, NULL);
1435 g_return_val_if_fail (subtrahend != NULL, NULL);
1437 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1438 return gst_caps_new_empty ();
1440 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1441 return gst_caps_ref (minuend);
1443 /* FIXME: Do we want this here or above?
1444 The reason we need this is that there is no definition about what
1445 ANY means for specific types, so it's not possible to reduce ANY partially
1446 You can only remove everything or nothing and that is done above.
1447 Note: there's a test that checks this behaviour. */
1448 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1449 sublen = GST_CAPS_LEN (subtrahend);
1450 g_assert (sublen > 0);
1452 src = _gst_caps_copy (minuend);
1453 for (i = 0; i < sublen; i++) {
1456 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1458 gst_caps_unref (src);
1461 dest = gst_caps_new_empty ();
1462 srclen = GST_CAPS_LEN (src);
1463 for (j = 0; j < srclen; j++) {
1464 min = gst_caps_get_structure_unchecked (src, j);
1465 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1468 if (gst_caps_structure_subtract (&list, min, sub)) {
1471 for (walk = list; walk; walk = g_slist_next (walk)) {
1472 gst_caps_append_structure_unchecked (dest,
1473 (GstStructure *) walk->data);
1475 g_slist_free (list);
1477 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1480 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1483 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1484 gst_caps_unref (src);
1489 gst_caps_unref (src);
1490 dest = gst_caps_simplify (dest);
1494 /* union operation */
1497 static GstStructure *
1498 gst_caps_structure_union (const GstStructure * struct1,
1499 const GstStructure * struct2)
1503 const GstStructureField *field1;
1504 const GstStructureField *field2;
1507 /* FIXME this doesn't actually work */
1509 if (struct1->name != struct2->name)
1512 dest = gst_structure_new_id_empty (struct1->name);
1514 for (i = 0; i < struct1->fields->len; i++) {
1515 GValue dest_value = { 0 };
1517 field1 = GST_STRUCTURE_FIELD (struct1, i);
1518 field2 = gst_structure_id_get_field (struct2, field1->name);
1520 if (field2 == NULL) {
1523 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1524 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1527 ret = gst_value_compare (&field1->value, &field2->value);
1538 * @caps1: a #GstCaps to union
1539 * @caps2: a #GstCaps to union
1541 * Creates a new #GstCaps that contains all the formats that are in
1542 * either @caps1 and @caps2.
1544 * Returns: the new #GstCaps
1547 gst_caps_union (GstCaps * caps1, GstCaps * caps2)
1551 /* NULL pointers are no correct GstCaps */
1552 g_return_val_if_fail (caps1 != NULL, NULL);
1553 g_return_val_if_fail (caps2 != NULL, NULL);
1555 if (CAPS_IS_EMPTY (caps1))
1556 return gst_caps_ref (caps2);
1558 if (CAPS_IS_EMPTY (caps2))
1559 return gst_caps_ref (caps1);
1561 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1562 return gst_caps_ref (caps1);
1564 dest1 = _gst_caps_copy (caps1);
1565 gst_caps_append (dest1, gst_caps_ref (caps2));
1567 dest1 = gst_caps_simplify (dest1);
1571 /* normalize/simplify operations */
1573 typedef struct _NormalizeForeach
1576 GstStructure *structure;
1581 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1583 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1587 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1588 guint len = gst_value_list_get_size (value);
1589 for (i = 1; i < len; i++) {
1590 const GValue *v = gst_value_list_get_value (value, i);
1591 GstStructure *structure = gst_structure_copy (nf->structure);
1593 gst_structure_id_set_value (structure, field_id, v);
1594 gst_caps_append_structure_unchecked (nf->caps, structure);
1597 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1598 gst_structure_id_set_value (nf->structure, field_id, &val);
1599 g_value_unset (&val);
1607 * gst_caps_normalize:
1608 * @caps: (transfer full): a #GstCaps to normalize
1610 * Returns a #GstCaps that represents the same set of formats as
1611 * @caps, but contains no lists. Each list is expanded into separate
1614 * This function takes ownership of @caps.
1616 * Returns: (transfer full): the normalized #GstCaps
1619 gst_caps_normalize (GstCaps * caps)
1621 NormalizeForeach nf;
1625 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1627 newcaps = gst_caps_make_writable (caps);
1630 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1631 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1633 while (!gst_structure_foreach (nf.structure,
1634 gst_caps_normalize_foreach, &nf));
1641 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1644 const GstStructure *struct1 = *((const GstStructure **) one);
1645 const GstStructure *struct2 = *((const GstStructure **) two);
1647 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1648 So what's the best way? */
1649 ret = strcmp (gst_structure_get_name (struct1),
1650 gst_structure_get_name (struct2));
1654 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1661 GstStructure *compare;
1666 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1669 UnionField *u = user_data;
1670 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1674 g_value_unset (&u->value);
1677 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1680 g_value_unset (&u->value);
1684 gst_value_union (&u->value, val, value);
1689 gst_caps_structure_simplify (GstStructure ** result,
1690 const GstStructure * simplify, GstStructure * compare)
1693 UnionField field = { 0, {0,}, NULL };
1695 /* try to subtract to get a real subset */
1696 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1697 if (list == NULL) { /* no result */
1700 } else if (list->next == NULL) { /* one result */
1701 *result = list->data;
1702 g_slist_free (list);
1704 } else { /* multiple results */
1705 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1706 g_slist_free (list);
1711 /* try to union both structs */
1712 field.compare = compare;
1713 if (gst_structure_foreach ((GstStructure *) simplify,
1714 gst_caps_structure_figure_out_union, &field)) {
1715 gboolean ret = FALSE;
1717 /* now we know all of simplify's fields are the same in compare
1718 * but at most one field: field.name */
1719 if (G_IS_VALUE (&field.value)) {
1720 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1721 gst_structure_id_set_value (compare, field.name, &field.value);
1725 g_value_unset (&field.value);
1726 } else if (gst_structure_n_fields (simplify) <=
1727 gst_structure_n_fields (compare)) {
1728 /* compare is just more specific, will be optimized away later */
1729 /* FIXME: do this here? */
1730 GST_LOG ("found a case that will be optimized later.");
1732 gchar *one = gst_structure_to_string (simplify);
1733 gchar *two = gst_structure_to_string (compare);
1736 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1748 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1749 GstStructure * new, gint i)
1751 gst_structure_set_parent_refcount (old, NULL);
1752 gst_structure_free (old);
1753 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1754 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1758 * gst_caps_simplify:
1759 * @caps: (transfer full): a #GstCaps to simplify
1761 * Modifies the given @caps inplace into a representation that represents the
1762 * same set of formats, but in a simpler form. Component structures that are
1763 * identical are merged. Component structures that have values that can be
1764 * merged are also merged.
1766 * Returns: The simplified caps.
1769 gst_caps_simplify (GstCaps * caps)
1771 GstStructure *simplify, *compare, *result = NULL;
1774 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1776 if (gst_caps_is_fixed (caps))
1779 caps = gst_caps_make_writable (caps);
1781 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1783 start = GST_CAPS_LEN (caps) - 1;
1784 for (i = start; i >= 0; i--) {
1785 simplify = gst_caps_get_structure_unchecked (caps, i);
1786 compare = gst_caps_get_structure_unchecked (caps, start);
1787 if (gst_structure_get_name_id (simplify) !=
1788 gst_structure_get_name_id (compare))
1790 for (j = start; j >= 0; j--) {
1793 compare = gst_caps_get_structure_unchecked (caps, j);
1794 if (gst_structure_get_name_id (simplify) !=
1795 gst_structure_get_name_id (compare)) {
1798 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1800 gst_caps_switch_structures (caps, simplify, result, i);
1803 gst_caps_remove_structure (caps, i);
1815 * @caps: (transfer full): a #GstCaps to fixate
1817 * Modifies the given @caps into a representation with only fixed
1818 * values. First the caps will be truncated and then the first structure will be
1819 * fixated with gst_structure_fixate().
1821 * Returns: (transfer full): the fixated caps
1824 gst_caps_fixate (GstCaps * caps)
1828 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1830 /* default fixation */
1831 caps = gst_caps_truncate (caps);
1832 caps = gst_caps_make_writable (caps);
1833 s = gst_caps_get_structure (caps, 0);
1834 gst_structure_fixate (s);
1842 * gst_caps_to_string:
1845 * Converts @caps to a string representation. This string representation
1846 * can be converted back to a #GstCaps by gst_caps_from_string().
1848 * For debugging purposes its easier to do something like this:
1850 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1852 * This prints the caps in human readble form.
1854 * Returns: (transfer full): a newly allocated string representing @caps.
1857 gst_caps_to_string (const GstCaps * caps)
1859 guint i, slen, clen;
1862 /* NOTE: This function is potentially called by the debug system,
1863 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1864 * should be careful to avoid recursion. This includes any functions
1865 * called by gst_caps_to_string. In particular, calls should
1866 * not use the GST_PTR_FORMAT extension. */
1869 return g_strdup ("NULL");
1871 if (CAPS_IS_ANY (caps)) {
1872 return g_strdup ("ANY");
1874 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1875 return g_strdup ("EMPTY");
1878 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1880 clen = GST_CAPS_LEN (caps);
1881 for (i = 0; i < clen; i++) {
1883 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1887 s = g_string_sized_new (slen);
1888 for (i = 0; i < clen; i++) {
1889 GstStructure *structure;
1892 /* ';' is now added by gst_structure_to_string */
1893 g_string_append_c (s, ' ');
1896 structure = gst_caps_get_structure_unchecked (caps, i);
1897 priv_gst_structure_append_to_gstring (structure, s);
1899 if (s->len && s->str[s->len - 1] == ';') {
1900 /* remove latest ';' */
1901 s->str[--s->len] = '\0';
1903 return g_string_free (s, FALSE);
1907 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1909 GstStructure *structure;
1912 if (strcmp ("ANY", string) == 0) {
1913 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1916 if (strcmp ("EMPTY", string) == 0) {
1920 structure = gst_structure_from_string (string, &s);
1921 if (structure == NULL) {
1924 gst_caps_append_structure_unchecked (caps, structure);
1928 while (g_ascii_isspace (*s))
1933 structure = gst_structure_from_string (s, &s);
1934 if (structure == NULL) {
1937 gst_caps_append_structure_unchecked (caps, structure);
1945 * gst_caps_from_string:
1946 * @string: a string to convert to #GstCaps
1948 * Converts @caps from a string representation.
1950 * Returns: (transfer full): a newly allocated #GstCaps
1953 gst_caps_from_string (const gchar * string)
1957 g_return_val_if_fail (string, FALSE);
1959 caps = gst_caps_new_empty ();
1960 if (gst_caps_from_string_inplace (caps, string)) {
1963 gst_caps_unref (caps);
1969 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1971 g_return_if_fail (G_IS_VALUE (src_value));
1972 g_return_if_fail (G_IS_VALUE (dest_value));
1973 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1974 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1975 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1977 g_value_take_string (dest_value,
1978 gst_caps_to_string (gst_value_get_caps (src_value)));