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
79 #define GST_CAPS_ARRAY(c) ((GPtrArray *)((c)->priv))
81 #define GST_CAPS_LEN(c) (GST_CAPS_ARRAY(c)->len)
83 #define IS_WRITABLE(caps) \
84 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
86 /* same as gst_caps_is_any () */
87 #define CAPS_IS_ANY(caps) \
88 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAG_ANY)
90 /* same as gst_caps_is_empty () */
91 #define CAPS_IS_EMPTY(caps) \
92 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
94 #define CAPS_IS_EMPTY_SIMPLE(caps) \
95 ((GST_CAPS_ARRAY (caps) == NULL) || (GST_CAPS_LEN (caps) == 0))
97 /* quick way to get a caps structure at an index without doing a type or array
99 #define gst_caps_get_structure_unchecked(caps, index) \
100 ((GstStructure *)g_ptr_array_index (GST_CAPS_ARRAY (caps), (index)))
101 /* quick way to append a structure without checking the args */
102 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
103 GstStructure *__s=structure; \
104 if (gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps))) \
105 g_ptr_array_add (GST_CAPS_ARRAY (caps), __s); \
108 /* lock to protect multiple invocations of static caps to caps conversion */
109 G_LOCK_DEFINE_STATIC (static_caps_lock);
111 static void gst_caps_transform_to_string (const GValue * src_value,
112 GValue * dest_value);
113 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
114 const gchar * string);
116 GType _gst_caps_type = 0;
117 GstCaps *_gst_caps_any;
118 GstCaps *_gst_caps_none;
120 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
123 _priv_gst_caps_initialize (void)
125 _gst_caps_type = gst_caps_get_type ();
127 _gst_caps_any = gst_caps_new_any ();
128 _gst_caps_none = gst_caps_new_empty ();
130 g_value_register_transform_func (_gst_caps_type,
131 G_TYPE_STRING, gst_caps_transform_to_string);
135 _gst_caps_copy (const GstCaps * caps)
138 GstStructure *structure;
141 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
143 newcaps = gst_caps_new_empty ();
144 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
145 n = GST_CAPS_LEN (caps);
147 for (i = 0; i < n; i++) {
148 structure = gst_caps_get_structure_unchecked (caps, i);
149 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
155 /* creation/deletion */
157 _gst_caps_free (GstCaps * caps)
159 GstStructure *structure;
162 /* The refcount must be 0, but since we're only called by gst_caps_unref,
163 * don't bother testing. */
164 len = GST_CAPS_LEN (caps);
165 /* This can be used to get statistics about caps sizes */
166 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
167 for (i = 0; i < len; i++) {
168 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
169 gst_structure_set_parent_refcount (structure, NULL);
170 gst_structure_free (structure);
172 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
174 #ifdef DEBUG_REFCOUNT
175 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
177 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
181 gst_caps_init (GstCaps * caps, gsize size)
183 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
185 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
186 caps->mini_object.dispose = NULL;
187 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
189 /* the 32 has been determined by logging caps sizes in _gst_caps_free
190 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
192 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
194 caps->priv = g_ptr_array_new ();
198 * gst_caps_new_empty:
200 * Creates a new #GstCaps that is empty. That is, the returned
201 * #GstCaps contains no media formats.
202 * Caller is responsible for unreffing the returned caps.
204 * Returns: (transfer full): the new #GstCaps
207 gst_caps_new_empty (void)
211 caps = g_slice_new (GstCaps);
213 gst_caps_init (caps, sizeof (GstCaps));
215 #ifdef DEBUG_REFCOUNT
216 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
225 * Creates a new #GstCaps that indicates that it is compatible with
228 * Returns: (transfer full): the new #GstCaps
231 gst_caps_new_any (void)
233 GstCaps *caps = gst_caps_new_empty ();
235 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAG_ANY);
241 * gst_caps_new_empty_simple:
242 * @media_type: the media type of the structure
244 * Creates a new #GstCaps that contains one #GstStructure with name
246 * Caller is responsible for unreffing the returned caps.
248 * Returns: (transfer full): the new #GstCaps
251 gst_caps_new_empty_simple (const char *media_type)
254 GstStructure *structure;
256 caps = gst_caps_new_empty ();
257 structure = gst_structure_new_empty (media_type);
259 gst_caps_append_structure_unchecked (caps, structure);
265 * gst_caps_new_simple:
266 * @media_type: the media type of the structure
267 * @fieldname: first field to set
268 * @...: additional arguments
270 * Creates a new #GstCaps that contains one #GstStructure. The
271 * structure is defined by the arguments, which have the same format
272 * as gst_structure_new().
273 * Caller is responsible for unreffing the returned caps.
275 * Returns: (transfer full): the new #GstCaps
278 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
281 GstStructure *structure;
284 caps = gst_caps_new_empty ();
286 va_start (var_args, fieldname);
287 structure = gst_structure_new_valist (media_type, fieldname, var_args);
291 gst_caps_append_structure_unchecked (caps, structure);
293 gst_caps_replace (&caps, NULL);
300 * @struct1: the first structure to add
301 * @...: additional structures to add
303 * Creates a new #GstCaps and adds all the structures listed as
304 * arguments. The list must be NULL-terminated. The structures
305 * are not copied; the returned #GstCaps owns the structures.
307 * Returns: (transfer full): the new #GstCaps
310 gst_caps_new_full (GstStructure * struct1, ...)
315 va_start (var_args, struct1);
316 caps = gst_caps_new_full_valist (struct1, var_args);
323 * gst_caps_new_full_valist:
324 * @structure: the first structure to add
325 * @var_args: additional structures to add
327 * Creates a new #GstCaps and adds all the structures listed as
328 * arguments. The list must be NULL-terminated. The structures
329 * are not copied; the returned #GstCaps owns the structures.
331 * Returns: (transfer full): the new #GstCaps
334 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
338 caps = gst_caps_new_empty ();
341 gst_caps_append_structure_unchecked (caps, structure);
342 structure = va_arg (var_args, GstStructure *);
349 gst_static_caps_get_type (void)
351 static GType staticcaps_type = 0;
353 if (G_UNLIKELY (staticcaps_type == 0)) {
354 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
356 return staticcaps_type;
360 * gst_static_caps_get:
361 * @static_caps: the #GstStaticCaps to convert
363 * Converts a #GstStaticCaps to a #GstCaps.
365 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
366 * Since the core holds an additional ref to the returned caps,
367 * use gst_caps_make_writable() on the returned caps to modify it.
370 gst_static_caps_get (GstStaticCaps * static_caps)
374 g_return_val_if_fail (static_caps != NULL, NULL);
376 caps = &static_caps->caps;
378 /* refcount is 0 when we need to convert */
379 if (G_UNLIKELY (*caps == NULL)) {
382 G_LOCK (static_caps_lock);
383 /* check if other thread already updated */
384 if (G_UNLIKELY (*caps != NULL))
387 string = static_caps->string;
389 if (G_UNLIKELY (string == NULL))
392 GST_CAT_TRACE (GST_CAT_CAPS, "creating %p", static_caps);
394 *caps = gst_caps_from_string (string);
396 /* convert to string */
397 if (G_UNLIKELY (*caps == NULL))
398 g_critical ("Could not convert static caps \"%s\"", string);
400 GST_CAT_TRACE (GST_CAT_CAPS, "created %p", static_caps);
402 G_UNLOCK (static_caps_lock);
404 /* ref the caps, makes it not writable */
405 if (G_LIKELY (*caps != NULL))
406 gst_caps_ref (*caps);
413 G_UNLOCK (static_caps_lock);
414 g_warning ("static caps %p string is NULL", static_caps);
420 * gst_static_caps_cleanup:
421 * @static_caps: the #GstStaticCaps to clean
423 * Clean up the cached caps contained in @static_caps.
426 gst_static_caps_cleanup (GstStaticCaps * static_caps)
428 G_LOCK (static_caps_lock);
429 gst_caps_replace (&static_caps->caps, NULL);
430 G_UNLOCK (static_caps_lock);
435 static GstStructure *
436 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
438 /* don't use index_fast, gst_caps_do_simplify relies on the order */
439 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
441 gst_structure_set_parent_refcount (s, NULL);
446 * gst_caps_steal_structure:
447 * @caps: the #GstCaps to retrieve from
448 * @index: Index of the structure to retrieve
450 * Retrieves the stucture with the given index from the list of structures
451 * contained in @caps. The caller becomes the owner of the returned structure.
453 * Returns: (transfer full): a pointer to the #GstStructure corresponding
459 gst_caps_steal_structure (GstCaps * caps, guint index)
461 g_return_val_if_fail (caps != NULL, NULL);
462 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
464 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
467 return gst_caps_remove_and_get_structure (caps, index);
472 * @caps1: the #GstCaps that will be appended to
473 * @caps2: (transfer full): the #GstCaps to append
475 * Appends the structures contained in @caps2 to @caps1. The structures in
476 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
477 * freed. If either caps is ANY, the resulting caps will be ANY.
480 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
482 GstStructure *structure;
485 g_return_if_fail (GST_IS_CAPS (caps1));
486 g_return_if_fail (GST_IS_CAPS (caps2));
487 g_return_if_fail (IS_WRITABLE (caps1));
489 caps2 = gst_caps_make_writable (caps2);
491 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
492 /* FIXME: this leaks */
493 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
494 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
495 structure = gst_caps_remove_and_get_structure (caps2, i);
496 gst_structure_free (structure);
499 for (i = GST_CAPS_LEN (caps2); i; i--) {
500 structure = gst_caps_remove_and_get_structure (caps2, 0);
501 gst_caps_append_structure_unchecked (caps1, structure);
504 gst_caps_unref (caps2); /* guaranteed to free it */
509 * @caps1: the #GstCaps that will take the new entries
510 * @caps2: (transfer full): the #GstCaps to merge in
512 * Appends the structures contained in @caps2 to @caps1 if they are not yet
513 * expressed by @caps1. The structures in @caps2 are not copied -- they are
514 * transferred to @caps1, and then @caps2 is freed.
515 * If either caps is ANY, the resulting caps will be ANY.
520 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
522 GstStructure *structure;
525 g_return_if_fail (GST_IS_CAPS (caps1));
526 g_return_if_fail (GST_IS_CAPS (caps2));
527 g_return_if_fail (IS_WRITABLE (caps1));
529 caps2 = gst_caps_make_writable (caps2);
531 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
532 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
533 structure = gst_caps_remove_and_get_structure (caps2, i);
534 gst_structure_free (structure);
536 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
537 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAG_ANY;
538 for (i = GST_CAPS_LEN (caps1) - 1; i >= 0; i--) {
539 structure = gst_caps_remove_and_get_structure (caps1, i);
540 gst_structure_free (structure);
543 for (i = GST_CAPS_LEN (caps2); i; i--) {
544 structure = gst_caps_remove_and_get_structure (caps2, 0);
545 gst_caps_merge_structure (caps1, structure);
548 GstCaps *com = gst_caps_intersect (caps1, caps2);
549 GstCaps *add = gst_caps_subtract (caps2, com);
551 GST_DEBUG ("common : %d", gst_caps_get_size (com));
552 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
553 gst_caps_append (caps1, add);
554 gst_caps_unref (com);
557 gst_caps_unref (caps2); /* guaranteed to free it */
561 * gst_caps_append_structure:
562 * @caps: the #GstCaps that will be appended to
563 * @structure: (transfer full): the #GstStructure to append
565 * Appends @structure to @caps. The structure is not copied; @caps
566 * becomes the owner of @structure.
569 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
571 g_return_if_fail (GST_IS_CAPS (caps));
572 g_return_if_fail (IS_WRITABLE (caps));
574 if (G_LIKELY (structure)) {
575 gst_caps_append_structure_unchecked (caps, structure);
580 * gst_caps_remove_structure:
581 * @caps: the #GstCaps to remove from
582 * @idx: Index of the structure to remove
584 * removes the stucture with the given index from the list of structures
585 * contained in @caps.
588 gst_caps_remove_structure (GstCaps * caps, guint idx)
590 GstStructure *structure;
592 g_return_if_fail (caps != NULL);
593 g_return_if_fail (idx <= gst_caps_get_size (caps));
594 g_return_if_fail (IS_WRITABLE (caps));
596 structure = gst_caps_remove_and_get_structure (caps, idx);
597 gst_structure_free (structure);
601 * gst_caps_merge_structure:
602 * @caps: the #GstCaps that will the new structure
603 * @structure: (transfer full): the #GstStructure to merge
605 * Appends @structure to @caps if its not already expressed by @caps. The
606 * structure is not copied; @caps becomes the owner of @structure.
609 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
611 g_return_if_fail (GST_IS_CAPS (caps));
612 g_return_if_fail (IS_WRITABLE (caps));
614 if (G_LIKELY (structure)) {
615 GstStructure *structure1;
617 gboolean unique = TRUE;
619 /* check each structure */
620 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
621 structure1 = gst_caps_get_structure_unchecked (caps, i);
622 /* if structure is a subset of structure1, then skip it */
623 if (gst_structure_is_subset (structure, structure1)) {
629 gst_caps_append_structure_unchecked (caps, structure);
631 gst_structure_free (structure);
640 * Gets the number of structures contained in @caps.
642 * Returns: the number of structures that @caps contains
645 gst_caps_get_size (const GstCaps * caps)
647 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
649 return GST_CAPS_LEN (caps);
653 * gst_caps_get_structure:
655 * @index: the index of the structure
657 * Finds the structure in @caps that has the index @index, and
660 * WARNING: This function takes a const GstCaps *, but returns a
661 * non-const GstStructure *. This is for programming convenience --
662 * the caller should be aware that structures inside a constant
663 * #GstCaps should not be modified. However, if you know the caps
664 * are writable, either because you have just copied them or made
665 * them writable with gst_caps_make_writable(), you may modify the
666 * structure returned in the usual way, e.g. with functions like
667 * gst_structure_set().
669 * You do not need to free or unref the structure returned, it
670 * belongs to the #GstCaps.
672 * Returns: (transfer none): a pointer to the #GstStructure corresponding
676 gst_caps_get_structure (const GstCaps * caps, guint index)
678 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
679 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
681 return gst_caps_get_structure_unchecked (caps, index);
686 * @caps: the #GstCaps to copy
687 * @nth: the nth structure to copy
689 * Creates a new #GstCaps and appends a copy of the nth structure
690 * contained in @caps.
692 * Returns: (transfer full): the new #GstCaps
695 gst_caps_copy_nth (const GstCaps * caps, guint nth)
698 GstStructure *structure;
700 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
702 newcaps = gst_caps_new_empty ();
703 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
705 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
706 structure = gst_caps_get_structure_unchecked (caps, nth);
707 gst_caps_append_structure_unchecked (newcaps,
708 gst_structure_copy (structure));
716 * @caps: the #GstCaps to truncate
718 * Destructively discard all but the first structure from @caps. Useful when
719 * fixating. @caps must be writable.
722 gst_caps_truncate (GstCaps * caps)
726 g_return_if_fail (GST_IS_CAPS (caps));
727 g_return_if_fail (IS_WRITABLE (caps));
729 i = GST_CAPS_LEN (caps) - 1;
732 gst_caps_remove_structure (caps, i--);
736 * gst_caps_set_value:
737 * @caps: a writable caps
738 * @field: name of the field to set
739 * @value: value to set the field to
741 * Sets the given @field on all structures of @caps to the given @value.
742 * This is a convenience function for calling gst_structure_set_value() on
743 * all structures of @caps.
748 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
752 g_return_if_fail (GST_IS_CAPS (caps));
753 g_return_if_fail (IS_WRITABLE (caps));
754 g_return_if_fail (field != NULL);
755 g_return_if_fail (G_IS_VALUE (value));
757 len = GST_CAPS_LEN (caps);
758 for (i = 0; i < len; i++) {
759 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
760 gst_structure_set_value (structure, field, value);
765 * gst_caps_set_simple_valist:
766 * @caps: the #GstCaps to set
767 * @field: first field to set
768 * @varargs: additional parameters
770 * Sets fields in a #GstCaps. The arguments must be passed in the same
771 * manner as gst_structure_set(), and be NULL-terminated.
772 * <note>Prior to GStreamer version 0.10.26, this function failed when
773 * @caps was not simple. If your code needs to work with those versions
774 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
775 * is %TRUE for @caps.</note>
778 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
780 GValue value = { 0, };
782 g_return_if_fail (GST_IS_CAPS (caps));
783 g_return_if_fail (IS_WRITABLE (caps));
789 type = va_arg (varargs, GType);
791 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
792 if (G_UNLIKELY (err)) {
793 g_critical ("%s", err);
797 gst_caps_set_value (caps, field, &value);
799 g_value_unset (&value);
801 field = va_arg (varargs, const gchar *);
806 * gst_caps_set_simple:
807 * @caps: the #GstCaps to set
808 * @field: first field to set
809 * @...: additional parameters
811 * Sets fields in a #GstCaps. The arguments must be passed in the same
812 * manner as gst_structure_set(), and be NULL-terminated.
813 * <note>Prior to GStreamer version 0.10.26, this function failed when
814 * @caps was not simple. If your code needs to work with those versions
815 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
816 * is %TRUE for @caps.</note>
819 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
823 g_return_if_fail (GST_IS_CAPS (caps));
824 g_return_if_fail (IS_WRITABLE (caps));
826 va_start (var_args, field);
827 gst_caps_set_simple_valist (caps, field, var_args);
835 * @caps: the #GstCaps to test
837 * Determines if @caps represents any media format.
839 * Returns: TRUE if @caps represents any format.
842 gst_caps_is_any (const GstCaps * caps)
844 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
846 return (CAPS_IS_ANY (caps));
851 * @caps: the #GstCaps to test
853 * Determines if @caps represents no media formats.
855 * Returns: TRUE if @caps represents no formats.
858 gst_caps_is_empty (const GstCaps * caps)
860 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
862 if (CAPS_IS_ANY (caps))
865 return CAPS_IS_EMPTY_SIMPLE (caps);
869 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
872 return gst_value_is_fixed (value);
877 * @caps: the #GstCaps to test
879 * Fixed #GstCaps describe exactly one format, that is, they have exactly
880 * one structure, and each field in the structure describes a fixed type.
881 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
883 * Returns: TRUE if @caps is fixed
886 gst_caps_is_fixed (const GstCaps * caps)
888 GstStructure *structure;
890 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
892 if (GST_CAPS_LEN (caps) != 1)
895 structure = gst_caps_get_structure_unchecked (caps, 0);
897 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
901 * gst_caps_is_equal_fixed:
902 * @caps1: the #GstCaps to test
903 * @caps2: the #GstCaps to test
905 * Tests if two #GstCaps are equal. This function only works on fixed
908 * Returns: TRUE if the arguments represent the same format
911 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
913 GstStructure *struct1, *struct2;
915 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
916 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
918 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
919 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
921 return gst_structure_is_equal (struct1, struct2);
925 * gst_caps_is_always_compatible:
926 * @caps1: the #GstCaps to test
927 * @caps2: the #GstCaps to test
929 * A given #GstCaps structure is always compatible with another if
930 * every media format that is in the first is also contained in the
931 * second. That is, @caps1 is a subset of @caps2.
933 * Returns: TRUE if @caps1 is a subset of @caps2.
936 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
938 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
939 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
941 return gst_caps_is_subset (caps1, caps2);
945 * gst_caps_is_subset:
946 * @subset: a #GstCaps
947 * @superset: a potentially greater #GstCaps
949 * Checks if all caps represented by @subset are also represented by @superset.
950 * <note>This function does not work reliably if optional properties for caps
951 * are included on one caps and omitted on the other.</note>
953 * Returns: %TRUE if @subset is a subset of @superset
956 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
958 GstStructure *s1, *s2;
962 g_return_val_if_fail (subset != NULL, FALSE);
963 g_return_val_if_fail (superset != NULL, FALSE);
965 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
967 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
970 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
971 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
972 s1 = gst_caps_get_structure_unchecked (subset, i);
973 s2 = gst_caps_get_structure_unchecked (superset, j);
974 if (gst_structure_is_subset (s1, s2)) {
975 /* If we found a superset, continue with the next
976 * subset structure */
980 /* If we found no superset for this subset structure
981 * we return FALSE immediately */
992 * gst_caps_is_subset_structure:
994 * @structure: a potential #GstStructure subset of @caps
996 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
997 * for more information.
999 * Returns: %TRUE if @structure is a subset of @caps
1004 gst_caps_is_subset_structure (const GstCaps * caps,
1005 const GstStructure * structure)
1010 g_return_val_if_fail (caps != NULL, FALSE);
1011 g_return_val_if_fail (structure != NULL, FALSE);
1013 if (CAPS_IS_ANY (caps))
1015 if (CAPS_IS_EMPTY (caps))
1018 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1019 s = gst_caps_get_structure_unchecked (caps, i);
1020 if (gst_structure_is_subset (structure, s)) {
1021 /* If we found a superset return TRUE */
1030 * gst_caps_is_equal:
1031 * @caps1: a #GstCaps
1032 * @caps2: another #GstCaps
1034 * Checks if the given caps represent the same set of caps.
1035 * <note>This function does not work reliably if optional properties for caps
1036 * are included on one caps and omitted on the other.</note>
1038 * This function deals correctly with passing NULL for any of the caps.
1040 * Returns: TRUE if both caps are equal.
1043 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1045 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1046 * So there should be an assertion that caps1 and caps2 != NULL */
1048 /* NULL <-> NULL is allowed here */
1049 if (G_UNLIKELY (caps1 == caps2))
1052 /* one of them NULL => they are different (can't be both NULL because
1053 * we checked that above) */
1054 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1057 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1058 return gst_caps_is_equal_fixed (caps1, caps2);
1060 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1064 * gst_caps_is_strictly_equal:
1065 * @caps1: a #GstCaps
1066 * @caps2: another #GstCaps
1068 * Checks if the given caps are exactly the same set of caps.
1070 * This function deals correctly with passing NULL for any of the caps.
1072 * Returns: TRUE if both caps are strictly equal.
1077 gst_caps_is_strictly_equal (const GstCaps * caps1, const GstCaps * caps2)
1080 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1081 * So there should be an assertion that caps1 and caps2 != NULL */
1083 /* NULL <-> NULL is allowed here */
1084 if (G_UNLIKELY (caps1 == caps2))
1087 /* one of them NULL => they are different (can't be both NULL because
1088 * we checked that above) */
1089 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1092 if (GST_CAPS_LEN (caps1) != GST_CAPS_LEN (caps2))
1095 for (i = 0; i < GST_CAPS_LEN (caps1); i++) {
1096 if (!gst_structure_is_equal (gst_caps_get_structure_unchecked (caps1, i),
1097 gst_caps_get_structure_unchecked (caps2, i)))
1104 /* intersect operation */
1107 * gst_caps_can_intersect:
1108 * @caps1: a #GstCaps to intersect
1109 * @caps2: a #GstCaps to intersect
1111 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1114 * Returns: %TRUE if intersection would be not empty
1119 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1121 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1122 guint j, k, len1, len2;
1123 GstStructure *struct1;
1124 GstStructure *struct2;
1126 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1127 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1129 /* caps are exactly the same pointers */
1130 if (G_UNLIKELY (caps1 == caps2))
1133 /* empty caps on either side, return empty */
1134 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1137 /* one of the caps is any */
1138 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1141 /* run zigzag on top line then right line, this preserves the caps order
1142 * much better than a simple loop.
1144 * This algorithm zigzags over the caps structures as demonstrated in
1145 * the folowing matrix:
1148 * +------------- total distance: +-------------
1149 * | 1 2 4 7 0 | 0 1 2 3
1150 * caps2 | 3 5 8 10 1 | 1 2 3 4
1151 * | 6 9 11 12 2 | 2 3 4 5
1153 * First we iterate over the caps1 structures (top line) intersecting
1154 * the structures diagonally down, then we iterate over the caps2
1155 * structures. The result is that the intersections are ordered based on the
1156 * sum of the indexes in the list.
1158 len1 = GST_CAPS_LEN (caps1);
1159 len2 = GST_CAPS_LEN (caps2);
1160 for (i = 0; i < len1 + len2 - 1; i++) {
1161 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1162 j = MIN (i, len1 - 1);
1163 /* subset index stays 0 until i reaches superset->structs->len, then it
1164 * counts up from 1 to subset->structs->len - 1 */
1165 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1167 /* now run the diagonal line, end condition is the left or bottom
1170 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1171 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1173 if (gst_structure_can_intersect (struct1, struct2)) {
1176 /* move down left */
1178 if (G_UNLIKELY (j == 0))
1179 break; /* so we don't roll back to G_MAXUINT */
1187 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1189 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1190 guint j, k, len1, len2;
1192 GstStructure *struct1;
1193 GstStructure *struct2;
1195 GstStructure *istruct;
1197 /* caps are exactly the same pointers, just copy one caps */
1198 if (G_UNLIKELY (caps1 == caps2))
1199 return _gst_caps_copy (caps1);
1201 /* empty caps on either side, return empty */
1202 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1203 return gst_caps_new_empty ();
1205 /* one of the caps is any, just copy the other caps */
1206 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1207 return _gst_caps_copy (caps2);
1208 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1209 return _gst_caps_copy (caps1);
1211 dest = gst_caps_new_empty ();
1213 /* run zigzag on top line then right line, this preserves the caps order
1214 * much better than a simple loop.
1216 * This algorithm zigzags over the caps structures as demonstrated in
1217 * the folowing matrix:
1225 * First we iterate over the caps1 structures (top line) intersecting
1226 * the structures diagonally down, then we iterate over the caps2
1229 len1 = GST_CAPS_LEN (caps1);
1230 len2 = GST_CAPS_LEN (caps2);
1231 for (i = 0; i < len1 + len2 - 1; i++) {
1232 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1233 j = MIN (i, len1 - 1);
1234 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1235 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1236 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1238 /* now run the diagonal line, end condition is the left or bottom
1241 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1242 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1244 istruct = gst_structure_intersect (struct1, struct2);
1246 gst_caps_merge_structure (dest, istruct);
1247 /* move down left */
1249 if (G_UNLIKELY (j == 0))
1250 break; /* so we don't roll back to G_MAXUINT */
1258 * gst_caps_intersect_first:
1259 * @caps1: a #GstCaps to intersect
1260 * @caps2: a #GstCaps to intersect
1262 * Creates a new #GstCaps that contains all the formats that are common
1263 * to both @caps1 and @caps2.
1265 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1266 * fashion as @caps1.
1268 * Returns: the new #GstCaps
1271 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1274 guint j, len1, len2;
1276 GstStructure *struct1;
1277 GstStructure *struct2;
1279 GstStructure *istruct;
1281 /* caps are exactly the same pointers, just copy one caps */
1282 if (G_UNLIKELY (caps1 == caps2))
1283 return gst_caps_copy (caps1);
1285 /* empty caps on either side, return empty */
1286 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1287 return gst_caps_new_empty ();
1289 /* one of the caps is any, just copy the other caps */
1290 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1291 return gst_caps_copy (caps2);
1292 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1293 return gst_caps_copy (caps1);
1295 dest = gst_caps_new_empty ();
1297 len1 = GST_CAPS_LEN (caps1);
1298 len2 = GST_CAPS_LEN (caps2);
1299 for (i = 0; i < len1; i++) {
1300 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1301 for (j = 0; j < len2; j++) {
1302 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1303 istruct = gst_structure_intersect (struct1, struct2);
1305 gst_caps_merge_structure (dest, istruct);
1313 * gst_caps_intersect_full:
1314 * @caps1: a #GstCaps to intersect
1315 * @caps2: a #GstCaps to intersect
1316 * @mode: The intersection algorithm/mode to use
1318 * Creates a new #GstCaps that contains all the formats that are common
1319 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1322 * Returns: the new #GstCaps
1326 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1327 GstCapsIntersectMode mode)
1329 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1330 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1333 case GST_CAPS_INTERSECT_FIRST:
1334 return gst_caps_intersect_first (caps1, caps2);
1336 g_warning ("Unknown caps intersect mode: %d", mode);
1338 case GST_CAPS_INTERSECT_ZIG_ZAG:
1339 return gst_caps_intersect_zig_zag (caps1, caps2);
1344 * gst_caps_intersect:
1345 * @caps1: a #GstCaps to intersect
1346 * @caps2: a #GstCaps to intersect
1348 * Creates a new #GstCaps that contains all the formats that are common
1349 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1351 * Returns: the new #GstCaps
1354 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1356 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1360 /* subtract operation */
1364 const GstStructure *subtract_from;
1370 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1373 SubtractionEntry *e = user_data;
1374 GValue subtraction = { 0, };
1375 const GValue *other;
1376 GstStructure *structure;
1378 other = gst_structure_id_get_value (e->subtract_from, field_id);
1382 if (!gst_value_subtract (&subtraction, other, value))
1384 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1385 g_value_unset (&subtraction);
1388 structure = gst_structure_copy (e->subtract_from);
1389 gst_structure_id_set_value (structure, field_id, &subtraction);
1390 g_value_unset (&subtraction);
1391 e->put_into = g_slist_prepend (e->put_into, structure);
1397 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1398 const GstStructure * subtrahend)
1403 e.subtract_from = minuend;
1406 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1407 gst_caps_structure_subtract_field, &e);
1413 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1414 gst_structure_free (walk->data);
1416 g_slist_free (e.put_into);
1422 * gst_caps_subtract:
1423 * @minuend: #GstCaps to subtract from
1424 * @subtrahend: #GstCaps to subtract
1426 * Subtracts the @subtrahend from the @minuend.
1427 * <note>This function does not work reliably if optional properties for caps
1428 * are included on one caps and omitted on the other.</note>
1430 * Returns: the resulting caps
1433 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1438 GstCaps *dest = NULL, *src;
1440 g_return_val_if_fail (minuend != NULL, NULL);
1441 g_return_val_if_fail (subtrahend != NULL, NULL);
1443 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1444 return gst_caps_new_empty ();
1446 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1447 return _gst_caps_copy (minuend);
1449 /* FIXME: Do we want this here or above?
1450 The reason we need this is that there is no definition about what
1451 ANY means for specific types, so it's not possible to reduce ANY partially
1452 You can only remove everything or nothing and that is done above.
1453 Note: there's a test that checks this behaviour. */
1454 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1455 sublen = GST_CAPS_LEN (subtrahend);
1456 g_assert (sublen > 0);
1458 src = _gst_caps_copy (minuend);
1459 for (i = 0; i < sublen; i++) {
1462 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1464 gst_caps_unref (src);
1467 dest = gst_caps_new_empty ();
1468 srclen = GST_CAPS_LEN (src);
1469 for (j = 0; j < srclen; j++) {
1470 min = gst_caps_get_structure_unchecked (src, j);
1471 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1474 if (gst_caps_structure_subtract (&list, min, sub)) {
1477 for (walk = list; walk; walk = g_slist_next (walk)) {
1478 gst_caps_append_structure_unchecked (dest,
1479 (GstStructure *) walk->data);
1481 g_slist_free (list);
1483 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1486 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1489 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1490 gst_caps_unref (src);
1495 gst_caps_unref (src);
1496 gst_caps_do_simplify (dest);
1500 /* union operation */
1503 static GstStructure *
1504 gst_caps_structure_union (const GstStructure * struct1,
1505 const GstStructure * struct2)
1509 const GstStructureField *field1;
1510 const GstStructureField *field2;
1513 /* FIXME this doesn't actually work */
1515 if (struct1->name != struct2->name)
1518 dest = gst_structure_new_id_empty (struct1->name);
1520 for (i = 0; i < struct1->fields->len; i++) {
1521 GValue dest_value = { 0 };
1523 field1 = GST_STRUCTURE_FIELD (struct1, i);
1524 field2 = gst_structure_id_get_field (struct2, field1->name);
1526 if (field2 == NULL) {
1529 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1530 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1533 ret = gst_value_compare (&field1->value, &field2->value);
1544 * @caps1: a #GstCaps to union
1545 * @caps2: a #GstCaps to union
1547 * Creates a new #GstCaps that contains all the formats that are in
1548 * either @caps1 and @caps2.
1550 * Returns: the new #GstCaps
1553 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1558 /* NULL pointers are no correct GstCaps */
1559 g_return_val_if_fail (caps1 != NULL, NULL);
1560 g_return_val_if_fail (caps2 != NULL, NULL);
1562 if (CAPS_IS_EMPTY (caps1))
1563 return _gst_caps_copy (caps2);
1565 if (CAPS_IS_EMPTY (caps2))
1566 return _gst_caps_copy (caps1);
1568 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1569 return gst_caps_new_any ();
1571 dest1 = _gst_caps_copy (caps1);
1572 dest2 = _gst_caps_copy (caps2);
1573 gst_caps_append (dest1, dest2);
1575 gst_caps_do_simplify (dest1);
1579 /* normalize/simplify operations */
1581 typedef struct _NormalizeForeach
1584 GstStructure *structure;
1589 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1591 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1595 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1596 guint len = gst_value_list_get_size (value);
1597 for (i = 1; i < len; i++) {
1598 const GValue *v = gst_value_list_get_value (value, i);
1599 GstStructure *structure = gst_structure_copy (nf->structure);
1601 gst_structure_id_set_value (structure, field_id, v);
1602 gst_caps_append_structure_unchecked (nf->caps, structure);
1605 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1606 gst_structure_id_set_value (nf->structure, field_id, &val);
1607 g_value_unset (&val);
1615 * gst_caps_normalize:
1616 * @caps: a #GstCaps to normalize
1618 * Creates a new #GstCaps that represents the same set of formats as
1619 * @caps, but contains no lists. Each list is expanded into separate
1622 * Returns: the new #GstCaps
1625 gst_caps_normalize (const GstCaps * caps)
1627 NormalizeForeach nf;
1631 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1633 newcaps = _gst_caps_copy (caps);
1636 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1637 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1639 while (!gst_structure_foreach (nf.structure,
1640 gst_caps_normalize_foreach, &nf));
1647 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1650 const GstStructure *struct1 = *((const GstStructure **) one);
1651 const GstStructure *struct2 = *((const GstStructure **) two);
1653 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1654 So what's the best way? */
1655 ret = strcmp (gst_structure_get_name (struct1),
1656 gst_structure_get_name (struct2));
1660 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1667 GstStructure *compare;
1672 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1675 UnionField *u = user_data;
1676 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1680 g_value_unset (&u->value);
1683 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1686 g_value_unset (&u->value);
1690 gst_value_union (&u->value, val, value);
1695 gst_caps_structure_simplify (GstStructure ** result,
1696 const GstStructure * simplify, GstStructure * compare)
1699 UnionField field = { 0, {0,}, NULL };
1701 /* try to subtract to get a real subset */
1702 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1703 if (list == NULL) { /* no result */
1706 } else if (list->next == NULL) { /* one result */
1707 *result = list->data;
1708 g_slist_free (list);
1710 } else { /* multiple results */
1711 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1712 g_slist_free (list);
1717 /* try to union both structs */
1718 field.compare = compare;
1719 if (gst_structure_foreach ((GstStructure *) simplify,
1720 gst_caps_structure_figure_out_union, &field)) {
1721 gboolean ret = FALSE;
1723 /* now we know all of simplify's fields are the same in compare
1724 * but at most one field: field.name */
1725 if (G_IS_VALUE (&field.value)) {
1726 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1727 gst_structure_id_set_value (compare, field.name, &field.value);
1731 g_value_unset (&field.value);
1732 } else if (gst_structure_n_fields (simplify) <=
1733 gst_structure_n_fields (compare)) {
1734 /* compare is just more specific, will be optimized away later */
1735 /* FIXME: do this here? */
1736 GST_LOG ("found a case that will be optimized later.");
1738 gchar *one = gst_structure_to_string (simplify);
1739 gchar *two = gst_structure_to_string (compare);
1742 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1754 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1755 GstStructure * new, gint i)
1757 gst_structure_set_parent_refcount (old, NULL);
1758 gst_structure_free (old);
1759 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1760 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1764 * gst_caps_do_simplify:
1765 * @caps: a #GstCaps to simplify
1767 * Modifies the given @caps inplace into a representation that represents the
1768 * same set of formats, but in a simpler form. Component structures that are
1769 * identical are merged. Component structures that have values that can be
1770 * merged are also merged.
1772 * Returns: TRUE, if the caps could be simplified
1775 gst_caps_do_simplify (GstCaps * caps)
1777 GstStructure *simplify, *compare, *result = NULL;
1779 gboolean changed = FALSE;
1781 g_return_val_if_fail (caps != NULL, FALSE);
1782 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1784 if (gst_caps_get_size (caps) < 2)
1787 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1789 start = GST_CAPS_LEN (caps) - 1;
1790 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1791 simplify = gst_caps_get_structure_unchecked (caps, i);
1792 if (gst_structure_get_name_id (simplify) !=
1793 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1796 for (j = start; j >= 0; j--) {
1799 compare = gst_caps_get_structure_unchecked (caps, j);
1800 if (gst_structure_get_name_id (simplify) !=
1801 gst_structure_get_name_id (compare)) {
1804 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1806 gst_caps_switch_structures (caps, simplify, result, i);
1809 gst_caps_remove_structure (caps, i);
1821 /* gst_caps_do_simplify (caps); */
1827 * @caps: a #GstCaps to fixate
1829 * Modifies the given @caps inplace into a representation with only fixed
1830 * values. First the caps will be truncated and then the first structure will be
1831 * fixated with gst_structure_fixate(). @caps should be writable.
1834 gst_caps_fixate (GstCaps * caps)
1838 g_return_if_fail (GST_IS_CAPS (caps));
1839 g_return_if_fail (IS_WRITABLE (caps));
1841 /* default fixation */
1842 gst_caps_truncate (caps);
1843 s = gst_caps_get_structure (caps, 0);
1844 gst_structure_fixate (s);
1850 * gst_caps_to_string:
1853 * Converts @caps to a string representation. This string representation
1854 * can be converted back to a #GstCaps by gst_caps_from_string().
1856 * For debugging purposes its easier to do something like this:
1858 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1860 * This prints the caps in human readble form.
1862 * Returns: (transfer full): a newly allocated string representing @caps.
1865 gst_caps_to_string (const GstCaps * caps)
1867 guint i, slen, clen;
1870 /* NOTE: This function is potentially called by the debug system,
1871 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1872 * should be careful to avoid recursion. This includes any functions
1873 * called by gst_caps_to_string. In particular, calls should
1874 * not use the GST_PTR_FORMAT extension. */
1877 return g_strdup ("NULL");
1879 if (CAPS_IS_ANY (caps)) {
1880 return g_strdup ("ANY");
1882 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1883 return g_strdup ("EMPTY");
1886 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1888 clen = GST_CAPS_LEN (caps);
1889 for (i = 0; i < clen; i++) {
1891 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1895 s = g_string_sized_new (slen);
1896 for (i = 0; i < clen; i++) {
1897 GstStructure *structure;
1900 /* ';' is now added by gst_structure_to_string */
1901 g_string_append_c (s, ' ');
1904 structure = gst_caps_get_structure_unchecked (caps, i);
1905 priv_gst_structure_append_to_gstring (structure, s);
1907 if (s->len && s->str[s->len - 1] == ';') {
1908 /* remove latest ';' */
1909 s->str[--s->len] = '\0';
1911 return g_string_free (s, FALSE);
1915 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1917 GstStructure *structure;
1920 if (strcmp ("ANY", string) == 0) {
1921 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAG_ANY;
1924 if (strcmp ("EMPTY", string) == 0) {
1928 structure = gst_structure_from_string (string, &s);
1929 if (structure == NULL) {
1932 gst_caps_append_structure_unchecked (caps, structure);
1936 while (g_ascii_isspace (*s))
1941 structure = gst_structure_from_string (s, &s);
1942 if (structure == NULL) {
1945 gst_caps_append_structure_unchecked (caps, structure);
1953 * gst_caps_from_string:
1954 * @string: a string to convert to #GstCaps
1956 * Converts @caps from a string representation.
1958 * Returns: (transfer full): a newly allocated #GstCaps
1961 gst_caps_from_string (const gchar * string)
1965 g_return_val_if_fail (string, FALSE);
1967 caps = gst_caps_new_empty ();
1968 if (gst_caps_from_string_inplace (caps, string)) {
1971 gst_caps_unref (caps);
1977 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1979 g_return_if_fail (G_IS_VALUE (src_value));
1980 g_return_if_fail (G_IS_VALUE (dest_value));
1981 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1982 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1983 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1985 g_value_take_string (dest_value,
1986 gst_caps_to_string (gst_value_get_caps (src_value)));