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_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1307 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1308 guint j, k, len1, len2;
1310 GstStructure *struct1;
1311 GstStructure *struct2;
1313 GstStructure *istruct;
1315 /* caps are exactly the same pointers, just copy one caps */
1316 if (G_UNLIKELY (caps1 == caps2))
1317 return _gst_caps_copy (caps1);
1319 /* empty caps on either side, return empty */
1320 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1321 return gst_caps_new_empty ();
1323 /* one of the caps is any, just copy the other caps */
1324 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1325 return _gst_caps_copy (caps2);
1326 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1327 return _gst_caps_copy (caps1);
1329 dest = gst_caps_new_empty ();
1331 /* run zigzag on top line then right line, this preserves the caps order
1332 * much better than a simple loop.
1334 * This algorithm zigzags over the caps structures as demonstrated in
1335 * the folowing matrix:
1343 * First we iterate over the caps1 structures (top line) intersecting
1344 * the structures diagonally down, then we iterate over the caps2
1347 len1 = caps1->structs->len;
1348 len2 = caps2->structs->len;
1349 for (i = 0; i < len1 + len2 - 1; i++) {
1350 /* caps1 index goes from 0 to caps1->structs->len-1 */
1351 j = MIN (i, len1 - 1);
1352 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1353 * up from 1 to caps2->structs->len - 1 */
1356 /* now run the diagonal line, end condition is the left or bottom
1359 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1360 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1362 istruct = gst_caps_structure_intersect (struct1, struct2);
1364 gst_caps_append_structure (dest, istruct);
1365 /* move down left */
1367 if (G_UNLIKELY (j == 0))
1368 break; /* so we don't roll back to G_MAXUINT */
1376 * gst_caps_intersect_first:
1377 * @caps1: a #GstCaps to intersect
1378 * @caps2: a #GstCaps to intersect
1380 * Creates a new #GstCaps that contains all the formats that are common
1381 * to both @caps1 and @caps2.
1383 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1384 * fashion as @caps1.
1386 * Returns: the new #GstCaps
1389 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1391 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1392 guint j, len1, len2;
1394 GstStructure *struct1;
1395 GstStructure *struct2;
1397 GstStructure *istruct;
1399 /* caps are exactly the same pointers, just copy one caps */
1400 if (G_UNLIKELY (caps1 == caps2))
1401 return gst_caps_copy (caps1);
1403 /* empty caps on either side, return empty */
1404 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1405 return gst_caps_new_empty ();
1407 /* one of the caps is any, just copy the other caps */
1408 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1409 return gst_caps_copy (caps2);
1410 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1411 return gst_caps_copy (caps1);
1413 dest = gst_caps_new_empty ();
1415 len1 = caps1->structs->len;
1416 len2 = caps2->structs->len;
1417 for (i = 0; i < len1; i++) {
1418 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1419 for (j = 0; j < len2; j++) {
1420 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1421 istruct = gst_caps_structure_intersect (struct1, struct2);
1423 gst_caps_append_structure (dest, istruct);
1431 * gst_caps_intersect_full:
1432 * @caps1: a #GstCaps to intersect
1433 * @caps2: a #GstCaps to intersect
1434 * @mode: The intersection algorithm/mode to use
1436 * Creates a new #GstCaps that contains all the formats that are common
1437 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1440 * Returns: the new #GstCaps
1444 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1445 GstCapsIntersectMode mode)
1447 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1448 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1451 case GST_CAPS_INTERSECT_FIRST:
1452 return gst_caps_intersect_first (caps1, caps2);
1454 g_warning ("Unknown caps intersect mode: %d", mode);
1456 case GST_CAPS_INTERSECT_ZIG_ZAG:
1457 return gst_caps_intersect_zig_zag (caps1, caps2);
1462 * gst_caps_intersect:
1463 * @caps1: a #GstCaps to intersect
1464 * @caps2: a #GstCaps to intersect
1466 * Creates a new #GstCaps that contains all the formats that are common
1467 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1469 * Returns: the new #GstCaps
1472 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1474 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1478 /* subtract operation */
1482 const GstStructure *subtract_from;
1488 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1491 SubtractionEntry *e = user_data;
1492 GValue subtraction = { 0, };
1493 const GValue *other;
1494 GstStructure *structure;
1496 other = gst_structure_id_get_value (e->subtract_from, field_id);
1500 if (!gst_value_subtract (&subtraction, other, value))
1502 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1503 g_value_unset (&subtraction);
1506 structure = gst_structure_copy (e->subtract_from);
1507 gst_structure_id_set_value (structure, field_id, &subtraction);
1508 g_value_unset (&subtraction);
1509 e->put_into = g_slist_prepend (e->put_into, structure);
1515 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1516 const GstStructure * subtrahend)
1521 e.subtract_from = minuend;
1524 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1525 gst_caps_structure_subtract_field, &e);
1531 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1532 gst_structure_free (walk->data);
1534 g_slist_free (e.put_into);
1540 * gst_caps_subtract:
1541 * @minuend: #GstCaps to substract from
1542 * @subtrahend: #GstCaps to substract
1544 * Subtracts the @subtrahend from the @minuend.
1545 * <note>This function does not work reliably if optional properties for caps
1546 * are included on one caps and omitted on the other.</note>
1548 * Returns: the resulting caps
1551 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1556 GstCaps *dest = NULL, *src;
1558 g_return_val_if_fail (minuend != NULL, NULL);
1559 g_return_val_if_fail (subtrahend != NULL, NULL);
1561 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1562 return gst_caps_new_empty ();
1564 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1565 return _gst_caps_copy (minuend);
1567 /* FIXME: Do we want this here or above?
1568 The reason we need this is that there is no definition about what
1569 ANY means for specific types, so it's not possible to reduce ANY partially
1570 You can only remove everything or nothing and that is done above.
1571 Note: there's a test that checks this behaviour. */
1572 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1573 sublen = subtrahend->structs->len;
1574 g_assert (sublen > 0);
1576 src = _gst_caps_copy (minuend);
1577 for (i = 0; i < sublen; i++) {
1580 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1582 gst_caps_unref (src);
1585 dest = gst_caps_new_empty ();
1586 srclen = src->structs->len;
1587 for (j = 0; j < srclen; j++) {
1588 min = gst_caps_get_structure_unchecked (src, j);
1589 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1592 if (gst_caps_structure_subtract (&list, min, sub)) {
1595 for (walk = list; walk; walk = g_slist_next (walk)) {
1596 gst_caps_append_structure_unchecked (dest,
1597 (GstStructure *) walk->data);
1599 g_slist_free (list);
1601 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1604 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1607 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1608 gst_caps_unref (src);
1613 gst_caps_unref (src);
1614 gst_caps_do_simplify (dest);
1618 /* union operation */
1621 static GstStructure *
1622 gst_caps_structure_union (const GstStructure * struct1,
1623 const GstStructure * struct2)
1627 const GstStructureField *field1;
1628 const GstStructureField *field2;
1631 /* FIXME this doesn't actually work */
1633 if (struct1->name != struct2->name)
1636 dest = gst_structure_id_empty_new (struct1->name);
1638 for (i = 0; i < struct1->fields->len; i++) {
1639 GValue dest_value = { 0 };
1641 field1 = GST_STRUCTURE_FIELD (struct1, i);
1642 field2 = gst_structure_id_get_field (struct2, field1->name);
1644 if (field2 == NULL) {
1647 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1648 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1651 ret = gst_value_compare (&field1->value, &field2->value);
1662 * @caps1: a #GstCaps to union
1663 * @caps2: a #GstCaps to union
1665 * Creates a new #GstCaps that contains all the formats that are in
1666 * either @caps1 and @caps2.
1668 * Returns: the new #GstCaps
1671 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1676 /* NULL pointers are no correct GstCaps */
1677 g_return_val_if_fail (caps1 != NULL, NULL);
1678 g_return_val_if_fail (caps2 != NULL, NULL);
1680 if (CAPS_IS_EMPTY (caps1))
1681 return _gst_caps_copy (caps2);
1683 if (CAPS_IS_EMPTY (caps2))
1684 return _gst_caps_copy (caps1);
1686 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1687 return gst_caps_new_any ();
1689 dest1 = _gst_caps_copy (caps1);
1690 dest2 = _gst_caps_copy (caps2);
1691 gst_caps_append (dest1, dest2);
1693 gst_caps_do_simplify (dest1);
1697 /* normalize/simplify operations */
1699 typedef struct _NormalizeForeach
1702 GstStructure *structure;
1707 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1709 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1713 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1714 guint len = gst_value_list_get_size (value);
1715 for (i = 1; i < len; i++) {
1716 const GValue *v = gst_value_list_get_value (value, i);
1717 GstStructure *structure = gst_structure_copy (nf->structure);
1719 gst_structure_id_set_value (structure, field_id, v);
1720 gst_caps_append_structure_unchecked (nf->caps, structure);
1723 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1724 gst_structure_id_set_value (nf->structure, field_id, &val);
1725 g_value_unset (&val);
1733 * gst_caps_normalize:
1734 * @caps: a #GstCaps to normalize
1736 * Creates a new #GstCaps that represents the same set of formats as
1737 * @caps, but contains no lists. Each list is expanded into separate
1740 * Returns: the new #GstCaps
1743 gst_caps_normalize (const GstCaps * caps)
1745 NormalizeForeach nf;
1749 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1751 newcaps = _gst_caps_copy (caps);
1754 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1755 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1757 while (!gst_structure_foreach (nf.structure,
1758 gst_caps_normalize_foreach, &nf));
1765 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1768 const GstStructure *struct1 = *((const GstStructure **) one);
1769 const GstStructure *struct2 = *((const GstStructure **) two);
1771 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1772 So what's the best way? */
1773 ret = strcmp (gst_structure_get_name (struct1),
1774 gst_structure_get_name (struct2));
1778 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1785 GstStructure *compare;
1790 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1793 UnionField *u = user_data;
1794 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1798 g_value_unset (&u->value);
1801 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1804 g_value_unset (&u->value);
1808 gst_value_union (&u->value, val, value);
1813 gst_caps_structure_simplify (GstStructure ** result,
1814 const GstStructure * simplify, GstStructure * compare)
1817 UnionField field = { 0, {0,}, NULL };
1819 /* try to subtract to get a real subset */
1820 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1821 if (list == NULL) { /* no result */
1824 } else if (list->next == NULL) { /* one result */
1825 *result = list->data;
1826 g_slist_free (list);
1828 } else { /* multiple results */
1829 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1830 g_slist_free (list);
1835 /* try to union both structs */
1836 field.compare = compare;
1837 if (gst_structure_foreach ((GstStructure *) simplify,
1838 gst_caps_structure_figure_out_union, &field)) {
1839 gboolean ret = FALSE;
1841 /* now we know all of simplify's fields are the same in compare
1842 * but at most one field: field.name */
1843 if (G_IS_VALUE (&field.value)) {
1844 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1845 gst_structure_id_set_value (compare, field.name, &field.value);
1849 g_value_unset (&field.value);
1850 } else if (gst_structure_n_fields (simplify) <=
1851 gst_structure_n_fields (compare)) {
1852 /* compare is just more specific, will be optimized away later */
1853 /* FIXME: do this here? */
1854 GST_LOG ("found a case that will be optimized later.");
1856 gchar *one = gst_structure_to_string (simplify);
1857 gchar *two = gst_structure_to_string (compare);
1860 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1872 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1873 GstStructure * new, gint i)
1875 gst_structure_set_parent_refcount (old, NULL);
1876 gst_structure_free (old);
1877 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1878 g_ptr_array_index (caps->structs, i) = new;
1882 * gst_caps_do_simplify:
1883 * @caps: a #GstCaps to simplify
1885 * Modifies the given @caps inplace into a representation that represents the
1886 * same set of formats, but in a simpler form. Component structures that are
1887 * identical are merged. Component structures that have values that can be
1888 * merged are also merged.
1890 * Returns: TRUE, if the caps could be simplified
1893 gst_caps_do_simplify (GstCaps * caps)
1895 GstStructure *simplify, *compare, *result = NULL;
1897 gboolean changed = FALSE;
1899 g_return_val_if_fail (caps != NULL, FALSE);
1900 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1902 if (gst_caps_get_size (caps) < 2)
1905 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1907 start = caps->structs->len - 1;
1908 for (i = caps->structs->len - 1; i >= 0; i--) {
1909 simplify = gst_caps_get_structure_unchecked (caps, i);
1910 if (gst_structure_get_name_id (simplify) !=
1911 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1914 for (j = start; j >= 0; j--) {
1917 compare = gst_caps_get_structure_unchecked (caps, j);
1918 if (gst_structure_get_name_id (simplify) !=
1919 gst_structure_get_name_id (compare)) {
1922 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1924 gst_caps_switch_structures (caps, simplify, result, i);
1927 gst_caps_remove_structure (caps, i);
1939 /* gst_caps_do_simplify (caps); */
1947 * @caps: (inout) (transfer full): a pointer to #GstCaps
1948 * @newcaps: a #GstCaps to replace *caps
1950 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1951 * pointed to by @caps, if applicable, then modifies @caps to point to
1952 * @newcaps. An additional ref on @newcaps is taken.
1954 * This function does not take any locks so you might want to lock
1955 * the object owning @caps pointer.
1958 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1962 g_return_if_fail (caps != NULL);
1966 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1968 if (newcaps != oldcaps) {
1970 gst_caps_ref (newcaps);
1975 gst_caps_unref (oldcaps);
1980 * gst_caps_to_string:
1983 * Converts @caps to a string representation. This string representation
1984 * can be converted back to a #GstCaps by gst_caps_from_string().
1986 * For debugging purposes its easier to do something like this:
1988 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1990 * This prints the caps in human readble form.
1992 * Returns: (transfer full): a newly allocated string representing @caps.
1995 gst_caps_to_string (const GstCaps * caps)
1997 guint i, slen, clen;
2000 /* NOTE: This function is potentially called by the debug system,
2001 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
2002 * should be careful to avoid recursion. This includes any functions
2003 * called by gst_caps_to_string. In particular, calls should
2004 * not use the GST_PTR_FORMAT extension. */
2007 return g_strdup ("NULL");
2009 if (CAPS_IS_ANY (caps)) {
2010 return g_strdup ("ANY");
2012 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
2013 return g_strdup ("EMPTY");
2016 /* estimate a rough string length to avoid unnecessary reallocs in GString */
2018 clen = caps->structs->len;
2019 for (i = 0; i < clen; i++) {
2021 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
2025 s = g_string_sized_new (slen);
2026 for (i = 0; i < clen; i++) {
2027 GstStructure *structure;
2030 /* ';' is now added by gst_structure_to_string */
2031 g_string_append_c (s, ' ');
2034 structure = gst_caps_get_structure_unchecked (caps, i);
2035 priv_gst_structure_append_to_gstring (structure, s);
2037 if (s->len && s->str[s->len - 1] == ';') {
2038 /* remove latest ';' */
2039 s->str[--s->len] = '\0';
2041 return g_string_free (s, FALSE);
2045 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2047 GstStructure *structure;
2050 if (strcmp ("ANY", string) == 0) {
2051 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
2054 if (strcmp ("EMPTY", string) == 0) {
2058 structure = gst_structure_from_string (string, &s);
2059 if (structure == NULL) {
2062 gst_caps_append_structure_unchecked (caps, structure);
2066 while (g_ascii_isspace (*s))
2071 structure = gst_structure_from_string (s, &s);
2072 if (structure == NULL) {
2075 gst_caps_append_structure_unchecked (caps, structure);
2083 * gst_caps_from_string:
2084 * @string: a string to convert to #GstCaps
2086 * Converts @caps from a string representation.
2088 * Returns: (transfer full): a newly allocated #GstCaps
2091 gst_caps_from_string (const gchar * string)
2095 g_return_val_if_fail (string, FALSE);
2097 caps = gst_caps_new_empty ();
2098 if (gst_caps_from_string_inplace (caps, string)) {
2101 gst_caps_unref (caps);
2107 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2109 g_return_if_fail (G_IS_VALUE (src_value));
2110 g_return_if_fail (G_IS_VALUE (dest_value));
2111 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2112 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2113 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2115 dest_value->data[0].v_pointer =
2116 gst_caps_to_string (src_value->data[0].v_pointer);