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 _gst_caps_type = gst_mini_object_register ("GstCaps");
118 g_value_register_transform_func (_gst_caps_type,
119 G_TYPE_STRING, gst_caps_transform_to_string);
123 _gst_caps_copy (const GstCaps * caps)
126 GstStructure *structure;
129 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
131 newcaps = gst_caps_new_empty ();
132 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
133 n = caps->structs->len;
135 for (i = 0; i < n; i++) {
136 structure = gst_caps_get_structure_unchecked (caps, i);
137 gst_caps_append_structure (newcaps, gst_structure_copy (structure));
143 /* creation/deletion */
145 _gst_caps_free (GstCaps * caps)
147 GstStructure *structure;
150 /* The refcount must be 0, but since we're only called by gst_caps_unref,
151 * don't bother testing. */
152 len = caps->structs->len;
153 /* This can be used to get statistics about caps sizes */
154 /*GST_CAT_INFO (GST_CAT_CAPS, "caps size: %d", len); */
155 for (i = 0; i < len; i++) {
156 structure = (GstStructure *) gst_caps_get_structure_unchecked (caps, i);
157 gst_structure_set_parent_refcount (structure, NULL);
158 gst_structure_free (structure);
160 g_ptr_array_free (caps->structs, TRUE);
162 #ifdef DEBUG_REFCOUNT
163 GST_CAT_LOG (GST_CAT_CAPS, "freeing caps %p", caps);
165 g_slice_free1 (GST_MINI_OBJECT_SIZE (caps), caps);
169 gst_caps_init (GstCaps * caps, gsize size)
171 gst_mini_object_init (GST_MINI_OBJECT_CAST (caps), _gst_caps_type, size);
173 caps->mini_object.copy = (GstMiniObjectCopyFunction) _gst_caps_copy;
174 caps->mini_object.dispose = NULL;
175 caps->mini_object.free = (GstMiniObjectFreeFunction) _gst_caps_free;
177 /* the 32 has been determined by logging caps sizes in _gst_caps_free
178 * but g_ptr_array uses 16 anyway if it expands once, so this does not help
180 * caps->structs = g_ptr_array_sized_new (32);
182 caps->structs = g_ptr_array_new ();
186 * gst_caps_new_empty:
188 * Creates a new #GstCaps that is empty. That is, the returned
189 * #GstCaps contains no media formats.
190 * Caller is responsible for unreffing the returned caps.
192 * Returns: (transfer full): the new #GstCaps
195 gst_caps_new_empty (void)
199 caps = g_slice_new (GstCaps);
201 gst_caps_init (caps, sizeof (GstCaps));
203 #ifdef DEBUG_REFCOUNT
204 GST_CAT_LOG (GST_CAT_CAPS, "created caps %p", caps);
213 * Creates a new #GstCaps that indicates that it is compatible with
216 * Returns: (transfer full): the new #GstCaps
219 gst_caps_new_any (void)
221 GstCaps *caps = gst_caps_new_empty ();
223 GST_CAPS_FLAG_SET (caps, GST_CAPS_FLAGS_ANY);
229 * gst_caps_new_simple:
230 * @media_type: the media type of the structure
231 * @fieldname: first field to set
232 * @...: additional arguments
234 * Creates a new #GstCaps that contains one #GstStructure. The
235 * structure is defined by the arguments, which have the same format
236 * as gst_structure_new().
237 * Caller is responsible for unreffing the returned caps.
239 * Returns: (transfer full): the new #GstCaps
242 gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
245 GstStructure *structure;
248 caps = gst_caps_new_empty ();
250 va_start (var_args, fieldname);
251 structure = gst_structure_new_valist (media_type, fieldname, var_args);
255 gst_caps_append_structure_unchecked (caps, structure);
257 gst_caps_replace (&caps, NULL);
264 * @struct1: the first structure to add
265 * @...: additional structures to add
267 * Creates a new #GstCaps and adds all the structures listed as
268 * arguments. The list must be NULL-terminated. The structures
269 * are not copied; the returned #GstCaps owns the structures.
271 * Returns: (transfer full): the new #GstCaps
274 gst_caps_new_full (GstStructure * struct1, ...)
279 va_start (var_args, struct1);
280 caps = gst_caps_new_full_valist (struct1, var_args);
287 * gst_caps_new_full_valist:
288 * @structure: the first structure to add
289 * @var_args: additional structures to add
291 * Creates a new #GstCaps and adds all the structures listed as
292 * arguments. The list must be NULL-terminated. The structures
293 * are not copied; the returned #GstCaps owns the structures.
295 * Returns: (transfer full): the new #GstCaps
298 gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
302 caps = gst_caps_new_empty ();
305 gst_caps_append_structure_unchecked (caps, structure);
306 structure = va_arg (var_args, GstStructure *);
313 * gst_caps_make_writable:
314 * @caps: (transfer full): the #GstCaps to make writable
316 * Returns a writable copy of @caps.
318 * If there is only one reference count on @caps, the caller must be the owner,
319 * and so this function will return the caps object unchanged. If on the other
320 * hand there is more than one reference on the object, a new caps object will
321 * be returned. The caller's reference on @caps will be removed, and instead the
322 * caller will own a reference to the returned object.
324 * In short, this function unrefs the caps in the argument and refs the caps
325 * that it returns. Don't access the argument after calling this function. See
326 * also: gst_caps_ref().
328 * Returns: (transfer full): the same #GstCaps object.
331 gst_caps_make_writable (GstCaps * caps)
335 g_return_val_if_fail (caps != NULL, NULL);
337 /* we are the only instance reffing this caps */
338 if (IS_WRITABLE (caps))
342 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy caps");
343 copy = _gst_caps_copy (caps);
344 gst_caps_unref (caps);
350 gst_static_caps_get_type (void)
352 static GType staticcaps_type = 0;
354 if (G_UNLIKELY (staticcaps_type == 0)) {
355 staticcaps_type = g_pointer_type_register_static ("GstStaticCaps");
357 return staticcaps_type;
362 * gst_static_caps_get:
363 * @static_caps: the #GstStaticCaps to convert
365 * Converts a #GstStaticCaps to a #GstCaps.
367 * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
368 * Since the core holds an additional ref to the returned caps,
369 * use gst_caps_make_writable() on the returned caps to modify it.
372 gst_static_caps_get (GstStaticCaps * static_caps)
376 g_return_val_if_fail (static_caps != NULL, NULL);
378 caps = (GstCaps *) static_caps;
380 /* refcount is 0 when we need to convert */
381 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) == 0)) {
385 G_LOCK (static_caps_lock);
386 /* check if other thread already updated */
387 if (G_UNLIKELY (GST_CAPS_REFCOUNT_VALUE (caps) > 0))
390 string = static_caps->string;
392 if (G_UNLIKELY (string == NULL))
395 GST_CAT_LOG (GST_CAT_CAPS, "creating %p", static_caps);
397 /* we construct the caps on the stack, then copy over the struct into our
398 * real caps, refcount last. We do this because we must leave the refcount
399 * of the result caps to 0 so that other threads don't run away with the
400 * caps while we are constructing it. */
401 gst_caps_init (&temp, sizeof (GstCaps));
403 /* convert to string */
404 if (G_UNLIKELY (!gst_caps_from_string_inplace (&temp, string)))
405 g_critical ("Could not convert static caps \"%s\"", string);
407 gst_caps_init (caps, sizeof (GstCaps));
408 /* now copy stuff over to the real caps. */
409 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS (&temp);
410 caps->structs = temp.structs;
412 GST_CAT_LOG (GST_CAT_CAPS, "created %p", static_caps);
414 G_UNLOCK (static_caps_lock);
416 /* ref the caps, makes it not writable */
424 G_UNLOCK (static_caps_lock);
425 g_warning ("static caps %p string is NULL", static_caps);
432 static GstStructure *
433 gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
435 /* don't use index_fast, gst_caps_do_simplify relies on the order */
436 GstStructure *s = g_ptr_array_remove_index (caps->structs, idx);
438 gst_structure_set_parent_refcount (s, NULL);
443 * gst_caps_steal_structure:
444 * @caps: the #GstCaps to retrieve from
445 * @index: Index of the structure to retrieve
447 * Retrieves the stucture with the given index from the list of structures
448 * contained in @caps. The caller becomes the owner of the returned structure.
450 * Returns: (transfer full): a pointer to the #GstStructure corresponding
456 gst_caps_steal_structure (GstCaps * caps, guint index)
458 g_return_val_if_fail (caps != NULL, NULL);
459 g_return_val_if_fail (IS_WRITABLE (caps), NULL);
461 if (G_UNLIKELY (index >= caps->structs->len))
464 return gst_caps_remove_and_get_structure (caps, index);
468 gst_caps_structure_is_subset_field (GQuark field_id, const GValue * value,
471 GstStructure *subtract_from = user_data;
472 GValue subtraction = { 0, };
475 if (!(other = gst_structure_id_get_value (subtract_from, field_id)))
476 /* field is missing in one set */
479 /* equal values are subset */
480 if (gst_value_compare (other, value) == GST_VALUE_EQUAL)
488 * -> 1 - [1,2] = empty
492 * -> [1,2] - [1,3] = empty
496 * -> {1,3} - {1,2} = 3
499 * First caps subtraction needs to return a non-empty set, second
500 * subtractions needs to give en empty set.
502 if (gst_value_subtract (&subtraction, other, value)) {
503 g_value_unset (&subtraction);
504 /* !empty result, swapping must be empty */
505 if (!gst_value_subtract (&subtraction, value, other))
508 g_value_unset (&subtraction);
514 gst_caps_structure_is_subset (const GstStructure * minuend,
515 const GstStructure * subtrahend)
517 if ((minuend->name != subtrahend->name)
518 || (gst_structure_n_fields (minuend) !=
519 gst_structure_n_fields (subtrahend))) {
523 return gst_structure_foreach ((GstStructure *) subtrahend,
524 gst_caps_structure_is_subset_field, (gpointer) minuend);
529 * @caps1: the #GstCaps that will be appended to
530 * @caps2: (transfer full): the #GstCaps to append
532 * Appends the structures contained in @caps2 to @caps1. The structures in
533 * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
534 * freed. If either caps is ANY, the resulting caps will be ANY.
537 gst_caps_append (GstCaps * caps1, GstCaps * caps2)
539 GstStructure *structure;
542 g_return_if_fail (GST_IS_CAPS (caps1));
543 g_return_if_fail (GST_IS_CAPS (caps2));
544 g_return_if_fail (IS_WRITABLE (caps1));
545 g_return_if_fail (IS_WRITABLE (caps2));
547 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))) {
548 /* FIXME: this leaks */
549 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
550 for (i = caps2->structs->len - 1; i >= 0; i--) {
551 structure = gst_caps_remove_and_get_structure (caps2, i);
552 gst_structure_free (structure);
555 for (i = caps2->structs->len; i; i--) {
556 structure = gst_caps_remove_and_get_structure (caps2, 0);
557 gst_caps_append_structure_unchecked (caps1, structure);
560 gst_caps_unref (caps2); /* guaranteed to free it */
565 * @caps1: the #GstCaps that will take the new entries
566 * @caps2: (transfer full): the #GstCaps to merge in
568 * Appends the structures contained in @caps2 to @caps1 if they are not yet
569 * expressed by @caps1. The structures in @caps2 are not copied -- they are
570 * transferred to @caps1, and then @caps2 is freed.
571 * If either caps is ANY, the resulting caps will be ANY.
576 gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
578 GstStructure *structure;
581 g_return_if_fail (GST_IS_CAPS (caps1));
582 g_return_if_fail (GST_IS_CAPS (caps2));
583 g_return_if_fail (IS_WRITABLE (caps1));
584 g_return_if_fail (IS_WRITABLE (caps2));
586 if (G_UNLIKELY (CAPS_IS_ANY (caps1))) {
587 for (i = caps2->structs->len - 1; i >= 0; i--) {
588 structure = gst_caps_remove_and_get_structure (caps2, i);
589 gst_structure_free (structure);
591 } else if (G_UNLIKELY (CAPS_IS_ANY (caps2))) {
592 GST_CAPS_FLAGS (caps1) |= GST_CAPS_FLAGS_ANY;
593 for (i = caps1->structs->len - 1; i >= 0; i--) {
594 structure = gst_caps_remove_and_get_structure (caps1, i);
595 gst_structure_free (structure);
598 for (i = caps2->structs->len; i; i--) {
599 structure = gst_caps_remove_and_get_structure (caps2, 0);
600 gst_caps_merge_structure (caps1, structure);
603 GstCaps *com = gst_caps_intersect (caps1, caps2);
604 GstCaps *add = gst_caps_subtract (caps2, com);
606 GST_DEBUG ("common : %d", gst_caps_get_size (com));
607 GST_DEBUG ("adding : %d", gst_caps_get_size (add));
608 gst_caps_append (caps1, add);
609 gst_caps_unref (com);
612 gst_caps_unref (caps2); /* guaranteed to free it */
616 * gst_caps_append_structure:
617 * @caps: the #GstCaps that will be appended to
618 * @structure: (transfer full): the #GstStructure to append
620 * Appends @structure to @caps. The structure is not copied; @caps
621 * becomes the owner of @structure.
624 gst_caps_append_structure (GstCaps * caps, GstStructure * structure)
626 g_return_if_fail (GST_IS_CAPS (caps));
627 g_return_if_fail (IS_WRITABLE (caps));
629 if (G_LIKELY (structure)) {
630 gst_caps_append_structure_unchecked (caps, structure);
635 * gst_caps_remove_structure:
636 * @caps: the #GstCaps to remove from
637 * @idx: Index of the structure to remove
639 * removes the stucture with the given index from the list of structures
640 * contained in @caps.
643 gst_caps_remove_structure (GstCaps * caps, guint idx)
645 GstStructure *structure;
647 g_return_if_fail (caps != NULL);
648 g_return_if_fail (idx <= gst_caps_get_size (caps));
649 g_return_if_fail (IS_WRITABLE (caps));
651 structure = gst_caps_remove_and_get_structure (caps, idx);
652 gst_structure_free (structure);
656 * gst_caps_merge_structure:
657 * @caps: the #GstCaps that will the the new structure
658 * @structure: (transfer full): the #GstStructure to merge
660 * Appends @structure to @caps if its not already expressed by @caps. The
661 * structure is not copied; @caps becomes the owner of @structure.
664 gst_caps_merge_structure (GstCaps * caps, GstStructure * structure)
666 g_return_if_fail (GST_IS_CAPS (caps));
667 g_return_if_fail (IS_WRITABLE (caps));
669 if (G_LIKELY (structure)) {
670 GstStructure *structure1;
672 gboolean unique = TRUE;
674 /* check each structure */
675 for (i = caps->structs->len - 1; i >= 0; i--) {
676 structure1 = gst_caps_get_structure_unchecked (caps, i);
677 /* if structure is a subset of structure1, then skip it */
678 if (gst_caps_structure_is_subset (structure1, structure)) {
684 gst_caps_append_structure_unchecked (caps, structure);
686 gst_structure_free (structure);
695 * Gets the number of structures contained in @caps.
697 * Returns: the number of structures that @caps contains
700 gst_caps_get_size (const GstCaps * caps)
702 g_return_val_if_fail (GST_IS_CAPS (caps), 0);
704 return caps->structs->len;
708 * gst_caps_get_structure:
710 * @index: the index of the structure
712 * Finds the structure in @caps that has the index @index, and
715 * WARNING: This function takes a const GstCaps *, but returns a
716 * non-const GstStructure *. This is for programming convenience --
717 * the caller should be aware that structures inside a constant
718 * #GstCaps should not be modified. However, if you know the caps
719 * are writable, either because you have just copied them or made
720 * them writable with gst_caps_make_writable(), you may modify the
721 * structure returned in the usual way, e.g. with functions like
722 * gst_structure_set().
724 * You do not need to free or unref the structure returned, it
725 * belongs to the #GstCaps.
727 * Returns: (transfer none): a pointer to the #GstStructure corresponding
731 gst_caps_get_structure (const GstCaps * caps, guint index)
733 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
734 g_return_val_if_fail (index < caps->structs->len, NULL);
736 return gst_caps_get_structure_unchecked (caps, index);
741 * @caps: the #GstCaps to copy
742 * @nth: the nth structure to copy
744 * Creates a new #GstCaps and appends a copy of the nth structure
745 * contained in @caps.
747 * Returns: (transfer full): the new #GstCaps
750 gst_caps_copy_nth (const GstCaps * caps, guint nth)
753 GstStructure *structure;
755 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
757 newcaps = gst_caps_new_empty ();
758 GST_CAPS_FLAGS (newcaps) = GST_CAPS_FLAGS (caps);
760 if (G_LIKELY (caps->structs->len > nth)) {
761 structure = gst_caps_get_structure_unchecked (caps, nth);
762 gst_caps_append_structure_unchecked (newcaps,
763 gst_structure_copy (structure));
771 * @caps: the #GstCaps to truncate
773 * Destructively discard all but the first structure from @caps. Useful when
774 * fixating. @caps must be writable.
777 gst_caps_truncate (GstCaps * caps)
781 g_return_if_fail (GST_IS_CAPS (caps));
782 g_return_if_fail (IS_WRITABLE (caps));
784 i = caps->structs->len - 1;
787 gst_caps_remove_structure (caps, i--);
791 * gst_caps_set_value:
792 * @caps: a writable caps
793 * @field: name of the field to set
794 * @value: value to set the field to
796 * Sets the given @field on all structures of @caps to the given @value.
797 * This is a convenience function for calling gst_structure_set_value() on
798 * all structures of @caps.
803 gst_caps_set_value (GstCaps * caps, const char *field, const GValue * value)
807 g_return_if_fail (GST_IS_CAPS (caps));
808 g_return_if_fail (IS_WRITABLE (caps));
809 g_return_if_fail (field != NULL);
810 g_return_if_fail (G_IS_VALUE (value));
812 len = caps->structs->len;
813 for (i = 0; i < len; i++) {
814 GstStructure *structure = gst_caps_get_structure_unchecked (caps, i);
815 gst_structure_set_value (structure, field, value);
820 * gst_caps_set_simple_valist:
821 * @caps: the #GstCaps to set
822 * @field: first field to set
823 * @varargs: additional parameters
825 * Sets fields in a #GstCaps. The arguments must be passed in the same
826 * manner as gst_structure_set(), and be NULL-terminated.
827 * <note>Prior to GStreamer version 0.10.26, this function failed when
828 * @caps was not simple. If your code needs to work with those versions
829 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
830 * is %TRUE for @caps.</note>
833 gst_caps_set_simple_valist (GstCaps * caps, const char *field, va_list varargs)
835 GValue value = { 0, };
837 g_return_if_fail (GST_IS_CAPS (caps));
838 g_return_if_fail (IS_WRITABLE (caps));
844 type = va_arg (varargs, GType);
846 if (G_UNLIKELY (type == G_TYPE_DATE)) {
847 g_warning ("Don't use G_TYPE_DATE, use GST_TYPE_DATE instead\n");
848 type = GST_TYPE_DATE;
850 #if GLIB_CHECK_VERSION(2,23,3)
851 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
853 g_value_init (&value, type);
854 G_VALUE_COLLECT (&value, varargs, 0, &err);
856 if (G_UNLIKELY (err)) {
857 g_critical ("%s", err);
861 gst_caps_set_value (caps, field, &value);
863 g_value_unset (&value);
865 field = va_arg (varargs, const gchar *);
870 * gst_caps_set_simple:
871 * @caps: the #GstCaps to set
872 * @field: first field to set
873 * @...: additional parameters
875 * Sets fields in a #GstCaps. The arguments must be passed in the same
876 * manner as gst_structure_set(), and be NULL-terminated.
877 * <note>Prior to GStreamer version 0.10.26, this function failed when
878 * @caps was not simple. If your code needs to work with those versions
879 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
880 * is %TRUE for @caps.</note>
883 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
887 g_return_if_fail (GST_IS_CAPS (caps));
888 g_return_if_fail (IS_WRITABLE (caps));
890 va_start (var_args, field);
891 gst_caps_set_simple_valist (caps, field, var_args);
899 * @caps: the #GstCaps to test
901 * Determines if @caps represents any media format.
903 * Returns: TRUE if @caps represents any format.
906 gst_caps_is_any (const GstCaps * caps)
908 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
910 return (CAPS_IS_ANY (caps));
915 * @caps: the #GstCaps to test
917 * Determines if @caps represents no media formats.
919 * Returns: TRUE if @caps represents no formats.
922 gst_caps_is_empty (const GstCaps * caps)
924 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
926 if (CAPS_IS_ANY (caps))
929 return CAPS_IS_EMPTY_SIMPLE (caps);
933 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
936 return gst_value_is_fixed (value);
941 * @caps: the #GstCaps to test
943 * Fixed #GstCaps describe exactly one format, that is, they have exactly
944 * one structure, and each field in the structure describes a fixed type.
945 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
947 * Returns: TRUE if @caps is fixed
950 gst_caps_is_fixed (const GstCaps * caps)
952 GstStructure *structure;
954 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
956 if (caps->structs->len != 1)
959 structure = gst_caps_get_structure_unchecked (caps, 0);
961 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
965 * gst_caps_is_equal_fixed:
966 * @caps1: the #GstCaps to test
967 * @caps2: the #GstCaps to test
969 * Tests if two #GstCaps are equal. This function only works on fixed
972 * Returns: TRUE if the arguments represent the same format
975 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
977 GstStructure *struct1, *struct2;
979 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
980 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
982 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
983 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
985 return gst_structure_is_equal (struct1, struct2);
989 * gst_caps_is_always_compatible:
990 * @caps1: the #GstCaps to test
991 * @caps2: the #GstCaps to test
993 * A given #GstCaps structure is always compatible with another if
994 * every media format that is in the first is also contained in the
995 * second. That is, @caps1 is a subset of @caps2.
997 * Returns: TRUE if @caps1 is a subset of @caps2.
1000 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
1002 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1003 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1005 return gst_caps_is_subset (caps1, caps2);
1009 * gst_caps_is_subset:
1010 * @subset: a #GstCaps
1011 * @superset: a potentially greater #GstCaps
1013 * Checks if all caps represented by @subset are also represented by @superset.
1014 * <note>This function does not work reliably if optional properties for caps
1015 * are included on one caps and omitted on the other.</note>
1017 * Returns: %TRUE if @subset is a subset of @superset
1020 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1025 g_return_val_if_fail (subset != NULL, FALSE);
1026 g_return_val_if_fail (superset != NULL, FALSE);
1028 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1030 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1033 caps = gst_caps_subtract (subset, superset);
1034 ret = CAPS_IS_EMPTY_SIMPLE (caps);
1035 gst_caps_unref (caps);
1040 * gst_caps_is_equal:
1041 * @caps1: a #GstCaps
1042 * @caps2: another #GstCaps
1044 * Checks if the given caps represent the same set of caps.
1045 * <note>This function does not work reliably if optional properties for caps
1046 * are included on one caps and omitted on the other.</note>
1048 * This function deals correctly with passing NULL for any of the caps.
1050 * Returns: TRUE if both caps are equal.
1053 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1055 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1056 * So there should be an assertion that caps1 and caps2 != NULL */
1058 /* NULL <-> NULL is allowed here */
1059 if (G_UNLIKELY (caps1 == caps2))
1062 /* one of them NULL => they are different (can't be both NULL because
1063 * we checked that above) */
1064 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1067 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1068 return gst_caps_is_equal_fixed (caps1, caps2);
1070 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1073 /* intersect operation */
1078 const GstStructure *intersect;
1083 gst_caps_structure_intersect_field1 (GQuark id, const GValue * val1,
1086 IntersectData *idata = (IntersectData *) data;
1087 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1089 if (G_UNLIKELY (val2 == NULL)) {
1090 gst_structure_id_set_value (idata->dest, id, val1);
1092 GValue dest_value = { 0 };
1093 if (gst_value_intersect (&dest_value, val1, val2)) {
1094 gst_structure_id_set_value (idata->dest, id, &dest_value);
1095 g_value_unset (&dest_value);
1104 gst_caps_structure_intersect_field2 (GQuark id, const GValue * val1,
1107 IntersectData *idata = (IntersectData *) data;
1108 const GValue *val2 = gst_structure_id_get_value (idata->intersect, id);
1110 if (G_UNLIKELY (val2 == NULL)) {
1111 gst_structure_id_set_value (idata->dest, id, val1);
1116 static GstStructure *
1117 gst_caps_structure_intersect (const GstStructure * struct1,
1118 const GstStructure * struct2)
1122 g_assert (struct1 != NULL);
1123 g_assert (struct2 != NULL);
1125 if (G_UNLIKELY (struct1->name != struct2->name))
1128 /* copy fields from struct1 which we have not in struct2 to target
1129 * intersect if we have the field in both */
1130 data.dest = gst_structure_id_empty_new (struct1->name);
1131 data.intersect = struct2;
1132 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1133 gst_caps_structure_intersect_field1, &data)))
1136 /* copy fields from struct2 which we have not in struct1 to target */
1137 data.intersect = struct1;
1138 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct2,
1139 gst_caps_structure_intersect_field2, &data)))
1145 gst_structure_free (data.dest);
1150 gst_caps_structure_can_intersect_field (GQuark id, const GValue * val1,
1153 GstStructure *other = (GstStructure *) data;
1154 const GValue *val2 = gst_structure_id_get_value (other, id);
1156 if (G_LIKELY (val2)) {
1157 if (!gst_value_can_intersect (val1, val2)) {
1160 gint eq = gst_value_compare (val1, val2);
1162 if (eq == GST_VALUE_UNORDERED) {
1163 /* we need to try interseting */
1164 GValue dest_value = { 0 };
1165 if (gst_value_intersect (&dest_value, val1, val2)) {
1166 g_value_unset (&dest_value);
1170 } else if (eq != GST_VALUE_EQUAL) {
1179 gst_caps_structure_can_intersect (const GstStructure * struct1,
1180 const GstStructure * struct2)
1182 g_assert (struct1 != NULL);
1183 g_assert (struct2 != NULL);
1185 if (G_UNLIKELY (struct1->name != struct2->name))
1188 /* tries to intersect if we have the field in both */
1189 if (G_UNLIKELY (!gst_structure_foreach ((GstStructure *) struct1,
1190 gst_caps_structure_can_intersect_field, (gpointer) struct2)))
1197 * gst_caps_can_intersect:
1198 * @caps1: a #GstCaps to intersect
1199 * @caps2: a #GstCaps to intersect
1201 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1204 * Returns: %TRUE if intersection would be not empty
1209 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1211 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1212 guint j, k, len1, len2;
1213 GstStructure *struct1;
1214 GstStructure *struct2;
1216 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1217 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1219 /* caps are exactly the same pointers */
1220 if (G_UNLIKELY (caps1 == caps2))
1223 /* empty caps on either side, return empty */
1224 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1227 /* one of the caps is any */
1228 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1231 /* run zigzag on top line then right line, this preserves the caps order
1232 * much better than a simple loop.
1234 * This algorithm zigzags over the caps structures as demonstrated in
1235 * the folowing matrix:
1238 * +------------- total distance: +-------------
1239 * | 1 2 4 7 0 | 0 1 2 3
1240 * caps2 | 3 5 8 10 1 | 1 2 3 4
1241 * | 6 9 11 12 2 | 2 3 4 5
1243 * First we iterate over the caps1 structures (top line) intersecting
1244 * the structures diagonally down, then we iterate over the caps2
1245 * structures. The result is that the intersections are ordered based on the
1246 * sum of the indexes in the list.
1248 len1 = caps1->structs->len;
1249 len2 = caps2->structs->len;
1250 for (i = 0; i < len1 + len2 - 1; i++) {
1251 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1252 j = MIN (i, len1 - 1);
1253 /* subset index stays 0 until i reaches superset->structs->len, then it
1254 * counts up from 1 to subset->structs->len - 1 */
1257 /* now run the diagonal line, end condition is the left or bottom
1260 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1261 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1263 if (gst_caps_structure_can_intersect (struct1, struct2)) {
1266 /* move down left */
1268 if (G_UNLIKELY (j == 0))
1269 break; /* so we don't roll back to G_MAXUINT */
1277 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1279 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1280 guint j, k, len1, len2;
1282 GstStructure *struct1;
1283 GstStructure *struct2;
1285 GstStructure *istruct;
1287 /* caps are exactly the same pointers, just copy one caps */
1288 if (G_UNLIKELY (caps1 == caps2))
1289 return _gst_caps_copy (caps1);
1291 /* empty caps on either side, return empty */
1292 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1293 return gst_caps_new_empty ();
1295 /* one of the caps is any, just copy the other caps */
1296 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1297 return _gst_caps_copy (caps2);
1298 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1299 return _gst_caps_copy (caps1);
1301 dest = gst_caps_new_empty ();
1303 /* run zigzag on top line then right line, this preserves the caps order
1304 * much better than a simple loop.
1306 * This algorithm zigzags over the caps structures as demonstrated in
1307 * the folowing matrix:
1315 * First we iterate over the caps1 structures (top line) intersecting
1316 * the structures diagonally down, then we iterate over the caps2
1319 len1 = caps1->structs->len;
1320 len2 = caps2->structs->len;
1321 for (i = 0; i < len1 + len2 - 1; i++) {
1322 /* caps1 index goes from 0 to caps1->structs->len-1 */
1323 j = MIN (i, len1 - 1);
1324 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1325 * up from 1 to caps2->structs->len - 1 */
1328 /* now run the diagonal line, end condition is the left or bottom
1331 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1332 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1334 istruct = gst_caps_structure_intersect (struct1, struct2);
1336 gst_caps_merge_structure (dest, istruct);
1337 /* move down left */
1339 if (G_UNLIKELY (j == 0))
1340 break; /* so we don't roll back to G_MAXUINT */
1348 * gst_caps_intersect_first:
1349 * @caps1: a #GstCaps to intersect
1350 * @caps2: a #GstCaps to intersect
1352 * Creates a new #GstCaps that contains all the formats that are common
1353 * to both @caps1 and @caps2.
1355 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1356 * fashion as @caps1.
1358 * Returns: the new #GstCaps
1361 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1363 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1364 guint j, len1, len2;
1366 GstStructure *struct1;
1367 GstStructure *struct2;
1369 GstStructure *istruct;
1371 /* caps are exactly the same pointers, just copy one caps */
1372 if (G_UNLIKELY (caps1 == caps2))
1373 return gst_caps_copy (caps1);
1375 /* empty caps on either side, return empty */
1376 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1377 return gst_caps_new_empty ();
1379 /* one of the caps is any, just copy the other caps */
1380 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1381 return gst_caps_copy (caps2);
1382 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1383 return gst_caps_copy (caps1);
1385 dest = gst_caps_new_empty ();
1387 len1 = caps1->structs->len;
1388 len2 = caps2->structs->len;
1389 for (i = 0; i < len1; i++) {
1390 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1391 for (j = 0; j < len2; j++) {
1392 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1393 istruct = gst_caps_structure_intersect (struct1, struct2);
1395 gst_caps_merge_structure (dest, istruct);
1403 * gst_caps_intersect_full:
1404 * @caps1: a #GstCaps to intersect
1405 * @caps2: a #GstCaps to intersect
1406 * @mode: The intersection algorithm/mode to use
1408 * Creates a new #GstCaps that contains all the formats that are common
1409 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1412 * Returns: the new #GstCaps
1416 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1417 GstCapsIntersectMode mode)
1419 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1420 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1423 case GST_CAPS_INTERSECT_FIRST:
1424 return gst_caps_intersect_first (caps1, caps2);
1426 g_warning ("Unknown caps intersect mode: %d", mode);
1428 case GST_CAPS_INTERSECT_ZIG_ZAG:
1429 return gst_caps_intersect_zig_zag (caps1, caps2);
1434 * gst_caps_intersect:
1435 * @caps1: a #GstCaps to intersect
1436 * @caps2: a #GstCaps to intersect
1438 * Creates a new #GstCaps that contains all the formats that are common
1439 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1441 * Returns: the new #GstCaps
1444 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1446 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1450 /* subtract operation */
1454 const GstStructure *subtract_from;
1460 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1463 SubtractionEntry *e = user_data;
1464 GValue subtraction = { 0, };
1465 const GValue *other;
1466 GstStructure *structure;
1468 other = gst_structure_id_get_value (e->subtract_from, field_id);
1472 if (!gst_value_subtract (&subtraction, other, value))
1474 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1475 g_value_unset (&subtraction);
1478 structure = gst_structure_copy (e->subtract_from);
1479 gst_structure_id_set_value (structure, field_id, &subtraction);
1480 g_value_unset (&subtraction);
1481 e->put_into = g_slist_prepend (e->put_into, structure);
1487 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1488 const GstStructure * subtrahend)
1493 e.subtract_from = minuend;
1496 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1497 gst_caps_structure_subtract_field, &e);
1503 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1504 gst_structure_free (walk->data);
1506 g_slist_free (e.put_into);
1512 * gst_caps_subtract:
1513 * @minuend: #GstCaps to substract from
1514 * @subtrahend: #GstCaps to substract
1516 * Subtracts the @subtrahend from the @minuend.
1517 * <note>This function does not work reliably if optional properties for caps
1518 * are included on one caps and omitted on the other.</note>
1520 * Returns: the resulting caps
1523 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1528 GstCaps *dest = NULL, *src;
1530 g_return_val_if_fail (minuend != NULL, NULL);
1531 g_return_val_if_fail (subtrahend != NULL, NULL);
1533 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1534 return gst_caps_new_empty ();
1536 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1537 return _gst_caps_copy (minuend);
1539 /* FIXME: Do we want this here or above?
1540 The reason we need this is that there is no definition about what
1541 ANY means for specific types, so it's not possible to reduce ANY partially
1542 You can only remove everything or nothing and that is done above.
1543 Note: there's a test that checks this behaviour. */
1544 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1545 sublen = subtrahend->structs->len;
1546 g_assert (sublen > 0);
1548 src = _gst_caps_copy (minuend);
1549 for (i = 0; i < sublen; i++) {
1552 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1554 gst_caps_unref (src);
1557 dest = gst_caps_new_empty ();
1558 srclen = src->structs->len;
1559 for (j = 0; j < srclen; j++) {
1560 min = gst_caps_get_structure_unchecked (src, j);
1561 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1564 if (gst_caps_structure_subtract (&list, min, sub)) {
1567 for (walk = list; walk; walk = g_slist_next (walk)) {
1568 gst_caps_append_structure_unchecked (dest,
1569 (GstStructure *) walk->data);
1571 g_slist_free (list);
1573 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1576 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1579 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1580 gst_caps_unref (src);
1585 gst_caps_unref (src);
1586 gst_caps_do_simplify (dest);
1590 /* union operation */
1593 static GstStructure *
1594 gst_caps_structure_union (const GstStructure * struct1,
1595 const GstStructure * struct2)
1599 const GstStructureField *field1;
1600 const GstStructureField *field2;
1603 /* FIXME this doesn't actually work */
1605 if (struct1->name != struct2->name)
1608 dest = gst_structure_id_empty_new (struct1->name);
1610 for (i = 0; i < struct1->fields->len; i++) {
1611 GValue dest_value = { 0 };
1613 field1 = GST_STRUCTURE_FIELD (struct1, i);
1614 field2 = gst_structure_id_get_field (struct2, field1->name);
1616 if (field2 == NULL) {
1619 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1620 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1623 ret = gst_value_compare (&field1->value, &field2->value);
1634 * @caps1: a #GstCaps to union
1635 * @caps2: a #GstCaps to union
1637 * Creates a new #GstCaps that contains all the formats that are in
1638 * either @caps1 and @caps2.
1640 * Returns: the new #GstCaps
1643 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1648 /* NULL pointers are no correct GstCaps */
1649 g_return_val_if_fail (caps1 != NULL, NULL);
1650 g_return_val_if_fail (caps2 != NULL, NULL);
1652 if (CAPS_IS_EMPTY (caps1))
1653 return _gst_caps_copy (caps2);
1655 if (CAPS_IS_EMPTY (caps2))
1656 return _gst_caps_copy (caps1);
1658 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1659 return gst_caps_new_any ();
1661 dest1 = _gst_caps_copy (caps1);
1662 dest2 = _gst_caps_copy (caps2);
1663 gst_caps_append (dest1, dest2);
1665 gst_caps_do_simplify (dest1);
1669 /* normalize/simplify operations */
1671 typedef struct _NormalizeForeach
1674 GstStructure *structure;
1679 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1681 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1685 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1686 guint len = gst_value_list_get_size (value);
1687 for (i = 1; i < len; i++) {
1688 const GValue *v = gst_value_list_get_value (value, i);
1689 GstStructure *structure = gst_structure_copy (nf->structure);
1691 gst_structure_id_set_value (structure, field_id, v);
1692 gst_caps_append_structure_unchecked (nf->caps, structure);
1695 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1696 gst_structure_id_set_value (nf->structure, field_id, &val);
1697 g_value_unset (&val);
1705 * gst_caps_normalize:
1706 * @caps: a #GstCaps to normalize
1708 * Creates a new #GstCaps that represents the same set of formats as
1709 * @caps, but contains no lists. Each list is expanded into separate
1712 * Returns: the new #GstCaps
1715 gst_caps_normalize (const GstCaps * caps)
1717 NormalizeForeach nf;
1721 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1723 newcaps = _gst_caps_copy (caps);
1726 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1727 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1729 while (!gst_structure_foreach (nf.structure,
1730 gst_caps_normalize_foreach, &nf));
1737 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1740 const GstStructure *struct1 = *((const GstStructure **) one);
1741 const GstStructure *struct2 = *((const GstStructure **) two);
1743 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1744 So what's the best way? */
1745 ret = strcmp (gst_structure_get_name (struct1),
1746 gst_structure_get_name (struct2));
1750 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1757 GstStructure *compare;
1762 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1765 UnionField *u = user_data;
1766 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1770 g_value_unset (&u->value);
1773 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1776 g_value_unset (&u->value);
1780 gst_value_union (&u->value, val, value);
1785 gst_caps_structure_simplify (GstStructure ** result,
1786 const GstStructure * simplify, GstStructure * compare)
1789 UnionField field = { 0, {0,}, NULL };
1791 /* try to subtract to get a real subset */
1792 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1793 if (list == NULL) { /* no result */
1796 } else if (list->next == NULL) { /* one result */
1797 *result = list->data;
1798 g_slist_free (list);
1800 } else { /* multiple results */
1801 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1802 g_slist_free (list);
1807 /* try to union both structs */
1808 field.compare = compare;
1809 if (gst_structure_foreach ((GstStructure *) simplify,
1810 gst_caps_structure_figure_out_union, &field)) {
1811 gboolean ret = FALSE;
1813 /* now we know all of simplify's fields are the same in compare
1814 * but at most one field: field.name */
1815 if (G_IS_VALUE (&field.value)) {
1816 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1817 gst_structure_id_set_value (compare, field.name, &field.value);
1821 g_value_unset (&field.value);
1822 } else if (gst_structure_n_fields (simplify) <=
1823 gst_structure_n_fields (compare)) {
1824 /* compare is just more specific, will be optimized away later */
1825 /* FIXME: do this here? */
1826 GST_LOG ("found a case that will be optimized later.");
1828 gchar *one = gst_structure_to_string (simplify);
1829 gchar *two = gst_structure_to_string (compare);
1832 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1844 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1845 GstStructure * new, gint i)
1847 gst_structure_set_parent_refcount (old, NULL);
1848 gst_structure_free (old);
1849 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1850 g_ptr_array_index (caps->structs, i) = new;
1854 * gst_caps_do_simplify:
1855 * @caps: a #GstCaps to simplify
1857 * Modifies the given @caps inplace into a representation that represents the
1858 * same set of formats, but in a simpler form. Component structures that are
1859 * identical are merged. Component structures that have values that can be
1860 * merged are also merged.
1862 * Returns: TRUE, if the caps could be simplified
1865 gst_caps_do_simplify (GstCaps * caps)
1867 GstStructure *simplify, *compare, *result = NULL;
1869 gboolean changed = FALSE;
1871 g_return_val_if_fail (caps != NULL, FALSE);
1872 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1874 if (gst_caps_get_size (caps) < 2)
1877 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1879 start = caps->structs->len - 1;
1880 for (i = caps->structs->len - 1; i >= 0; i--) {
1881 simplify = gst_caps_get_structure_unchecked (caps, i);
1882 if (gst_structure_get_name_id (simplify) !=
1883 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1886 for (j = start; j >= 0; j--) {
1889 compare = gst_caps_get_structure_unchecked (caps, j);
1890 if (gst_structure_get_name_id (simplify) !=
1891 gst_structure_get_name_id (compare)) {
1894 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1896 gst_caps_switch_structures (caps, simplify, result, i);
1899 gst_caps_remove_structure (caps, i);
1911 /* gst_caps_do_simplify (caps); */
1919 * @caps: (inout) (transfer full): a pointer to #GstCaps
1920 * @newcaps: a #GstCaps to replace *caps
1922 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1923 * pointed to by @caps, if applicable, then modifies @caps to point to
1924 * @newcaps. An additional ref on @newcaps is taken.
1926 * This function does not take any locks so you might want to lock
1927 * the object owning @caps pointer.
1930 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1934 g_return_if_fail (caps != NULL);
1938 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1940 if (newcaps != oldcaps) {
1942 gst_caps_ref (newcaps);
1947 gst_caps_unref (oldcaps);
1952 * gst_caps_to_string:
1955 * Converts @caps to a string representation. This string representation
1956 * can be converted back to a #GstCaps by gst_caps_from_string().
1958 * For debugging purposes its easier to do something like this:
1960 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1962 * This prints the caps in human readble form.
1964 * Returns: (transfer full): a newly allocated string representing @caps.
1967 gst_caps_to_string (const GstCaps * caps)
1969 guint i, slen, clen;
1972 /* NOTE: This function is potentially called by the debug system,
1973 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1974 * should be careful to avoid recursion. This includes any functions
1975 * called by gst_caps_to_string. In particular, calls should
1976 * not use the GST_PTR_FORMAT extension. */
1979 return g_strdup ("NULL");
1981 if (CAPS_IS_ANY (caps)) {
1982 return g_strdup ("ANY");
1984 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1985 return g_strdup ("EMPTY");
1988 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1990 clen = caps->structs->len;
1991 for (i = 0; i < clen; i++) {
1993 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1997 s = g_string_sized_new (slen);
1998 for (i = 0; i < clen; i++) {
1999 GstStructure *structure;
2002 /* ';' is now added by gst_structure_to_string */
2003 g_string_append_c (s, ' ');
2006 structure = gst_caps_get_structure_unchecked (caps, i);
2007 priv_gst_structure_append_to_gstring (structure, s);
2009 if (s->len && s->str[s->len - 1] == ';') {
2010 /* remove latest ';' */
2011 s->str[--s->len] = '\0';
2013 return g_string_free (s, FALSE);
2017 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
2019 GstStructure *structure;
2022 if (strcmp ("ANY", string) == 0) {
2023 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
2026 if (strcmp ("EMPTY", string) == 0) {
2030 structure = gst_structure_from_string (string, &s);
2031 if (structure == NULL) {
2034 gst_caps_append_structure_unchecked (caps, structure);
2038 while (g_ascii_isspace (*s))
2043 structure = gst_structure_from_string (s, &s);
2044 if (structure == NULL) {
2047 gst_caps_append_structure_unchecked (caps, structure);
2055 * gst_caps_from_string:
2056 * @string: a string to convert to #GstCaps
2058 * Converts @caps from a string representation.
2060 * Returns: (transfer full): a newly allocated #GstCaps
2063 gst_caps_from_string (const gchar * string)
2067 g_return_val_if_fail (string, FALSE);
2069 caps = gst_caps_new_empty ();
2070 if (gst_caps_from_string_inplace (caps, string)) {
2073 gst_caps_unref (caps);
2079 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
2081 g_return_if_fail (G_IS_VALUE (src_value));
2082 g_return_if_fail (G_IS_VALUE (dest_value));
2083 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
2084 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
2085 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
2087 dest_value->data[0].v_pointer =
2088 gst_caps_to_string (src_value->data[0].v_pointer);