gst/gstcaps.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstcaps.c: Element capabilities subsystem
   6  *
   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.
  11  *
  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.
  16  *
  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.
  21  */
  22
  23 /* #define GST_DEBUG_ENABLED */
  24 #include "gst_private.h"
  25
  26 #include "gstcaps.h"
  27 #include "gsttype.h"
  28
  29 static GMemChunk *_gst_caps_chunk;
  30 static GMutex *_gst_caps_chunk_lock;
  31
  32 GType _gst_caps_type;
  33
  34 void
  35 _gst_caps_initialize (void)
  36 {
  37   _gst_caps_chunk = g_mem_chunk_new ("GstCaps",
  38                   sizeof (GstCaps), sizeof (GstCaps) * 256,
  39                   G_ALLOC_AND_FREE);
  40   _gst_caps_chunk_lock = g_mutex_new ();
  41
  42   _gst_caps_type = g_boxed_type_register_static ("GstCaps",
  43                                        (GBoxedCopyFunc) gst_caps_ref,
  44                                        (GBoxedFreeFunc) gst_caps_unref);
  45
  46 }
  47
  48 static guint16
  49 get_type_for_mime (const gchar *mime)
  50 {
  51   guint16 typeid;
  52
  53   typeid = gst_type_find_by_mime (mime);
  54   if (typeid == 0) {
  55      GstTypeDefinition definition;
  56      GstTypeFactory *factory;
  57
  58      definition.name = "capstype";
  59      definition.mime = g_strdup (mime);
  60      definition.exts = NULL;
  61      definition.typefindfunc = NULL;
  62
  63      factory = gst_type_factory_new (&definition);
  64
  65      typeid = gst_type_register (factory);
  66   }
  67   return typeid;
  68 }
  69
  70 /**
  71  * gst_caps_new:
  72  * @name: the name of this capability
  73  * @mime: the mime type to attach to the capability
  74  * @props: the properties to add to this capability
  75  *
  76  * Create a new capability with the given mime typei and properties.
  77  *
  78  * Returns: a new capability
  79  */
  80 GstCaps*
  81 gst_caps_new (const gchar *name, const gchar *mime, GstProps *props)
  82 {
  83   g_return_val_if_fail (mime != NULL, NULL);
  84
  85   return gst_caps_new_id (name, get_type_for_mime (mime), props);
  86 }
  87
  88 /**
  89  * gst_caps_new_id:
  90  * @name: the name of this capability
  91  * @id: the id of the mime type
  92  * @props: the properties to add to this capability
  93  *
  94  * Create a new capability with the given mime typeid and properties.
  95  *
  96  * Returns: a new capability
  97  */
  98 GstCaps*
  99 gst_caps_new_id (const gchar *name, const guint16 id, GstProps *props)
 100 {
 101   GstCaps *caps;
 102
 103   g_mutex_lock (_gst_caps_chunk_lock);
 104   caps = g_mem_chunk_alloc (_gst_caps_chunk);
 105   g_mutex_unlock (_gst_caps_chunk_lock);
 106
 107   caps->name = g_strdup (name);
 108   caps->id = id;
 109   caps->properties = props;
 110   caps->next = NULL;
 111   caps->refcount = 1;
 112   if (props)
 113     caps->fixed = props->fixed;
 114   else
 115     caps->fixed = TRUE;
 116
 117   return caps;
 118 }
 119
 120 /**
 121  * gst_caps_destroy:
 122  * @caps: the caps to destroy
 123  *
 124  * Frees the memory used by this caps structure and all
 125  * the chained caps and properties.
 126  */
 127 void
 128 gst_caps_destroy (GstCaps *caps)
 129 {
 130   GstCaps *next;
 131
 132   if (caps == NULL)
 133     return;
 134
 135   next = caps->next;
 136
 137   gst_props_unref (caps->properties);
 138   g_free (caps->name);
 139   g_mutex_lock (_gst_caps_chunk_lock);
 140   g_mem_chunk_free (_gst_caps_chunk, caps);
 141   g_mutex_unlock (_gst_caps_chunk_lock);
 142
 143   if (next)
 144     gst_caps_unref (next);
 145 }
 146
 147 /**
 148  * gst_caps_debug:
 149  * @caps: the caps to print out
 150  * @label: a label to put on the printout, or NULL
 151  *
 152  * Print out the contents of the caps structure. Useful for debugging.
 153  */
 154 void
 155 gst_caps_debug (GstCaps *caps, const gchar *label)
 156 {
 157   GST_DEBUG_ENTER ("caps debug: %s", label);
 158   while (caps) {
 159     GST_DEBUG (GST_CAT_CAPS, "caps: %p %s %s (%sfixed)", caps, caps->name, gst_caps_get_mime (caps),
 160                caps->fixed ? "" : "NOT ");
 161
 162     if (caps->properties) {
 163       gst_props_debug (caps->properties);
 164     }
 165     else {
 166       GST_DEBUG (GST_CAT_CAPS, "no properties");
 167     }
 168
 169     caps = caps->next;
 170   }
 171   GST_DEBUG_LEAVE ("caps debug");
 172 }
 173
 174 /**
 175  * gst_caps_unref:
 176  * @caps: the caps to unref
 177  *
 178  * Decrease the refcount of this caps structure,
 179  * destroying it when the refcount is 0
 180  *
 181  * Returns: caps or NULL if the refcount reached 0
 182  */
 183 GstCaps*
 184 gst_caps_unref (GstCaps *caps)
 185 {
 186   gboolean zero;
 187   GstCaps **next;
 188
 189   if (caps == NULL)
 190     return NULL;
 191
 192   g_return_val_if_fail (caps->refcount > 0, NULL);
 193
 194   caps->refcount--;
 195   zero = (caps->refcount == 0);
 196   next = &caps->next;
 197
 198   if (*next)
 199     *next = gst_caps_unref (*next);
 200
 201   if (zero) {
 202     gst_caps_destroy (caps);
 203     caps = NULL;
 204   }
 205   return caps;
 206 }
 207
 208 /**
 209  * gst_caps_ref:
 210  * @caps: the caps to ref
 211  *
 212  * Increase the refcount of this caps structure
 213  *
 214  * Returns: the caps with the refcount incremented
 215  */
 216 GstCaps*
 217 gst_caps_ref (GstCaps *caps)
 218 {
 219   g_return_val_if_fail (caps != NULL, NULL);
 220
 221   caps->refcount++;
 222
 223   return caps;
 224 }
 225
 226 /**
 227  * gst_caps_copy_1:
 228  * @caps: the caps to copy
 229  *
 230  * Copies the caps, not copying any chained caps.
 231  *
 232  * Returns: a copy of the GstCaps structure.
 233  */
 234 GstCaps*
 235 gst_caps_copy_1 (GstCaps *caps)
 236 {
 237   GstCaps *newcaps;
 238
 239   if (!caps)
 240     return NULL;
 241
 242   newcaps = gst_caps_new_id (
 243                   caps->name,
 244                   caps->id,
 245                   gst_props_copy (caps->properties));
 246
 247   return newcaps;
 248 }
 249
 250 /**
 251  * gst_caps_copy:
 252  * @caps: the caps to copy
 253  *
 254  * Copies the caps.
 255  *
 256  * Returns: a copy of the GstCaps structure.
 257  */
 258 GstCaps*
 259 gst_caps_copy (GstCaps *caps)
 260 {
 261   GstCaps *new = NULL, *walk = NULL;
 262
 263   while (caps) {
 264     GstCaps *newcaps;
 265
 266     newcaps = gst_caps_copy_1 (caps);
 267
 268     if (new == NULL) {
 269       new = walk = newcaps;
 270     }
 271     else {
 272       walk = walk->next = newcaps;
 273     }
 274     caps = caps->next;
 275   }
 276
 277   return new;
 278 }
 279
 280 /**
 281  * gst_caps_copy_on_write:
 282  * @caps: the caps to copy
 283  *
 284  * Copies the caps if the refcount is greater than 1
 285  *
 286  * Returns: a pointer to a GstCaps strcuture that can
 287  * be safely written to
 288  */
 289 GstCaps*
 290 gst_caps_copy_on_write (GstCaps *caps)
 291 {
 292   GstCaps *new = caps;
 293   gboolean needcopy;
 294
 295   g_return_val_if_fail (caps != NULL, NULL);
 296
 297   needcopy = (caps->refcount > 1);
 298
 299   if (needcopy) {
 300     new = gst_caps_copy (caps);
 301     gst_caps_unref (caps);
 302   }
 303
 304   return new;
 305 }
 306
 307 /**
 308  * gst_caps_get_name:
 309  * @caps: the caps to get the name from
 310  *
 311  * Get the name of a GstCaps structure.
 312  *
 313  * Returns: the name of the caps
 314  */
 315 const gchar*
 316 gst_caps_get_name (GstCaps *caps)
 317 {
 318   g_return_val_if_fail (caps != NULL, NULL);
 319
 320   return (const gchar *)caps->name;
 321 }
 322
 323 /**
 324  * gst_caps_set_name:
 325  * @caps: the caps to set the name to
 326  * @name: the name to set
 327  *
 328  * Set the name of a caps.
 329  */
 330 void
 331 gst_caps_set_name (GstCaps *caps, const gchar *name)
 332 {
 333   g_return_if_fail (caps != NULL);
 334
 335   if (caps->name)
 336     g_free (caps->name);
 337
 338   caps->name = g_strdup (name);
 339 }
 340
 341 /**
 342  * gst_caps_get_mime:
 343  * @caps: the caps to get the mime type from
 344  *
 345  * Get the mime type of the caps as a string.
 346  *
 347  * Returns: the mime type of the caps
 348  */
 349 const gchar*
 350 gst_caps_get_mime (GstCaps *caps)
 351 {
 352   GstType *type;
 353
 354   g_return_val_if_fail (caps != NULL, NULL);
 355
 356   type = gst_type_find_by_id (caps->id);
 357
 358   if (type)
 359     return type->mime;
 360   else
 361     return "unknown/unknown";
 362 }
 363
 364 /**
 365  * gst_caps_set_mime:
 366  * @caps: the caps to set the mime type to
 367  * @mime: the mime type to attach to the caps
 368  *
 369  * Set the mime type of the caps as a string.
 370  */
 371 void
 372 gst_caps_set_mime (GstCaps *caps, const gchar *mime)
 373 {
 374   g_return_if_fail (caps != NULL);
 375   g_return_if_fail (mime != NULL);
 376
 377   caps->id = get_type_for_mime (mime);
 378 }
 379
 380 /**
 381  * gst_caps_get_type_id:
 382  * @caps: the caps to get the type id from
 383  *
 384  * Get the type id of the caps.
 385  *
 386  * Returns: the type id of the caps
 387  */
 388 guint16
 389 gst_caps_get_type_id (GstCaps *caps)
 390 {
 391   g_return_val_if_fail (caps != NULL, 0);
 392
 393   return caps->id;
 394 }
 395
 396 /**
 397  * gst_caps_set_type_id:
 398  * @caps: the caps to set the type id to
 399  * @type_id: the type id to set
 400  *
 401  * Set the type id of the caps.
 402  */
 403 void
 404 gst_caps_set_type_id (GstCaps *caps, guint16 type_id)
 405 {
 406   g_return_if_fail (caps != NULL);
 407
 408   caps->id = type_id;
 409 }
 410
 411 /**
 412  * gst_caps_set_props:
 413  * @caps: the caps to attach the properties to
 414  * @props: the properties to attach
 415  *
 416  * Set the properties to the given caps.
 417  *
 418  * Returns: the new caps structure
 419  */
 420 GstCaps*
 421 gst_caps_set_props (GstCaps *caps, GstProps *props)
 422 {
 423   g_return_val_if_fail (caps != NULL, caps);
 424   g_return_val_if_fail (props != NULL, caps);
 425   g_return_val_if_fail (caps->properties == NULL, caps);
 426
 427   caps->properties = props;
 428
 429   return caps;
 430 }
 431
 432 /**
 433  * gst_caps_get_props:
 434  * @caps: the caps to get the properties from
 435  *
 436  * Get the properties of the given caps.
 437  *
 438  * Returns: the properties of the caps
 439  */
 440 GstProps*
 441 gst_caps_get_props (GstCaps *caps)
 442 {
 443   g_return_val_if_fail (caps != NULL, NULL);
 444
 445   return caps->properties;
 446 }
 447
 448 /**
 449  * gst_caps_chain:
 450  * @caps: a capabilty
 451  * @...: more capabilities
 452  *
 453  * chains the given capabilities
 454  *
 455  * Returns: the new capability
 456  */
 457 GstCaps*
 458 gst_caps_chain (GstCaps *caps, ...)
 459 {
 460   GstCaps *orig = caps;
 461   va_list var_args;
 462
 463   va_start (var_args, caps);
 464
 465   while (caps) {
 466     GstCaps *toadd;
 467
 468     toadd = va_arg (var_args, GstCaps*);
 469     gst_caps_append (caps, toadd);
 470
 471     caps = toadd;
 472   }
 473   va_end (var_args);
 474
 475   return orig;
 476 }
 477
 478 /**
 479  * gst_caps_append:
 480  * @caps: a capabilty
 481  * @capstoadd: the capability to append
 482  *
 483  * Appends a capability to the existing capability.
 484  *
 485  * Returns: the new capability
 486  */
 487 GstCaps*
 488 gst_caps_append (GstCaps *caps, GstCaps *capstoadd)
 489 {
 490   GstCaps *orig = caps;
 491
 492   if (caps == NULL || caps == capstoadd)
 493     return capstoadd;
 494
 495   while (caps->next) {
 496     caps = caps->next;
 497   }
 498   caps->next = capstoadd;
 499
 500   return orig;
 501 }
 502
 503 /**
 504  * gst_caps_prepend:
 505  * @caps: a capabilty
 506  * @capstoadd: a capabilty to prepend
 507  *
 508  * prepend the capability to the list of capabilities
 509  *
 510  * Returns: the new capability
 511  */
 512 GstCaps*
 513 gst_caps_prepend (GstCaps *caps, GstCaps *capstoadd)
 514 {
 515   GstCaps *orig = capstoadd;
 516
 517   if (capstoadd == NULL)
 518     return caps;
 519
 520   g_return_val_if_fail (caps != capstoadd, caps);
 521
 522   while (capstoadd->next) {
 523     capstoadd = capstoadd->next;
 524   }
 525   capstoadd->next = caps;
 526
 527   return orig;
 528 }
 529
 530 /**
 531  * gst_caps_get_by_name:
 532  * @caps: a capabilty
 533  * @name: the name of the capability to get
 534  *
 535  * Get the capability with the given name from this
 536  * chain of capabilities.
 537  *
 538  * Returns: the first capability in the chain with the
 539  * given name
 540  */
 541 GstCaps*
 542 gst_caps_get_by_name (GstCaps *caps, const gchar *name)
 543 {
 544   g_return_val_if_fail (caps != NULL, NULL);
 545   g_return_val_if_fail (name != NULL, NULL);
 546
 547   while (caps) {
 548     if (!strcmp (caps->name, name))
 549       return caps;
 550     caps = caps->next;
 551   }
 552
 553   return NULL;
 554 }
 555
 556 static gboolean
 557 gst_caps_check_compatibility_func (GstCaps *fromcaps, GstCaps *tocaps)
 558 {
 559   if (fromcaps->id != tocaps->id) {
 560     GST_DEBUG (GST_CAT_CAPS,"mime types differ (%s to %s)",
 561                gst_type_find_by_id (fromcaps->id)->mime,
 562                gst_type_find_by_id (tocaps->id)->mime);
 563     return FALSE;
 564   }
 565
 566   if (tocaps->properties) {
 567     if (fromcaps->properties) {
 568       return gst_props_check_compatibility (fromcaps->properties, tocaps->properties);
 569     }
 570     else {
 571       GST_DEBUG (GST_CAT_CAPS,"no source caps");
 572       return FALSE;
 573     }
 574   }
 575   else {
 576     /* assume it accepts everything */
 577     GST_DEBUG (GST_CAT_CAPS,"no caps");
 578     return TRUE;
 579   }
 580 }
 581
 582 /**
 583  * gst_caps_check_compatibility:
 584  * @fromcaps: a capabilty
 585  * @tocaps: a capabilty
 586  *
 587  * Checks whether two capabilities are compatible.
 588  *
 589  * Returns: TRUE if compatible, FALSE otherwise
 590  */
 591 gboolean
 592 gst_caps_check_compatibility (GstCaps *fromcaps, GstCaps *tocaps)
 593 {
 594   if (fromcaps == NULL) {
 595     if (tocaps == NULL) {
 596       GST_DEBUG (GST_CAT_CAPS,"no caps");
 597       return TRUE;
 598     }
 599     else {
 600       GST_DEBUG (GST_CAT_CAPS,"no source but destination caps");
 601       return FALSE;
 602     }
 603   }
 604   else {
 605     if (tocaps == NULL) {
 606       GST_DEBUG (GST_CAT_CAPS,"source caps and no destination caps");
 607       return TRUE;
 608     }
 609   }
 610
 611   while (fromcaps) {
 612     GstCaps *destcaps = tocaps;
 613
 614     while (destcaps) {
 615       if (gst_caps_check_compatibility_func (fromcaps, destcaps))
 616         return TRUE;
 617
 618       destcaps =  destcaps->next;
 619     }
 620     fromcaps =  fromcaps->next;
 621   }
 622   return FALSE;
 623 }
 624
 625 static GstCaps*
 626 gst_caps_intersect_func (GstCaps *caps1, GstCaps *caps2)
 627 {
 628   GstCaps *result = NULL;
 629   GstProps *props;
 630
 631   if (caps1->id != caps2->id) {
 632     GST_DEBUG (GST_CAT_CAPS,"mime types differ (%s to %s)",
 633                gst_type_find_by_id (caps1->id)->mime,
 634                gst_type_find_by_id (caps2->id)->mime);
 635     return NULL;
 636   }
 637
 638   if (caps1->properties == NULL) {
 639     return gst_caps_ref (caps2);
 640   }
 641   if (caps2->properties == NULL) {
 642     return gst_caps_ref (caps1);
 643   }
 644
 645   props = gst_props_intersect (caps1->properties, caps2->properties);
 646   if (props) {
 647     result = gst_caps_new_id ("intersect", caps1->id, props);
 648   }
 649
 650   return result;
 651 }
 652
 653 /**
 654  * gst_caps_intersect:
 655  * @caps1: a capabilty
 656  * @caps2: a capabilty
 657  *
 658  * Make the intersection between two caps.
 659  *
 660  * Returns: The intersection of the two caps or NULL if the intersection
 661  * is empty.
 662  */
 663 GstCaps*
 664 gst_caps_intersect (GstCaps *caps1, GstCaps *caps2)
 665 {
 666   GstCaps *result = NULL, *walk = NULL;
 667
 668   if (caps1 == NULL) {
 669     GST_DEBUG (GST_CAT_CAPS, "first caps is NULL, return other caps");
 670     return gst_caps_copy (caps2);
 671   }
 672   if (caps2 == NULL) {
 673     GST_DEBUG (GST_CAT_CAPS, "second caps is NULL, return other caps");
 674     return gst_caps_copy (caps1);
 675   }
 676
 677   while (caps1) {
 678     GstCaps *othercaps = caps2;
 679
 680     while (othercaps) {
 681       GstCaps *intersection;
 682
 683       intersection = gst_caps_intersect_func (caps1, othercaps);
 684
 685       if (intersection) {
 686         if (!result) {
 687           walk = result = intersection;
 688         }
 689         else {
 690           walk = walk->next = intersection;
 691         }
 692       }
 693       othercaps = othercaps->next;
 694     }
 695     caps1 =  caps1->next;
 696   }
 697
 698   return result;
 699 }
 700
 701 /**
 702  * gst_caps_normalize:
 703  * @caps: a capabilty
 704  *
 705  * Make the normalisation of the caps. This will return a new caps
 706  * that is equivalent to the input caps with the exception that all
 707  * lists are unrolled. This function is useful when you want to iterate
 708  * the caps.
 709  *
 710  * Returns: The normalisation of the caps.
 711  */
 712 GstCaps*
 713 gst_caps_normalize (GstCaps *caps)
 714 {
 715   GstCaps *result = NULL, *walk = caps;
 716
 717   if (caps == NULL)
 718     return caps;
 719
 720   while (caps) {
 721     GList *proplist;
 722
 723     proplist = gst_props_normalize (caps->properties);
 724     if (proplist && g_list_next (proplist) == NULL) {
 725       if (result == NULL)
 726         walk = result = caps;
 727       else {
 728         walk = walk->next = caps;
 729       }
 730       goto next;
 731     }
 732
 733     while (proplist) {
 734       GstProps *props = (GstProps *) proplist->data;
 735       GstCaps *newcaps = gst_caps_new_id (caps->name, caps->id, props);
 736
 737       if (result == NULL)
 738         walk = result = newcaps;
 739       else {
 740         walk = walk->next = newcaps;
 741       }
 742       proplist = g_list_next (proplist);
 743     }
 744 next:
 745     caps = caps->next;
 746   }
 747   return result;
 748 }
 749
 750 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
 751 /**
 752  * gst_caps_save_thyself:
 753  * @caps: a capabilty to save
 754  * @parent: the parent XML node pointer
 755  *
 756  * Save the capability into an XML representation.
 757  *
 758  * Returns: a new XML node pointer
 759  */
 760 xmlNodePtr
 761 gst_caps_save_thyself (GstCaps *caps, xmlNodePtr parent)
 762 {
 763   xmlNodePtr subtree;
 764   xmlNodePtr subsubtree;
 765
 766   while (caps) {
 767     subtree = xmlNewChild (parent, NULL, "capscomp", NULL);
 768
 769     xmlNewChild (subtree, NULL, "name", caps->name);
 770     xmlNewChild (subtree, NULL, "type", gst_type_find_by_id (caps->id)->mime);
 771     if (caps->properties) {
 772       subsubtree = xmlNewChild (subtree, NULL, "properties", NULL);
 773
 774       gst_props_save_thyself (caps->properties, subsubtree);
 775     }
 776
 777     caps = caps->next;
 778   }
 779
 780   return parent;
 781 }
 782
 783 /**
 784  * gst_caps_load_thyself:
 785  * @parent: the parent XML node pointer
 786  *
 787  * Load a new caps from the XML representation.
 788  *
 789  * Returns: a new capability
 790  */
 791 GstCaps*
 792 gst_caps_load_thyself (xmlNodePtr parent)
 793 {
 794   GstCaps *result = NULL;
 795   xmlNodePtr field = parent->xmlChildrenNode;
 796
 797   while (field) {
 798     if (!strcmp (field->name, "capscomp")) {
 799       xmlNodePtr subfield = field->xmlChildrenNode;
 800       GstCaps *caps;
 801       gchar *content;
 802
 803       g_mutex_lock (_gst_caps_chunk_lock);
 804       caps = g_mem_chunk_alloc0 (_gst_caps_chunk);
 805       g_mutex_unlock (_gst_caps_chunk_lock);
 806
 807       caps->refcount = 1;
 808       caps->next = NULL;
 809       caps->fixed = TRUE;
 810
 811       while (subfield) {
 812         if (!strcmp (subfield->name, "name")) {
 813           caps->name = xmlNodeGetContent (subfield);
 814         }
 815         if (!strcmp (subfield->name, "type")) {
 816           content = xmlNodeGetContent (subfield);
 817           caps->id = get_type_for_mime (content);
 818           g_free (content);
 819         }
 820         else if (!strcmp (subfield->name, "properties")) {
 821           caps->properties = gst_props_load_thyself (subfield);
 822         }
 823
 824         subfield = subfield->next;
 825       }
 826       result = gst_caps_append (result, caps);
 827     }
 828     field = field->next;
 829   }
 830
 831   return result;
 832 }
 833
 834 #endif /* GST_DISABLE_LOADSAVE_REGISTRY */