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-yuv",
47 * "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
48 * "framerate", GST_TYPE_FRACTION, 25, 1,
49 * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
50 * "width", G_TYPE_INT, 320,
51 * "height", G_TYPE_INT, 240,
56 * A #GstCaps is fixed when it has no properties with ranges or lists. Use
57 * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
58 * set on a #GstPad or #GstBuffer.
60 * Various methods exist to work with the media types such as subtracting
63 * Last reviewed on 2007-02-13 (0.10.10)
72 #include "gst_private.h"
74 #include <gobject/gvaluecollector.h>
76 #define DEBUG_REFCOUNT
78 #define IS_WRITABLE(caps) \
79 (GST_CAPS_REFCOUNT_VALUE (caps) == 1)
81 /* same as gst_caps_is_any () */
82 #define CAPS_IS_ANY(caps) \
83 (GST_CAPS_FLAGS(caps) & GST_CAPS_FLAGS_ANY)
85 /* same as gst_caps_is_empty () */
86 #define CAPS_IS_EMPTY(caps) \
87 (!CAPS_IS_ANY(caps) && CAPS_IS_EMPTY_SIMPLE(caps))
89 #define CAPS_IS_EMPTY_SIMPLE(caps) \
90 (((caps)->structs == NULL) || ((caps)->structs->len == 0))
92 /* quick way to get a caps structure at an index without doing a type or array
94 #define gst_caps_get_structure_unchecked(caps, index) \
95 ((GstStructure *)g_ptr_array_index ((caps)->structs, (index)))
96 /* quick way to append a structure without checking the args */
97 #define gst_caps_append_structure_unchecked(caps, structure) G_STMT_START{\
98 GstStructure *__s=structure; \
99 gst_structure_set_parent_refcount (__s, &GST_MINI_OBJECT_REFCOUNT(caps)); \
100 g_ptr_array_add (caps->structs, __s); \
103 /* lock to protect multiple invocations of static caps to caps conversion */
104 G_LOCK_DEFINE_STATIC (static_caps_lock);
106 static void gst_caps_transform_to_string (const GValue * src_value,
107 GValue * dest_value);
108 static gboolean gst_caps_from_string_inplace (GstCaps * caps,
109 const gchar * string);
111 GType _gst_caps_type = 0;
114 _gst_caps_initialize (void)
116 if (G_LIKELY (_gst_caps_type == 0)) {
117 _gst_caps_type = gst_mini_object_register ("GstCaps");
119 g_value_register_transform_func (_gst_caps_type,
120 G_TYPE_STRING, gst_caps_transform_to_string);
125 _gst_caps_copy (const GstCaps * caps)
128 GstStructure *structure;
131 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
133 newcaps = gst_caps_new_empty ();
134 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
135 n = caps->structs->len;
137 for (i = 0; i < n; i++) {
138 structure = gst_caps_get_structure_unchecked (caps, i);
139 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
145 /* creation/deletion */
147 _gst_caps_free (GstCaps * caps)
149 GstStructure *structure;
152 /* The refcount must be 0, but since we're only called by gst_caps_unref,
153 * don't bother testing. */
154 len = caps->structs->len;
155 /* This can be used to get statistics about caps sizes */
156 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
157 for (i = 0; i < len; i++) {
158 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
159 gst_structure_set_parent_refcount (structure, NULL);
160 gst_structure_free (structure);
162 g_ptr_array_free (caps->structs, TRUE);
164 #ifdef DEBUG_REFCOUNT
165 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
167 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
171 gst_caps_init (GstCaps * caps, gsize size)
173 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
175 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
176 caps->mini_object.dispose = NULL;
177 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
179 /* the 32 has been determined by logging caps sizes in _gst_caps_free
180 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
182 * caps->structs = g_ptr_array_sized_new (32);
184 caps->structs = g_ptr_array_new ();
188 * gst_caps_new_empty:
190 * Creates a new #GstCaps that is empty. That is, the returned
191 * #GstCaps contains no media formats.
192 * Caller is responsible for unreffing the returned caps.
194 * Returns: (transfer full): the new #GstCaps
197 gst_caps_new_empty (void)
201 caps = g_slice_new (GstCaps);
203 gst_caps_init (caps, sizeof (GstCaps));
205 #ifdef DEBUG_REFCOUNT
206 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
215 * Creates a new #GstCaps that indicates that it is compatible with
218 * Returns: (transfer full): the new #GstCaps
221 gst_caps_new_any (void)
223 GstCaps *caps = gst_caps_new_empty ();
225 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAGS_ANY);
231 * gst_caps_new_simple:
232 * @media_type: the media type of the structure
233 * @fieldname: first field to set
234 * @...: additional arguments
236 * Creates a new #GstCaps that contains one #GstStructure. The
237 * structure is defined by the arguments, which have the same format
238 * as gst_structure_new().
239 * Caller is responsible for unreffing the returned caps.
241 * Returns: (transfer full): the new #GstCaps
244 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
247 GstStructure *structure;
250 caps = gst_caps_new_empty ();
252 va_start (var_args, fieldname);
253 structure = gst_structure_new_valist (media_type, fieldname, var_args);
257 gst_caps_append_structure_unchecked (caps, structure);
259 gst_caps_replace (&caps, NULL);
266 * @struct1: the first structure to add
267 * @...: additional structures to add
269 * Creates a new #GstCaps and adds all the structures listed as
270 * arguments. The list must be NULL-terminated. The structures
271 * are not copied; the returned #GstCaps owns the structures.
273 * Returns: (transfer full): the new #GstCaps
276 gst_caps_new_full (GstStructure * struct1, ...)
281 va_start (var_args, struct1);
282 caps = gst_caps_new_full_valist (struct1, var_args);
289 * gst_caps_new_full_valist:
290 * @structure: the first structure to add
291 * @var_args: additional structures to add
293 * Creates a new #GstCaps and adds all the structures listed as
294 * arguments. The list must be NULL-terminated. The structures
295 * are not copied; the returned #GstCaps owns the structures.
297 * Returns: (transfer full): the new #GstCaps
300 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
304 caps = gst_caps_new_empty ();
307 gst_caps_append_structure_unchecked (caps, structure);
308 structure = va_arg (var_args, GstStructure *);
315 * gst_caps_make_writable:
316 * @caps: (transfer full): the #GstCaps to make writable
318 * Returns a writable copy of @caps.
320 * If there is only one reference count on @caps, the caller must be the owner,
321 * and so this function will return the caps object unchanged. If on the other
322 * hand there is more than one reference on the object, a new caps object will
323 * be returned. The caller's reference on @caps will be removed, and instead the
324 * caller will own a reference to the returned object.
326 * In short, this function unrefs the caps in the argument and refs the caps
327 * that it returns. Don't access the argument after calling this function. See
328 * also: gst_caps_ref().
330 * Returns: (transfer full): the same #GstCaps object.
333 gst_caps_make_writable (GstCaps * caps)
337 g_return_val_if_fail (caps != NULL, NULL);
339 /* we are the only instance reffing this caps */
340 if (IS_WRITABLE (caps))
344 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy caps");
345 copy = _gst_caps_copy (caps);
346 gst_caps_unref (caps);
352 gst_static_caps_get_type (void)
354 static GType staticcaps_type = 0;
356 if (G_UNLIKELY (staticcaps_type == 0)) {
357 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
359 return staticcaps_type;
364 * gst_static_caps_get:
365 * @static_caps: the #GstStaticCaps to convert
367 * Converts a #GstStaticCaps to a #GstCaps.
369 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
370 * Since the core holds an additional ref to the returned caps,
371 * use gst_caps_make_writable() on the returned caps to modify it.
374 gst_static_caps_get (GstStaticCaps * static_caps)
378 g_return_val_if_fail (static_caps != NULL, NULL);
380 caps = (GstCaps *) static_caps;
382 /* refcount is 0 when we need to convert */
383 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) == 0)) {
387 G_LOCK (static_caps_lock);
388 /* check if other thread already updated */
389 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) > 0))
392 string = static_caps->string;
394 if (G_UNLIKELY (string == NULL))
397 GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);
399 /* we construct the caps on the stack, then copy over the struct into our
400 * real caps, refcount last. We do this because we must leave the refcount
401 * of the result caps to 0 so that other threads don't run away with the
402 * caps while we are constructing it. */
403 gst_caps_init (&temp, sizeof (GstCaps));
405 /* convert to string */
406 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
407 g_critical ("Could not convert static caps \"%s\"", string);
409 gst_caps_init (caps, sizeof (GstCaps));
410 /* now copy stuff over to the real caps. */
411 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS (&temp);
412 caps->structs = temp.structs;
414 GST_CAT_LOG (GST_CAT_CAPS, "created %p", static_caps);
416 G_UNLOCK (static_caps_lock);
418 /* ref the caps, makes it not writable */
426 G_UNLOCK (static_caps_lock);
427 g_warning ("static caps %p string is NULL", static_caps);
434 static GstStructure *
435 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
437 /* don't use index_fast, gst_caps_do_simplify relies on the order */
438 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
440 gst_structure_set_parent_refcount (s, NULL);
445 * gst_caps_steal_structure:
446 * @caps: the #GstCaps to retrieve from
447 * @index: Index of the structure to retrieve
449 * Retrieves the stucture with the given index from the list of structures
450 * contained in @caps. The caller becomes the owner of the returned structure.
452 * Returns: (transfer full): a pointer to the #GstStructure corresponding
458 gst_caps_steal_structure (GstCaps * caps, guint index)
460 g_return_val_if_fail (caps != NULL, NULL);
461 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
463 if (G_UNLIKELY (index >= caps->structs->len))
466 return gst_caps_remove_and_get_structure (caps, index);
470 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
473 GstStructure *struct1 = (GstStructure *) data;
474 const GValue *val1 = gst_structure_id_get_value (struct1, field_id);
476 if (G_UNLIKELY (val1 == NULL))
478 if (gst_value_compare (val1, val2) == GST_VALUE_EQUAL) {
486 gst_caps_structure_is_subset_field (GQuark field_id, const GValue * value,
489 GstStructure *subtract_from = user_data;
490 GValue subtraction = { 0, };
493 if (!(other = gst_structure_id_get_value (subtract_from, field_id)))
494 /* field is missing in one set */
497 /* equal values are subset */
498 if (gst_value_compare (other, value) == GST_VALUE_EQUAL)
506 * -> 1 - [1,2] = empty
510 * -> [1,2] - [1,3] = empty
514 * -> {1,3} - {1,2} = 3
517 * First caps subtraction needs to return a non-empty set, second
518 * subtractions needs to give en empty set.
520 if (gst_value_subtract (&subtraction, other, value)) {
521 g_value_unset (&subtraction);
522 /* !empty result, swapping must be empty */
523 if (!gst_value_subtract (&subtraction, value, other))
526 g_value_unset (&subtraction);
532 gst_caps_structure_is_subset (const GstStructure * minuend,
533 const GstStructure * subtrahend)
535 if ((minuend->name != subtrahend->name) ||
536 (gst_structure_n_fields (minuend) !=
537 gst_structure_n_fields (subtrahend))) {
541 return gst_structure_foreach ((GstStructure *) subtrahend,
542 gst_caps_structure_is_subset_field, (gpointer) minuend);
547 * @caps1: the #GstCaps that will be appended to
548 * @caps2: (transfer full): the #GstCaps to append
550 * Appends the structures contained in @caps2 to @caps1. The structures in
551 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
552 * freed. If either caps is ANY, the resulting caps will be ANY.
555 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
557 GstStructure *structure;
560 g_return_if_fail (GST_IS_CAPS (caps1));
561 g_return_if_fail (GST_IS_CAPS (caps2));
562 g_return_if_fail (IS_WRITABLE (caps1));
563 g_return_if_fail (IS_WRITABLE (caps2));
565 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
566 /* FIXME: this leaks */
567 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
568 for (i = caps2->structs->len - 1; i >= 0; i--) {
569 structure = gst_caps_remove_and_get_structure (caps2, i);
570 gst_structure_free (structure);
573 for (i = caps2->structs->len; i; i--) {
574 structure = gst_caps_remove_and_get_structure (caps2, 0);
575 gst_caps_append_structure_unchecked (caps1, structure);
578 gst_caps_unref (caps2); /* guaranteed to free it */
583 * @caps1: the #GstCaps that will take the new entries
584 * @caps2: (transfer full): the #GstCaps to merge in
586 * Appends the structures contained in @caps2 to @caps1 if they are not yet
587 * expressed by @caps1. The structures in @caps2 are not copied -- they are
588 * transferred to @caps1, and then @caps2 is freed.
589 * If either caps is ANY, the resulting caps will be ANY.
594 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
596 GstStructure *structure;
599 g_return_if_fail (GST_IS_CAPS (caps1));
600 g_return_if_fail (GST_IS_CAPS (caps2));
601 g_return_if_fail (IS_WRITABLE (caps1));
602 g_return_if_fail (IS_WRITABLE (caps2));
604 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
605 for (i = caps2->structs->len - 1; i >= 0; i--) {
606 structure = gst_caps_remove_and_get_structure (caps2, i);
607 gst_structure_free (structure);
609 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
610 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
611 for (i = caps1->structs->len - 1; i >= 0; i--) {
612 structure = gst_caps_remove_and_get_structure (caps1, i);
613 gst_structure_free (structure);
616 for (i = caps2->structs->len; i; i--) {
617 structure = gst_caps_remove_and_get_structure (caps2, 0);
618 gst_caps_merge_structure (caps1, structure);
621 GstCaps *com = gst_caps_intersect (caps1, caps2);
622 GstCaps *add = gst_caps_subtract (caps2, com);
624 GST_DEBUG ("common : %d", gst_caps_get_size (com));
625 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
626 gst_caps_append (caps1, add);
627 gst_caps_unref (com);
630 gst_caps_unref (caps2); /* guaranteed to free it */
634 * gst_caps_append_structure:
635 * @caps: the #GstCaps that will be appended to
636 * @structure: (transfer full): the #GstStructure to append
638 * Appends @structure to @caps. The structure is not copied; @caps
639 * becomes the owner of @structure.
642 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
644 g_return_if_fail (GST_IS_CAPS (caps));
645 g_return_if_fail (IS_WRITABLE (caps));
647 if (G_LIKELY (structure)) {
648 g_return_if_fail (structure->parent_refcount == NULL);
649 gst_caps_append_structure_unchecked (caps, structure);
654 * gst_caps_remove_structure:
655 * @caps: the #GstCaps to remove from
656 * @idx: Index of the structure to remove
658 * removes the stucture with the given index from the list of structures
659 * contained in @caps.
662 gst_caps_remove_structure (GstCaps * caps, guint idx)
664 GstStructure *structure;
666 g_return_if_fail (caps != NULL);
667 g_return_if_fail (idx <= gst_caps_get_size (caps));
668 g_return_if_fail (IS_WRITABLE (caps));
670 structure = gst_caps_remove_and_get_structure (caps, idx);
671 gst_structure_free (structure);
675 * gst_caps_merge_structure:
676 * @caps: the #GstCaps that will the the new structure
677 * @structure: (transfer full): the #GstStructure to merge
679 * Appends @structure to @caps if its not already expressed by @caps. The
680 * structure is not copied; @caps becomes the owner of @structure.
683 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
685 g_return_if_fail (GST_IS_CAPS (caps));
686 g_return_if_fail (IS_WRITABLE (caps));
688 if (G_LIKELY (structure)) {
689 GstStructure *structure1;
691 gboolean unique = TRUE;
693 g_return_if_fail (structure->parent_refcount == NULL);
694 /* check each structure */
695 for (i = caps->structs->len - 1; i >= 0; i--) {
696 structure1 = gst_caps_get_structure_unchecked (caps, i);
697 /* if structure is a subset of structure1, then skip it */
698 if (gst_caps_structure_is_subset (structure1, structure)) {
704 gst_caps_append_structure_unchecked (caps, structure);
706 gst_structure_free (structure);
715 * Gets the number of structures contained in @caps.
717 * Returns: the number of structures that @caps contains
720 gst_caps_get_size (const GstCaps * caps)
722 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
724 return caps->structs->len;
728 * gst_caps_get_structure:
730 * @index: the index of the structure
732 * Finds the structure in @caps that has the index @index, and
735 * WARNING: This function takes a const GstCaps *, but returns a
736 * non-const GstStructure *. This is for programming convenience --
737 * the caller should be aware that structures inside a constant
738 * #GstCaps should not be modified. However, if you know the caps
739 * are writable, either because you have just copied them or made
740 * them writable with gst_caps_make_writable(), you may modify the
741 * structure returned in the usual way, e.g. with functions like
742 * gst_structure_set().
744 * You do not need to free or unref the structure returned, it
745 * belongs to the #GstCaps.
747 * Returns: (transfer none): a pointer to the #GstStructure corresponding
751 gst_caps_get_structure (const GstCaps * caps, guint index)
753 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
754 g_return_val_if_fail (index < caps->structs->len, NULL);
756 return gst_caps_get_structure_unchecked (caps, index);
761 * @caps: the #GstCaps to copy
762 * @nth: the nth structure to copy
764 * Creates a new #GstCaps and appends a copy of the nth structure
765 * contained in @caps.
767 * Returns: (transfer full): the new #GstCaps
770 gst_caps_copy_nth (const GstCaps * caps, guint nth)
773 GstStructure *structure;
775 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
777 newcaps = gst_caps_new_empty ();
778 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
780 if (G_LIKELY (caps->structs->len > nth)) {
781 structure = gst_caps_get_structure_unchecked (caps, nth);
782 gst_caps_append_structure_unchecked (newcaps,
783 gst_structure_copy (structure));
791 * @caps: the #GstCaps to truncate
793 * Destructively discard all but the first structure from @caps. Useful when
794 * fixating. @caps must be writable.
797 gst_caps_truncate (GstCaps * caps)
801 g_return_if_fail (GST_IS_CAPS (caps));
802 g_return_if_fail (IS_WRITABLE (caps));
804 i = caps->structs->len - 1;
807 gst_caps_remove_structure (caps, i--);
811 * gst_caps_set_value:
812 * @caps: a writable caps
813 * @field: name of the field to set
814 * @value: value to set the field to
816 * Sets the given @field on all structures of @caps to the given @value.
817 * This is a convenience function for calling gst_structure_set_value() on
818 * all structures of @caps.
823 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
827 g_return_if_fail (GST_IS_CAPS (caps));
828 g_return_if_fail (IS_WRITABLE (caps));
829 g_return_if_fail (field != NULL);
830 g_return_if_fail (G_IS_VALUE (value));
832 len = caps->structs->len;
833 for (i = 0; i < len; i++) {
834 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
835 gst_structure_set_value (structure, field, value);
840 * gst_caps_set_simple_valist:
841 * @caps: the #GstCaps to set
842 * @field: first field to set
843 * @varargs: additional parameters
845 * Sets fields in a #GstCaps. The arguments must be passed in the same
846 * manner as gst_structure_set(), and be NULL-terminated.
847 * <note>Prior to GStreamer version 0.10.26, this function failed when
848 * @caps was not simple. If your code needs to work with those versions
849 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
850 * is %TRUE for @caps.</note>
853 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
855 GValue value = { 0, };
857 g_return_if_fail (GST_IS_CAPS (caps));
858 g_return_if_fail (IS_WRITABLE (caps));
864 type = va_arg (varargs, GType);
866 if (G_UNLIKELY (type == G_TYPE_DATE)) {
867 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
868 type = GST_TYPE_DATE;
870 #if GLIB_CHECK_VERSION(2,23,3)
871 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
873 g_value_init (&value, type);
874 G_VALUE_COLLECT (&value, varargs, 0, &err);
876 if (G_UNLIKELY (err)) {
877 g_critical ("%s", err);
881 gst_caps_set_value (caps, field, &value);
883 g_value_unset (&value);
885 field = va_arg (varargs, const gchar *);
890 * gst_caps_set_simple:
891 * @caps: the #GstCaps to set
892 * @field: first field to set
893 * @...: additional parameters
895 * Sets fields in a #GstCaps. The arguments must be passed in the same
896 * manner as gst_structure_set(), and be NULL-terminated.
897 * <note>Prior to GStreamer version 0.10.26, this function failed when
898 * @caps was not simple. If your code needs to work with those versions
899 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
900 * is %TRUE for @caps.</note>
903 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
907 g_return_if_fail (GST_IS_CAPS (caps));
908 g_return_if_fail (IS_WRITABLE (caps));
910 va_start (var_args, field);
911 gst_caps_set_simple_valist (caps, field, var_args);
919 * @caps: the #GstCaps to test
921 * Determines if @caps represents any media format.
923 * Returns: TRUE if @caps represents any format.
926 gst_caps_is_any (const GstCaps * caps)
928 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
930 return (CAPS_IS_ANY (caps));
935 * @caps: the #GstCaps to test
937 * Determines if @caps represents no media formats.
939 * Returns: TRUE if @caps represents no formats.
942 gst_caps_is_empty (const GstCaps * caps)
944 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
946 if (CAPS_IS_ANY (caps))
949 return CAPS_IS_EMPTY_SIMPLE (caps);
953 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
956 return gst_value_is_fixed (value);
961 * @caps: the #GstCaps to test
963 * Fixed #GstCaps describe exactly one format, that is, they have exactly
964 * one structure, and each field in the structure describes a fixed type.
965 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
967 * Returns: TRUE if @caps is fixed
970 gst_caps_is_fixed (const GstCaps * caps)
972 GstStructure *structure;
974 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
976 if (caps->structs->len != 1)
979 structure = gst_caps_get_structure_unchecked (caps, 0);
981 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
985 * gst_caps_is_equal_fixed:
986 * @caps1: the #GstCaps to test
987 * @caps2: the #GstCaps to test
989 * Tests if two #GstCaps are equal. This function only works on fixed
992 * Returns: TRUE if the arguments represent the same format
995 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
997 GstStructure *struct1, *struct2;
999 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
1000 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
1002 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
1003 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
1005 if (struct1->name != struct2->name) {
1008 if (struct1->fields->len != struct2->fields->len) {
1012 return gst_structure_foreach (struct1, gst_structure_is_equal_foreach,
1017 * gst_caps_is_always_compatible:
1018 * @caps1: the #GstCaps to test
1019 * @caps2: the #GstCaps to test
1021 * A given #GstCaps structure is always compatible with another if
1022 * every media format that is in the first is also contained in the
1023 * second. That is, @caps1 is a subset of @caps2.
1025 * Returns: TRUE if @caps1 is a subset of @caps2.
1028 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1030 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1031 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1033 return gst_caps_is_subset (caps1, caps2);
1037 * gst_caps_is_subset:
1038 * @subset: a #GstCaps
1039 * @superset: a potentially greater #GstCaps
1041 * Checks if all caps represented by @subset are also represented by @superset.
1042 * <note>This function does not work reliably if optional properties for caps
1043 * are included on one caps and omitted on the other.</note>
1045 * Returns: %TRUE if @subset is a subset of @superset
1048 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1053 g_return_val_if_fail (subset != NULL, FALSE);
1054 g_return_val_if_fail (superset != NULL, FALSE);
1056 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1058 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1061 caps = gst_caps_subtract (subset, superset);
1062 ret = CAPS_IS_EMPTY_SIMPLE (caps);
1063 gst_caps_unref (caps);
1068 * gst_caps_is_equal:
1069 * @caps1: a #GstCaps
1070 * @caps2: another #GstCaps
1072 * Checks if the given caps represent the same set of caps.
1073 * <note>This function does not work reliably if optional properties for caps
1074 * are included on one caps and omitted on the other.</note>
1076 * This function deals correctly with passing NULL for any of the caps.
1078 * Returns: TRUE if both caps are equal.
1081 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1083 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1084 * So there should be an assertion that caps1 and caps2 != NULL */
1086 /* NULL <-> NULL is allowed here */
1087 if (G_UNLIKELY (caps1 == caps2))
1090 /* one of them NULL => they are different (can't be both NULL because
1091 * we checked that above) */
1092 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1095 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1096 return gst_caps_is_equal_fixed (caps1, caps2);
1098 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1101 /* intersect operation */
1106 const GstStructure *intersect;
1111 gst_caps_structure_intersect_field1 (GQuark id, const GValue * val1,
1114 IntersectData *idata = (IntersectData *) data;
1115 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1117 if (G_UNLIKELY (val2 == NULL)) {
1118 gst_structure_id_set_value (idata->dest, id, val1);
1120 GValue dest_value = { 0 };
1121 if (gst_value_intersect (&dest_value, val1, val2)) {
1122 gst_structure_id_set_value (idata->dest, id, &dest_value);
1123 g_value_unset (&dest_value);
1132 gst_caps_structure_intersect_field2 (GQuark id, const GValue * val1,
1135 IntersectData *idata = (IntersectData *) data;
1136 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1138 if (G_UNLIKELY (val2 == NULL)) {
1139 gst_structure_id_set_value (idata->dest, id, val1);
1144 static GstStructure *
1145 gst_caps_structure_intersect (const GstStructure * struct1,
1146 const GstStructure * struct2)
1150 g_assert (struct1 != NULL);
1151 g_assert (struct2 != NULL);
1153 if (G_UNLIKELY (struct1->name != struct2->name))
1156 /* copy fields from struct1 which we have not in struct2 to target
1157 * intersect if we have the field in both */
1158 data.dest = gst_structure_id_empty_new (struct1->name);
1159 data.intersect = struct2;
1160 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1161 gst_caps_structure_intersect_field1, &data)))
1164 /* copy fields from struct2 which we have not in struct1 to target */
1165 data.intersect = struct1;
1166 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
1167 gst_caps_structure_intersect_field2, &data)))
1173 gst_structure_free (data.dest);
1178 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
1181 GstStructure *other = (GstStructure *) data;
1182 const GValue *val2 = gst_structure_id_get_value (other, id);
1184 if (G_LIKELY (val2)) {
1185 if (!gst_value_can_intersect (val1, val2)) {
1188 gint eq = gst_value_compare (val1, val2);
1190 if (eq == GST_VALUE_UNORDERED) {
1191 /* we need to try interseting */
1192 GValue dest_value = { 0 };
1193 if (gst_value_intersect (&dest_value, val1, val2)) {
1194 g_value_unset (&dest_value);
1198 } else if (eq != GST_VALUE_EQUAL) {
1207 gst_caps_structure_can_intersect (const GstStructure * struct1,
1208 const GstStructure * struct2)
1210 g_assert (struct1 != NULL);
1211 g_assert (struct2 != NULL);
1213 if (G_UNLIKELY (struct1->name != struct2->name))
1216 /* tries to intersect if we have the field in both */
1217 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1218 gst_caps_structure_can_intersect_field, (gpointer) struct2)))
1225 * gst_caps_can_intersect:
1226 * @caps1: a #GstCaps to intersect
1227 * @caps2: a #GstCaps to intersect
1229 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1232 * Returns: %TRUE if intersection would be not empty
1237 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1239 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1240 guint j, k, len1, len2;
1241 GstStructure *struct1;
1242 GstStructure *struct2;
1244 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1245 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1247 /* caps are exactly the same pointers */
1248 if (G_UNLIKELY (caps1 == caps2))
1251 /* empty caps on either side, return empty */
1252 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1255 /* one of the caps is any */
1256 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1259 /* run zigzag on top line then right line, this preserves the caps order
1260 * much better than a simple loop.
1262 * This algorithm zigzags over the caps structures as demonstrated in
1263 * the folowing matrix:
1266 * +------------- total distance: +-------------
1267 * | 1 2 4 7 0 | 0 1 2 3
1268 * caps2 | 3 5 8 10 1 | 1 2 3 4
1269 * | 6 9 11 12 2 | 2 3 4 5
1271 * First we iterate over the caps1 structures (top line) intersecting
1272 * the structures diagonally down, then we iterate over the caps2
1273 * structures. The result is that the intersections are ordered based on the
1274 * sum of the indexes in the list.
1276 len1 = caps1->structs->len;
1277 len2 = caps2->structs->len;
1278 for (i = 0; i < len1 + len2 - 1; i++) {
1279 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1280 j = MIN (i, len1 - 1);
1281 /* subset index stays 0 until i reaches superset->structs->len, then it
1282 * counts up from 1 to subset->structs->len - 1 */
1285 /* now run the diagonal line, end condition is the left or bottom
1288 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1289 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1291 if (gst_caps_structure_can_intersect (struct1, struct2)) {
1294 /* move down left */
1296 if (G_UNLIKELY (j == 0))
1297 break; /* so we don't roll back to G_MAXUINT */
1305 * gst_caps_intersect:
1306 * @caps1: a #GstCaps to intersect
1307 * @caps2: a #GstCaps to intersect
1309 * Creates a new #GstCaps that contains all the formats that are common
1310 * to both @caps1 and @caps2.
1312 * Returns: the new #GstCaps
1315 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1317 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1318 guint j, k, len1, len2;
1320 GstStructure *struct1;
1321 GstStructure *struct2;
1323 GstStructure *istruct;
1325 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1326 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1328 /* caps are exactly the same pointers, just copy one caps */
1329 if (G_UNLIKELY (caps1 == caps2))
1330 return _gst_caps_copy (caps1);
1332 /* empty caps on either side, return empty */
1333 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1334 return gst_caps_new_empty ();
1336 /* one of the caps is any, just copy the other caps */
1337 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1338 return _gst_caps_copy (caps2);
1339 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1340 return _gst_caps_copy (caps1);
1342 dest = gst_caps_new_empty ();
1344 /* run zigzag on top line then right line, this preserves the caps order
1345 * much better than a simple loop.
1347 * This algorithm zigzags over the caps structures as demonstrated in
1348 * the folowing matrix:
1356 * First we iterate over the caps1 structures (top line) intersecting
1357 * the structures diagonally down, then we iterate over the caps2
1360 len1 = caps1->structs->len;
1361 len2 = caps2->structs->len;
1362 for (i = 0; i < len1 + len2 - 1; i++) {
1363 /* caps1 index goes from 0 to caps1->structs->len-1 */
1364 j = MIN (i, len1 - 1);
1365 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1366 * up from 1 to caps2->structs->len - 1 */
1369 /* now run the diagonal line, end condition is the left or bottom
1372 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1373 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1375 istruct = gst_caps_structure_intersect (struct1, struct2);
1377 gst_caps_append_structure (dest, istruct);
1378 /* move down left */
1380 if (G_UNLIKELY (j == 0))
1381 break; /* so we don't roll back to G_MAXUINT */
1388 /* subtract operation */
1392 const GstStructure *subtract_from;
1398 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1401 SubtractionEntry *e = user_data;
1402 GValue subtraction = { 0, };
1403 const GValue *other;
1404 GstStructure *structure;
1406 other = gst_structure_id_get_value (e->subtract_from, field_id);
1410 if (!gst_value_subtract (&subtraction, other, value))
1412 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1413 g_value_unset (&subtraction);
1416 structure = gst_structure_copy (e->subtract_from);
1417 gst_structure_id_set_value (structure, field_id, &subtraction);
1418 g_value_unset (&subtraction);
1419 e->put_into = g_slist_prepend (e->put_into, structure);
1425 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1426 const GstStructure * subtrahend)
1431 e.subtract_from = minuend;
1434 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1435 gst_caps_structure_subtract_field, &e);
1441 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1442 gst_structure_free (walk->data);
1444 g_slist_free (e.put_into);
1450 * gst_caps_subtract:
1451 * @minuend: #GstCaps to substract from
1452 * @subtrahend: #GstCaps to substract
1454 * Subtracts the @subtrahend from the @minuend.
1455 * <note>This function does not work reliably if optional properties for caps
1456 * are included on one caps and omitted on the other.</note>
1458 * Returns: the resulting caps
1461 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1466 GstCaps *dest = NULL, *src;
1468 g_return_val_if_fail (minuend != NULL, NULL);
1469 g_return_val_if_fail (subtrahend != NULL, NULL);
1471 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1472 return gst_caps_new_empty ();
1474 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1475 return _gst_caps_copy (minuend);
1477 /* FIXME: Do we want this here or above?
1478 The reason we need this is that there is no definition about what
1479 ANY means for specific types, so it's not possible to reduce ANY partially
1480 You can only remove everything or nothing and that is done above.
1481 Note: there's a test that checks this behaviour. */
1482 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1483 sublen = subtrahend->structs->len;
1484 g_assert (sublen > 0);
1486 src = _gst_caps_copy (minuend);
1487 for (i = 0; i < sublen; i++) {
1490 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1492 gst_caps_unref (src);
1495 dest = gst_caps_new_empty ();
1496 srclen = src->structs->len;
1497 for (j = 0; j < srclen; j++) {
1498 min = gst_caps_get_structure_unchecked (src, j);
1499 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1502 if (gst_caps_structure_subtract (&list, min, sub)) {
1505 for (walk = list; walk; walk = g_slist_next (walk)) {
1506 gst_caps_append_structure_unchecked (dest,
1507 (GstStructure *) walk->data);
1509 g_slist_free (list);
1511 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1514 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1517 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1518 gst_caps_unref (src);
1523 gst_caps_unref (src);
1524 gst_caps_do_simplify (dest);
1528 /* union operation */
1531 static GstStructure *
1532 gst_caps_structure_union (const GstStructure * struct1,
1533 const GstStructure * struct2)
1537 const GstStructureField *field1;
1538 const GstStructureField *field2;
1541 /* FIXME this doesn't actually work */
1543 if (struct1->name != struct2->name)
1546 dest = gst_structure_id_empty_new (struct1->name);
1548 for (i = 0; i < struct1->fields->len; i++) {
1549 GValue dest_value = { 0 };
1551 field1 = GST_STRUCTURE_FIELD (struct1, i);
1552 field2 = gst_structure_id_get_field (struct2, field1->name);
1554 if (field2 == NULL) {
1557 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1558 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1561 ret = gst_value_compare (&field1->value, &field2->value);
1572 * @caps1: a #GstCaps to union
1573 * @caps2: a #GstCaps to union
1575 * Creates a new #GstCaps that contains all the formats that are in
1576 * either @caps1 and @caps2.
1578 * Returns: the new #GstCaps
1581 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1586 /* NULL pointers are no correct GstCaps */
1587 g_return_val_if_fail (caps1 != NULL, NULL);
1588 g_return_val_if_fail (caps2 != NULL, NULL);
1590 if (CAPS_IS_EMPTY (caps1))
1591 return _gst_caps_copy (caps2);
1593 if (CAPS_IS_EMPTY (caps2))
1594 return _gst_caps_copy (caps1);
1596 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1597 return gst_caps_new_any ();
1599 dest1 = _gst_caps_copy (caps1);
1600 dest2 = _gst_caps_copy (caps2);
1601 gst_caps_append (dest1, dest2);
1603 gst_caps_do_simplify (dest1);
1607 /* normalize/simplify operations */
1609 typedef struct _NormalizeForeach
1612 GstStructure *structure;
1617 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1619 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1623 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1624 guint len = gst_value_list_get_size (value);
1625 for (i = 1; i < len; i++) {
1626 const GValue *v = gst_value_list_get_value (value, i);
1627 GstStructure *structure = gst_structure_copy (nf->structure);
1629 gst_structure_id_set_value (structure, field_id, v);
1630 gst_caps_append_structure_unchecked (nf->caps, structure);
1633 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1634 gst_structure_id_set_value (nf->structure, field_id, &val);
1635 g_value_unset (&val);
1643 * gst_caps_normalize:
1644 * @caps: a #GstCaps to normalize
1646 * Creates a new #GstCaps that represents the same set of formats as
1647 * @caps, but contains no lists. Each list is expanded into separate
1650 * Returns: the new #GstCaps
1653 gst_caps_normalize (const GstCaps * caps)
1655 NormalizeForeach nf;
1659 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1661 newcaps = _gst_caps_copy (caps);
1664 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1665 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1667 while (!gst_structure_foreach (nf.structure,
1668 gst_caps_normalize_foreach, &nf));
1675 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1678 const GstStructure *struct1 = *((const GstStructure **) one);
1679 const GstStructure *struct2 = *((const GstStructure **) two);
1681 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1682 So what's the best way? */
1683 ret = strcmp (gst_structure_get_name (struct1),
1684 gst_structure_get_name (struct2));
1688 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1695 GstStructure *compare;
1700 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1703 UnionField *u = user_data;
1704 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1708 g_value_unset (&u->value);
1711 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1714 g_value_unset (&u->value);
1718 gst_value_union (&u->value, val, value);
1723 gst_caps_structure_simplify (GstStructure ** result,
1724 const GstStructure * simplify, GstStructure * compare)
1727 UnionField field = { 0, {0,}, NULL };
1729 /* try to subtract to get a real subset */
1730 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1731 if (list == NULL) { /* no result */
1734 } else if (list->next == NULL) { /* one result */
1735 *result = list->data;
1736 g_slist_free (list);
1738 } else { /* multiple results */
1739 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1740 g_slist_free (list);
1745 /* try to union both structs */
1746 field.compare = compare;
1747 if (gst_structure_foreach ((GstStructure *) simplify,
1748 gst_caps_structure_figure_out_union, &field)) {
1749 gboolean ret = FALSE;
1751 /* now we know all of simplify's fields are the same in compare
1752 * but at most one field: field.name */
1753 if (G_IS_VALUE (&field.value)) {
1754 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1755 gst_structure_id_set_value (compare, field.name, &field.value);
1759 g_value_unset (&field.value);
1760 } else if (gst_structure_n_fields (simplify) <=
1761 gst_structure_n_fields (compare)) {
1762 /* compare is just more specific, will be optimized away later */
1763 /* FIXME: do this here? */
1764 GST_LOG ("found a case that will be optimized later.");
1766 gchar *one = gst_structure_to_string (simplify);
1767 gchar *two = gst_structure_to_string (compare);
1770 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1782 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1783 GstStructure * new, gint i)
1785 gst_structure_set_parent_refcount (old, NULL);
1786 gst_structure_free (old);
1787 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1788 g_ptr_array_index (caps->structs, i) = new;
1792 * gst_caps_do_simplify:
1793 * @caps: a #GstCaps to simplify
1795 * Modifies the given @caps inplace into a representation that represents the
1796 * same set of formats, but in a simpler form. Component structures that are
1797 * identical are merged. Component structures that have values that can be
1798 * merged are also merged.
1800 * Returns: TRUE, if the caps could be simplified
1803 gst_caps_do_simplify (GstCaps * caps)
1805 GstStructure *simplify, *compare, *result = NULL;
1807 gboolean changed = FALSE;
1809 g_return_val_if_fail (caps != NULL, FALSE);
1810 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1812 if (gst_caps_get_size (caps) < 2)
1815 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1817 start = caps->structs->len - 1;
1818 for (i = caps->structs->len - 1; i >= 0; i--) {
1819 simplify = gst_caps_get_structure_unchecked (caps, i);
1820 if (gst_structure_get_name_id (simplify) !=
1821 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1824 for (j = start; j >= 0; j--) {
1827 compare = gst_caps_get_structure_unchecked (caps, j);
1828 if (gst_structure_get_name_id (simplify) !=
1829 gst_structure_get_name_id (compare)) {
1832 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1834 gst_caps_switch_structures (caps, simplify, result, i);
1837 gst_caps_remove_structure (caps, i);
1849 /* gst_caps_do_simplify (caps); */
1857 * @caps: (inout) (transfer full): a pointer to #GstCaps
1858 * @newcaps: a #GstCaps to replace *caps
1860 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1861 * pointed to by @caps, if applicable, then modifies @caps to point to
1862 * @newcaps. An additional ref on @newcaps is taken.
1864 * This function does not take any locks so you might want to lock
1865 * the object owning @caps pointer.
1868 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1872 g_return_if_fail (caps != NULL);
1876 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1878 if (newcaps != oldcaps) {
1880 gst_caps_ref (newcaps);
1885 gst_caps_unref (oldcaps);
1890 * gst_caps_to_string:
1893 * Converts @caps to a string representation. This string representation
1894 * can be converted back to a #GstCaps by gst_caps_from_string().
1896 * For debugging purposes its easier to do something like this:
1898 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1900 * This prints the caps in human readble form.
1902 * Returns: (transfer full): a newly allocated string representing @caps.
1905 gst_caps_to_string (const GstCaps * caps)
1907 guint i, slen, clen;
1910 /* NOTE: This function is potentially called by the debug system,
1911 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1912 * should be careful to avoid recursion. This includes any functions
1913 * called by gst_caps_to_string. In particular, calls should
1914 * not use the GST_PTR_FORMAT extension. */
1917 return g_strdup ("NULL");
1919 if (CAPS_IS_ANY (caps)) {
1920 return g_strdup ("ANY");
1922 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1923 return g_strdup ("EMPTY");
1926 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1928 clen = caps->structs->len;
1929 for (i = 0; i < clen; i++) {
1931 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1935 s = g_string_sized_new (slen);
1936 for (i = 0; i < clen; i++) {
1937 GstStructure *structure;
1940 /* ';' is now added by gst_structure_to_string */
1941 g_string_append_c (s, ' ');
1944 structure = gst_caps_get_structure_unchecked (caps, i);
1945 priv_gst_structure_append_to_gstring (structure, s);
1947 if (s->len && s->str[s->len - 1] == ';') {
1948 /* remove latest ';' */
1949 s->str[--s->len] = '\0';
1951 return g_string_free (s, FALSE);
1955 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1957 GstStructure *structure;
1960 if (strcmp ("ANY", string) == 0) {
1961 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
1964 if (strcmp ("EMPTY", string) == 0) {
1968 structure = gst_structure_from_string (string, &s);
1969 if (structure == NULL) {
1972 gst_caps_append_structure_unchecked (caps, structure);
1976 while (g_ascii_isspace (*s))
1981 structure = gst_structure_from_string (s, &s);
1982 if (structure == NULL) {
1985 gst_caps_append_structure_unchecked (caps, structure);
1993 * gst_caps_from_string:
1994 * @string: a string to convert to #GstCaps
1996 * Converts @caps from a string representation.
1998 * Returns: (transfer full): a newly allocated #GstCaps
2001 gst_caps_from_string (const gchar * string)
2005 g_return_val_if_fail (string, FALSE);
2007 caps = gst_caps_new_empty ();
2008 if (gst_caps_from_string_inplace (caps, string)) {
2011 gst_caps_unref (caps);
2017 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2019 g_return_if_fail (G_IS_VALUE (src_value));
2020 g_return_if_fail (G_IS_VALUE (dest_value));
2021 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2022 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2023 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2025 dest_value->data[0].v_pointer =
2026 gst_caps_to_string (src_value->data[0].v_pointer);