gst/gstelementfactory.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *                    2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
   5  *
   6  * gstelementfactory.c: GstElementFactory object, support routines
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #include "gst_private.h"
  25
  26 #include "gstelement.h"
  27 #include "gstregistrypool.h"
  28 #include "gstinfo.h"
  29 #include "gsturi.h"
  30
  31 GST_DEBUG_CATEGORY_STATIC (element_factory_debug);
  32 #define GST_CAT_DEFAULT element_factory_debug
  33
  34 static void gst_element_factory_class_init (GstElementFactoryClass * klass);
  35 static void gst_element_factory_init (GstElementFactory * factory);
  36
  37 static void gst_element_factory_unload_thyself (GstPluginFeature * feature);
  38
  39 static GstPluginFeatureClass *parent_class = NULL;
  40
  41 /* static guint gst_element_factory_signals[LAST_SIGNAL] = { 0 }; */
  42
  43 GType
  44 gst_element_factory_get_type (void)
  45 {
  46   static GType elementfactory_type = 0;
  47
  48   if (!elementfactory_type) {
  49     static const GTypeInfo elementfactory_info = {
  50       sizeof (GstElementFactoryClass),
  51       NULL,
  52       NULL,
  53       (GClassInitFunc) gst_element_factory_class_init,
  54       NULL,
  55       NULL,
  56       sizeof (GstElementFactory),
  57       0,
  58       (GInstanceInitFunc) gst_element_factory_init,
  59       NULL
  60     };
  61
  62     elementfactory_type = g_type_register_static (GST_TYPE_PLUGIN_FEATURE,
  63         "GstElementFactory", &elementfactory_info, 0);
  64     GST_DEBUG_CATEGORY_INIT (element_factory_debug, "GST_ELEMENT_FACTORY",
  65         GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED,
  66         "element factories keep information about installed elements");
  67   }
  68   return elementfactory_type;
  69 }
  70 static void
  71 gst_element_factory_class_init (GstElementFactoryClass * klass)
  72 {
  73   GObjectClass *gobject_class;
  74   GstObjectClass *gstobject_class;
  75   GstPluginFeatureClass *gstpluginfeature_class;
  76
  77   gobject_class = (GObjectClass *) klass;
  78   gstobject_class = (GstObjectClass *) klass;
  79   gstpluginfeature_class = (GstPluginFeatureClass *) klass;
  80
  81   parent_class = g_type_class_peek_parent (klass);
  82
  83   gstpluginfeature_class->unload_thyself =
  84       GST_DEBUG_FUNCPTR (gst_element_factory_unload_thyself);
  85 }
  86 static void
  87 gst_element_factory_init (GstElementFactory * factory)
  88 {
  89   factory->padtemplates = NULL;
  90   factory->numpadtemplates = 0;
  91
  92   factory->uri_type = GST_URI_UNKNOWN;
  93   factory->uri_protocols = NULL;
  94
  95   factory->interfaces = NULL;
  96 }
  97
  98 /**
  99  * gst_element_factory_find:
 100  * @name: name of factory to find
 101  *
 102  * Search for an element factory of the given name.
 103  *
 104  * Returns: #GstElementFactory if found, NULL otherwise
 105  */
 106 GstElementFactory *
 107 gst_element_factory_find (const gchar * name)
 108 {
 109   GstPluginFeature *feature;
 110
 111   g_return_val_if_fail (name != NULL, NULL);
 112
 113   feature = gst_registry_pool_find_feature (name, GST_TYPE_ELEMENT_FACTORY);
 114   if (feature)
 115     return GST_ELEMENT_FACTORY (feature);
 116
 117   /* this isn't an error, for instance when you query if an element factory is
 118    * present */
 119   GST_LOG ("no such element factory \"%s\"", name);
 120   return NULL;
 121 }
 122
 123 void
 124 __gst_element_details_clear (GstElementDetails * dp)
 125 {
 126   g_free (dp->longname);
 127   dp->longname = NULL;
 128   g_free (dp->klass);
 129   dp->klass = NULL;
 130   g_free (dp->description);
 131   dp->description = NULL;
 132   g_free (dp->author);
 133   dp->author = NULL;
 134 }
 135
 136 void
 137 __gst_element_details_set (GstElementDetails * dest,
 138     const GstElementDetails * src)
 139 {
 140   dest->longname = g_strdup (src->longname);
 141   dest->klass = g_strdup (src->klass);
 142   dest->description = g_strdup (src->description);
 143   dest->author = g_strdup (src->author);
 144 }
 145
 146 void
 147 __gst_element_details_copy (GstElementDetails * dest,
 148     const GstElementDetails * src)
 149 {
 150   __gst_element_details_clear (dest);
 151   __gst_element_details_set (dest, src);
 152 }
 153 static void
 154 gst_element_factory_cleanup (GstElementFactory * factory)
 155 {
 156   __gst_element_details_clear (&factory->details);
 157   if (factory->type) {
 158     g_type_class_unref (g_type_class_peek (factory->type));
 159     factory->type = 0;
 160   }
 161
 162   g_list_foreach (factory->padtemplates, (GFunc) g_object_unref, NULL);
 163   g_list_free (factory->padtemplates);
 164   factory->padtemplates = NULL;
 165   factory->numpadtemplates = 0;
 166   factory->uri_type = GST_URI_UNKNOWN;
 167   if (factory->uri_protocols) {
 168     g_strfreev (factory->uri_protocols);
 169     factory->uri_protocols = NULL;
 170   }
 171
 172   g_list_foreach (factory->interfaces, (GFunc) g_free, NULL);
 173   g_list_free (factory->interfaces);
 174   factory->interfaces = NULL;
 175 }
 176
 177 /**
 178  * gst_element_register:
 179  * @plugin:
 180  * @name: name of elements of this type
 181  * @rank: rank of element (higher rank means more importance when autoplugging)
 182  * @type: GType of element to register
 183  *
 184  * Create a new elementfactory capable of insantiating objects of the
 185  * given type.
 186  *
 187  * Returns: TRUE, if the registering succeeded, FALSE on error
 188  */
 189 gboolean
 190 gst_element_register (GstPlugin * plugin, const gchar * name, guint rank,
 191     GType type)
 192 {
 193   GstElementFactory *factory;
 194   GType *interfaces;
 195   guint n_interfaces, i;
 196   GstElementClass *klass;
 197
 198   g_return_val_if_fail (name != NULL, FALSE);
 199   g_return_val_if_fail (g_type_is_a (type, GST_TYPE_ELEMENT), FALSE);
 200
 201   factory = gst_element_factory_find (name);
 202
 203   if (!factory) {
 204     klass = GST_ELEMENT_CLASS (g_type_class_ref (type));
 205     factory =
 206         GST_ELEMENT_FACTORY (g_object_new (GST_TYPE_ELEMENT_FACTORY, NULL));
 207     gst_plugin_feature_set_name (GST_PLUGIN_FEATURE (factory), name);
 208     GST_LOG_OBJECT (factory, "Created new elementfactory for type %s",
 209         g_type_name (type));
 210   } else {
 211     g_return_val_if_fail (factory->type == 0, FALSE);
 212     klass = GST_ELEMENT_CLASS (g_type_class_ref (type));
 213     gst_element_factory_cleanup (factory);
 214     GST_LOG_OBJECT (factory, "Reuse existing elementfactory for type %s",
 215         g_type_name (type));
 216   }
 217
 218   factory->type = type;
 219   __gst_element_details_copy (&factory->details, &klass->details);
 220   factory->padtemplates = g_list_copy (klass->padtemplates);
 221   g_list_foreach (factory->padtemplates, (GFunc) g_object_ref, NULL);
 222   factory->numpadtemplates = klass->numpadtemplates;
 223
 224   /* special stuff for URI handling */
 225   if (g_type_is_a (type, GST_TYPE_URI_HANDLER)) {
 226     GstURIHandlerInterface *iface = (GstURIHandlerInterface *)
 227         g_type_interface_peek (klass, GST_TYPE_URI_HANDLER);
 228
 229     if (!iface || !iface->get_type || !iface->get_protocols)
 230       goto error;
 231     factory->uri_type = iface->get_type ();
 232     if (!GST_URI_TYPE_IS_VALID (factory->uri_type))
 233       goto error;
 234     factory->uri_protocols = g_strdupv (iface->get_protocols ());
 235     if (!factory->uri_protocols)
 236       goto error;
 237   }
 238
 239   interfaces = g_type_interfaces (type, &n_interfaces);
 240   for (i = 0; i < n_interfaces; i++) {
 241     __gst_element_factory_add_interface (factory, g_type_name (interfaces[i]));
 242   }
 243   g_free (interfaces);
 244
 245   gst_plugin_feature_set_rank (GST_PLUGIN_FEATURE (factory), rank);
 246   gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (factory));
 247
 248   return TRUE;
 249
 250 error:
 251   gst_element_factory_cleanup (factory);
 252   return FALSE;
 253 }
 254
 255 /**
 256  * gst_element_factory_create:
 257  * @factory: factory to instantiate
 258  * @name: name of new element
 259  *
 260  * Create a new element of the type defined by the given elementfactory.
 261  * It will be given the name supplied, since all elements require a name as
 262  * their first argument.
 263  *
 264  * Returns: new #GstElement or NULL if the element couldn't be created
 265  */
 266 GstElement *
 267 gst_element_factory_create (GstElementFactory * factory, const gchar * name)
 268 {
 269   GstElement *element;
 270   GstElementClass *oclass;
 271
 272   g_return_val_if_fail (factory != NULL, NULL);
 273
 274   if (!gst_plugin_feature_ensure_loaded (GST_PLUGIN_FEATURE (factory))) {
 275     GST_INFO ("could not load element factory for element \"%s\"", name);
 276     return NULL;
 277   }
 278
 279   if (name)
 280     GST_INFO ("creating \"%s\" named \"%s\"", GST_PLUGIN_FEATURE_NAME (factory),
 281         GST_STR_NULL (name));
 282   else
 283     GST_INFO ("creating \"%s\"", GST_PLUGIN_FEATURE_NAME (factory));
 284
 285   if (factory->type == 0) {
 286     g_critical ("Factory for `%s' has no type",
 287         GST_PLUGIN_FEATURE_NAME (factory));
 288     return NULL;
 289   }
 290
 291   oclass = GST_ELEMENT_CLASS (g_type_class_ref (factory->type));
 292   if (oclass->elementfactory == NULL)
 293     oclass->elementfactory = factory;
 294
 295   /* create an instance of the element */
 296   element = GST_ELEMENT (g_object_new (factory->type, NULL));
 297   g_assert (element != NULL);
 298
 299   g_type_class_unref (oclass);
 300
 301   gst_object_set_name (GST_OBJECT (element), name);
 302
 303   return element;
 304 }
 305
 306 /**
 307  * gst_element_factory_make:
 308  * @factoryname: a named factory to instantiate
 309  * @name: name of new element
 310  *
 311  * Create a new element of the type defined by the given element factory.
 312  * If name is NULL, then the element will receive a guaranteed unique name,
 313  * consisting of the element factory name and a number.
 314  * If name is given, it will be given the name supplied.
 315  *
 316  * Returns: new #GstElement or NULL if unable to create element
 317  */
 318 GstElement *
 319 gst_element_factory_make (const gchar * factoryname, const gchar * name)
 320 {
 321   GstElementFactory *factory;
 322   GstElement *element;
 323
 324   g_return_val_if_fail (factoryname != NULL, NULL);
 325
 326   GST_LOG ("gstelementfactory: make \"%s\" \"%s\"",
 327       factoryname, GST_STR_NULL (name));
 328
 329   /* gst_plugin_load_element_factory (factoryname); */
 330   factory = gst_element_factory_find (factoryname);
 331   if (factory == NULL) {
 332     GST_INFO ("no such element factory \"%s\"!", factoryname);
 333     return NULL;
 334   }
 335   element = gst_element_factory_create (factory, name);
 336   if (element == NULL) {
 337     GST_INFO_OBJECT (factory, "couldn't create instance!");
 338     return NULL;
 339   }
 340
 341   return element;
 342 }
 343
 344 void
 345 __gst_element_factory_add_pad_template (GstElementFactory * factory,
 346     GstPadTemplate * templ)
 347 {
 348   g_return_if_fail (factory != NULL);
 349   g_return_if_fail (templ != NULL);
 350
 351   gst_object_ref (GST_OBJECT (templ));
 352   gst_object_sink (GST_OBJECT (templ));
 353
 354   factory->padtemplates = g_list_append (factory->padtemplates, templ);
 355   factory->numpadtemplates++;
 356 }
 357
 358 /**
 359  * gst_element_factory_get_element_type:
 360  * @factory: factory to get managed #GType from
 361  *
 362  * Get the #GType for elements managed by this factory
 363  *
 364  * Returns: the #GType for elements managed by this factory
 365  */
 366 GType
 367 gst_element_factory_get_element_type (GstElementFactory * factory)
 368 {
 369   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), 0);
 370
 371   return factory->type;
 372 }
 373
 374 /**
 375  * gst_element_factory_get_longname:
 376  * @factory: a #GstElementFactory
 377  *
 378  * Gets the longname for this factory
 379  *
 380  * Returns: the longname
 381  */
 382 G_CONST_RETURN gchar *
 383 gst_element_factory_get_longname (GstElementFactory * factory)
 384 {
 385   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 386
 387   return factory->details.longname;
 388 }
 389
 390 /**
 391  * gst_element_factory_get_class:
 392  * @factory: a #GstElementFactory
 393  *
 394  * Gets the class for this factory.
 395  *
 396  * Returns: the class
 397  */
 398 G_CONST_RETURN gchar *
 399 gst_element_factory_get_klass (GstElementFactory * factory)
 400 {
 401   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 402
 403   return factory->details.klass;
 404 }
 405
 406 /**
 407  * gst_element_factory_get_description:
 408  * @factory: a #GstElementFactory
 409  *
 410  * Gets the description for this factory.
 411  *
 412  * Returns: the description
 413  */
 414 G_CONST_RETURN gchar *
 415 gst_element_factory_get_description (GstElementFactory * factory)
 416 {
 417   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 418
 419   return factory->details.description;
 420 }
 421
 422 /**
 423  * gst_element_factory_get_author:
 424  * @factory: a #GstElementFactory
 425  *
 426  * Gets the author for this factory.
 427  *
 428  * Returns: the author
 429  */
 430 G_CONST_RETURN gchar *
 431 gst_element_factory_get_author (GstElementFactory * factory)
 432 {
 433   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 434
 435   return factory->details.author;
 436 }
 437
 438 /**
 439  * gst_element_factory_get_num_pad_templates:
 440  * @factory: a #GstElementFactory
 441  *
 442  * Gets the number of pad_templates in this factory.
 443  *
 444  * Returns: the number of pad_templates
 445  */
 446 guint
 447 gst_element_factory_get_num_pad_templates (GstElementFactory * factory)
 448 {
 449   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), 0);
 450
 451   return factory->numpadtemplates;
 452 }
 453
 454 /**
 455  * __gst_element_factory_add_interface:
 456  * @elementfactory: The elementfactory to add the interface to
 457  * @interfacename: Name of the interface
 458  *
 459  * Adds the given interfacename to the list of implemented interfaces of the
 460  * element.
 461  */
 462 void
 463 __gst_element_factory_add_interface (GstElementFactory * elementfactory,
 464     const gchar * interfacename)
 465 {
 466   g_return_if_fail (GST_IS_ELEMENT_FACTORY (elementfactory));
 467   g_return_if_fail (interfacename != NULL);
 468   g_return_if_fail (interfacename[0] != '\0');  /* no empty string */
 469
 470   elementfactory->interfaces =
 471       g_list_prepend (elementfactory->interfaces, g_strdup (interfacename));
 472 }
 473
 474 /**
 475  * gst_element_factory_get_pad_templates:
 476  * @factory: a #GstElementFactory
 477  *
 478  * Gets the #GList of padtemplates for this factory.
 479  *
 480  * Returns: the padtemplates
 481  */
 482 G_CONST_RETURN GList *
 483 gst_element_factory_get_pad_templates (GstElementFactory * factory)
 484 {
 485   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 486
 487   return factory->padtemplates;
 488 }
 489
 490 /**
 491  * gst_element_factory_get_uri_type:
 492  * @factory: a #GstElementFactory
 493  *
 494  * Gets the type of URIs the element supports or GST_URI_UNKNOWN if none.
 495  *
 496  * Returns: type of URIs this element supports
 497  */
 498 guint
 499 gst_element_factory_get_uri_type (GstElementFactory * factory)
 500 {
 501   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), GST_URI_UNKNOWN);
 502
 503   return factory->uri_type;
 504 }
 505
 506 /**
 507  * gst_element_factory_get_uri_protocols:
 508  * @factory: a #GstElementFactory
 509  *
 510  * Gets a NULL-terminated array of protocols this element supports or NULL, if
 511  * no protocols are supported. You may not change the contents of the returned
 512  * array as it is still ownt by the element factory. Use g_strdupv() if you want to.
 513  *
 514  * Returns: the supported protocols or NULL
 515  */
 516 gchar **
 517 gst_element_factory_get_uri_protocols (GstElementFactory * factory)
 518 {
 519   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 520
 521   return factory->uri_protocols;
 522 }
 523
 524 /**
 525  * gst_element_factory_can_src_caps :
 526  * @factory: factory to query
 527  * @caps: the caps to check
 528  *
 529  * Checks if the factory can source the given capability.
 530  *
 531  * Returns: true if it can src the capabilities
 532  */
 533 gboolean
 534 gst_element_factory_can_src_caps (GstElementFactory * factory,
 535     const GstCaps * caps)
 536 {
 537   GList *templates;
 538
 539   g_return_val_if_fail (factory != NULL, FALSE);
 540   g_return_val_if_fail (caps != NULL, FALSE);
 541
 542   templates = factory->padtemplates;
 543
 544   while (templates) {
 545     GstPadTemplate *template = (GstPadTemplate *) templates->data;
 546
 547     if (template->direction == GST_PAD_SRC) {
 548       if (gst_caps_is_always_compatible (GST_PAD_TEMPLATE_CAPS (template),
 549               caps))
 550         return TRUE;
 551     }
 552     templates = g_list_next (templates);
 553   }
 554
 555   return FALSE;
 556 }
 557
 558 /**
 559  * gst_element_factory_can_sink_caps :
 560  * @factory: factory to query
 561  * @caps: the caps to check
 562  *
 563  * Checks if the factory can sink the given capability.
 564  *
 565  * Returns: true if it can sink the capabilities
 566  */
 567 gboolean
 568 gst_element_factory_can_sink_caps (GstElementFactory * factory,
 569     const GstCaps * caps)
 570 {
 571   GList *templates;
 572
 573   g_return_val_if_fail (factory != NULL, FALSE);
 574   g_return_val_if_fail (caps != NULL, FALSE);
 575
 576   templates = factory->padtemplates;
 577
 578   while (templates) {
 579     GstPadTemplate *template = (GstPadTemplate *) templates->data;
 580
 581     if (template->direction == GST_PAD_SINK) {
 582       if (gst_caps_is_always_compatible (caps,
 583               GST_PAD_TEMPLATE_CAPS (template)))
 584         return TRUE;
 585     }
 586     templates = g_list_next (templates);
 587   }
 588
 589   return FALSE;
 590 }
 591 static void
 592 gst_element_factory_unload_thyself (GstPluginFeature * feature)
 593 {
 594   GstElementFactory *factory;
 595
 596   factory = GST_ELEMENT_FACTORY (feature);
 597
 598   if (factory->type) {
 599     g_type_class_unref (g_type_class_peek (factory->type));
 600     factory->type = 0;
 601   }
 602 }