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 for (i = 0; i < n; i++) {
154 structure = gst_caps_get_structure_unchecked (caps, i);
155 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
161 /* creation/deletion */
163 _gst_caps_free (GstCaps * caps)
165 GstStructure *structure;
168 /* The refcount must be 0, but since we're only called by gst_caps_unref,
169 * don't bother testing. */
170 len = GST_CAPS_LEN (caps);
171 /* This can be used to get statistics about caps sizes */
172 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
173 for (i = 0; i < len; i++) {
174 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
175 gst_structure_set_parent_refcount (structure, NULL);
176 gst_structure_free (structure);
178 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
180 #ifdef DEBUG_REFCOUNT
181 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
183 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
187 gst_caps_init (GstCaps * caps, gsize size)
189 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
191 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
192 caps->mini_object.dispose = NULL;
193 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
195 /* the 32 has been determined by logging caps sizes in _gst_caps_free
196 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
198 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
200 GST_CAPS_ARRAY (caps) = g_ptr_array_new ();
204 * gst_caps_new_empty:
206 * Creates a new #GstCaps that is empty. That is, the returned
207 * #GstCaps contains no media formats.
208 * Caller is responsible for unreffing the returned caps.
210 * Returns: (transfer full): the new #GstCaps
213 gst_caps_new_empty (void)
217 caps = (GstCaps *) g_slice_new (GstCapsImpl);
219 gst_caps_init (caps, sizeof (GstCapsImpl));
221 #ifdef DEBUG_REFCOUNT
222 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
231 * Creates a new #GstCaps that indicates that it is compatible with
234 * Returns: (transfer full): the new #GstCaps
237 gst_caps_new_any (void)
239 GstCaps *caps = gst_caps_new_empty ();
241 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
247 * gst_caps_new_empty_simple:
248 * @media_type: the media type of the structure
250 * Creates a new #GstCaps that contains one #GstStructure with name
252 * Caller is responsible for unreffing the returned caps.
254 * Returns: (transfer full): the new #GstCaps
257 gst_caps_new_empty_simple (const char *media_type)
260 GstStructure *structure;
262 caps = gst_caps_new_empty ();
263 structure = gst_structure_new_empty (media_type);
265 gst_caps_append_structure_unchecked (caps, structure);
271 * gst_caps_new_simple:
272 * @media_type: the media type of the structure
273 * @fieldname: first field to set
274 * @...: additional arguments
276 * Creates a new #GstCaps that contains one #GstStructure. The
277 * structure is defined by the arguments, which have the same format
278 * as gst_structure_new().
279 * Caller is responsible for unreffing the returned caps.
281 * Returns: (transfer full): the new #GstCaps
284 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
287 GstStructure *structure;
290 caps = gst_caps_new_empty ();
292 va_start (var_args, fieldname);
293 structure = gst_structure_new_valist (media_type, fieldname, var_args);
297 gst_caps_append_structure_unchecked (caps, structure);
299 gst_caps_replace (&caps, NULL);
306 * @struct1: the first structure to add
307 * @...: additional structures to add
309 * Creates a new #GstCaps and adds all the structures listed as
310 * arguments. The list must be NULL-terminated. The structures
311 * are not copied; the returned #GstCaps owns the structures.
313 * Returns: (transfer full): the new #GstCaps
316 gst_caps_new_full (GstStructure * struct1, ...)
321 va_start (var_args, struct1);
322 caps = gst_caps_new_full_valist (struct1, var_args);
329 * gst_caps_new_full_valist:
330 * @structure: the first structure to add
331 * @var_args: additional structures to add
333 * Creates a new #GstCaps and adds all the structures listed as
334 * arguments. The list must be NULL-terminated. The structures
335 * are not copied; the returned #GstCaps owns the structures.
337 * Returns: (transfer full): the new #GstCaps
340 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
344 caps = gst_caps_new_empty ();
347 gst_caps_append_structure_unchecked (caps, structure);
348 structure = va_arg (var_args, GstStructure *);
355 gst_static_caps_get_type (void)
357 static GType staticcaps_type = 0;
359 if (G_UNLIKELY (staticcaps_type == 0)) {
360 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
362 return staticcaps_type;
366 * gst_static_caps_get:
367 * @static_caps: the #GstStaticCaps to convert
369 * Converts a #GstStaticCaps to a #GstCaps.
371 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
372 * Since the core holds an additional ref to the returned caps,
373 * use gst_caps_make_writable() on the returned caps to modify it.
376 gst_static_caps_get (GstStaticCaps * static_caps)
380 g_return_val_if_fail (static_caps != NULL, NULL);
382 caps = &static_caps->caps;
384 /* refcount is 0 when we need to convert */
385 if (G_UNLIKELY (*caps == NULL)) {
388 G_LOCK (static_caps_lock);
389 /* check if other thread already updated */
390 if (G_UNLIKELY (*caps != NULL))
393 string = static_caps->string;
395 if (G_UNLIKELY (string == NULL))
398 GST_CAT_TRACE (GST_CAT_CAPS, "creating %p", static_caps);
400 *caps = gst_caps_from_string (string);
402 /* convert to string */
403 if (G_UNLIKELY (*caps == NULL))
404 g_critical ("Could not convert static caps \"%s\"", string);
406 GST_CAT_TRACE (GST_CAT_CAPS, "created %p", static_caps);
408 G_UNLOCK (static_caps_lock);
410 /* ref the caps, makes it not writable */
411 if (G_LIKELY (*caps != NULL))
412 gst_caps_ref (*caps);
419 G_UNLOCK (static_caps_lock);
420 g_warning ("static caps %p string is NULL", static_caps);
426 * gst_static_caps_cleanup:
427 * @static_caps: the #GstStaticCaps to clean
429 * Clean up the cached caps contained in @static_caps.
432 gst_static_caps_cleanup (GstStaticCaps * static_caps)
434 G_LOCK (static_caps_lock);
435 gst_caps_replace (&static_caps->caps, NULL);
436 G_UNLOCK (static_caps_lock);
441 static GstStructure *
442 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
444 /* don't use index_fast, gst_caps_do_simplify relies on the order */
445 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
447 gst_structure_set_parent_refcount (s, NULL);
452 * gst_caps_steal_structure:
453 * @caps: the #GstCaps to retrieve from
454 * @index: Index of the structure to retrieve
456 * Retrieves the stucture with the given index from the list of structures
457 * contained in @caps. The caller becomes the owner of the returned structure.
459 * Returns: (transfer full): a pointer to the #GstStructure corresponding
465 gst_caps_steal_structure (GstCaps * caps, guint index)
467 g_return_val_if_fail (caps != NULL, NULL);
468 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
470 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
473 return gst_caps_remove_and_get_structure (caps, index);
478 * @caps1: the #GstCaps that will be appended to
479 * @caps2: (transfer full): the #GstCaps to append
481 * Appends the structures contained in @caps2 to @caps1. The structures in
482 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
483 * freed. If either caps is ANY, the resulting caps will be ANY.
486 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
488 GstStructure *structure;
491 g_return_if_fail (GST_IS_CAPS (caps1));
492 g_return_if_fail (GST_IS_CAPS (caps2));
493 g_return_if_fail (IS_WRITABLE (caps1));
495 caps2 = gst_caps_make_writable (caps2);
497 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
498 /* FIXME: this leaks */
499 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
500 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
501 structure = gst_caps_remove_and_get_structure (caps2, i);
502 gst_structure_free (structure);
505 for (i = GST_CAPS_LEN (caps2); i; i--) {
506 structure = gst_caps_remove_and_get_structure (caps2, 0);
507 gst_caps_append_structure_unchecked (caps1, structure);
510 gst_caps_unref (caps2); /* guaranteed to free it */
515 * @caps1: the #GstCaps that will take the new entries
516 * @caps2: (transfer full): the #GstCaps to merge in
518 * Appends the structures contained in @caps2 to @caps1 if they are not yet
519 * expressed by @caps1. The structures in @caps2 are not copied -- they are
520 * transferred to @caps1, and then @caps2 is freed.
521 * If either caps is ANY, the resulting caps will be ANY.
526 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
528 GstStructure *structure;
531 g_return_if_fail (GST_IS_CAPS (caps1));
532 g_return_if_fail (GST_IS_CAPS (caps2));
533 g_return_if_fail (IS_WRITABLE (caps1));
535 caps2 = gst_caps_make_writable (caps2);
537 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
538 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
539 structure = gst_caps_remove_and_get_structure (caps2, i);
540 gst_structure_free (structure);
542 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
543 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
544 for (i = GST_CAPS_LEN (caps1) - 1; i >= 0; i--) {
545 structure = gst_caps_remove_and_get_structure (caps1, i);
546 gst_structure_free (structure);
549 for (i = GST_CAPS_LEN (caps2); i; i--) {
550 structure = gst_caps_remove_and_get_structure (caps2, 0);
551 gst_caps_merge_structure (caps1, structure);
554 GstCaps *com = gst_caps_intersect (caps1, caps2);
555 GstCaps *add = gst_caps_subtract (caps2, com);
557 GST_DEBUG ("common : %d", gst_caps_get_size (com));
558 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
559 gst_caps_append (caps1, add);
560 gst_caps_unref (com);
563 gst_caps_unref (caps2); /* guaranteed to free it */
567 * gst_caps_append_structure:
568 * @caps: the #GstCaps that will be appended to
569 * @structure: (transfer full): the #GstStructure to append
571 * Appends @structure to @caps. The structure is not copied; @caps
572 * becomes the owner of @structure.
575 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
577 g_return_if_fail (GST_IS_CAPS (caps));
578 g_return_if_fail (IS_WRITABLE (caps));
580 if (G_LIKELY (structure)) {
581 gst_caps_append_structure_unchecked (caps, structure);
586 * gst_caps_remove_structure:
587 * @caps: the #GstCaps to remove from
588 * @idx: Index of the structure to remove
590 * removes the stucture with the given index from the list of structures
591 * contained in @caps.
594 gst_caps_remove_structure (GstCaps * caps, guint idx)
596 GstStructure *structure;
598 g_return_if_fail (caps != NULL);
599 g_return_if_fail (idx <= gst_caps_get_size (caps));
600 g_return_if_fail (IS_WRITABLE (caps));
602 structure = gst_caps_remove_and_get_structure (caps, idx);
603 gst_structure_free (structure);
607 * gst_caps_merge_structure:
608 * @caps: the #GstCaps that will the new structure
609 * @structure: (transfer full): the #GstStructure to merge
611 * Appends @structure to @caps if its not already expressed by @caps. The
612 * structure is not copied; @caps becomes the owner of @structure.
615 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
617 g_return_if_fail (GST_IS_CAPS (caps));
618 g_return_if_fail (IS_WRITABLE (caps));
620 if (G_LIKELY (structure)) {
621 GstStructure *structure1;
623 gboolean unique = TRUE;
625 /* check each structure */
626 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
627 structure1 = gst_caps_get_structure_unchecked (caps, i);
628 /* if structure is a subset of structure1, then skip it */
629 if (gst_structure_is_subset (structure, structure1)) {
635 gst_caps_append_structure_unchecked (caps, structure);
637 gst_structure_free (structure);
646 * Gets the number of structures contained in @caps.
648 * Returns: the number of structures that @caps contains
651 gst_caps_get_size (const GstCaps * caps)
653 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
655 return GST_CAPS_LEN (caps);
659 * gst_caps_get_structure:
661 * @index: the index of the structure
663 * Finds the structure in @caps that has the index @index, and
666 * WARNING: This function takes a const GstCaps *, but returns a
667 * non-const GstStructure *. This is for programming convenience --
668 * the caller should be aware that structures inside a constant
669 * #GstCaps should not be modified. However, if you know the caps
670 * are writable, either because you have just copied them or made
671 * them writable with gst_caps_make_writable(), you may modify the
672 * structure returned in the usual way, e.g. with functions like
673 * gst_structure_set().
675 * You do not need to free or unref the structure returned, it
676 * belongs to the #GstCaps.
678 * Returns: (transfer none): a pointer to the #GstStructure corresponding
682 gst_caps_get_structure (const GstCaps * caps, guint index)
684 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
685 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
687 return gst_caps_get_structure_unchecked (caps, index);
692 * @caps: the #GstCaps to copy
693 * @nth: the nth structure to copy
695 * Creates a new #GstCaps and appends a copy of the nth structure
696 * contained in @caps.
698 * Returns: (transfer full): the new #GstCaps
701 gst_caps_copy_nth (const GstCaps * caps, guint nth)
704 GstStructure *structure;
706 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
708 newcaps = gst_caps_new_empty ();
709 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
711 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
712 structure = gst_caps_get_structure_unchecked (caps, nth);
713 gst_caps_append_structure_unchecked (newcaps,
714 gst_structure_copy (structure));
722 * @caps: the #GstCaps to truncate
724 * Destructively discard all but the first structure from @caps. Useful when
725 * fixating. @caps must be writable.
728 gst_caps_truncate (GstCaps * caps)
732 g_return_if_fail (GST_IS_CAPS (caps));
733 g_return_if_fail (IS_WRITABLE (caps));
735 i = GST_CAPS_LEN (caps) - 1;
738 gst_caps_remove_structure (caps, i--);
742 * gst_caps_set_value:
743 * @caps: a writable caps
744 * @field: name of the field to set
745 * @value: value to set the field to
747 * Sets the given @field on all structures of @caps to the given @value.
748 * This is a convenience function for calling gst_structure_set_value() on
749 * all structures of @caps.
754 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
758 g_return_if_fail (GST_IS_CAPS (caps));
759 g_return_if_fail (IS_WRITABLE (caps));
760 g_return_if_fail (field != NULL);
761 g_return_if_fail (G_IS_VALUE (value));
763 len = GST_CAPS_LEN (caps);
764 for (i = 0; i < len; i++) {
765 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
766 gst_structure_set_value (structure, field, value);
771 * gst_caps_set_simple_valist:
772 * @caps: the #GstCaps to set
773 * @field: first field to set
774 * @varargs: additional parameters
776 * Sets fields in a #GstCaps. The arguments must be passed in the same
777 * manner as gst_structure_set(), and be NULL-terminated.
778 * <note>Prior to GStreamer version 0.10.26, this function failed when
779 * @caps was not simple. If your code needs to work with those versions
780 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
781 * is %TRUE for @caps.</note>
784 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
786 GValue value = { 0, };
788 g_return_if_fail (GST_IS_CAPS (caps));
789 g_return_if_fail (IS_WRITABLE (caps));
795 type = va_arg (varargs, GType);
797 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
798 if (G_UNLIKELY (err)) {
799 g_critical ("%s", err);
803 gst_caps_set_value (caps, field, &value);
805 g_value_unset (&value);
807 field = va_arg (varargs, const gchar *);
812 * gst_caps_set_simple:
813 * @caps: the #GstCaps to set
814 * @field: first field to set
815 * @...: additional parameters
817 * Sets fields in a #GstCaps. The arguments must be passed in the same
818 * manner as gst_structure_set(), and be NULL-terminated.
819 * <note>Prior to GStreamer version 0.10.26, this function failed when
820 * @caps was not simple. If your code needs to work with those versions
821 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
822 * is %TRUE for @caps.</note>
825 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
829 g_return_if_fail (GST_IS_CAPS (caps));
830 g_return_if_fail (IS_WRITABLE (caps));
832 va_start (var_args, field);
833 gst_caps_set_simple_valist (caps, field, var_args);
841 * @caps: the #GstCaps to test
843 * Determines if @caps represents any media format.
845 * Returns: TRUE if @caps represents any format.
848 gst_caps_is_any (const GstCaps * caps)
850 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
852 return (CAPS_IS_ANY (caps));
857 * @caps: the #GstCaps to test
859 * Determines if @caps represents no media formats.
861 * Returns: TRUE if @caps represents no formats.
864 gst_caps_is_empty (const GstCaps * caps)
866 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
868 if (CAPS_IS_ANY (caps))
871 return CAPS_IS_EMPTY_SIMPLE (caps);
875 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
878 return gst_value_is_fixed (value);
883 * @caps: the #GstCaps to test
885 * Fixed #GstCaps describe exactly one format, that is, they have exactly
886 * one structure, and each field in the structure describes a fixed type.
887 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
889 * Returns: TRUE if @caps is fixed
892 gst_caps_is_fixed (const GstCaps * caps)
894 GstStructure *structure;
896 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
898 if (GST_CAPS_LEN (caps) != 1)
901 structure = gst_caps_get_structure_unchecked (caps, 0);
903 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
907 * gst_caps_is_equal_fixed:
908 * @caps1: the #GstCaps to test
909 * @caps2: the #GstCaps to test
911 * Tests if two #GstCaps are equal. This function only works on fixed
914 * Returns: TRUE if the arguments represent the same format
917 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
919 GstStructure *struct1, *struct2;
921 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
922 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
924 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
925 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
927 return gst_structure_is_equal (struct1, struct2);
931 * gst_caps_is_always_compatible:
932 * @caps1: the #GstCaps to test
933 * @caps2: the #GstCaps to test
935 * A given #GstCaps structure is always compatible with another if
936 * every media format that is in the first is also contained in the
937 * second. That is, @caps1 is a subset of @caps2.
939 * Returns: TRUE if @caps1 is a subset of @caps2.
942 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
944 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
945 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
947 return gst_caps_is_subset (caps1, caps2);
951 * gst_caps_is_subset:
952 * @subset: a #GstCaps
953 * @superset: a potentially greater #GstCaps
955 * Checks if all caps represented by @subset are also represented by @superset.
956 * <note>This function does not work reliably if optional properties for caps
957 * are included on one caps and omitted on the other.</note>
959 * Returns: %TRUE if @subset is a subset of @superset
962 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
964 GstStructure *s1, *s2;
968 g_return_val_if_fail (subset != NULL, FALSE);
969 g_return_val_if_fail (superset != NULL, FALSE);
971 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
973 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
976 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
977 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
978 s1 = gst_caps_get_structure_unchecked (subset, i);
979 s2 = gst_caps_get_structure_unchecked (superset, j);
980 if (gst_structure_is_subset (s1, s2)) {
981 /* If we found a superset, continue with the next
982 * subset structure */
986 /* If we found no superset for this subset structure
987 * we return FALSE immediately */
998 * gst_caps_is_subset_structure:
1000 * @structure: a potential #GstStructure subset of @caps
1002 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
1003 * for more information.
1005 * Returns: %TRUE if @structure is a subset of @caps
1010 gst_caps_is_subset_structure (const GstCaps * caps,
1011 const GstStructure * structure)
1016 g_return_val_if_fail (caps != NULL, FALSE);
1017 g_return_val_if_fail (structure != NULL, FALSE);
1019 if (CAPS_IS_ANY (caps))
1021 if (CAPS_IS_EMPTY (caps))
1024 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1025 s = gst_caps_get_structure_unchecked (caps, i);
1026 if (gst_structure_is_subset (structure, s)) {
1027 /* If we found a superset return TRUE */
1036 * gst_caps_is_equal:
1037 * @caps1: a #GstCaps
1038 * @caps2: another #GstCaps
1040 * Checks if the given caps represent the same set of caps.
1041 * <note>This function does not work reliably if optional properties for caps
1042 * are included on one caps and omitted on the other.</note>
1044 * This function deals correctly with passing NULL for any of the caps.
1046 * Returns: TRUE if both caps are equal.
1049 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1051 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1052 * So there should be an assertion that caps1 and caps2 != NULL */
1054 /* NULL <-> NULL is allowed here */
1055 if (G_UNLIKELY (caps1 == caps2))
1058 /* one of them NULL => they are different (can't be both NULL because
1059 * we checked that above) */
1060 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1063 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1064 return gst_caps_is_equal_fixed (caps1, caps2);
1066 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1070 * gst_caps_is_strictly_equal:
1071 * @caps1: a #GstCaps
1072 * @caps2: another #GstCaps
1074 * Checks if the given caps are exactly the same set of caps.
1076 * This function deals correctly with passing NULL for any of the caps.
1078 * Returns: TRUE if both caps are strictly equal.
1083 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1086 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1087 * So there should be an assertion that caps1 and caps2 != NULL */
1089 /* NULL <-> NULL is allowed here */
1090 if (G_UNLIKELY (caps1 == caps2))
1093 /* one of them NULL => they are different (can't be both NULL because
1094 * we checked that above) */
1095 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1098 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1101 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1102 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1103 gst_caps_get_structure_unchecked (caps2, i)))
1110 /* intersect operation */
1113 * gst_caps_can_intersect:
1114 * @caps1: a #GstCaps to intersect
1115 * @caps2: a #GstCaps to intersect
1117 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1120 * Returns: %TRUE if intersection would be not empty
1125 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1127 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1128 guint j, k, len1, len2;
1129 GstStructure *struct1;
1130 GstStructure *struct2;
1132 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1133 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1135 /* caps are exactly the same pointers */
1136 if (G_UNLIKELY (caps1 == caps2))
1139 /* empty caps on either side, return empty */
1140 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1143 /* one of the caps is any */
1144 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1147 /* run zigzag on top line then right line, this preserves the caps order
1148 * much better than a simple loop.
1150 * This algorithm zigzags over the caps structures as demonstrated in
1151 * the folowing matrix:
1154 * +------------- total distance: +-------------
1155 * | 1 2 4 7 0 | 0 1 2 3
1156 * caps2 | 3 5 8 10 1 | 1 2 3 4
1157 * | 6 9 11 12 2 | 2 3 4 5
1159 * First we iterate over the caps1 structures (top line) intersecting
1160 * the structures diagonally down, then we iterate over the caps2
1161 * structures. The result is that the intersections are ordered based on the
1162 * sum of the indexes in the list.
1164 len1 = GST_CAPS_LEN (caps1);
1165 len2 = GST_CAPS_LEN (caps2);
1166 for (i = 0; i < len1 + len2 - 1; i++) {
1167 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1168 j = MIN (i, len1 - 1);
1169 /* subset index stays 0 until i reaches superset->structs->len, then it
1170 * counts up from 1 to subset->structs->len - 1 */
1171 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1173 /* now run the diagonal line, end condition is the left or bottom
1176 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1177 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1179 if (gst_structure_can_intersect (struct1, struct2)) {
1182 /* move down left */
1184 if (G_UNLIKELY (j == 0))
1185 break; /* so we don't roll back to G_MAXUINT */
1193 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1195 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1196 guint j, k, len1, len2;
1198 GstStructure *struct1;
1199 GstStructure *struct2;
1201 GstStructure *istruct;
1203 /* caps are exactly the same pointers, just copy one caps */
1204 if (G_UNLIKELY (caps1 == caps2))
1205 return _gst_caps_copy (caps1);
1207 /* empty caps on either side, return empty */
1208 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1209 return gst_caps_new_empty ();
1211 /* one of the caps is any, just copy the other caps */
1212 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1213 return _gst_caps_copy (caps2);
1214 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1215 return _gst_caps_copy (caps1);
1217 dest = gst_caps_new_empty ();
1219 /* run zigzag on top line then right line, this preserves the caps order
1220 * much better than a simple loop.
1222 * This algorithm zigzags over the caps structures as demonstrated in
1223 * the folowing matrix:
1231 * First we iterate over the caps1 structures (top line) intersecting
1232 * the structures diagonally down, then we iterate over the caps2
1235 len1 = GST_CAPS_LEN (caps1);
1236 len2 = GST_CAPS_LEN (caps2);
1237 for (i = 0; i < len1 + len2 - 1; i++) {
1238 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1239 j = MIN (i, len1 - 1);
1240 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1241 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1242 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1244 /* now run the diagonal line, end condition is the left or bottom
1247 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1248 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1250 istruct = gst_structure_intersect (struct1, struct2);
1252 gst_caps_merge_structure (dest, istruct);
1253 /* move down left */
1255 if (G_UNLIKELY (j == 0))
1256 break; /* so we don't roll back to G_MAXUINT */
1264 * gst_caps_intersect_first:
1265 * @caps1: a #GstCaps to intersect
1266 * @caps2: a #GstCaps to intersect
1268 * Creates a new #GstCaps that contains all the formats that are common
1269 * to both @caps1 and @caps2.
1271 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1272 * fashion as @caps1.
1274 * Returns: the new #GstCaps
1277 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1280 guint j, len1, len2;
1282 GstStructure *struct1;
1283 GstStructure *struct2;
1285 GstStructure *istruct;
1287 /* caps are exactly the same pointers, just copy one caps */
1288 if (G_UNLIKELY (caps1 == caps2))
1289 return gst_caps_copy (caps1);
1291 /* empty caps on either side, return empty */
1292 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1293 return gst_caps_new_empty ();
1295 /* one of the caps is any, just copy the other caps */
1296 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1297 return gst_caps_copy (caps2);
1298 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1299 return gst_caps_copy (caps1);
1301 dest = gst_caps_new_empty ();
1303 len1 = GST_CAPS_LEN (caps1);
1304 len2 = GST_CAPS_LEN (caps2);
1305 for (i = 0; i < len1; i++) {
1306 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1307 for (j = 0; j < len2; j++) {
1308 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1309 istruct = gst_structure_intersect (struct1, struct2);
1311 gst_caps_merge_structure (dest, istruct);
1319 * gst_caps_intersect_full:
1320 * @caps1: a #GstCaps to intersect
1321 * @caps2: a #GstCaps to intersect
1322 * @mode: The intersection algorithm/mode to use
1324 * Creates a new #GstCaps that contains all the formats that are common
1325 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1328 * Returns: the new #GstCaps
1332 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1333 GstCapsIntersectMode mode)
1335 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1336 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1339 case GST_CAPS_INTERSECT_FIRST:
1340 return gst_caps_intersect_first (caps1, caps2);
1342 g_warning ("Unknown caps intersect mode: %d", mode);
1344 case GST_CAPS_INTERSECT_ZIG_ZAG:
1345 return gst_caps_intersect_zig_zag (caps1, caps2);
1350 * gst_caps_intersect:
1351 * @caps1: a #GstCaps to intersect
1352 * @caps2: a #GstCaps to intersect
1354 * Creates a new #GstCaps that contains all the formats that are common
1355 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1357 * Returns: the new #GstCaps
1360 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1362 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1366 /* subtract operation */
1370 const GstStructure *subtract_from;
1376 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1379 SubtractionEntry *e = user_data;
1380 GValue subtraction = { 0, };
1381 const GValue *other;
1382 GstStructure *structure;
1384 other = gst_structure_id_get_value (e->subtract_from, field_id);
1388 if (!gst_value_subtract (&subtraction, other, value))
1390 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1391 g_value_unset (&subtraction);
1394 structure = gst_structure_copy (e->subtract_from);
1395 gst_structure_id_set_value (structure, field_id, &subtraction);
1396 g_value_unset (&subtraction);
1397 e->put_into = g_slist_prepend (e->put_into, structure);
1403 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1404 const GstStructure * subtrahend)
1409 e.subtract_from = minuend;
1412 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1413 gst_caps_structure_subtract_field, &e);
1419 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1420 gst_structure_free (walk->data);
1422 g_slist_free (e.put_into);
1428 * gst_caps_subtract:
1429 * @minuend: #GstCaps to subtract from
1430 * @subtrahend: #GstCaps to subtract
1432 * Subtracts the @subtrahend from the @minuend.
1433 * <note>This function does not work reliably if optional properties for caps
1434 * are included on one caps and omitted on the other.</note>
1436 * Returns: the resulting caps
1439 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1444 GstCaps *dest = NULL, *src;
1446 g_return_val_if_fail (minuend != NULL, NULL);
1447 g_return_val_if_fail (subtrahend != NULL, NULL);
1449 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1450 return gst_caps_new_empty ();
1452 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1453 return _gst_caps_copy (minuend);
1455 /* FIXME: Do we want this here or above?
1456 The reason we need this is that there is no definition about what
1457 ANY means for specific types, so it's not possible to reduce ANY partially
1458 You can only remove everything or nothing and that is done above.
1459 Note: there's a test that checks this behaviour. */
1460 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1461 sublen = GST_CAPS_LEN (subtrahend);
1462 g_assert (sublen > 0);
1464 src = _gst_caps_copy (minuend);
1465 for (i = 0; i < sublen; i++) {
1468 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1470 gst_caps_unref (src);
1473 dest = gst_caps_new_empty ();
1474 srclen = GST_CAPS_LEN (src);
1475 for (j = 0; j < srclen; j++) {
1476 min = gst_caps_get_structure_unchecked (src, j);
1477 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1480 if (gst_caps_structure_subtract (&list, min, sub)) {
1483 for (walk = list; walk; walk = g_slist_next (walk)) {
1484 gst_caps_append_structure_unchecked (dest,
1485 (GstStructure *) walk->data);
1487 g_slist_free (list);
1489 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1492 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1495 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1496 gst_caps_unref (src);
1501 gst_caps_unref (src);
1502 gst_caps_do_simplify (dest);
1506 /* union operation */
1509 static GstStructure *
1510 gst_caps_structure_union (const GstStructure * struct1,
1511 const GstStructure * struct2)
1515 const GstStructureField *field1;
1516 const GstStructureField *field2;
1519 /* FIXME this doesn't actually work */
1521 if (struct1->name != struct2->name)
1524 dest = gst_structure_new_id_empty (struct1->name);
1526 for (i = 0; i < struct1->fields->len; i++) {
1527 GValue dest_value = { 0 };
1529 field1 = GST_STRUCTURE_FIELD (struct1, i);
1530 field2 = gst_structure_id_get_field (struct2, field1->name);
1532 if (field2 == NULL) {
1535 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1536 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1539 ret = gst_value_compare (&field1->value, &field2->value);
1550 * @caps1: a #GstCaps to union
1551 * @caps2: a #GstCaps to union
1553 * Creates a new #GstCaps that contains all the formats that are in
1554 * either @caps1 and @caps2.
1556 * Returns: the new #GstCaps
1559 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1564 /* NULL pointers are no correct GstCaps */
1565 g_return_val_if_fail (caps1 != NULL, NULL);
1566 g_return_val_if_fail (caps2 != NULL, NULL);
1568 if (CAPS_IS_EMPTY (caps1))
1569 return _gst_caps_copy (caps2);
1571 if (CAPS_IS_EMPTY (caps2))
1572 return _gst_caps_copy (caps1);
1574 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1575 return gst_caps_new_any ();
1577 dest1 = _gst_caps_copy (caps1);
1578 dest2 = _gst_caps_copy (caps2);
1579 gst_caps_append (dest1, dest2);
1581 gst_caps_do_simplify (dest1);
1585 /* normalize/simplify operations */
1587 typedef struct _NormalizeForeach
1590 GstStructure *structure;
1595 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1597 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1601 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1602 guint len = gst_value_list_get_size (value);
1603 for (i = 1; i < len; i++) {
1604 const GValue *v = gst_value_list_get_value (value, i);
1605 GstStructure *structure = gst_structure_copy (nf->structure);
1607 gst_structure_id_set_value (structure, field_id, v);
1608 gst_caps_append_structure_unchecked (nf->caps, structure);
1611 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1612 gst_structure_id_set_value (nf->structure, field_id, &val);
1613 g_value_unset (&val);
1621 * gst_caps_normalize:
1622 * @caps: a #GstCaps to normalize
1624 * Creates a new #GstCaps that represents the same set of formats as
1625 * @caps, but contains no lists. Each list is expanded into separate
1628 * Returns: the new #GstCaps
1631 gst_caps_normalize (const GstCaps * caps)
1633 NormalizeForeach nf;
1637 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1639 newcaps = _gst_caps_copy (caps);
1642 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1643 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1645 while (!gst_structure_foreach (nf.structure,
1646 gst_caps_normalize_foreach, &nf));
1653 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1656 const GstStructure *struct1 = *((const GstStructure **) one);
1657 const GstStructure *struct2 = *((const GstStructure **) two);
1659 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1660 So what's the best way? */
1661 ret = strcmp (gst_structure_get_name (struct1),
1662 gst_structure_get_name (struct2));
1666 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1673 GstStructure *compare;
1678 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1681 UnionField *u = user_data;
1682 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1686 g_value_unset (&u->value);
1689 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1692 g_value_unset (&u->value);
1696 gst_value_union (&u->value, val, value);
1701 gst_caps_structure_simplify (GstStructure ** result,
1702 const GstStructure * simplify, GstStructure * compare)
1705 UnionField field = { 0, {0,}, NULL };
1707 /* try to subtract to get a real subset */
1708 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1709 if (list == NULL) { /* no result */
1712 } else if (list->next == NULL) { /* one result */
1713 *result = list->data;
1714 g_slist_free (list);
1716 } else { /* multiple results */
1717 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1718 g_slist_free (list);
1723 /* try to union both structs */
1724 field.compare = compare;
1725 if (gst_structure_foreach ((GstStructure *) simplify,
1726 gst_caps_structure_figure_out_union, &field)) {
1727 gboolean ret = FALSE;
1729 /* now we know all of simplify's fields are the same in compare
1730 * but at most one field: field.name */
1731 if (G_IS_VALUE (&field.value)) {
1732 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1733 gst_structure_id_set_value (compare, field.name, &field.value);
1737 g_value_unset (&field.value);
1738 } else if (gst_structure_n_fields (simplify) <=
1739 gst_structure_n_fields (compare)) {
1740 /* compare is just more specific, will be optimized away later */
1741 /* FIXME: do this here? */
1742 GST_LOG ("found a case that will be optimized later.");
1744 gchar *one = gst_structure_to_string (simplify);
1745 gchar *two = gst_structure_to_string (compare);
1748 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1760 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1761 GstStructure * new, gint i)
1763 gst_structure_set_parent_refcount (old, NULL);
1764 gst_structure_free (old);
1765 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1766 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1770 * gst_caps_do_simplify:
1771 * @caps: a #GstCaps to simplify
1773 * Modifies the given @caps inplace into a representation that represents the
1774 * same set of formats, but in a simpler form. Component structures that are
1775 * identical are merged. Component structures that have values that can be
1776 * merged are also merged.
1778 * Returns: TRUE, if the caps could be simplified
1781 gst_caps_do_simplify (GstCaps * caps)
1783 GstStructure *simplify, *compare, *result = NULL;
1785 gboolean changed = FALSE;
1787 g_return_val_if_fail (caps != NULL, FALSE);
1788 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1790 if (gst_caps_get_size (caps) < 2)
1793 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1795 start = GST_CAPS_LEN (caps) - 1;
1796 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1797 simplify = gst_caps_get_structure_unchecked (caps, i);
1798 if (gst_structure_get_name_id (simplify) !=
1799 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1802 for (j = start; j >= 0; j--) {
1805 compare = gst_caps_get_structure_unchecked (caps, j);
1806 if (gst_structure_get_name_id (simplify) !=
1807 gst_structure_get_name_id (compare)) {
1810 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1812 gst_caps_switch_structures (caps, simplify, result, i);
1815 gst_caps_remove_structure (caps, i);
1827 /* gst_caps_do_simplify (caps); */
1833 * @caps: a #GstCaps to fixate
1835 * Modifies the given @caps inplace into a representation with only fixed
1836 * values. First the caps will be truncated and then the first structure will be
1837 * fixated with gst_structure_fixate(). @caps should be writable.
1840 gst_caps_fixate (GstCaps * caps)
1844 g_return_if_fail (GST_IS_CAPS (caps));
1845 g_return_if_fail (IS_WRITABLE (caps));
1847 /* default fixation */
1848 gst_caps_truncate (caps);
1849 s = gst_caps_get_structure (caps, 0);
1850 gst_structure_fixate (s);
1856 * gst_caps_to_string:
1859 * Converts @caps to a string representation. This string representation
1860 * can be converted back to a #GstCaps by gst_caps_from_string().
1862 * For debugging purposes its easier to do something like this:
1864 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1866 * This prints the caps in human readble form.
1868 * Returns: (transfer full): a newly allocated string representing @caps.
1871 gst_caps_to_string (const GstCaps * caps)
1873 guint i, slen, clen;
1876 /* NOTE: This function is potentially called by the debug system,
1877 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1878 * should be careful to avoid recursion. This includes any functions
1879 * called by gst_caps_to_string. In particular, calls should
1880 * not use the GST_PTR_FORMAT extension. */
1883 return g_strdup ("NULL");
1885 if (CAPS_IS_ANY (caps)) {
1886 return g_strdup ("ANY");
1888 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1889 return g_strdup ("EMPTY");
1892 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1894 clen = GST_CAPS_LEN (caps);
1895 for (i = 0; i < clen; i++) {
1897 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1901 s = g_string_sized_new (slen);
1902 for (i = 0; i < clen; i++) {
1903 GstStructure *structure;
1906 /* ';' is now added by gst_structure_to_string */
1907 g_string_append_c (s, ' ');
1910 structure = gst_caps_get_structure_unchecked (caps, i);
1911 priv_gst_structure_append_to_gstring (structure, s);
1913 if (s->len && s->str[s->len - 1] == ';') {
1914 /* remove latest ';' */
1915 s->str[--s->len] = '\0';
1917 return g_string_free (s, FALSE);
1921 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1923 GstStructure *structure;
1926 if (strcmp ("ANY", string) == 0) {
1927 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1930 if (strcmp ("EMPTY", string) == 0) {
1934 structure = gst_structure_from_string (string, &s);
1935 if (structure == NULL) {
1938 gst_caps_append_structure_unchecked (caps, structure);
1942 while (g_ascii_isspace (*s))
1947 structure = gst_structure_from_string (s, &s);
1948 if (structure == NULL) {
1951 gst_caps_append_structure_unchecked (caps, structure);
1959 * gst_caps_from_string:
1960 * @string: a string to convert to #GstCaps
1962 * Converts @caps from a string representation.
1964 * Returns: (transfer full): a newly allocated #GstCaps
1967 gst_caps_from_string (const gchar * string)
1971 g_return_val_if_fail (string, FALSE);
1973 caps = gst_caps_new_empty ();
1974 if (gst_caps_from_string_inplace (caps, string)) {
1977 gst_caps_unref (caps);
1983 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1985 g_return_if_fail (G_IS_VALUE (src_value));
1986 g_return_if_fail (G_IS_VALUE (dest_value));
1987 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1988 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1989 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1991 g_value_take_string (dest_value,
1992 gst_caps_to_string (gst_value_get_caps (src_value)));