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 if (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 G_VALUE_COLLECT_INIT (&value, type, varargs, 0, &err);
851 if (G_UNLIKELY (err)) {
852 g_critical ("%s", err);
856 gst_caps_set_value (caps, field, &value);
858 g_value_unset (&value);
860 field = va_arg (varargs, const gchar *);
865 * gst_caps_set_simple:
866 * @caps: the #GstCaps to set
867 * @field: first field to set
868 * @...: additional parameters
870 * Sets fields in a #GstCaps. The arguments must be passed in the same
871 * manner as gst_structure_set(), and be NULL-terminated.
872 * <note>Prior to GStreamer version 0.10.26, this function failed when
873 * @caps was not simple. If your code needs to work with those versions
874 * of GStreamer, you may only call this function when GST_CAPS_IS_SIMPLE()
875 * is %TRUE for @caps.</note>
878 gst_caps_set_simple (GstCaps * caps, const char *field, ...)
882 g_return_if_fail (GST_IS_CAPS (caps));
883 g_return_if_fail (IS_WRITABLE (caps));
885 va_start (var_args, field);
886 gst_caps_set_simple_valist (caps, field, var_args);
894 * @caps: the #GstCaps to test
896 * Determines if @caps represents any media format.
898 * Returns: TRUE if @caps represents any format.
901 gst_caps_is_any (const GstCaps * caps)
903 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
905 return (CAPS_IS_ANY (caps));
910 * @caps: the #GstCaps to test
912 * Determines if @caps represents no media formats.
914 * Returns: TRUE if @caps represents no formats.
917 gst_caps_is_empty (const GstCaps * caps)
919 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
921 if (CAPS_IS_ANY (caps))
924 return CAPS_IS_EMPTY_SIMPLE (caps);
928 gst_caps_is_fixed_foreach (GQuark field_id, const GValue * value,
931 return gst_value_is_fixed (value);
936 * @caps: the #GstCaps to test
938 * Fixed #GstCaps describe exactly one format, that is, they have exactly
939 * one structure, and each field in the structure describes a fixed type.
940 * Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
942 * Returns: TRUE if @caps is fixed
945 gst_caps_is_fixed (const GstCaps * caps)
947 GstStructure *structure;
949 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
951 if (caps->structs->len != 1)
954 structure = gst_caps_get_structure_unchecked (caps, 0);
956 return gst_structure_foreach (structure, gst_caps_is_fixed_foreach, NULL);
960 * gst_caps_is_equal_fixed:
961 * @caps1: the #GstCaps to test
962 * @caps2: the #GstCaps to test
964 * Tests if two #GstCaps are equal. This function only works on fixed
967 * Returns: TRUE if the arguments represent the same format
970 gst_caps_is_equal_fixed (const GstCaps * caps1, const GstCaps * caps2)
972 GstStructure *struct1, *struct2;
974 g_return_val_if_fail (gst_caps_is_fixed (caps1), FALSE);
975 g_return_val_if_fail (gst_caps_is_fixed (caps2), FALSE);
977 struct1 = gst_caps_get_structure_unchecked (caps1, 0);
978 struct2 = gst_caps_get_structure_unchecked (caps2, 0);
980 return gst_structure_is_equal (struct1, struct2);
984 * gst_caps_is_always_compatible:
985 * @caps1: the #GstCaps to test
986 * @caps2: the #GstCaps to test
988 * A given #GstCaps structure is always compatible with another if
989 * every media format that is in the first is also contained in the
990 * second. That is, @caps1 is a subset of @caps2.
992 * Returns: TRUE if @caps1 is a subset of @caps2.
995 gst_caps_is_always_compatible (const GstCaps * caps1, const GstCaps * caps2)
997 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
998 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1000 return gst_caps_is_subset (caps1, caps2);
1004 * gst_caps_is_subset:
1005 * @subset: a #GstCaps
1006 * @superset: a potentially greater #GstCaps
1008 * Checks if all caps represented by @subset are also represented by @superset.
1009 * <note>This function does not work reliably if optional properties for caps
1010 * are included on one caps and omitted on the other.</note>
1012 * Returns: %TRUE if @subset is a subset of @superset
1015 gst_caps_is_subset (const GstCaps * subset, const GstCaps * superset)
1020 g_return_val_if_fail (subset != NULL, FALSE);
1021 g_return_val_if_fail (superset != NULL, FALSE);
1023 if (CAPS_IS_EMPTY (subset) || CAPS_IS_ANY (superset))
1025 if (CAPS_IS_ANY (subset) || CAPS_IS_EMPTY (superset))
1028 caps = gst_caps_subtract (subset, superset);
1029 ret = CAPS_IS_EMPTY_SIMPLE (caps);
1030 gst_caps_unref (caps);
1035 * gst_caps_is_equal:
1036 * @caps1: a #GstCaps
1037 * @caps2: another #GstCaps
1039 * Checks if the given caps represent the same set of caps.
1040 * <note>This function does not work reliably if optional properties for caps
1041 * are included on one caps and omitted on the other.</note>
1043 * This function deals correctly with passing NULL for any of the caps.
1045 * Returns: TRUE if both caps are equal.
1048 gst_caps_is_equal (const GstCaps * caps1, const GstCaps * caps2)
1050 /* FIXME 0.11: NULL pointers are no valid Caps but indicate an error
1051 * So there should be an assertion that caps1 and caps2 != NULL */
1053 /* NULL <-> NULL is allowed here */
1054 if (G_UNLIKELY (caps1 == caps2))
1057 /* one of them NULL => they are different (can't be both NULL because
1058 * we checked that above) */
1059 if (G_UNLIKELY (caps1 == NULL || caps2 == NULL))
1062 if (G_UNLIKELY (gst_caps_is_fixed (caps1) && gst_caps_is_fixed (caps2)))
1063 return gst_caps_is_equal_fixed (caps1, caps2);
1065 return gst_caps_is_subset (caps1, caps2) && gst_caps_is_subset (caps2, caps1);
1068 /* intersect operation */
1071 * gst_caps_can_intersect:
1072 * @caps1: a #GstCaps to intersect
1073 * @caps2: a #GstCaps to intersect
1075 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1078 * Returns: %TRUE if intersection would be not empty
1083 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1085 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1086 guint j, k, len1, len2;
1087 GstStructure *struct1;
1088 GstStructure *struct2;
1090 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1091 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1093 /* caps are exactly the same pointers */
1094 if (G_UNLIKELY (caps1 == caps2))
1097 /* empty caps on either side, return empty */
1098 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1101 /* one of the caps is any */
1102 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1105 /* run zigzag on top line then right line, this preserves the caps order
1106 * much better than a simple loop.
1108 * This algorithm zigzags over the caps structures as demonstrated in
1109 * the folowing matrix:
1112 * +------------- total distance: +-------------
1113 * | 1 2 4 7 0 | 0 1 2 3
1114 * caps2 | 3 5 8 10 1 | 1 2 3 4
1115 * | 6 9 11 12 2 | 2 3 4 5
1117 * First we iterate over the caps1 structures (top line) intersecting
1118 * the structures diagonally down, then we iterate over the caps2
1119 * structures. The result is that the intersections are ordered based on the
1120 * sum of the indexes in the list.
1122 len1 = caps1->structs->len;
1123 len2 = caps2->structs->len;
1124 for (i = 0; i < len1 + len2 - 1; i++) {
1125 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1126 j = MIN (i, len1 - 1);
1127 /* subset index stays 0 until i reaches superset->structs->len, then it
1128 * counts up from 1 to subset->structs->len - 1 */
1131 /* now run the diagonal line, end condition is the left or bottom
1134 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1135 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1137 if (gst_structure_can_intersect (struct1, struct2)) {
1140 /* move down left */
1142 if (G_UNLIKELY (j == 0))
1143 break; /* so we don't roll back to G_MAXUINT */
1151 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1153 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1154 guint j, k, len1, len2;
1156 GstStructure *struct1;
1157 GstStructure *struct2;
1159 GstStructure *istruct;
1161 /* caps are exactly the same pointers, just copy one caps */
1162 if (G_UNLIKELY (caps1 == caps2))
1163 return _gst_caps_copy (caps1);
1165 /* empty caps on either side, return empty */
1166 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1167 return gst_caps_new_empty ();
1169 /* one of the caps is any, just copy the other caps */
1170 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1171 return _gst_caps_copy (caps2);
1172 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1173 return _gst_caps_copy (caps1);
1175 dest = gst_caps_new_empty ();
1177 /* run zigzag on top line then right line, this preserves the caps order
1178 * much better than a simple loop.
1180 * This algorithm zigzags over the caps structures as demonstrated in
1181 * the folowing matrix:
1189 * First we iterate over the caps1 structures (top line) intersecting
1190 * the structures diagonally down, then we iterate over the caps2
1193 len1 = caps1->structs->len;
1194 len2 = caps2->structs->len;
1195 for (i = 0; i < len1 + len2 - 1; i++) {
1196 /* caps1 index goes from 0 to caps1->structs->len-1 */
1197 j = MIN (i, len1 - 1);
1198 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1199 * up from 1 to caps2->structs->len - 1 */
1202 /* now run the diagonal line, end condition is the left or bottom
1205 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1206 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1208 istruct = gst_structure_intersect (struct1, struct2);
1210 gst_caps_merge_structure (dest, istruct);
1211 /* move down left */
1213 if (G_UNLIKELY (j == 0))
1214 break; /* so we don't roll back to G_MAXUINT */
1222 * gst_caps_intersect_first:
1223 * @caps1: a #GstCaps to intersect
1224 * @caps2: a #GstCaps to intersect
1226 * Creates a new #GstCaps that contains all the formats that are common
1227 * to both @caps1 and @caps2.
1229 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1230 * fashion as @caps1.
1232 * Returns: the new #GstCaps
1235 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1237 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1238 guint j, len1, len2;
1240 GstStructure *struct1;
1241 GstStructure *struct2;
1243 GstStructure *istruct;
1245 /* caps are exactly the same pointers, just copy one caps */
1246 if (G_UNLIKELY (caps1 == caps2))
1247 return gst_caps_copy (caps1);
1249 /* empty caps on either side, return empty */
1250 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1251 return gst_caps_new_empty ();
1253 /* one of the caps is any, just copy the other caps */
1254 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1255 return gst_caps_copy (caps2);
1256 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1257 return gst_caps_copy (caps1);
1259 dest = gst_caps_new_empty ();
1261 len1 = caps1->structs->len;
1262 len2 = caps2->structs->len;
1263 for (i = 0; i < len1; i++) {
1264 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1265 for (j = 0; j < len2; j++) {
1266 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1267 istruct = gst_structure_intersect (struct1, struct2);
1269 gst_caps_merge_structure (dest, istruct);
1277 * gst_caps_intersect_full:
1278 * @caps1: a #GstCaps to intersect
1279 * @caps2: a #GstCaps to intersect
1280 * @mode: The intersection algorithm/mode to use
1282 * Creates a new #GstCaps that contains all the formats that are common
1283 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1286 * Returns: the new #GstCaps
1290 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1291 GstCapsIntersectMode mode)
1293 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1294 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1297 case GST_CAPS_INTERSECT_FIRST:
1298 return gst_caps_intersect_first (caps1, caps2);
1300 g_warning ("Unknown caps intersect mode: %d", mode);
1302 case GST_CAPS_INTERSECT_ZIG_ZAG:
1303 return gst_caps_intersect_zig_zag (caps1, caps2);
1308 * gst_caps_intersect:
1309 * @caps1: a #GstCaps to intersect
1310 * @caps2: a #GstCaps to intersect
1312 * Creates a new #GstCaps that contains all the formats that are common
1313 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1315 * Returns: the new #GstCaps
1318 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1320 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1324 /* subtract operation */
1328 const GstStructure *subtract_from;
1334 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1337 SubtractionEntry *e = user_data;
1338 GValue subtraction = { 0, };
1339 const GValue *other;
1340 GstStructure *structure;
1342 other = gst_structure_id_get_value (e->subtract_from, field_id);
1346 if (!gst_value_subtract (&subtraction, other, value))
1348 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1349 g_value_unset (&subtraction);
1352 structure = gst_structure_copy (e->subtract_from);
1353 gst_structure_id_set_value (structure, field_id, &subtraction);
1354 g_value_unset (&subtraction);
1355 e->put_into = g_slist_prepend (e->put_into, structure);
1361 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1362 const GstStructure * subtrahend)
1367 e.subtract_from = minuend;
1370 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1371 gst_caps_structure_subtract_field, &e);
1377 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1378 gst_structure_free (walk->data);
1380 g_slist_free (e.put_into);
1386 * gst_caps_subtract:
1387 * @minuend: #GstCaps to substract from
1388 * @subtrahend: #GstCaps to substract
1390 * Subtracts the @subtrahend from the @minuend.
1391 * <note>This function does not work reliably if optional properties for caps
1392 * are included on one caps and omitted on the other.</note>
1394 * Returns: the resulting caps
1397 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1402 GstCaps *dest = NULL, *src;
1404 g_return_val_if_fail (minuend != NULL, NULL);
1405 g_return_val_if_fail (subtrahend != NULL, NULL);
1407 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1408 return gst_caps_new_empty ();
1410 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1411 return _gst_caps_copy (minuend);
1413 /* FIXME: Do we want this here or above?
1414 The reason we need this is that there is no definition about what
1415 ANY means for specific types, so it's not possible to reduce ANY partially
1416 You can only remove everything or nothing and that is done above.
1417 Note: there's a test that checks this behaviour. */
1418 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1419 sublen = subtrahend->structs->len;
1420 g_assert (sublen > 0);
1422 src = _gst_caps_copy (minuend);
1423 for (i = 0; i < sublen; i++) {
1426 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1428 gst_caps_unref (src);
1431 dest = gst_caps_new_empty ();
1432 srclen = src->structs->len;
1433 for (j = 0; j < srclen; j++) {
1434 min = gst_caps_get_structure_unchecked (src, j);
1435 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1438 if (gst_caps_structure_subtract (&list, min, sub)) {
1441 for (walk = list; walk; walk = g_slist_next (walk)) {
1442 gst_caps_append_structure_unchecked (dest,
1443 (GstStructure *) walk->data);
1445 g_slist_free (list);
1447 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1450 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1453 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1454 gst_caps_unref (src);
1459 gst_caps_unref (src);
1460 gst_caps_do_simplify (dest);
1464 /* union operation */
1467 static GstStructure *
1468 gst_caps_structure_union (const GstStructure * struct1,
1469 const GstStructure * struct2)
1473 const GstStructureField *field1;
1474 const GstStructureField *field2;
1477 /* FIXME this doesn't actually work */
1479 if (struct1->name != struct2->name)
1482 dest = gst_structure_id_empty_new (struct1->name);
1484 for (i = 0; i < struct1->fields->len; i++) {
1485 GValue dest_value = { 0 };
1487 field1 = GST_STRUCTURE_FIELD (struct1, i);
1488 field2 = gst_structure_id_get_field (struct2, field1->name);
1490 if (field2 == NULL) {
1493 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1494 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1497 ret = gst_value_compare (&field1->value, &field2->value);
1508 * @caps1: a #GstCaps to union
1509 * @caps2: a #GstCaps to union
1511 * Creates a new #GstCaps that contains all the formats that are in
1512 * either @caps1 and @caps2.
1514 * Returns: the new #GstCaps
1517 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1522 /* NULL pointers are no correct GstCaps */
1523 g_return_val_if_fail (caps1 != NULL, NULL);
1524 g_return_val_if_fail (caps2 != NULL, NULL);
1526 if (CAPS_IS_EMPTY (caps1))
1527 return _gst_caps_copy (caps2);
1529 if (CAPS_IS_EMPTY (caps2))
1530 return _gst_caps_copy (caps1);
1532 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1533 return gst_caps_new_any ();
1535 dest1 = _gst_caps_copy (caps1);
1536 dest2 = _gst_caps_copy (caps2);
1537 gst_caps_append (dest1, dest2);
1539 gst_caps_do_simplify (dest1);
1543 /* normalize/simplify operations */
1545 typedef struct _NormalizeForeach
1548 GstStructure *structure;
1553 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1555 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1559 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1560 guint len = gst_value_list_get_size (value);
1561 for (i = 1; i < len; i++) {
1562 const GValue *v = gst_value_list_get_value (value, i);
1563 GstStructure *structure = gst_structure_copy (nf->structure);
1565 gst_structure_id_set_value (structure, field_id, v);
1566 gst_caps_append_structure_unchecked (nf->caps, structure);
1569 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1570 gst_structure_id_set_value (nf->structure, field_id, &val);
1571 g_value_unset (&val);
1579 * gst_caps_normalize:
1580 * @caps: a #GstCaps to normalize
1582 * Creates a new #GstCaps that represents the same set of formats as
1583 * @caps, but contains no lists. Each list is expanded into separate
1586 * Returns: the new #GstCaps
1589 gst_caps_normalize (const GstCaps * caps)
1591 NormalizeForeach nf;
1595 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1597 newcaps = _gst_caps_copy (caps);
1600 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1601 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1603 while (!gst_structure_foreach (nf.structure,
1604 gst_caps_normalize_foreach, &nf));
1611 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1614 const GstStructure *struct1 = *((const GstStructure **) one);
1615 const GstStructure *struct2 = *((const GstStructure **) two);
1617 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1618 So what's the best way? */
1619 ret = strcmp (gst_structure_get_name (struct1),
1620 gst_structure_get_name (struct2));
1624 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1631 GstStructure *compare;
1636 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1639 UnionField *u = user_data;
1640 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1644 g_value_unset (&u->value);
1647 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1650 g_value_unset (&u->value);
1654 gst_value_union (&u->value, val, value);
1659 gst_caps_structure_simplify (GstStructure ** result,
1660 const GstStructure * simplify, GstStructure * compare)
1663 UnionField field = { 0, {0,}, NULL };
1665 /* try to subtract to get a real subset */
1666 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1667 if (list == NULL) { /* no result */
1670 } else if (list->next == NULL) { /* one result */
1671 *result = list->data;
1672 g_slist_free (list);
1674 } else { /* multiple results */
1675 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1676 g_slist_free (list);
1681 /* try to union both structs */
1682 field.compare = compare;
1683 if (gst_structure_foreach ((GstStructure *) simplify,
1684 gst_caps_structure_figure_out_union, &field)) {
1685 gboolean ret = FALSE;
1687 /* now we know all of simplify's fields are the same in compare
1688 * but at most one field: field.name */
1689 if (G_IS_VALUE (&field.value)) {
1690 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1691 gst_structure_id_set_value (compare, field.name, &field.value);
1695 g_value_unset (&field.value);
1696 } else if (gst_structure_n_fields (simplify) <=
1697 gst_structure_n_fields (compare)) {
1698 /* compare is just more specific, will be optimized away later */
1699 /* FIXME: do this here? */
1700 GST_LOG ("found a case that will be optimized later.");
1702 gchar *one = gst_structure_to_string (simplify);
1703 gchar *two = gst_structure_to_string (compare);
1706 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1718 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1719 GstStructure * new, gint i)
1721 gst_structure_set_parent_refcount (old, NULL);
1722 gst_structure_free (old);
1723 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1724 g_ptr_array_index (caps->structs, i) = new;
1728 * gst_caps_do_simplify:
1729 * @caps: a #GstCaps to simplify
1731 * Modifies the given @caps inplace into a representation that represents the
1732 * same set of formats, but in a simpler form. Component structures that are
1733 * identical are merged. Component structures that have values that can be
1734 * merged are also merged.
1736 * Returns: TRUE, if the caps could be simplified
1739 gst_caps_do_simplify (GstCaps * caps)
1741 GstStructure *simplify, *compare, *result = NULL;
1743 gboolean changed = FALSE;
1745 g_return_val_if_fail (caps != NULL, FALSE);
1746 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1748 if (gst_caps_get_size (caps) < 2)
1751 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1753 start = caps->structs->len - 1;
1754 for (i = caps->structs->len - 1; i >= 0; i--) {
1755 simplify = gst_caps_get_structure_unchecked (caps, i);
1756 if (gst_structure_get_name_id (simplify) !=
1757 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1760 for (j = start; j >= 0; j--) {
1763 compare = gst_caps_get_structure_unchecked (caps, j);
1764 if (gst_structure_get_name_id (simplify) !=
1765 gst_structure_get_name_id (compare)) {
1768 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1770 gst_caps_switch_structures (caps, simplify, result, i);
1773 gst_caps_remove_structure (caps, i);
1785 /* gst_caps_do_simplify (caps); */
1793 * @caps: (inout) (transfer full): a pointer to #GstCaps
1794 * @newcaps: a #GstCaps to replace *caps
1796 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1797 * pointed to by @caps, if applicable, then modifies @caps to point to
1798 * @newcaps. An additional ref on @newcaps is taken.
1800 * This function does not take any locks so you might want to lock
1801 * the object owning @caps pointer.
1804 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1808 g_return_if_fail (caps != NULL);
1812 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1814 if (newcaps != oldcaps) {
1816 gst_caps_ref (newcaps);
1821 gst_caps_unref (oldcaps);
1826 * gst_caps_to_string:
1829 * Converts @caps to a string representation. This string representation
1830 * can be converted back to a #GstCaps by gst_caps_from_string().
1832 * For debugging purposes its easier to do something like this:
1834 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1836 * This prints the caps in human readble form.
1838 * Returns: (transfer full): a newly allocated string representing @caps.
1841 gst_caps_to_string (const GstCaps * caps)
1843 guint i, slen, clen;
1846 /* NOTE: This function is potentially called by the debug system,
1847 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1848 * should be careful to avoid recursion. This includes any functions
1849 * called by gst_caps_to_string. In particular, calls should
1850 * not use the GST_PTR_FORMAT extension. */
1853 return g_strdup ("NULL");
1855 if (CAPS_IS_ANY (caps)) {
1856 return g_strdup ("ANY");
1858 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1859 return g_strdup ("EMPTY");
1862 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1864 clen = caps->structs->len;
1865 for (i = 0; i < clen; i++) {
1867 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1871 s = g_string_sized_new (slen);
1872 for (i = 0; i < clen; i++) {
1873 GstStructure *structure;
1876 /* ';' is now added by gst_structure_to_string */
1877 g_string_append_c (s, ' ');
1880 structure = gst_caps_get_structure_unchecked (caps, i);
1881 priv_gst_structure_append_to_gstring (structure, s);
1883 if (s->len && s->str[s->len - 1] == ';') {
1884 /* remove latest ';' */
1885 s->str[--s->len] = '\0';
1887 return g_string_free (s, FALSE);
1891 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1893 GstStructure *structure;
1896 if (strcmp ("ANY", string) == 0) {
1897 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
1900 if (strcmp ("EMPTY", string) == 0) {
1904 structure = gst_structure_from_string (string, &s);
1905 if (structure == NULL) {
1908 gst_caps_append_structure_unchecked (caps, structure);
1912 while (g_ascii_isspace (*s))
1917 structure = gst_structure_from_string (s, &s);
1918 if (structure == NULL) {
1921 gst_caps_append_structure_unchecked (caps, structure);
1929 * gst_caps_from_string:
1930 * @string: a string to convert to #GstCaps
1932 * Converts @caps from a string representation.
1934 * Returns: (transfer full): a newly allocated #GstCaps
1937 gst_caps_from_string (const gchar * string)
1941 g_return_val_if_fail (string, FALSE);
1943 caps = gst_caps_new_empty ();
1944 if (gst_caps_from_string_inplace (caps, string)) {
1947 gst_caps_unref (caps);
1953 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1955 g_return_if_fail (G_IS_VALUE (src_value));
1956 g_return_if_fail (G_IS_VALUE (dest_value));
1957 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1958 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1959 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1961 dest_value->data[0].v_pointer =
1962 gst_caps_to_string (src_value->data[0].v_pointer);