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_FLAGS_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;
118 GST_DEFINE_MINI_OBJECT_TYPE (GstCaps, gst_caps);
121 _priv_gst_caps_initialize (void)
123 _gst_caps_type = gst_caps_get_type ();
125 g_value_register_transform_func (_gst_caps_type,
126 G_TYPE_STRING, gst_caps_transform_to_string);
130 _gst_caps_copy (const GstCaps * caps)
133 GstStructure *structure;
136 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
138 newcaps = gst_caps_new_empty ();
139 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
140 n = GST_CAPS_LEN (caps);
142 for (i = 0; i < n; i++) {
143 structure = gst_caps_get_structure_unchecked (caps, i);
144 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
150 /* creation/deletion */
152 _gst_caps_free (GstCaps * caps)
154 GstStructure *structure;
157 /* The refcount must be 0, but since we're only called by gst_caps_unref,
158 * don't bother testing. */
159 len = GST_CAPS_LEN (caps);
160 /* This can be used to get statistics about caps sizes */
161 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
162 for (i = 0; i < len; i++) {
163 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
164 gst_structure_set_parent_refcount (structure, NULL);
165 gst_structure_free (structure);
167 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
169 #ifdef DEBUG_REFCOUNT
170 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
172 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
176 gst_caps_init (GstCaps * caps, gsize size)
178 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
180 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
181 caps->mini_object.dispose = NULL;
182 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
184 /* the 32 has been determined by logging caps sizes in _gst_caps_free
185 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
187 * GST_CAPS_ARRAY (caps) = g_ptr_array_sized_new (32);
189 caps->priv = g_ptr_array_new ();
193 * gst_caps_new_empty:
195 * Creates a new #GstCaps that is empty. That is, the returned
196 * #GstCaps contains no media formats.
197 * Caller is responsible for unreffing the returned caps.
199 * Returns: (transfer full): the new #GstCaps
202 gst_caps_new_empty (void)
206 caps = g_slice_new (GstCaps);
208 gst_caps_init (caps, sizeof (GstCaps));
210 #ifdef DEBUG_REFCOUNT
211 GST_CAT_TRACE (GST_CAT_CAPS, "created caps %p", caps);
220 * Creates a new #GstCaps that indicates that it is compatible with
223 * Returns: (transfer full): the new #GstCaps
226 gst_caps_new_any (void)
228 GstCaps *caps = gst_caps_new_empty ();
230 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAGS_ANY);
236 * gst_caps_new_simple:
237 * @media_type: the media type of the structure
238 * @fieldname: first field to set
239 * @...: additional arguments
241 * Creates a new #GstCaps that contains one #GstStructure. The
242 * structure is defined by the arguments, which have the same format
243 * as gst_structure_new().
244 * Caller is responsible for unreffing the returned caps.
246 * Returns: (transfer full): the new #GstCaps
249 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
252 GstStructure *structure;
255 caps = gst_caps_new_empty ();
257 va_start (var_args, fieldname);
258 structure = gst_structure_new_valist (media_type, fieldname, var_args);
262 gst_caps_append_structure_unchecked (caps, structure);
264 gst_caps_replace (&caps, NULL);
271 * @struct1: the first structure to add
272 * @...: additional structures to add
274 * Creates a new #GstCaps and adds all the structures listed as
275 * arguments. The list must be NULL-terminated. The structures
276 * are not copied; the returned #GstCaps owns the structures.
278 * Returns: (transfer full): the new #GstCaps
281 gst_caps_new_full (GstStructure * struct1, ...)
286 va_start (var_args, struct1);
287 caps = gst_caps_new_full_valist (struct1, var_args);
294 * gst_caps_new_full_valist:
295 * @structure: the first structure to add
296 * @var_args: additional structures to add
298 * Creates a new #GstCaps and adds all the structures listed as
299 * arguments. The list must be NULL-terminated. The structures
300 * are not copied; the returned #GstCaps owns the structures.
302 * Returns: (transfer full): the new #GstCaps
305 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
309 caps = gst_caps_new_empty ();
312 gst_caps_append_structure_unchecked (caps, structure);
313 structure = va_arg (var_args, GstStructure *);
320 gst_static_caps_get_type (void)
322 static GType staticcaps_type = 0;
324 if (G_UNLIKELY (staticcaps_type == 0)) {
325 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
327 return staticcaps_type;
332 * gst_static_caps_get:
333 * @static_caps: the #GstStaticCaps to convert
335 * Converts a #GstStaticCaps to a #GstCaps.
337 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
338 * Since the core holds an additional ref to the returned caps,
339 * use gst_caps_make_writable() on the returned caps to modify it.
342 gst_static_caps_get (GstStaticCaps * static_caps)
346 g_return_val_if_fail (static_caps != NULL, NULL);
348 caps = (GstCaps *) static_caps;
350 /* refcount is 0 when we need to convert */
351 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) == 0)) {
355 G_LOCK (static_caps_lock);
356 /* check if other thread already updated */
357 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) > 0))
360 string = static_caps->string;
362 if (G_UNLIKELY (string == NULL))
365 GST_CAT_TRACE (GST_CAT_CAPS, "creating %p", static_caps);
367 /* we construct the caps on the stack, then copy over the struct into our
368 * real caps, refcount last. We do this because we must leave the refcount
369 * of the result caps to 0 so that other threads don't run away with the
370 * caps while we are constructing it. */
371 gst_caps_init (&temp, sizeof (GstCaps));
373 /* convert to string */
374 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
375 g_critical ("Could not convert static caps \"%s\"", string);
377 gst_caps_init (caps, sizeof (GstCaps));
378 /* now copy stuff over to the real caps. */
379 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS (&temp);
380 caps->priv = GST_CAPS_ARRAY (&temp);
382 GST_CAT_TRACE (GST_CAT_CAPS, "created %p", static_caps);
384 G_UNLOCK (static_caps_lock);
386 /* ref the caps, makes it not writable */
394 G_UNLOCK (static_caps_lock);
395 g_warning ("static caps %p string is NULL", static_caps);
401 * gst_static_caps_cleanup:
402 * @static_caps: the #GstStaticCaps to convert
404 * Clean up the caps contained in @static_caps when the refcount is 0.
407 gst_static_caps_cleanup (GstStaticCaps * static_caps)
409 GstCaps *caps = (GstCaps *) static_caps;
411 /* FIXME: this is not threadsafe */
412 if (GST_CAPS_REFCOUNT_VALUE (caps) == 1) {
413 GstStructure *structure;
416 clen = GST_CAPS_LEN (caps);
418 for (i = 0; i < clen; i++) {
419 structure = (GstStructure *) gst_caps_get_structure (caps, i);
420 gst_structure_set_parent_refcount (structure, NULL);
421 gst_structure_free (structure);
423 g_ptr_array_free (GST_CAPS_ARRAY (caps), TRUE);
424 GST_CAPS_REFCOUNT (caps) = 0;
430 static GstStructure *
431 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
433 /* don't use index_fast, gst_caps_do_simplify relies on the order */
434 GstStructure *s = g_ptr_array_remove_index (GST_CAPS_ARRAY (caps), idx);
436 gst_structure_set_parent_refcount (s, NULL);
441 * gst_caps_steal_structure:
442 * @caps: the #GstCaps to retrieve from
443 * @index: Index of the structure to retrieve
445 * Retrieves the stucture with the given index from the list of structures
446 * contained in @caps. The caller becomes the owner of the returned structure.
448 * Returns: (transfer full): a pointer to the #GstStructure corresponding
454 gst_caps_steal_structure (GstCaps * caps, guint index)
456 g_return_val_if_fail (caps != NULL, NULL);
457 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
459 if (G_UNLIKELY (index >= GST_CAPS_LEN (caps)))
462 return gst_caps_remove_and_get_structure (caps, index);
467 * @caps1: the #GstCaps that will be appended to
468 * @caps2: (transfer full): the #GstCaps to append
470 * Appends the structures contained in @caps2 to @caps1. The structures in
471 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
472 * freed. If either caps is ANY, the resulting caps will be ANY.
475 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
477 GstStructure *structure;
480 g_return_if_fail (GST_IS_CAPS (caps1));
481 g_return_if_fail (GST_IS_CAPS (caps2));
482 g_return_if_fail (IS_WRITABLE (caps1));
483 g_return_if_fail (IS_WRITABLE (caps2));
485 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
486 /* FIXME: this leaks */
487 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
488 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
489 structure = gst_caps_remove_and_get_structure (caps2, i);
490 gst_structure_free (structure);
493 for (i = GST_CAPS_LEN (caps2); i; i--) {
494 structure = gst_caps_remove_and_get_structure (caps2, 0);
495 gst_caps_append_structure_unchecked (caps1, structure);
498 gst_caps_unref (caps2); /* guaranteed to free it */
503 * @caps1: the #GstCaps that will take the new entries
504 * @caps2: (transfer full): the #GstCaps to merge in
506 * Appends the structures contained in @caps2 to @caps1 if they are not yet
507 * expressed by @caps1. The structures in @caps2 are not copied -- they are
508 * transferred to @caps1, and then @caps2 is freed.
509 * If either caps is ANY, the resulting caps will be ANY.
514 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
516 GstStructure *structure;
519 g_return_if_fail (GST_IS_CAPS (caps1));
520 g_return_if_fail (GST_IS_CAPS (caps2));
521 g_return_if_fail (IS_WRITABLE (caps1));
522 g_return_if_fail (IS_WRITABLE (caps2));
524 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
525 for (i = GST_CAPS_LEN (caps2) - 1; i >= 0; i--) {
526 structure = gst_caps_remove_and_get_structure (caps2, i);
527 gst_structure_free (structure);
529 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
530 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
531 for (i = GST_CAPS_LEN (caps1) - 1; i >= 0; i--) {
532 structure = gst_caps_remove_and_get_structure (caps1, i);
533 gst_structure_free (structure);
536 for (i = GST_CAPS_LEN (caps2); i; i--) {
537 structure = gst_caps_remove_and_get_structure (caps2, 0);
538 gst_caps_merge_structure (caps1, structure);
541 GstCaps *com = gst_caps_intersect (caps1, caps2);
542 GstCaps *add = gst_caps_subtract (caps2, com);
544 GST_DEBUG ("common : %d", gst_caps_get_size (com));
545 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
546 gst_caps_append (caps1, add);
547 gst_caps_unref (com);
550 gst_caps_unref (caps2); /* guaranteed to free it */
554 * gst_caps_append_structure:
555 * @caps: the #GstCaps that will be appended to
556 * @structure: (transfer full): the #GstStructure to append
558 * Appends @structure to @caps. The structure is not copied; @caps
559 * becomes the owner of @structure.
562 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
564 g_return_if_fail (GST_IS_CAPS (caps));
565 g_return_if_fail (IS_WRITABLE (caps));
567 if (G_LIKELY (structure)) {
568 gst_caps_append_structure_unchecked (caps, structure);
573 * gst_caps_remove_structure:
574 * @caps: the #GstCaps to remove from
575 * @idx: Index of the structure to remove
577 * removes the stucture with the given index from the list of structures
578 * contained in @caps.
581 gst_caps_remove_structure (GstCaps * caps, guint idx)
583 GstStructure *structure;
585 g_return_if_fail (caps != NULL);
586 g_return_if_fail (idx <= gst_caps_get_size (caps));
587 g_return_if_fail (IS_WRITABLE (caps));
589 structure = gst_caps_remove_and_get_structure (caps, idx);
590 gst_structure_free (structure);
594 * gst_caps_merge_structure:
595 * @caps: the #GstCaps that will the new structure
596 * @structure: (transfer full): the #GstStructure to merge
598 * Appends @structure to @caps if its not already expressed by @caps. The
599 * structure is not copied; @caps becomes the owner of @structure.
602 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
604 g_return_if_fail (GST_IS_CAPS (caps));
605 g_return_if_fail (IS_WRITABLE (caps));
607 if (G_LIKELY (structure)) {
608 GstStructure *structure1;
610 gboolean unique = TRUE;
612 /* check each structure */
613 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
614 structure1 = gst_caps_get_structure_unchecked (caps, i);
615 /* if structure is a subset of structure1, then skip it */
616 if (gst_structure_is_subset (structure, structure1)) {
622 gst_caps_append_structure_unchecked (caps, structure);
624 gst_structure_free (structure);
633 * Gets the number of structures contained in @caps.
635 * Returns: the number of structures that @caps contains
638 gst_caps_get_size (const GstCaps * caps)
640 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
642 return GST_CAPS_LEN (caps);
646 * gst_caps_get_structure:
648 * @index: the index of the structure
650 * Finds the structure in @caps that has the index @index, and
653 * WARNING: This function takes a const GstCaps *, but returns a
654 * non-const GstStructure *. This is for programming convenience --
655 * the caller should be aware that structures inside a constant
656 * #GstCaps should not be modified. However, if you know the caps
657 * are writable, either because you have just copied them or made
658 * them writable with gst_caps_make_writable(), you may modify the
659 * structure returned in the usual way, e.g. with functions like
660 * gst_structure_set().
662 * You do not need to free or unref the structure returned, it
663 * belongs to the #GstCaps.
665 * Returns: (transfer none): a pointer to the #GstStructure corresponding
669 gst_caps_get_structure (const GstCaps * caps, guint index)
671 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
672 g_return_val_if_fail (index < GST_CAPS_LEN (caps), NULL);
674 return gst_caps_get_structure_unchecked (caps, index);
679 * @caps: the #GstCaps to copy
680 * @nth: the nth structure to copy
682 * Creates a new #GstCaps and appends a copy of the nth structure
683 * contained in @caps.
685 * Returns: (transfer full): the new #GstCaps
688 gst_caps_copy_nth (const GstCaps * caps, guint nth)
691 GstStructure *structure;
693 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
695 newcaps = gst_caps_new_empty ();
696 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
698 if (G_LIKELY (GST_CAPS_LEN (caps) > nth)) {
699 structure = gst_caps_get_structure_unchecked (caps, nth);
700 gst_caps_append_structure_unchecked (newcaps,
701 gst_structure_copy (structure));
709 * @caps: the #GstCaps to truncate
711 * Destructively discard all but the first structure from @caps. Useful when
712 * fixating. @caps must be writable.
715 gst_caps_truncate (GstCaps * caps)
719 g_return_if_fail (GST_IS_CAPS (caps));
720 g_return_if_fail (IS_WRITABLE (caps));
722 i = GST_CAPS_LEN (caps) - 1;
725 gst_caps_remove_structure (caps, i--);
729 * gst_caps_set_value:
730 * @caps: a writable caps
731 * @field: name of the field to set
732 * @value: value to set the field to
734 * Sets the given @field on all structures of @caps to the given @value.
735 * This is a convenience function for calling gst_structure_set_value() on
736 * all structures of @caps.
741 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
745 g_return_if_fail (GST_IS_CAPS (caps));
746 g_return_if_fail (IS_WRITABLE (caps));
747 g_return_if_fail (field != NULL);
748 g_return_if_fail (G_IS_VALUE (value));
750 len = GST_CAPS_LEN (caps);
751 for (i = 0; i < len; i++) {
752 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
753 gst_structure_set_value (structure, field, value);
758 * gst_caps_set_simple_valist:
759 * @caps: the #GstCaps to set
760 * @field: first field to set
761 * @varargs: additional parameters
763 * Sets fields in a #GstCaps. The arguments must be passed in the same
764 * manner as gst_structure_set(), and be NULL-terminated.
765 * <note>Prior to GStreamer version 0.10.26, this function failed when
766 * @caps was not simple. If your code needs to work with those versions
767 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
768 * is %TRUE for @caps.</note>
771 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
773 GValue value = { 0, };
775 g_return_if_fail (GST_IS_CAPS (caps));
776 g_return_if_fail (IS_WRITABLE (caps));
782 type = va_arg (varargs, GType);
784 if (G_UNLIKELY (type == G_TYPE_DATE)) {
785 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
786 type = GST_TYPE_DATE;
788 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
789 if (G_UNLIKELY (err)) {
790 g_critical ("%s", err);
794 gst_caps_set_value (caps, field, &value);
796 g_value_unset (&value);
798 field = va_arg (varargs, const gchar *);
803 * gst_caps_set_simple:
804 * @caps: the #GstCaps to set
805 * @field: first field to set
806 * @...: additional parameters
808 * Sets fields in a #GstCaps. The arguments must be passed in the same
809 * manner as gst_structure_set(), and be NULL-terminated.
810 * <note>Prior to GStreamer version 0.10.26, this function failed when
811 * @caps was not simple. If your code needs to work with those versions
812 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
813 * is %TRUE for @caps.</note>
816 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
820 g_return_if_fail (GST_IS_CAPS (caps));
821 g_return_if_fail (IS_WRITABLE (caps));
823 va_start (var_args, field);
824 gst_caps_set_simple_valist (caps, field, var_args);
832 * @caps: the #GstCaps to test
834 * Determines if @caps represents any media format.
836 * Returns: TRUE if @caps represents any format.
839 gst_caps_is_any (const GstCaps * caps)
841 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
843 return (CAPS_IS_ANY (caps));
848 * @caps: the #GstCaps to test
850 * Determines if @caps represents no media formats.
852 * Returns: TRUE if @caps represents no formats.
855 gst_caps_is_empty (const GstCaps * caps)
857 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
859 if (CAPS_IS_ANY (caps))
862 return CAPS_IS_EMPTY_SIMPLE (caps);
866 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
869 return gst_value_is_fixed (value);
874 * @caps: the #GstCaps to test
876 * Fixed #GstCaps describe exactly one format, that is, they have exactly
877 * one structure, and each field in the structure describes a fixed type.
878 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
880 * Returns: TRUE if @caps is fixed
883 gst_caps_is_fixed (const GstCaps * caps)
885 GstStructure *structure;
887 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
889 if (GST_CAPS_LEN (caps) != 1)
892 structure = gst_caps_get_structure_unchecked (caps, 0);
894 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
898 * gst_caps_is_equal_fixed:
899 * @caps1: the #GstCaps to test
900 * @caps2: the #GstCaps to test
902 * Tests if two #GstCaps are equal. This function only works on fixed
905 * Returns: TRUE if the arguments represent the same format
908 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
910 GstStructure *struct1, *struct2;
912 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
913 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
915 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
916 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
918 return gst_structure_is_equal (struct1, struct2);
922 * gst_caps_is_always_compatible:
923 * @caps1: the #GstCaps to test
924 * @caps2: the #GstCaps to test
926 * A given #GstCaps structure is always compatible with another if
927 * every media format that is in the first is also contained in the
928 * second. That is, @caps1 is a subset of @caps2.
930 * Returns: TRUE if @caps1 is a subset of @caps2.
933 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
935 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
936 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
938 return gst_caps_is_subset (caps1, caps2);
942 * gst_caps_is_subset:
943 * @subset: a #GstCaps
944 * @superset: a potentially greater #GstCaps
946 * Checks if all caps represented by @subset are also represented by @superset.
947 * <note>This function does not work reliably if optional properties for caps
948 * are included on one caps and omitted on the other.</note>
950 * Returns: %TRUE if @subset is a subset of @superset
953 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
955 GstStructure *s1, *s2;
959 g_return_val_if_fail (subset != NULL, FALSE);
960 g_return_val_if_fail (superset != NULL, FALSE);
962 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
964 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
967 for (i = GST_CAPS_LEN (subset) - 1; i >= 0; i--) {
968 for (j = GST_CAPS_LEN (superset) - 1; j >= 0; j--) {
969 s1 = gst_caps_get_structure_unchecked (subset, i);
970 s2 = gst_caps_get_structure_unchecked (superset, j);
971 if (gst_structure_is_subset (s1, s2)) {
972 /* If we found a superset, continue with the next
973 * subset structure */
977 /* If we found no superset for this subset structure
978 * we return FALSE immediately */
989 * gst_caps_is_subset_structure:
991 * @structure: a potential #GstStructure subset of @caps
993 * Checks if @structure is a subset of @caps. See gst_caps_is_subset()
994 * for more information.
996 * Returns: %TRUE if @structure is a subset of @caps
1001 gst_caps_is_subset_structure (const GstCaps * caps,
1002 const GstStructure * structure)
1007 g_return_val_if_fail (caps != NULL, FALSE);
1008 g_return_val_if_fail (structure != NULL, FALSE);
1010 if (CAPS_IS_ANY (caps))
1012 if (CAPS_IS_EMPTY (caps))
1015 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1016 s = gst_caps_get_structure_unchecked (caps, i);
1017 if (gst_structure_is_subset (structure, s)) {
1018 /* If we found a superset return TRUE */
1027 * gst_caps_is_equal:
1028 * @caps1: a #GstCaps
1029 * @caps2: another #GstCaps
1031 * Checks if the given caps represent the same set of caps.
1032 * <note>This function does not work reliably if optional properties for caps
1033 * are included on one caps and omitted on the other.</note>
1035 * This function deals correctly with passing NULL for any of the caps.
1037 * Returns: TRUE if both caps are equal.
1040 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1042 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1043 * So there should be an assertion that caps1 and caps2 != NULL */
1045 /* NULL <-> NULL is allowed here */
1046 if (G_UNLIKELY (caps1 == caps2))
1049 /* one of them NULL => they are different (can't be both NULL because
1050 * we checked that above) */
1051 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1054 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1055 return gst_caps_is_equal_fixed (caps1, caps2);
1057 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1060 /* intersect operation */
1063 * gst_caps_can_intersect:
1064 * @caps1: a #GstCaps to intersect
1065 * @caps2: a #GstCaps to intersect
1067 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1070 * Returns: %TRUE if intersection would be not empty
1075 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1077 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1078 guint j, k, len1, len2;
1079 GstStructure *struct1;
1080 GstStructure *struct2;
1082 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1083 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1085 /* caps are exactly the same pointers */
1086 if (G_UNLIKELY (caps1 == caps2))
1089 /* empty caps on either side, return empty */
1090 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1093 /* one of the caps is any */
1094 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1097 /* run zigzag on top line then right line, this preserves the caps order
1098 * much better than a simple loop.
1100 * This algorithm zigzags over the caps structures as demonstrated in
1101 * the folowing matrix:
1104 * +------------- total distance: +-------------
1105 * | 1 2 4 7 0 | 0 1 2 3
1106 * caps2 | 3 5 8 10 1 | 1 2 3 4
1107 * | 6 9 11 12 2 | 2 3 4 5
1109 * First we iterate over the caps1 structures (top line) intersecting
1110 * the structures diagonally down, then we iterate over the caps2
1111 * structures. The result is that the intersections are ordered based on the
1112 * sum of the indexes in the list.
1114 len1 = GST_CAPS_LEN (caps1);
1115 len2 = GST_CAPS_LEN (caps2);
1116 for (i = 0; i < len1 + len2 - 1; i++) {
1117 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1118 j = MIN (i, len1 - 1);
1119 /* subset index stays 0 until i reaches superset->structs->len, then it
1120 * counts up from 1 to subset->structs->len - 1 */
1121 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1123 /* now run the diagonal line, end condition is the left or bottom
1126 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1127 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1129 if (gst_structure_can_intersect (struct1, struct2)) {
1132 /* move down left */
1134 if (G_UNLIKELY (j == 0))
1135 break; /* so we don't roll back to G_MAXUINT */
1143 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1145 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1146 guint j, k, len1, len2;
1148 GstStructure *struct1;
1149 GstStructure *struct2;
1151 GstStructure *istruct;
1153 /* caps are exactly the same pointers, just copy one caps */
1154 if (G_UNLIKELY (caps1 == caps2))
1155 return _gst_caps_copy (caps1);
1157 /* empty caps on either side, return empty */
1158 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1159 return gst_caps_new_empty ();
1161 /* one of the caps is any, just copy the other caps */
1162 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1163 return _gst_caps_copy (caps2);
1164 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1165 return _gst_caps_copy (caps1);
1167 dest = gst_caps_new_empty ();
1169 /* run zigzag on top line then right line, this preserves the caps order
1170 * much better than a simple loop.
1172 * This algorithm zigzags over the caps structures as demonstrated in
1173 * the folowing matrix:
1181 * First we iterate over the caps1 structures (top line) intersecting
1182 * the structures diagonally down, then we iterate over the caps2
1185 len1 = GST_CAPS_LEN (caps1);
1186 len2 = GST_CAPS_LEN (caps2);
1187 for (i = 0; i < len1 + len2 - 1; i++) {
1188 /* caps1 index goes from 0 to GST_CAPS_LEN (caps1)-1 */
1189 j = MIN (i, len1 - 1);
1190 /* caps2 index stays 0 until i reaches GST_CAPS_LEN (caps1), then it counts
1191 * up from 1 to GST_CAPS_LEN (caps2) - 1 */
1192 k = (i > j) ? (i - j) : 0; /* MAX (0, i - j) */
1194 /* now run the diagonal line, end condition is the left or bottom
1197 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1198 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1200 istruct = gst_structure_intersect (struct1, struct2);
1202 gst_caps_merge_structure (dest, istruct);
1203 /* move down left */
1205 if (G_UNLIKELY (j == 0))
1206 break; /* so we don't roll back to G_MAXUINT */
1214 * gst_caps_intersect_first:
1215 * @caps1: a #GstCaps to intersect
1216 * @caps2: a #GstCaps to intersect
1218 * Creates a new #GstCaps that contains all the formats that are common
1219 * to both @caps1 and @caps2.
1221 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1222 * fashion as @caps1.
1224 * Returns: the new #GstCaps
1227 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1229 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1230 guint j, len1, len2;
1232 GstStructure *struct1;
1233 GstStructure *struct2;
1235 GstStructure *istruct;
1237 /* caps are exactly the same pointers, just copy one caps */
1238 if (G_UNLIKELY (caps1 == caps2))
1239 return gst_caps_copy (caps1);
1241 /* empty caps on either side, return empty */
1242 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1243 return gst_caps_new_empty ();
1245 /* one of the caps is any, just copy the other caps */
1246 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1247 return gst_caps_copy (caps2);
1248 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1249 return gst_caps_copy (caps1);
1251 dest = gst_caps_new_empty ();
1253 len1 = GST_CAPS_LEN (caps1);
1254 len2 = GST_CAPS_LEN (caps2);
1255 for (i = 0; i < len1; i++) {
1256 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1257 for (j = 0; j < len2; j++) {
1258 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1259 istruct = gst_structure_intersect (struct1, struct2);
1261 gst_caps_merge_structure (dest, istruct);
1269 * gst_caps_intersect_full:
1270 * @caps1: a #GstCaps to intersect
1271 * @caps2: a #GstCaps to intersect
1272 * @mode: The intersection algorithm/mode to use
1274 * Creates a new #GstCaps that contains all the formats that are common
1275 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1278 * Returns: the new #GstCaps
1282 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1283 GstCapsIntersectMode mode)
1285 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1286 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1289 case GST_CAPS_INTERSECT_FIRST:
1290 return gst_caps_intersect_first (caps1, caps2);
1292 g_warning ("Unknown caps intersect mode: %d", mode);
1294 case GST_CAPS_INTERSECT_ZIG_ZAG:
1295 return gst_caps_intersect_zig_zag (caps1, caps2);
1300 * gst_caps_intersect:
1301 * @caps1: a #GstCaps to intersect
1302 * @caps2: a #GstCaps to intersect
1304 * Creates a new #GstCaps that contains all the formats that are common
1305 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1307 * Returns: the new #GstCaps
1310 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1312 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1316 /* subtract operation */
1320 const GstStructure *subtract_from;
1326 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1329 SubtractionEntry *e = user_data;
1330 GValue subtraction = { 0, };
1331 const GValue *other;
1332 GstStructure *structure;
1334 other = gst_structure_id_get_value (e->subtract_from, field_id);
1338 if (!gst_value_subtract (&subtraction, other, value))
1340 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1341 g_value_unset (&subtraction);
1344 structure = gst_structure_copy (e->subtract_from);
1345 gst_structure_id_set_value (structure, field_id, &subtraction);
1346 g_value_unset (&subtraction);
1347 e->put_into = g_slist_prepend (e->put_into, structure);
1353 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1354 const GstStructure * subtrahend)
1359 e.subtract_from = minuend;
1362 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1363 gst_caps_structure_subtract_field, &e);
1369 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1370 gst_structure_free (walk->data);
1372 g_slist_free (e.put_into);
1378 * gst_caps_subtract:
1379 * @minuend: #GstCaps to subtract from
1380 * @subtrahend: #GstCaps to subtract
1382 * Subtracts the @subtrahend from the @minuend.
1383 * <note>This function does not work reliably if optional properties for caps
1384 * are included on one caps and omitted on the other.</note>
1386 * Returns: the resulting caps
1389 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1394 GstCaps *dest = NULL, *src;
1396 g_return_val_if_fail (minuend != NULL, NULL);
1397 g_return_val_if_fail (subtrahend != NULL, NULL);
1399 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1400 return gst_caps_new_empty ();
1402 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1403 return _gst_caps_copy (minuend);
1405 /* FIXME: Do we want this here or above?
1406 The reason we need this is that there is no definition about what
1407 ANY means for specific types, so it's not possible to reduce ANY partially
1408 You can only remove everything or nothing and that is done above.
1409 Note: there's a test that checks this behaviour. */
1410 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1411 sublen = GST_CAPS_LEN (subtrahend);
1412 g_assert (sublen > 0);
1414 src = _gst_caps_copy (minuend);
1415 for (i = 0; i < sublen; i++) {
1418 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1420 gst_caps_unref (src);
1423 dest = gst_caps_new_empty ();
1424 srclen = GST_CAPS_LEN (src);
1425 for (j = 0; j < srclen; j++) {
1426 min = gst_caps_get_structure_unchecked (src, j);
1427 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1430 if (gst_caps_structure_subtract (&list, min, sub)) {
1433 for (walk = list; walk; walk = g_slist_next (walk)) {
1434 gst_caps_append_structure_unchecked (dest,
1435 (GstStructure *) walk->data);
1437 g_slist_free (list);
1439 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1442 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1445 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1446 gst_caps_unref (src);
1451 gst_caps_unref (src);
1452 gst_caps_do_simplify (dest);
1456 /* union operation */
1459 static GstStructure *
1460 gst_caps_structure_union (const GstStructure * struct1,
1461 const GstStructure * struct2)
1465 const GstStructureField *field1;
1466 const GstStructureField *field2;
1469 /* FIXME this doesn't actually work */
1471 if (struct1->name != struct2->name)
1474 dest = gst_structure_id_empty_new (struct1->name);
1476 for (i = 0; i < struct1->fields->len; i++) {
1477 GValue dest_value = { 0 };
1479 field1 = GST_STRUCTURE_FIELD (struct1, i);
1480 field2 = gst_structure_id_get_field (struct2, field1->name);
1482 if (field2 == NULL) {
1485 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1486 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1489 ret = gst_value_compare (&field1->value, &field2->value);
1500 * @caps1: a #GstCaps to union
1501 * @caps2: a #GstCaps to union
1503 * Creates a new #GstCaps that contains all the formats that are in
1504 * either @caps1 and @caps2.
1506 * Returns: the new #GstCaps
1509 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1514 /* NULL pointers are no correct GstCaps */
1515 g_return_val_if_fail (caps1 != NULL, NULL);
1516 g_return_val_if_fail (caps2 != NULL, NULL);
1518 if (CAPS_IS_EMPTY (caps1))
1519 return _gst_caps_copy (caps2);
1521 if (CAPS_IS_EMPTY (caps2))
1522 return _gst_caps_copy (caps1);
1524 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1525 return gst_caps_new_any ();
1527 dest1 = _gst_caps_copy (caps1);
1528 dest2 = _gst_caps_copy (caps2);
1529 gst_caps_append (dest1, dest2);
1531 gst_caps_do_simplify (dest1);
1535 /* normalize/simplify operations */
1537 typedef struct _NormalizeForeach
1540 GstStructure *structure;
1545 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1547 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1551 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1552 guint len = gst_value_list_get_size (value);
1553 for (i = 1; i < len; i++) {
1554 const GValue *v = gst_value_list_get_value (value, i);
1555 GstStructure *structure = gst_structure_copy (nf->structure);
1557 gst_structure_id_set_value (structure, field_id, v);
1558 gst_caps_append_structure_unchecked (nf->caps, structure);
1561 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1562 gst_structure_id_set_value (nf->structure, field_id, &val);
1563 g_value_unset (&val);
1571 * gst_caps_normalize:
1572 * @caps: a #GstCaps to normalize
1574 * Creates a new #GstCaps that represents the same set of formats as
1575 * @caps, but contains no lists. Each list is expanded into separate
1578 * Returns: the new #GstCaps
1581 gst_caps_normalize (const GstCaps * caps)
1583 NormalizeForeach nf;
1587 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1589 newcaps = _gst_caps_copy (caps);
1592 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1593 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1595 while (!gst_structure_foreach (nf.structure,
1596 gst_caps_normalize_foreach, &nf));
1603 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1606 const GstStructure *struct1 = *((const GstStructure **) one);
1607 const GstStructure *struct2 = *((const GstStructure **) two);
1609 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1610 So what's the best way? */
1611 ret = strcmp (gst_structure_get_name (struct1),
1612 gst_structure_get_name (struct2));
1616 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1623 GstStructure *compare;
1628 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1631 UnionField *u = user_data;
1632 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1636 g_value_unset (&u->value);
1639 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1642 g_value_unset (&u->value);
1646 gst_value_union (&u->value, val, value);
1651 gst_caps_structure_simplify (GstStructure ** result,
1652 const GstStructure * simplify, GstStructure * compare)
1655 UnionField field = { 0, {0,}, NULL };
1657 /* try to subtract to get a real subset */
1658 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1659 if (list == NULL) { /* no result */
1662 } else if (list->next == NULL) { /* one result */
1663 *result = list->data;
1664 g_slist_free (list);
1666 } else { /* multiple results */
1667 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1668 g_slist_free (list);
1673 /* try to union both structs */
1674 field.compare = compare;
1675 if (gst_structure_foreach ((GstStructure *) simplify,
1676 gst_caps_structure_figure_out_union, &field)) {
1677 gboolean ret = FALSE;
1679 /* now we know all of simplify's fields are the same in compare
1680 * but at most one field: field.name */
1681 if (G_IS_VALUE (&field.value)) {
1682 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1683 gst_structure_id_set_value (compare, field.name, &field.value);
1687 g_value_unset (&field.value);
1688 } else if (gst_structure_n_fields (simplify) <=
1689 gst_structure_n_fields (compare)) {
1690 /* compare is just more specific, will be optimized away later */
1691 /* FIXME: do this here? */
1692 GST_LOG ("found a case that will be optimized later.");
1694 gchar *one = gst_structure_to_string (simplify);
1695 gchar *two = gst_structure_to_string (compare);
1698 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1710 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1711 GstStructure * new, gint i)
1713 gst_structure_set_parent_refcount (old, NULL);
1714 gst_structure_free (old);
1715 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1716 g_ptr_array_index (GST_CAPS_ARRAY (caps), i) = new;
1720 * gst_caps_do_simplify:
1721 * @caps: a #GstCaps to simplify
1723 * Modifies the given @caps inplace into a representation that represents the
1724 * same set of formats, but in a simpler form. Component structures that are
1725 * identical are merged. Component structures that have values that can be
1726 * merged are also merged.
1728 * Returns: TRUE, if the caps could be simplified
1731 gst_caps_do_simplify (GstCaps * caps)
1733 GstStructure *simplify, *compare, *result = NULL;
1735 gboolean changed = FALSE;
1737 g_return_val_if_fail (caps != NULL, FALSE);
1738 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1740 if (gst_caps_get_size (caps) < 2)
1743 g_ptr_array_sort (GST_CAPS_ARRAY (caps), gst_caps_compare_structures);
1745 start = GST_CAPS_LEN (caps) - 1;
1746 for (i = GST_CAPS_LEN (caps) - 1; i >= 0; i--) {
1747 simplify = gst_caps_get_structure_unchecked (caps, i);
1748 if (gst_structure_get_name_id (simplify) !=
1749 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1752 for (j = start; j >= 0; j--) {
1755 compare = gst_caps_get_structure_unchecked (caps, j);
1756 if (gst_structure_get_name_id (simplify) !=
1757 gst_structure_get_name_id (compare)) {
1760 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1762 gst_caps_switch_structures (caps, simplify, result, i);
1765 gst_caps_remove_structure (caps, i);
1777 /* gst_caps_do_simplify (caps); */
1783 * @caps: a #GstCaps to fixate
1785 * Modifies the given @caps inplace into a representation with only fixed
1786 * values. First the caps will be truncated and then the first structure will be
1787 * fixated with gst_structure_fixate(). @caps should be writable.
1790 gst_caps_fixate (GstCaps * caps)
1794 g_return_if_fail (GST_IS_CAPS (caps));
1795 g_return_if_fail (IS_WRITABLE (caps));
1797 /* default fixation */
1798 gst_caps_truncate (caps);
1799 s = gst_caps_get_structure (caps, 0);
1800 gst_structure_fixate (s);
1806 * gst_caps_to_string:
1809 * Converts @caps to a string representation. This string representation
1810 * can be converted back to a #GstCaps by gst_caps_from_string().
1812 * For debugging purposes its easier to do something like this:
1814 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1816 * This prints the caps in human readble form.
1818 * Returns: (transfer full): a newly allocated string representing @caps.
1821 gst_caps_to_string (const GstCaps * caps)
1823 guint i, slen, clen;
1826 /* NOTE: This function is potentially called by the debug system,
1827 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1828 * should be careful to avoid recursion. This includes any functions
1829 * called by gst_caps_to_string. In particular, calls should
1830 * not use the GST_PTR_FORMAT extension. */
1833 return g_strdup ("NULL");
1835 if (CAPS_IS_ANY (caps)) {
1836 return g_strdup ("ANY");
1838 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1839 return g_strdup ("EMPTY");
1842 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1844 clen = GST_CAPS_LEN (caps);
1845 for (i = 0; i < clen; i++) {
1847 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1851 s = g_string_sized_new (slen);
1852 for (i = 0; i < clen; i++) {
1853 GstStructure *structure;
1856 /* ';' is now added by gst_structure_to_string */
1857 g_string_append_c (s, ' ');
1860 structure = gst_caps_get_structure_unchecked (caps, i);
1861 priv_gst_structure_append_to_gstring (structure, s);
1863 if (s->len && s->str[s->len - 1] == ';') {
1864 /* remove latest ';' */
1865 s->str[--s->len] = '\0';
1867 return g_string_free (s, FALSE);
1871 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1873 GstStructure *structure;
1876 if (strcmp ("ANY", string) == 0) {
1877 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
1880 if (strcmp ("EMPTY", string) == 0) {
1884 structure = gst_structure_from_string (string, &s);
1885 if (structure == NULL) {
1888 gst_caps_append_structure_unchecked (caps, structure);
1892 while (g_ascii_isspace (*s))
1897 structure = gst_structure_from_string (s, &s);
1898 if (structure == NULL) {
1901 gst_caps_append_structure_unchecked (caps, structure);
1909 * gst_caps_from_string:
1910 * @string: a string to convert to #GstCaps
1912 * Converts @caps from a string representation.
1914 * Returns: (transfer full): a newly allocated #GstCaps
1917 gst_caps_from_string (const gchar * string)
1921 g_return_val_if_fail (string, FALSE);
1923 caps = gst_caps_new_empty ();
1924 if (gst_caps_from_string_inplace (caps, string)) {
1927 gst_caps_unref (caps);
1933 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1935 g_return_if_fail (G_IS_VALUE (src_value));
1936 g_return_if_fail (G_IS_VALUE (dest_value));
1937 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1938 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1939 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1941 g_value_take_string (dest_value,
1942 gst_caps_to_string (gst_value_get_caps (src_value)));