2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gstcaps.c: Element capabilities subsystem
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 /* #define GST_DEBUG_ENABLED */
24 #include "gst_private.h"
30 static GMemChunk *_gst_caps_chunk;
31 static GMutex *_gst_caps_chunk_lock;
36 transform_func (const GValue *src_value,
39 GstCaps *caps = g_value_peek_pointer (src_value);
40 GString *result = g_string_new ("");
42 g_string_append_printf (result, "(GstCaps *) ");
46 GValue value = { 0, }; /* the important thing is that value.type = 0 */
48 g_string_append_printf (result,
49 "{ %s; ", gst_caps_get_mime (caps));
51 g_value_init (&value, GST_TYPE_PROPS);
52 g_value_set_boxed (&value, caps->properties);
53 props = g_strdup_value_contents (&value);
55 g_string_append (result, props);
59 g_string_append_printf (result, " }%s", caps?", ":"");
61 dest_value->data[0].v_pointer = result->str;
65 _gst_caps_initialize (void)
67 _gst_caps_chunk = g_mem_chunk_new ("GstCaps",
68 sizeof (GstCaps), sizeof (GstCaps) * 256,
70 _gst_caps_chunk_lock = g_mutex_new ();
72 _gst_caps_type = g_boxed_type_register_static ("GstCaps",
73 (GBoxedCopyFunc) gst_caps_ref,
74 (GBoxedFreeFunc) gst_caps_unref);
76 g_value_register_transform_func (_gst_caps_type,
82 get_type_for_mime (const gchar *mime)
86 typeid = gst_type_find_by_mime (mime);
88 GstTypeDefinition definition;
89 GstTypeFactory *factory;
91 definition.name = "capstype";
92 definition.mime = g_strdup (mime);
93 definition.exts = NULL;
94 definition.typefindfunc = NULL;
96 factory = gst_type_factory_new (&definition);
98 typeid = gst_type_register (factory);
105 * @name: the name of this capability
106 * @mime: the mime type to attach to the capability
107 * @props: the properties to add to this capability
109 * Create a new capability with the given mime type and properties.
111 * Returns: a new capability
114 gst_caps_new (const gchar *name, const gchar *mime, GstProps *props)
116 g_return_val_if_fail (mime != NULL, NULL);
118 return gst_caps_new_id (name, get_type_for_mime (mime), props);
123 * @name: the name of this capability
124 * @id: the id of the mime type
125 * @props: the properties to add to this capability
127 * Create a new capability with the given mime typeid and properties.
129 * Returns: a new capability
132 gst_caps_new_id (const gchar *name, const guint16 id, GstProps *props)
136 g_mutex_lock (_gst_caps_chunk_lock);
137 caps = g_mem_chunk_alloc (_gst_caps_chunk);
138 g_mutex_unlock (_gst_caps_chunk_lock);
140 caps->name = g_strdup (name);
142 caps->properties = props;
146 caps->fixed = props->fixed;
155 * @caps: the caps to destroy
157 * Frees the memory used by this caps structure and all
158 * the chained caps and properties.
161 gst_caps_destroy (GstCaps *caps)
170 gst_props_unref (caps->properties);
172 g_mutex_lock (_gst_caps_chunk_lock);
173 g_mem_chunk_free (_gst_caps_chunk, caps);
174 g_mutex_unlock (_gst_caps_chunk_lock);
177 gst_caps_unref (next);
182 * @caps: the caps to print out
183 * @label: a label to put on the printout, or NULL
185 * Print out the contents of the caps structure. Useful for debugging.
188 gst_caps_debug (GstCaps *caps, const gchar *label)
190 GST_DEBUG_ENTER ("caps debug: %s", label);
192 GST_DEBUG (GST_CAT_CAPS, "caps: %p %s %s (%sfixed)", caps, caps->name, gst_caps_get_mime (caps),
193 caps->fixed ? "" : "NOT ");
195 if (caps->properties) {
196 gst_props_debug (caps->properties);
199 GST_DEBUG (GST_CAT_CAPS, "no properties");
204 GST_DEBUG_LEAVE ("caps debug");
209 * @caps: the caps to unref
211 * Decrease the refcount of this caps structure,
212 * destroying it when the refcount is 0
214 * Returns: caps or NULL if the refcount reached 0
217 gst_caps_unref (GstCaps *caps)
225 g_return_val_if_fail (caps->refcount > 0, NULL);
228 zero = (caps->refcount == 0);
232 *next = gst_caps_unref (*next);
235 gst_caps_destroy (caps);
243 * @caps: the caps to ref
245 * Increase the refcount of this caps structure
247 * Returns: the caps with the refcount incremented
250 gst_caps_ref (GstCaps *caps)
252 g_return_val_if_fail (caps != NULL, NULL);
261 * @caps: the caps to copy
263 * Copies the caps, not copying any chained caps.
265 * Returns: a copy of the GstCaps structure.
268 gst_caps_copy_1 (GstCaps *caps)
275 newcaps = gst_caps_new_id (
278 gst_props_copy (caps->properties));
285 * @caps: the caps to copy
289 * Returns: a copy of the GstCaps structure.
292 gst_caps_copy (GstCaps *caps)
294 GstCaps *new = NULL, *walk = NULL;
299 newcaps = gst_caps_copy_1 (caps);
302 new = walk = newcaps;
305 walk = walk->next = newcaps;
314 * gst_caps_copy_on_write:
315 * @caps: the caps to copy
317 * Copies the caps if the refcount is greater than 1
319 * Returns: a pointer to a GstCaps strcuture that can
320 * be safely written to
323 gst_caps_copy_on_write (GstCaps *caps)
328 g_return_val_if_fail (caps != NULL, NULL);
330 needcopy = (caps->refcount > 1);
333 new = gst_caps_copy (caps);
334 gst_caps_unref (caps);
342 * @caps: the caps to get the name from
344 * Get the name of a GstCaps structure.
346 * Returns: the name of the caps
349 gst_caps_get_name (GstCaps *caps)
351 g_return_val_if_fail (caps != NULL, NULL);
353 return (const gchar *)caps->name;
358 * @caps: the caps to set the name to
359 * @name: the name to set
361 * Set the name of a caps.
364 gst_caps_set_name (GstCaps *caps, const gchar *name)
366 g_return_if_fail (caps != NULL);
371 caps->name = g_strdup (name);
376 * @caps: the caps to get the mime type from
378 * Get the mime type of the caps as a string.
380 * Returns: the mime type of the caps
383 gst_caps_get_mime (GstCaps *caps)
387 g_return_val_if_fail (caps != NULL, NULL);
389 type = gst_type_find_by_id (caps->id);
394 return "unknown/unknown";
399 * @caps: the caps to set the mime type to
400 * @mime: the mime type to attach to the caps
402 * Set the mime type of the caps as a string.
405 gst_caps_set_mime (GstCaps *caps, const gchar *mime)
407 g_return_if_fail (caps != NULL);
408 g_return_if_fail (mime != NULL);
410 caps->id = get_type_for_mime (mime);
414 * gst_caps_get_type_id:
415 * @caps: the caps to get the type id from
417 * Get the type id of the caps.
419 * Returns: the type id of the caps
422 gst_caps_get_type_id (GstCaps *caps)
424 g_return_val_if_fail (caps != NULL, 0);
430 * gst_caps_set_type_id:
431 * @caps: the caps to set the type id to
432 * @type_id: the type id to set
434 * Set the type id of the caps.
437 gst_caps_set_type_id (GstCaps *caps, guint16 type_id)
439 g_return_if_fail (caps != NULL);
445 * gst_caps_set_props:
446 * @caps: the caps to attach the properties to
447 * @props: the properties to attach
449 * Set the properties to the given caps.
451 * Returns: the new caps structure
454 gst_caps_set_props (GstCaps *caps, GstProps *props)
456 g_return_val_if_fail (caps != NULL, caps);
457 g_return_val_if_fail (props != NULL, caps);
458 g_return_val_if_fail (caps->properties == NULL, caps);
460 caps->properties = props;
466 * gst_caps_get_props:
467 * @caps: the caps to get the properties from
469 * Get the properties of the given caps.
471 * Returns: the properties of the caps
474 gst_caps_get_props (GstCaps *caps)
476 g_return_val_if_fail (caps != NULL, NULL);
478 return caps->properties;
484 * @...: more capabilities
486 * chains the given capabilities
488 * Returns: the new capability
491 gst_caps_chain (GstCaps *caps, ...)
493 GstCaps *orig = caps;
496 va_start (var_args, caps);
501 toadd = va_arg (var_args, GstCaps*);
502 gst_caps_append (caps, toadd);
514 * @capstoadd: the capability to append
516 * Appends a capability to the existing capability.
518 * Returns: the new capability
521 gst_caps_append (GstCaps *caps, GstCaps *capstoadd)
523 GstCaps *orig = caps;
525 if (caps == NULL || caps == capstoadd)
531 caps->next = capstoadd;
539 * @capstoadd: a capabilty to prepend
541 * prepend the capability to the list of capabilities
543 * Returns: the new capability
546 gst_caps_prepend (GstCaps *caps, GstCaps *capstoadd)
548 GstCaps *orig = capstoadd;
550 if (capstoadd == NULL)
553 g_return_val_if_fail (caps != capstoadd, caps);
555 while (capstoadd->next) {
556 capstoadd = capstoadd->next;
558 capstoadd->next = caps;
564 * gst_caps_get_by_name:
566 * @name: the name of the capability to get
568 * Get the capability with the given name from this
569 * chain of capabilities.
571 * Returns: the first capability in the chain with the
575 gst_caps_get_by_name (GstCaps *caps, const gchar *name)
577 g_return_val_if_fail (caps != NULL, NULL);
578 g_return_val_if_fail (name != NULL, NULL);
581 if (!strcmp (caps->name, name))
590 gst_caps_check_compatibility_func (GstCaps *fromcaps, GstCaps *tocaps)
592 if (fromcaps->id != tocaps->id) {
593 GST_DEBUG (GST_CAT_CAPS,"mime types differ (%s to %s)",
594 gst_type_find_by_id (fromcaps->id)->mime,
595 gst_type_find_by_id (tocaps->id)->mime);
599 if (tocaps->properties) {
600 if (fromcaps->properties) {
601 return gst_props_check_compatibility (fromcaps->properties, tocaps->properties);
604 GST_DEBUG (GST_CAT_CAPS,"no source caps");
609 /* assume it accepts everything */
610 GST_DEBUG (GST_CAT_CAPS,"no caps");
616 * gst_caps_is_always_compatible:
617 * @fromcaps: a #GstCaps capability to check compatibility of.
618 * @tocaps: the #GstCaps capabilty to check compatibility with.
620 * Checks if a connection is always possible from fromcaps to tocaps, for all
621 * possible capabilities.
623 * Returns: TRUE if compatible under all circumstances, FALSE otherwise.
626 gst_caps_is_always_compatible (GstCaps *fromcaps, GstCaps *tocaps)
628 if (fromcaps == NULL) {
629 if (tocaps == NULL) {
630 /* if both are NULL, they can always connect. Think filesrc ! filesink */
631 GST_DEBUG (GST_CAT_CAPS, "both caps NULL, compatible");
635 /* if source caps are NULL, it could be sending anything, so the
636 * destination can't know if it can accept this. Think filesrc ! mad */
637 GST_DEBUG (GST_CAT_CAPS, "source caps NULL, not guaranteed compatible");
642 if (tocaps == NULL) {
643 /* if the dest caps are NULL, the element can accept anything, always,
644 * so they're compatible by definition. Think mad ! filesink */
645 GST_DEBUG (GST_CAT_CAPS,"destination caps NULL");
651 GstCaps *destcaps = tocaps;
654 if (gst_caps_check_compatibility_func (fromcaps, destcaps))
657 destcaps = destcaps->next;
659 fromcaps = fromcaps->next;
665 gst_caps_intersect_func (GstCaps *caps1, GstCaps *caps2)
667 GstCaps *result = NULL;
670 if (caps1->id != caps2->id) {
671 GST_DEBUG (GST_CAT_CAPS, "mime types differ (%s to %s)",
672 gst_type_find_by_id (caps1->id)->mime,
673 gst_type_find_by_id (caps2->id)->mime);
677 if (caps1->properties == NULL) {
678 return gst_caps_ref (caps2);
680 if (caps2->properties == NULL) {
681 return gst_caps_ref (caps1);
684 props = gst_props_intersect (caps1->properties, caps2->properties);
686 result = gst_caps_new_id ("intersect", caps1->id, props);
693 * gst_caps_intersect:
694 * @caps1: a capability
695 * @caps2: a capability
697 * Make the intersection between two caps.
699 * Returns: The intersection of the two caps or NULL if the intersection
703 gst_caps_intersect (GstCaps *caps1, GstCaps *caps2)
705 GstCaps *result = NULL, *walk = NULL;
707 /* printing the name is not useful here since caps can be chained */
708 GST_DEBUG (GST_CAT_CAPS, "intersecting caps %p and %p", caps1, caps2);
711 GST_DEBUG (GST_CAT_CAPS, "first caps is NULL, return other caps");
712 return gst_caps_copy (caps2);
715 GST_DEBUG (GST_CAT_CAPS, "second caps is NULL, return other caps");
716 return gst_caps_copy (caps1);
720 GstCaps *othercaps = caps2;
723 GstCaps *intersection;
725 intersection = gst_caps_intersect_func (caps1, othercaps);
729 walk = result = intersection;
732 walk = walk->next = intersection;
735 othercaps = othercaps->next;
744 * gst_caps_normalize:
747 * Make the normalisation of the caps. This will return a new caps
748 * that is equivalent to the input caps with the exception that all
749 * lists are unrolled. This function is useful when you want to iterate
752 * Returns: The normalisation of the caps.
755 gst_caps_normalize (GstCaps *caps)
757 GstCaps *result = NULL, *walk = caps;
765 proplist = gst_props_normalize (caps->properties);
766 if (proplist && g_list_next (proplist) == NULL) {
768 walk = result = caps;
770 walk = walk->next = caps;
776 GstProps *props = (GstProps *) proplist->data;
777 GstCaps *newcaps = gst_caps_new_id (caps->name, caps->id, props);
780 walk = result = newcaps;
782 walk = walk->next = newcaps;
784 proplist = g_list_next (proplist);
792 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
794 * gst_caps_save_thyself:
795 * @caps: a capabilty to save
796 * @parent: the parent XML node pointer
798 * Save the capability into an XML representation.
800 * Returns: a new XML node pointer
803 gst_caps_save_thyself (GstCaps *caps, xmlNodePtr parent)
806 xmlNodePtr subsubtree;
809 subtree = xmlNewChild (parent, NULL, "capscomp", NULL);
811 xmlNewChild (subtree, NULL, "name", caps->name);
812 xmlNewChild (subtree, NULL, "type", gst_type_find_by_id (caps->id)->mime);
813 if (caps->properties) {
814 subsubtree = xmlNewChild (subtree, NULL, "properties", NULL);
816 gst_props_save_thyself (caps->properties, subsubtree);
826 * gst_caps_load_thyself:
827 * @parent: the parent XML node pointer
829 * Load a new caps from the XML representation.
831 * Returns: a new capability
834 gst_caps_load_thyself (xmlNodePtr parent)
836 GstCaps *result = NULL;
837 xmlNodePtr field = parent->xmlChildrenNode;
840 if (!strcmp (field->name, "capscomp")) {
841 xmlNodePtr subfield = field->xmlChildrenNode;
845 g_mutex_lock (_gst_caps_chunk_lock);
846 caps = g_mem_chunk_alloc0 (_gst_caps_chunk);
847 g_mutex_unlock (_gst_caps_chunk_lock);
854 if (!strcmp (subfield->name, "name")) {
855 caps->name = xmlNodeGetContent (subfield);
857 if (!strcmp (subfield->name, "type")) {
858 content = xmlNodeGetContent (subfield);
859 caps->id = get_type_for_mime (content);
862 else if (!strcmp (subfield->name, "properties")) {
863 caps->properties = gst_props_load_thyself (subfield);
866 subfield = subfield->next;
868 result = gst_caps_append (result, caps);
876 #endif /* GST_DISABLE_LOADSAVE_REGISTRY */