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 #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 */
1076 * gst_caps_can_intersect:
1077 * @caps1: a #GstCaps to intersect
1078 * @caps2: a #GstCaps to intersect
1080 * Tries intersecting @caps1 and @caps2 and reports whether the result would not
1083 * Returns: %TRUE if intersection would be not empty
1088 gst_caps_can_intersect (const GstCaps * caps1, const GstCaps * caps2)
1090 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1091 guint j, k, len1, len2;
1092 GstStructure *struct1;
1093 GstStructure *struct2;
1095 g_return_val_if_fail (GST_IS_CAPS (caps1), FALSE);
1096 g_return_val_if_fail (GST_IS_CAPS (caps2), FALSE);
1098 /* caps are exactly the same pointers */
1099 if (G_UNLIKELY (caps1 == caps2))
1102 /* empty caps on either side, return empty */
1103 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1106 /* one of the caps is any */
1107 if (G_UNLIKELY (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2)))
1110 /* run zigzag on top line then right line, this preserves the caps order
1111 * much better than a simple loop.
1113 * This algorithm zigzags over the caps structures as demonstrated in
1114 * the folowing matrix:
1117 * +------------- total distance: +-------------
1118 * | 1 2 4 7 0 | 0 1 2 3
1119 * caps2 | 3 5 8 10 1 | 1 2 3 4
1120 * | 6 9 11 12 2 | 2 3 4 5
1122 * First we iterate over the caps1 structures (top line) intersecting
1123 * the structures diagonally down, then we iterate over the caps2
1124 * structures. The result is that the intersections are ordered based on the
1125 * sum of the indexes in the list.
1127 len1 = caps1->structs->len;
1128 len2 = caps2->structs->len;
1129 for (i = 0; i < len1 + len2 - 1; i++) {
1130 /* superset index goes from 0 to sgst_caps_structure_intersectuperset->structs->len-1 */
1131 j = MIN (i, len1 - 1);
1132 /* subset index stays 0 until i reaches superset->structs->len, then it
1133 * counts up from 1 to subset->structs->len - 1 */
1136 /* now run the diagonal line, end condition is the left or bottom
1139 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1140 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1142 if (gst_structure_can_intersect (struct1, struct2)) {
1145 /* move down left */
1147 if (G_UNLIKELY (j == 0))
1148 break; /* so we don't roll back to G_MAXUINT */
1156 gst_caps_intersect_zig_zag (const GstCaps * caps1, const GstCaps * caps2)
1158 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1159 guint j, k, len1, len2;
1161 GstStructure *struct1;
1162 GstStructure *struct2;
1164 GstStructure *istruct;
1166 /* caps are exactly the same pointers, just copy one caps */
1167 if (G_UNLIKELY (caps1 == caps2))
1168 return _gst_caps_copy (caps1);
1170 /* empty caps on either side, return empty */
1171 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1172 return gst_caps_new_empty ();
1174 /* one of the caps is any, just copy the other caps */
1175 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1176 return _gst_caps_copy (caps2);
1177 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1178 return _gst_caps_copy (caps1);
1180 dest = gst_caps_new_empty ();
1182 /* run zigzag on top line then right line, this preserves the caps order
1183 * much better than a simple loop.
1185 * This algorithm zigzags over the caps structures as demonstrated in
1186 * the folowing matrix:
1194 * First we iterate over the caps1 structures (top line) intersecting
1195 * the structures diagonally down, then we iterate over the caps2
1198 len1 = caps1->structs->len;
1199 len2 = caps2->structs->len;
1200 for (i = 0; i < len1 + len2 - 1; i++) {
1201 /* caps1 index goes from 0 to caps1->structs->len-1 */
1202 j = MIN (i, len1 - 1);
1203 /* caps2 index stays 0 until i reaches caps1->structs->len, then it counts
1204 * up from 1 to caps2->structs->len - 1 */
1207 /* now run the diagonal line, end condition is the left or bottom
1210 struct1 = gst_caps_get_structure_unchecked (caps1, j);
1211 struct2 = gst_caps_get_structure_unchecked (caps2, k);
1213 istruct = gst_structure_intersect (struct1, struct2);
1215 gst_caps_merge_structure (dest, istruct);
1216 /* move down left */
1218 if (G_UNLIKELY (j == 0))
1219 break; /* so we don't roll back to G_MAXUINT */
1227 * gst_caps_intersect_first:
1228 * @caps1: a #GstCaps to intersect
1229 * @caps2: a #GstCaps to intersect
1231 * Creates a new #GstCaps that contains all the formats that are common
1232 * to both @caps1 and @caps2.
1234 * Unlike @gst_caps_intersect, the returned caps will be ordered in a similar
1235 * fashion as @caps1.
1237 * Returns: the new #GstCaps
1240 gst_caps_intersect_first (const GstCaps * caps1, const GstCaps * caps2)
1242 guint64 i; /* index can be up to 2 * G_MAX_UINT */
1243 guint j, len1, len2;
1245 GstStructure *struct1;
1246 GstStructure *struct2;
1248 GstStructure *istruct;
1250 /* caps are exactly the same pointers, just copy one caps */
1251 if (G_UNLIKELY (caps1 == caps2))
1252 return gst_caps_copy (caps1);
1254 /* empty caps on either side, return empty */
1255 if (G_UNLIKELY (CAPS_IS_EMPTY (caps1) || CAPS_IS_EMPTY (caps2)))
1256 return gst_caps_new_empty ();
1258 /* one of the caps is any, just copy the other caps */
1259 if (G_UNLIKELY (CAPS_IS_ANY (caps1)))
1260 return gst_caps_copy (caps2);
1261 if (G_UNLIKELY (CAPS_IS_ANY (caps2)))
1262 return gst_caps_copy (caps1);
1264 dest = gst_caps_new_empty ();
1266 len1 = caps1->structs->len;
1267 len2 = caps2->structs->len;
1268 for (i = 0; i < len1; i++) {
1269 struct1 = gst_caps_get_structure_unchecked (caps1, i);
1270 for (j = 0; j < len2; j++) {
1271 struct2 = gst_caps_get_structure_unchecked (caps2, j);
1272 istruct = gst_structure_intersect (struct1, struct2);
1274 gst_caps_merge_structure (dest, istruct);
1282 * gst_caps_intersect_full:
1283 * @caps1: a #GstCaps to intersect
1284 * @caps2: a #GstCaps to intersect
1285 * @mode: The intersection algorithm/mode to use
1287 * Creates a new #GstCaps that contains all the formats that are common
1288 * to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode
1291 * Returns: the new #GstCaps
1295 gst_caps_intersect_full (const GstCaps * caps1, const GstCaps * caps2,
1296 GstCapsIntersectMode mode)
1298 g_return_val_if_fail (GST_IS_CAPS (caps1), NULL);
1299 g_return_val_if_fail (GST_IS_CAPS (caps2), NULL);
1302 case GST_CAPS_INTERSECT_FIRST:
1303 return gst_caps_intersect_first (caps1, caps2);
1305 g_warning ("Unknown caps intersect mode: %d", mode);
1307 case GST_CAPS_INTERSECT_ZIG_ZAG:
1308 return gst_caps_intersect_zig_zag (caps1, caps2);
1313 * gst_caps_intersect:
1314 * @caps1: a #GstCaps to intersect
1315 * @caps2: a #GstCaps to intersect
1317 * Creates a new #GstCaps that contains all the formats that are common
1318 * to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode.
1320 * Returns: the new #GstCaps
1323 gst_caps_intersect (const GstCaps * caps1, const GstCaps * caps2)
1325 return gst_caps_intersect_full (caps1, caps2, GST_CAPS_INTERSECT_ZIG_ZAG);
1329 /* subtract operation */
1333 const GstStructure *subtract_from;
1339 gst_caps_structure_subtract_field (GQuark field_id, const GValue * value,
1342 SubtractionEntry *e = user_data;
1343 GValue subtraction = { 0, };
1344 const GValue *other;
1345 GstStructure *structure;
1347 other = gst_structure_id_get_value (e->subtract_from, field_id);
1351 if (!gst_value_subtract (&subtraction, other, value))
1353 if (gst_value_compare (&subtraction, other) == GST_VALUE_EQUAL) {
1354 g_value_unset (&subtraction);
1357 structure = gst_structure_copy (e->subtract_from);
1358 gst_structure_id_set_value (structure, field_id, &subtraction);
1359 g_value_unset (&subtraction);
1360 e->put_into = g_slist_prepend (e->put_into, structure);
1366 gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
1367 const GstStructure * subtrahend)
1372 e.subtract_from = minuend;
1375 ret = gst_structure_foreach ((GstStructure *) subtrahend,
1376 gst_caps_structure_subtract_field, &e);
1382 for (walk = e.put_into; walk; walk = g_slist_next (walk)) {
1383 gst_structure_free (walk->data);
1385 g_slist_free (e.put_into);
1391 * gst_caps_subtract:
1392 * @minuend: #GstCaps to substract from
1393 * @subtrahend: #GstCaps to substract
1395 * Subtracts the @subtrahend from the @minuend.
1396 * <note>This function does not work reliably if optional properties for caps
1397 * are included on one caps and omitted on the other.</note>
1399 * Returns: the resulting caps
1402 gst_caps_subtract (const GstCaps * minuend, const GstCaps * subtrahend)
1407 GstCaps *dest = NULL, *src;
1409 g_return_val_if_fail (minuend != NULL, NULL);
1410 g_return_val_if_fail (subtrahend != NULL, NULL);
1412 if (CAPS_IS_EMPTY (minuend) || CAPS_IS_ANY (subtrahend)) {
1413 return gst_caps_new_empty ();
1415 if (CAPS_IS_EMPTY_SIMPLE (subtrahend))
1416 return _gst_caps_copy (minuend);
1418 /* FIXME: Do we want this here or above?
1419 The reason we need this is that there is no definition about what
1420 ANY means for specific types, so it's not possible to reduce ANY partially
1421 You can only remove everything or nothing and that is done above.
1422 Note: there's a test that checks this behaviour. */
1423 g_return_val_if_fail (!CAPS_IS_ANY (minuend), NULL);
1424 sublen = subtrahend->structs->len;
1425 g_assert (sublen > 0);
1427 src = _gst_caps_copy (minuend);
1428 for (i = 0; i < sublen; i++) {
1431 sub = gst_caps_get_structure_unchecked (subtrahend, i);
1433 gst_caps_unref (src);
1436 dest = gst_caps_new_empty ();
1437 srclen = src->structs->len;
1438 for (j = 0; j < srclen; j++) {
1439 min = gst_caps_get_structure_unchecked (src, j);
1440 if (gst_structure_get_name_id (min) == gst_structure_get_name_id (sub)) {
1443 if (gst_caps_structure_subtract (&list, min, sub)) {
1446 for (walk = list; walk; walk = g_slist_next (walk)) {
1447 gst_caps_append_structure_unchecked (dest,
1448 (GstStructure *) walk->data);
1450 g_slist_free (list);
1452 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1455 gst_caps_append_structure_unchecked (dest, gst_structure_copy (min));
1458 if (CAPS_IS_EMPTY_SIMPLE (dest)) {
1459 gst_caps_unref (src);
1464 gst_caps_unref (src);
1465 gst_caps_do_simplify (dest);
1469 /* union operation */
1472 static GstStructure *
1473 gst_caps_structure_union (const GstStructure * struct1,
1474 const GstStructure * struct2)
1478 const GstStructureField *field1;
1479 const GstStructureField *field2;
1482 /* FIXME this doesn't actually work */
1484 if (struct1->name != struct2->name)
1487 dest = gst_structure_id_empty_new (struct1->name);
1489 for (i = 0; i < struct1->fields->len; i++) {
1490 GValue dest_value = { 0 };
1492 field1 = GST_STRUCTURE_FIELD (struct1, i);
1493 field2 = gst_structure_id_get_field (struct2, field1->name);
1495 if (field2 == NULL) {
1498 if (gst_value_union (&dest_value, &field1->value, &field2->value)) {
1499 gst_structure_set_value (dest, g_quark_to_string (field1->name),
1502 ret = gst_value_compare (&field1->value, &field2->value);
1513 * @caps1: a #GstCaps to union
1514 * @caps2: a #GstCaps to union
1516 * Creates a new #GstCaps that contains all the formats that are in
1517 * either @caps1 and @caps2.
1519 * Returns: the new #GstCaps
1522 gst_caps_union (const GstCaps * caps1, const GstCaps * caps2)
1527 /* NULL pointers are no correct GstCaps */
1528 g_return_val_if_fail (caps1 != NULL, NULL);
1529 g_return_val_if_fail (caps2 != NULL, NULL);
1531 if (CAPS_IS_EMPTY (caps1))
1532 return _gst_caps_copy (caps2);
1534 if (CAPS_IS_EMPTY (caps2))
1535 return _gst_caps_copy (caps1);
1537 if (CAPS_IS_ANY (caps1) || CAPS_IS_ANY (caps2))
1538 return gst_caps_new_any ();
1540 dest1 = _gst_caps_copy (caps1);
1541 dest2 = _gst_caps_copy (caps2);
1542 gst_caps_append (dest1, dest2);
1544 gst_caps_do_simplify (dest1);
1548 /* normalize/simplify operations */
1550 typedef struct _NormalizeForeach
1553 GstStructure *structure;
1558 gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
1560 NormalizeForeach *nf = (NormalizeForeach *) ptr;
1564 if (G_VALUE_TYPE (value) == GST_TYPE_LIST) {
1565 guint len = gst_value_list_get_size (value);
1566 for (i = 1; i < len; i++) {
1567 const GValue *v = gst_value_list_get_value (value, i);
1568 GstStructure *structure = gst_structure_copy (nf->structure);
1570 gst_structure_id_set_value (structure, field_id, v);
1571 gst_caps_append_structure_unchecked (nf->caps, structure);
1574 gst_value_init_and_copy (&val, gst_value_list_get_value (value, 0));
1575 gst_structure_id_set_value (nf->structure, field_id, &val);
1576 g_value_unset (&val);
1584 * gst_caps_normalize:
1585 * @caps: a #GstCaps to normalize
1587 * Creates a new #GstCaps that represents the same set of formats as
1588 * @caps, but contains no lists. Each list is expanded into separate
1591 * Returns: the new #GstCaps
1594 gst_caps_normalize (const GstCaps * caps)
1596 NormalizeForeach nf;
1600 g_return_val_if_fail (GST_IS_CAPS (caps), NULL);
1602 newcaps = _gst_caps_copy (caps);
1605 for (i = 0; i < gst_caps_get_size (newcaps); i++) {
1606 nf.structure = gst_caps_get_structure_unchecked (newcaps, i);
1608 while (!gst_structure_foreach (nf.structure,
1609 gst_caps_normalize_foreach, &nf));
1616 gst_caps_compare_structures (gconstpointer one, gconstpointer two)
1619 const GstStructure *struct1 = *((const GstStructure **) one);
1620 const GstStructure *struct2 = *((const GstStructure **) two);
1622 /* FIXME: this orders alphabetically, but ordering the quarks might be faster
1623 So what's the best way? */
1624 ret = strcmp (gst_structure_get_name (struct1),
1625 gst_structure_get_name (struct2));
1629 return gst_structure_n_fields (struct2) - gst_structure_n_fields (struct1);
1636 GstStructure *compare;
1641 gst_caps_structure_figure_out_union (GQuark field_id, const GValue * value,
1644 UnionField *u = user_data;
1645 const GValue *val = gst_structure_id_get_value (u->compare, field_id);
1649 g_value_unset (&u->value);
1652 if (gst_value_compare (val, value) == GST_VALUE_EQUAL)
1655 g_value_unset (&u->value);
1659 gst_value_union (&u->value, val, value);
1664 gst_caps_structure_simplify (GstStructure ** result,
1665 const GstStructure * simplify, GstStructure * compare)
1668 UnionField field = { 0, {0,}, NULL };
1670 /* try to subtract to get a real subset */
1671 if (gst_caps_structure_subtract (&list, simplify, compare)) {
1672 if (list == NULL) { /* no result */
1675 } else if (list->next == NULL) { /* one result */
1676 *result = list->data;
1677 g_slist_free (list);
1679 } else { /* multiple results */
1680 g_slist_foreach (list, (GFunc) gst_structure_free, NULL);
1681 g_slist_free (list);
1686 /* try to union both structs */
1687 field.compare = compare;
1688 if (gst_structure_foreach ((GstStructure *) simplify,
1689 gst_caps_structure_figure_out_union, &field)) {
1690 gboolean ret = FALSE;
1692 /* now we know all of simplify's fields are the same in compare
1693 * but at most one field: field.name */
1694 if (G_IS_VALUE (&field.value)) {
1695 if (gst_structure_n_fields (simplify) == gst_structure_n_fields (compare)) {
1696 gst_structure_id_set_value (compare, field.name, &field.value);
1700 g_value_unset (&field.value);
1701 } else if (gst_structure_n_fields (simplify) <=
1702 gst_structure_n_fields (compare)) {
1703 /* compare is just more specific, will be optimized away later */
1704 /* FIXME: do this here? */
1705 GST_LOG ("found a case that will be optimized later.");
1707 gchar *one = gst_structure_to_string (simplify);
1708 gchar *two = gst_structure_to_string (compare);
1711 ("caps mismatch: structures %s and %s claim to be possible to unify, but aren't",
1723 gst_caps_switch_structures (GstCaps * caps, GstStructure * old,
1724 GstStructure * new, gint i)
1726 gst_structure_set_parent_refcount (old, NULL);
1727 gst_structure_free (old);
1728 gst_structure_set_parent_refcount (new, &GST_CAPS_REFCOUNT (caps));
1729 g_ptr_array_index (caps->structs, i) = new;
1733 * gst_caps_do_simplify:
1734 * @caps: a #GstCaps to simplify
1736 * Modifies the given @caps inplace into a representation that represents the
1737 * same set of formats, but in a simpler form. Component structures that are
1738 * identical are merged. Component structures that have values that can be
1739 * merged are also merged.
1741 * Returns: TRUE, if the caps could be simplified
1744 gst_caps_do_simplify (GstCaps * caps)
1746 GstStructure *simplify, *compare, *result = NULL;
1748 gboolean changed = FALSE;
1750 g_return_val_if_fail (caps != NULL, FALSE);
1751 g_return_val_if_fail (IS_WRITABLE (caps), FALSE);
1753 if (gst_caps_get_size (caps) < 2)
1756 g_ptr_array_sort (caps->structs, gst_caps_compare_structures);
1758 start = caps->structs->len - 1;
1759 for (i = caps->structs->len - 1; i >= 0; i--) {
1760 simplify = gst_caps_get_structure_unchecked (caps, i);
1761 if (gst_structure_get_name_id (simplify) !=
1762 gst_structure_get_name_id (gst_caps_get_structure_unchecked (caps,
1765 for (j = start; j >= 0; j--) {
1768 compare = gst_caps_get_structure_unchecked (caps, j);
1769 if (gst_structure_get_name_id (simplify) !=
1770 gst_structure_get_name_id (compare)) {
1773 if (gst_caps_structure_simplify (&result, simplify, compare)) {
1775 gst_caps_switch_structures (caps, simplify, result, i);
1778 gst_caps_remove_structure (caps, i);
1790 /* gst_caps_do_simplify (caps); */
1798 * @caps: (inout) (transfer full): a pointer to #GstCaps
1799 * @newcaps: a #GstCaps to replace *caps
1801 * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
1802 * pointed to by @caps, if applicable, then modifies @caps to point to
1803 * @newcaps. An additional ref on @newcaps is taken.
1805 * This function does not take any locks so you might want to lock
1806 * the object owning @caps pointer.
1809 gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
1813 g_return_if_fail (caps != NULL);
1817 GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p, %p -> %p", caps, oldcaps, newcaps);
1819 if (newcaps != oldcaps) {
1821 gst_caps_ref (newcaps);
1826 gst_caps_unref (oldcaps);
1831 * gst_caps_to_string:
1834 * Converts @caps to a string representation. This string representation
1835 * can be converted back to a #GstCaps by gst_caps_from_string().
1837 * For debugging purposes its easier to do something like this:
1839 * GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
1841 * This prints the caps in human readble form.
1843 * Returns: (transfer full): a newly allocated string representing @caps.
1846 gst_caps_to_string (const GstCaps * caps)
1848 guint i, slen, clen;
1851 /* NOTE: This function is potentially called by the debug system,
1852 * so any calls to gst_log() (and GST_DEBUG(), GST_LOG(), etc.)
1853 * should be careful to avoid recursion. This includes any functions
1854 * called by gst_caps_to_string. In particular, calls should
1855 * not use the GST_PTR_FORMAT extension. */
1858 return g_strdup ("NULL");
1860 if (CAPS_IS_ANY (caps)) {
1861 return g_strdup ("ANY");
1863 if (CAPS_IS_EMPTY_SIMPLE (caps)) {
1864 return g_strdup ("EMPTY");
1867 /* estimate a rough string length to avoid unnecessary reallocs in GString */
1869 clen = caps->structs->len;
1870 for (i = 0; i < clen; i++) {
1872 STRUCTURE_ESTIMATED_STRING_LEN (gst_caps_get_structure_unchecked (caps,
1876 s = g_string_sized_new (slen);
1877 for (i = 0; i < clen; i++) {
1878 GstStructure *structure;
1881 /* ';' is now added by gst_structure_to_string */
1882 g_string_append_c (s, ' ');
1885 structure = gst_caps_get_structure_unchecked (caps, i);
1886 priv_gst_structure_append_to_gstring (structure, s);
1888 if (s->len && s->str[s->len - 1] == ';') {
1889 /* remove latest ';' */
1890 s->str[--s->len] = '\0';
1892 return g_string_free (s, FALSE);
1896 gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
1898 GstStructure *structure;
1901 if (strcmp ("ANY", string) == 0) {
1902 GST_CAPS_FLAGS (caps) = GST_CAPS_FLAGS_ANY;
1905 if (strcmp ("EMPTY", string) == 0) {
1909 structure = gst_structure_from_string (string, &s);
1910 if (structure == NULL) {
1913 gst_caps_append_structure_unchecked (caps, structure);
1917 while (g_ascii_isspace (*s))
1922 structure = gst_structure_from_string (s, &s);
1923 if (structure == NULL) {
1926 gst_caps_append_structure_unchecked (caps, structure);
1934 * gst_caps_from_string:
1935 * @string: a string to convert to #GstCaps
1937 * Converts @caps from a string representation.
1939 * Returns: (transfer full): a newly allocated #GstCaps
1942 gst_caps_from_string (const gchar * string)
1946 g_return_val_if_fail (string, FALSE);
1948 caps = gst_caps_new_empty ();
1949 if (gst_caps_from_string_inplace (caps, string)) {
1952 gst_caps_unref (caps);
1958 gst_caps_transform_to_string (const GValue * src_value, GValue * dest_value)
1960 g_return_if_fail (G_IS_VALUE (src_value));
1961 g_return_if_fail (G_IS_VALUE (dest_value));
1962 g_return_if_fail (G_VALUE_HOLDS (src_value, GST_TYPE_CAPS));
1963 g_return_if_fail (G_VALUE_HOLDS (dest_value, G_TYPE_STRING)
1964 || G_VALUE_HOLDS (dest_value, G_TYPE_POINTER));
1966 dest_value->data[0].v_pointer =
1967 gst_caps_to_string (src_value->data[0].v_pointer);