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 *caps = gst_caps_from_string (string);
400 /* convert to string */
401 if (G_UNLIKELY (*caps == NULL))
402 g_critical ("Could not convert static caps \"%s\"", string);
404 GST_CAT_TRACE (GST_CAT_CAPS, "created %p from string %s", static_caps,
407 G_UNLOCK (static_caps_lock);
409 /* ref the caps, makes it not writable */
410 if (G_LIKELY (*caps != NULL))
411 gst_caps_ref (*caps);
418 G_UNLOCK (static_caps_lock);
419 g_warning ("static caps %p string is NULL", static_caps);
425 * gst_static_caps_cleanup:
426 * @static_caps: the #GstStaticCaps to clean
428 * Clean up the cached caps contained in @static_caps.
431 gst_static_caps_cleanup (GstStaticCaps * static_caps)
433 G_LOCK (static_caps_lock);
434 gst_caps_replace (&static_caps->caps, NULL);
435 G_UNLOCK (static_caps_lock);
440 static GstStructure *
441 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
443 /* don't use index_fast, gst_caps_do_simplify relies on the order */
444 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
446 gst_structure_set_parent_refcount (s, NULL);
451 * gst_caps_steal_structure:
452 * @caps: the #GstCaps to retrieve from
453 * @index: Index of the structure to retrieve
455 * Retrieves the stucture with the given index from the list of structures
456 * contained in @caps. The caller becomes the owner of the returned structure.
458 * Returns: (transfer full): a pointer to the #GstStructure corresponding
464 gst_caps_steal_structure (GstCaps * caps, guint index)
466 g_return_val_if_fail (caps != NULL, NULL);
467 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
469 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
472 return gst_caps_remove_and_get_structure (caps, index);
477 * @caps1: the #GstCaps that will be appended to
478 * @caps2: (transfer full): the #GstCaps to append
480 * Appends the structures contained in @caps2 to @caps1. The structures in
481 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
482 * freed. If either caps is ANY, the resulting caps will be ANY.
485 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
487 GstStructure *structure;
490 g_return_if_fail (GST_IS_CAPS (caps1));
491 g_return_if_fail (GST_IS_CAPS (caps2));
492 g_return_if_fail (IS_WRITABLE (caps1));
494 caps2 = gst_caps_make_writable (caps2);
496 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
497 /* FIXME: this leaks */
498 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
499 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
500 structure = gst_caps_remove_and_get_structure (caps2, i);
501 gst_structure_free (structure);
504 for (i = GST_CAPS_LEN (caps2); i; i--) {
505 structure = gst_caps_remove_and_get_structure (caps2, 0);
506 gst_caps_append_structure_unchecked (caps1, structure);
509 gst_caps_unref (caps2); /* guaranteed to free it */
514 * @caps1: the #GstCaps that will take the new entries
515 * @caps2: (transfer full): the #GstCaps to merge in
517 * Appends the structures contained in @caps2 to @caps1 if they are not yet
518 * expressed by @caps1. The structures in @caps2 are not copied -- they are
519 * transferred to @caps1, and then @caps2 is freed.
520 * If either caps is ANY, the resulting caps will be ANY.
525 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
527 GstStructure *structure;
530 g_return_if_fail (GST_IS_CAPS (caps1));
531 g_return_if_fail (GST_IS_CAPS (caps2));
532 g_return_if_fail (IS_WRITABLE (caps1));
534 caps2 = gst_caps_make_writable (caps2);
536 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
537 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
538 structure = gst_caps_remove_and_get_structure (caps2, i);
539 gst_structure_free (structure);
541 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
542 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
543 for (i = GST_CAPS_LEN (caps1) - 1; i >= 0; i--) {
544 structure = gst_caps_remove_and_get_structure (caps1, i);
545 gst_structure_free (structure);
548 for (i = GST_CAPS_LEN (caps2); i; i--) {
549 structure = gst_caps_remove_and_get_structure (caps2, 0);
550 gst_caps_merge_structure (caps1, structure);
553 GstCaps *com = gst_caps_intersect (caps1, caps2);
554 GstCaps *add = gst_caps_subtract (caps2, com);
556 GST_DEBUG ("common : %d", gst_caps_get_size (com));
557 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
558 gst_caps_append (caps1, add);
559 gst_caps_unref (com);
562 gst_caps_unref (caps2); /* guaranteed to free it */
566 * gst_caps_append_structure:
567 * @caps: the #GstCaps that will be appended to
568 * @structure: (transfer full): the #GstStructure to append
570 * Appends @structure to @caps. The structure is not copied; @caps
571 * becomes the owner of @structure.
574 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
576 g_return_if_fail (GST_IS_CAPS (caps));
577 g_return_if_fail (IS_WRITABLE (caps));
579 if (G_LIKELY (structure)) {
580 gst_caps_append_structure_unchecked (caps, structure);
585 * gst_caps_remove_structure:
586 * @caps: the #GstCaps to remove from
587 * @idx: Index of the structure to remove
589 * removes the stucture with the given index from the list of structures
590 * contained in @caps.
593 gst_caps_remove_structure (GstCaps * caps, guint idx)
595 GstStructure *structure;
597 g_return_if_fail (caps != NULL);
598 g_return_if_fail (idx <= gst_caps_get_size (caps));
599 g_return_if_fail (IS_WRITABLE (caps));
601 structure = gst_caps_remove_and_get_structure (caps, idx);
602 gst_structure_free (structure);
606 * gst_caps_merge_structure:
607 * @caps: the #GstCaps that will the new structure
608 * @structure: (transfer full): the #GstStructure to merge
610 * Appends @structure to @caps if its not already expressed by @caps. The
611 * structure is not copied; @caps becomes the owner of @structure.
614 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
616 g_return_if_fail (GST_IS_CAPS (caps));
617 g_return_if_fail (IS_WRITABLE (caps));
619 if (G_LIKELY (structure)) {
620 GstStructure *structure1;
622 gboolean unique = TRUE;
624 /* check each structure */
625 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
626 structure1 = gst_caps_get_structure_unchecked (caps, i);
627 /* if structure is a subset of structure1, then skip it */
628 if (gst_structure_is_subset (structure, structure1)) {
634 gst_caps_append_structure_unchecked (caps, structure);
636 gst_structure_free (structure);
645 * Gets the number of structures contained in @caps.
647 * Returns: the number of structures that @caps contains
650 gst_caps_get_size (const GstCaps * caps)
652 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
654 return GST_CAPS_LEN (caps);
658 * gst_caps_get_structure:
660 * @index: the index of the structure
662 * Finds the structure in @caps that has the index @index, and
665 * WARNING: This function takes a const GstCaps *, but returns a
666 * non-const GstStructure *. This is for programming convenience --
667 * the caller should be aware that structures inside a constant
668 * #GstCaps should not be modified. However, if you know the caps
669 * are writable, either because you have just copied them or made
670 * them writable with gst_caps_make_writable(), you may modify the
671 * structure returned in the usual way, e.g. with functions like
672 * gst_structure_set().
674 * You do not need to free or unref the structure returned, it
675 * belongs to the #GstCaps.
677 * Returns: (transfer none): a pointer to the #GstStructure corresponding
681 gst_caps_get_structure (const GstCaps * caps, guint index)
683 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
684 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
686 return gst_caps_get_structure_unchecked (caps, index);
691 * @caps: the #GstCaps to copy
692 * @nth: the nth structure to copy
694 * Creates a new #GstCaps and appends a copy of the nth structure
695 * contained in @caps.
697 * Returns: (transfer full): the new #GstCaps
700 gst_caps_copy_nth (const GstCaps * caps, guint nth)
703 GstStructure *structure;
705 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
707 newcaps = gst_caps_new_empty ();
708 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
710 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
711 structure = gst_caps_get_structure_unchecked (caps, nth);
712 gst_caps_append_structure_unchecked (newcaps,
713 gst_structure_copy (structure));
721 * @caps: the #GstCaps to truncate
723 * Destructively discard all but the first structure from @caps. Useful when
724 * fixating. @caps must be writable.
727 gst_caps_truncate (GstCaps * caps)
731 g_return_if_fail (GST_IS_CAPS (caps));
732 g_return_if_fail (IS_WRITABLE (caps));
734 i = GST_CAPS_LEN (caps) - 1;
737 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 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1051 * So there should be an assertion that caps1 and caps2 != NULL */
1053 /* NULL <-> NULL is allowed here */
1054 if (G_UNLIKELY (caps1 == caps2))
1057 /* one of them NULL => they are different (can't be both NULL because
1058 * we checked that above) */
1059 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1062 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1063 return gst_caps_is_equal_fixed (caps1, caps2);
1065 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1069 * gst_caps_is_strictly_equal:
1070 * @caps1: a #GstCaps
1071 * @caps2: another #GstCaps
1073 * Checks if the given caps are exactly the same set of caps.
1075 * This function deals correctly with passing NULL for any of the caps.
1077 * Returns: TRUE if both caps are strictly equal.
1082 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1085 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1086 * So there should be an assertion that caps1 and caps2 != NULL */
1088 /* NULL <-> NULL is allowed here */
1089 if (G_UNLIKELY (caps1 == caps2))
1092 /* one of them NULL => they are different (can't be both NULL because
1093 * we checked that above) */
1094 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1097 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1100 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1101 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1102 gst_caps_get_structure_unchecked (caps2, i)))
1109 /* intersect operation */
1112 * gst_caps_can_intersect:
1113 * @caps1: a #GstCaps to intersect
1114 * @caps2: a #GstCaps to intersect
1116 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1119 * Returns: %TRUE if intersection would be not empty
1124 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1126 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1127 guint j, k, len1, len2;
1128 GstStructure *struct1;
1129 GstStructure *struct2;
1131 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1132 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1134 /* caps are exactly the same pointers */
1135 if (G_UNLIKELY (caps1 == caps2))
1138 /* empty caps on either side, return empty */
1139 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1142 /* one of the caps is any */
1143 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1146 /* run zigzag on top line then right line, this preserves the caps order
1147 * much better than a simple loop.
1149 * This algorithm zigzags over the caps structures as demonstrated in
1150 * the folowing matrix:
1153 * +------------- total distance: +-------------
1154 * | 1 2 4 7 0 | 0 1 2 3
1155 * caps2 | 3 5 8 10 1 | 1 2 3 4
1156 * | 6 9 11 12 2 | 2 3 4 5
1158 * First we iterate over the caps1 structures (top line) intersecting
1159 * the structures diagonally down, then we iterate over the caps2
1160 * structures. The result is that the intersections are ordered based on the
1161 * sum of the indexes in the list.
1163 len1 = GST_CAPS_LEN (caps1);
1164 len2 = GST_CAPS_LEN (caps2);
1165 for (i = 0; i < len1 + len2 - 1; i++) {
1166 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1167 j = MIN (i, len1 - 1);
1168 /* subset index stays 0 until i reaches superset->structs->len, then it
1169 * counts up from 1 to subset->structs->len - 1 */
1170 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1172 /* now run the diagonal line, end condition is the left or bottom
1175 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1176 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1178 if (gst_structure_can_intersect (struct1, struct2)) {
1181 /* move down left */
1183 if (G_UNLIKELY (j == 0))
1184 break; /* so we don't roll back to G_MAXUINT */
1192 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1194 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1195 guint j, k, len1, len2;
1197 GstStructure *struct1;
1198 GstStructure *struct2;
1200 GstStructure *istruct;
1202 /* caps are exactly the same pointers, just copy one caps */
1203 if (G_UNLIKELY (caps1 == caps2))
1204 return _gst_caps_copy (caps1);
1206 /* empty caps on either side, return empty */
1207 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1208 return gst_caps_new_empty ();
1210 /* one of the caps is any, just copy the other caps */
1211 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1212 return _gst_caps_copy (caps2);
1213 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1214 return _gst_caps_copy (caps1);
1216 dest = gst_caps_new_empty ();
1218 /* run zigzag on top line then right line, this preserves the caps order
1219 * much better than a simple loop.
1221 * This algorithm zigzags over the caps structures as demonstrated in
1222 * the folowing matrix:
1230 * First we iterate over the caps1 structures (top line) intersecting
1231 * the structures diagonally down, then we iterate over the caps2
1234 len1 = GST_CAPS_LEN (caps1);
1235 len2 = GST_CAPS_LEN (caps2);
1236 for (i = 0; i < len1 + len2 - 1; i++) {
1237 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1238 j = MIN (i, len1 - 1);
1239 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1240 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1241 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1243 /* now run the diagonal line, end condition is the left or bottom
1246 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1247 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1249 istruct = gst_structure_intersect (struct1, struct2);
1251 gst_caps_merge_structure (dest, istruct);
1252 /* move down left */
1254 if (G_UNLIKELY (j == 0))
1255 break; /* so we don't roll back to G_MAXUINT */
1263 * gst_caps_intersect_first:
1264 * @caps1: a #GstCaps to intersect
1265 * @caps2: a #GstCaps to intersect
1267 * Creates a new #GstCaps that contains all the formats that are common
1268 * to both @caps1 and @caps2.
1270 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1271 * fashion as @caps1.
1273 * Returns: the new #GstCaps
1276 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1279 guint j, len1, len2;
1281 GstStructure *struct1;
1282 GstStructure *struct2;
1284 GstStructure *istruct;
1286 /* caps are exactly the same pointers, just copy one caps */
1287 if (G_UNLIKELY (caps1 == caps2))
1288 return gst_caps_copy (caps1);
1290 /* empty caps on either side, return empty */
1291 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1292 return gst_caps_new_empty ();
1294 /* one of the caps is any, just copy the other caps */
1295 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1296 return gst_caps_copy (caps2);
1297 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1298 return gst_caps_copy (caps1);
1300 dest = gst_caps_new_empty ();
1302 len1 = GST_CAPS_LEN (caps1);
1303 len2 = GST_CAPS_LEN (caps2);
1304 for (i = 0; i < len1; i++) {
1305 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1306 for (j = 0; j < len2; j++) {
1307 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1308 istruct = gst_structure_intersect (struct1, struct2);
1310 gst_caps_merge_structure (dest, istruct);
1318 * gst_caps_intersect_full:
1319 * @caps1: a #GstCaps to intersect
1320 * @caps2: a #GstCaps to intersect
1321 * @mode: The intersection algorithm/mode to use
1323 * Creates a new #GstCaps that contains all the formats that are common
1324 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1327 * Returns: the new #GstCaps
1331 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1332 GstCapsIntersectMode mode)
1334 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1335 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1338 case GST_CAPS_INTERSECT_FIRST:
1339 return gst_caps_intersect_first (caps1, caps2);
1341 g_warning ("Unknown caps intersect mode: %d", mode);
1343 case GST_CAPS_INTERSECT_ZIG_ZAG:
1344 return gst_caps_intersect_zig_zag (caps1, caps2);
1349 * gst_caps_intersect:
1350 * @caps1: a #GstCaps to intersect
1351 * @caps2: a #GstCaps to intersect
1353 * Creates a new #GstCaps that contains all the formats that are common
1354 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1356 * Returns: the new #GstCaps
1359 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1361 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1365 /* subtract operation */
1369 const GstStructure *subtract_from;
1375 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1378 SubtractionEntry *e = user_data;
1379 GValue subtraction = { 0, };
1380 const GValue *other;
1381 GstStructure *structure;
1383 other = gst_structure_id_get_value (e->subtract_from, field_id);
1387 if (!gst_value_subtract (&subtraction, other, value))
1389 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1390 g_value_unset (&subtraction);
1393 structure = gst_structure_copy (e->subtract_from);
1394 gst_structure_id_set_value (structure, field_id, &subtraction);
1395 g_value_unset (&subtraction);
1396 e->put_into = g_slist_prepend (e->put_into, structure);
1402 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1403 const GstStructure * subtrahend)
1408 e.subtract_from = minuend;
1411 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1412 gst_caps_structure_subtract_field, &e);
1418 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1419 gst_structure_free (walk->data);
1421 g_slist_free (e.put_into);
1427 * gst_caps_subtract:
1428 * @minuend: #GstCaps to subtract from
1429 * @subtrahend: #GstCaps to subtract
1431 * Subtracts the @subtrahend from the @minuend.
1432 * <note>This function does not work reliably if optional properties for caps
1433 * are included on one caps and omitted on the other.</note>
1435 * Returns: the resulting caps
1438 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1443 GstCaps *dest = NULL, *src;
1445 g_return_val_if_fail (minuend != NULL, NULL);
1446 g_return_val_if_fail (subtrahend != NULL, NULL);
1448 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1449 return gst_caps_new_empty ();
1451 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1452 return _gst_caps_copy (minuend);
1454 /* FIXME: Do we want this here or above?
1455 The reason we need this is that there is no definition about what
1456 ANY means for specific types, so it's not possible to reduce ANY partially
1457 You can only remove everything or nothing and that is done above.
1458 Note: there's a test that checks this behaviour. */
1459 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1460 sublen = GST_CAPS_LEN (subtrahend);
1461 g_assert (sublen > 0);
1463 src = _gst_caps_copy (minuend);
1464 for (i = 0; i < sublen; i++) {
1467 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1469 gst_caps_unref (src);
1472 dest = gst_caps_new_empty ();
1473 srclen = GST_CAPS_LEN (src);
1474 for (j = 0; j < srclen; j++) {
1475 min = gst_caps_get_structure_unchecked (src, j);
1476 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1479 if (gst_caps_structure_subtract (&list, min, sub)) {
1482 for (walk = list; walk; walk = g_slist_next (walk)) {
1483 gst_caps_append_structure_unchecked (dest,
1484 (GstStructure *) walk->data);
1486 g_slist_free (list);
1488 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1491 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1494 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1495 gst_caps_unref (src);
1500 gst_caps_unref (src);
1501 gst_caps_do_simplify (dest);
1505 /* union operation */
1508 static GstStructure *
1509 gst_caps_structure_union (const GstStructure * struct1,
1510 const GstStructure * struct2)
1514 const GstStructureField *field1;
1515 const GstStructureField *field2;
1518 /* FIXME this doesn't actually work */
1520 if (struct1->name != struct2->name)
1523 dest = gst_structure_new_id_empty (struct1->name);
1525 for (i = 0; i < struct1->fields->len; i++) {
1526 GValue dest_value = { 0 };
1528 field1 = GST_STRUCTURE_FIELD (struct1, i);
1529 field2 = gst_structure_id_get_field (struct2, field1->name);
1531 if (field2 == NULL) {
1534 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1535 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1538 ret = gst_value_compare (&field1->value, &field2->value);
1549 * @caps1: a #GstCaps to union
1550 * @caps2: a #GstCaps to union
1552 * Creates a new #GstCaps that contains all the formats that are in
1553 * either @caps1 and @caps2.
1555 * Returns: the new #GstCaps
1558 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1563 /* NULL pointers are no correct GstCaps */
1564 g_return_val_if_fail (caps1 != NULL, NULL);
1565 g_return_val_if_fail (caps2 != NULL, NULL);
1567 if (CAPS_IS_EMPTY (caps1))
1568 return _gst_caps_copy (caps2);
1570 if (CAPS_IS_EMPTY (caps2))
1571 return _gst_caps_copy (caps1);
1573 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1574 return gst_caps_new_any ();
1576 dest1 = _gst_caps_copy (caps1);
1577 dest2 = _gst_caps_copy (caps2);
1578 gst_caps_append (dest1, dest2);
1580 gst_caps_do_simplify (dest1);
1584 /* normalize/simplify operations */
1586 typedef struct _NormalizeForeach
1589 GstStructure *structure;
1594 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1596 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1600 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1601 guint len = gst_value_list_get_size (value);
1602 for (i = 1; i < len; i++) {
1603 const GValue *v = gst_value_list_get_value (value, i);
1604 GstStructure *structure = gst_structure_copy (nf->structure);
1606 gst_structure_id_set_value (structure, field_id, v);
1607 gst_caps_append_structure_unchecked (nf->caps, structure);
1610 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1611 gst_structure_id_set_value (nf->structure, field_id, &val);
1612 g_value_unset (&val);
1620 * gst_caps_normalize:
1621 * @caps: a #GstCaps to normalize
1623 * Creates a new #GstCaps that represents the same set of formats as
1624 * @caps, but contains no lists. Each list is expanded into separate
1627 * Returns: the new #GstCaps
1630 gst_caps_normalize (const GstCaps * caps)
1632 NormalizeForeach nf;
1636 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1638 newcaps = _gst_caps_copy (caps);
1641 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1642 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1644 while (!gst_structure_foreach (nf.structure,
1645 gst_caps_normalize_foreach, &nf));
1652 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1655 const GstStructure *struct1 = *((const GstStructure **) one);
1656 const GstStructure *struct2 = *((const GstStructure **) two);
1658 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1659 So what's the best way? */
1660 ret = strcmp (gst_structure_get_name (struct1),
1661 gst_structure_get_name (struct2));
1665 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1672 GstStructure *compare;
1677 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1680 UnionField *u = user_data;
1681 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1685 g_value_unset (&u->value);
1688 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1691 g_value_unset (&u->value);
1695 gst_value_union (&u->value, val, value);
1700 gst_caps_structure_simplify (GstStructure ** result,
1701 const GstStructure * simplify, GstStructure * compare)
1704 UnionField field = { 0, {0,}, NULL };
1706 /* try to subtract to get a real subset */
1707 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1708 if (list == NULL) { /* no result */
1711 } else if (list->next == NULL) { /* one result */
1712 *result = list->data;
1713 g_slist_free (list);
1715 } else { /* multiple results */
1716 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1717 g_slist_free (list);
1722 /* try to union both structs */
1723 field.compare = compare;
1724 if (gst_structure_foreach ((GstStructure *) simplify,
1725 gst_caps_structure_figure_out_union, &field)) {
1726 gboolean ret = FALSE;
1728 /* now we know all of simplify's fields are the same in compare
1729 * but at most one field: field.name */
1730 if (G_IS_VALUE (&field.value)) {
1731 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1732 gst_structure_id_set_value (compare, field.name, &field.value);
1736 g_value_unset (&field.value);
1737 } else if (gst_structure_n_fields (simplify) <=
1738 gst_structure_n_fields (compare)) {
1739 /* compare is just more specific, will be optimized away later */
1740 /* FIXME: do this here? */
1741 GST_LOG ("found a case that will be optimized later.");
1743 gchar *one = gst_structure_to_string (simplify);
1744 gchar *two = gst_structure_to_string (compare);
1747 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1759 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1760 GstStructure * new, gint i)
1762 gst_structure_set_parent_refcount (old, NULL);
1763 gst_structure_free (old);
1764 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1765 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1769 * gst_caps_do_simplify:
1770 * @caps: a #GstCaps to simplify
1772 * Modifies the given @caps inplace into a representation that represents the
1773 * same set of formats, but in a simpler form. Component structures that are
1774 * identical are merged. Component structures that have values that can be
1775 * merged are also merged.
1777 * Returns: TRUE, if the caps could be simplified
1780 gst_caps_do_simplify (GstCaps * caps)
1782 GstStructure *simplify, *compare, *result = NULL;
1784 gboolean changed = FALSE;
1786 g_return_val_if_fail (caps != NULL, FALSE);
1787 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1789 if (gst_caps_get_size (caps) < 2)
1792 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1794 start = GST_CAPS_LEN (caps) - 1;
1795 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1796 simplify = gst_caps_get_structure_unchecked (caps, i);
1797 if (gst_structure_get_name_id (simplify) !=
1798 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1801 for (j = start; j >= 0; j--) {
1804 compare = gst_caps_get_structure_unchecked (caps, j);
1805 if (gst_structure_get_name_id (simplify) !=
1806 gst_structure_get_name_id (compare)) {
1809 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1811 gst_caps_switch_structures (caps, simplify, result, i);
1814 gst_caps_remove_structure (caps, i);
1826 /* gst_caps_do_simplify (caps); */
1832 * @caps: a #GstCaps to fixate
1834 * Modifies the given @caps inplace into a representation with only fixed
1835 * values. First the caps will be truncated and then the first structure will be
1836 * fixated with gst_structure_fixate(). @caps should be writable.
1839 gst_caps_fixate (GstCaps * caps)
1843 g_return_if_fail (GST_IS_CAPS (caps));
1844 g_return_if_fail (IS_WRITABLE (caps));
1846 /* default fixation */
1847 gst_caps_truncate (caps);
1848 s = gst_caps_get_structure (caps, 0);
1849 gst_structure_fixate (s);
1855 * gst_caps_to_string:
1858 * Converts @caps to a string representation. This string representation
1859 * can be converted back to a #GstCaps by gst_caps_from_string().
1861 * For debugging purposes its easier to do something like this:
1863 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1865 * This prints the caps in human readble form.
1867 * Returns: (transfer full): a newly allocated string representing @caps.
1870 gst_caps_to_string (const GstCaps * caps)
1872 guint i, slen, clen;
1875 /* NOTE: This function is potentially called by the debug system,
1876 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1877 * should be careful to avoid recursion. This includes any functions
1878 * called by gst_caps_to_string. In particular, calls should
1879 * not use the GST_PTR_FORMAT extension. */
1882 return g_strdup ("NULL");
1884 if (CAPS_IS_ANY (caps)) {
1885 return g_strdup ("ANY");
1887 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1888 return g_strdup ("EMPTY");
1891 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1893 clen = GST_CAPS_LEN (caps);
1894 for (i = 0; i < clen; i++) {
1896 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1900 s = g_string_sized_new (slen);
1901 for (i = 0; i < clen; i++) {
1902 GstStructure *structure;
1905 /* ';' is now added by gst_structure_to_string */
1906 g_string_append_c (s, ' ');
1909 structure = gst_caps_get_structure_unchecked (caps, i);
1910 priv_gst_structure_append_to_gstring (structure, s);
1912 if (s->len && s->str[s->len - 1] == ';') {
1913 /* remove latest ';' */
1914 s->str[--s->len] = '\0';
1916 return g_string_free (s, FALSE);
1920 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1922 GstStructure *structure;
1925 if (strcmp ("ANY", string) == 0) {
1926 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1929 if (strcmp ("EMPTY", string) == 0) {
1933 structure = gst_structure_from_string (string, &s);
1934 if (structure == NULL) {
1937 gst_caps_append_structure_unchecked (caps, structure);
1941 while (g_ascii_isspace (*s))
1946 structure = gst_structure_from_string (s, &s);
1947 if (structure == NULL) {
1950 gst_caps_append_structure_unchecked (caps, structure);
1958 * gst_caps_from_string:
1959 * @string: a string to convert to #GstCaps
1961 * Converts @caps from a string representation.
1963 * Returns: (transfer full): a newly allocated #GstCaps
1966 gst_caps_from_string (const gchar * string)
1970 g_return_val_if_fail (string, FALSE);
1972 caps = gst_caps_new_empty ();
1973 if (gst_caps_from_string_inplace (caps, string)) {
1976 gst_caps_unref (caps);
1982 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1984 g_return_if_fail (G_IS_VALUE (src_value));
1985 g_return_if_fail (G_IS_VALUE (dest_value));
1986 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1987 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1988 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1990 g_value_take_string (dest_value,
1991 gst_caps_to_string (gst_value_get_caps (src_value)));