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., 51 Franklin St, Fifth Floor,
  21  * Boston, MA 02110-1301, USA.
  22  */
  23
  24 /**
  25  * SECTION:gstelementfactory
  26  * @title: GstElementFactory
  27  * @short_description: Create GstElements from a factory
  28  * @see_also: #GstElement, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
  29  *
  30  * #GstElementFactory is used to create instances of elements. A
  31  * GstElementFactory can be added to a #GstPlugin as it is also a
  32  * #GstPluginFeature.
  33  *
  34  * Use the gst_element_factory_find() and gst_element_factory_create()
  35  * functions to create element instances or use gst_element_factory_make() as a
  36  * convenient shortcut.
  37  *
  38  * The following code example shows you how to create a GstFileSrc element.
  39  *
  40  * ## Using an element factory
  41  * |[<!-- language="C" -->
  42  *   #include &lt;gst/gst.h&gt;
  43  *
  44  *   GstElement *src;
  45  *   GstElementFactory *srcfactory;
  46  *
  47  *   gst_init (&amp;argc, &amp;argv);
  48  *
  49  *   srcfactory = gst_element_factory_find ("filesrc");
  50  *   g_return_if_fail (srcfactory != NULL);
  51  *   src = gst_element_factory_create (srcfactory, "src");
  52  *   g_return_if_fail (src != NULL);
  53  *   ...
  54  * ]|
  55  */
  56
  57 #include "gst_private.h"
  58
  59 #include "gstelement.h"
  60 #include "gstelementmetadata.h"
  61 #include "gstinfo.h"
  62 #include "gsturi.h"
  63 #include "gstregistry.h"
  64 #include "gst.h"
  65
  66 #include "glib-compat-private.h"
  67
  68 #include <gobject/gvaluecollector.h>
  69
  70 GST_DEBUG_CATEGORY_STATIC (element_factory_debug);
  71 #define GST_CAT_DEFAULT element_factory_debug
  72
  73 static void gst_element_factory_finalize (GObject * object);
  74 static void gst_element_factory_cleanup (GstElementFactory * factory);
  75
  76 /* static guint gst_element_factory_signals[LAST_SIGNAL] = { 0 }; */
  77
  78 /* this is defined in gstelement.c */
  79 extern GQuark __gst_elementclass_factory;
  80
  81 #define _do_init \
  82 { \
  83   GST_DEBUG_CATEGORY_INIT (element_factory_debug, "GST_ELEMENT_FACTORY", \
  84       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, \
  85       "element factories keep information about installed elements"); \
  86 }
  87
  88 G_DEFINE_TYPE_WITH_CODE (GstElementFactory, gst_element_factory,
  89     GST_TYPE_PLUGIN_FEATURE, _do_init);
  90
  91 #ifdef TIZEN_PROFILE_TV
  92 static GMutex pool_mutex;
  93 static GList *pool = NULL;
  94 #endif
  95
  96 static void
  97 gst_element_factory_class_init (GstElementFactoryClass * klass)
  98 {
  99   GObjectClass *gobject_class = (GObjectClass *) klass;
 100
 101   gobject_class->finalize = gst_element_factory_finalize;
 102 }
 103
 104 static void
 105 gst_element_factory_init (GstElementFactory * factory)
 106 {
 107   factory->staticpadtemplates = NULL;
 108   factory->numpadtemplates = 0;
 109
 110   factory->uri_type = GST_URI_UNKNOWN;
 111   factory->uri_protocols = NULL;
 112
 113   factory->interfaces = NULL;
 114 }
 115
 116 static void
 117 gst_element_factory_finalize (GObject * object)
 118 {
 119   GstElementFactory *factory = GST_ELEMENT_FACTORY (object);
 120
 121   gst_element_factory_cleanup (factory);
 122   G_OBJECT_CLASS (gst_element_factory_parent_class)->finalize (object);
 123 }
 124
 125 /**
 126  * gst_element_factory_find:
 127  * @name: name of factory to find
 128  *
 129  * Search for an element factory of the given name. Refs the returned
 130  * element factory; caller is responsible for unreffing.
 131  *
 132  * Returns: (transfer full) (nullable): #GstElementFactory if found,
 133  * %NULL otherwise
 134  */
 135 GstElementFactory *
 136 gst_element_factory_find (const gchar * name)
 137 {
 138   GstPluginFeature *feature;
 139
 140   g_return_val_if_fail (name != NULL, NULL);
 141
 142   feature = gst_registry_find_feature (gst_registry_get (), name,
 143       GST_TYPE_ELEMENT_FACTORY);
 144   if (feature)
 145     return GST_ELEMENT_FACTORY (feature);
 146
 147   /* this isn't an error, for instance when you query if an element factory is
 148    * present */
 149   GST_LOG ("no such element factory \"%s\"", name);
 150   return NULL;
 151 }
 152
 153 static void
 154 gst_element_factory_cleanup (GstElementFactory * factory)
 155 {
 156   GList *item;
 157
 158   if (factory->metadata) {
 159     gst_structure_free ((GstStructure *) factory->metadata);
 160     factory->metadata = NULL;
 161   }
 162   if (factory->type) {
 163     factory->type = G_TYPE_INVALID;
 164   }
 165
 166   for (item = factory->staticpadtemplates; item; item = item->next) {
 167     GstStaticPadTemplate *templ = item->data;
 168
 169     gst_static_caps_cleanup (&templ->static_caps);
 170     g_slice_free (GstStaticPadTemplate, templ);
 171   }
 172   g_list_free (factory->staticpadtemplates);
 173   factory->staticpadtemplates = NULL;
 174   factory->numpadtemplates = 0;
 175   factory->uri_type = GST_URI_UNKNOWN;
 176   if (factory->uri_protocols) {
 177     g_strfreev (factory->uri_protocols);
 178     factory->uri_protocols = NULL;
 179   }
 180
 181   g_list_free (factory->interfaces);
 182   factory->interfaces = NULL;
 183 }
 184
 185 #define CHECK_METADATA_FIELD(klass, name, key)                                 \
 186   G_STMT_START {                                                               \
 187     const gchar *metafield = gst_element_class_get_metadata (klass, key);      \
 188     if (G_UNLIKELY (metafield == NULL || *metafield == '\0')) {                \
 189       g_warning ("Element factory metadata for '%s' has no valid %s field", name, key);    \
 190       goto detailserror;                                                       \
 191     } \
 192   } G_STMT_END;
 193
 194 /**
 195  * gst_element_register:
 196  * @plugin: (allow-none): #GstPlugin to register the element with, or %NULL for
 197  *     a static element.
 198  * @name: name of elements of this type
 199  * @rank: rank of element (higher rank means more importance when autoplugging)
 200  * @type: GType of element to register
 201  *
 202  * Create a new elementfactory capable of instantiating objects of the
 203  * @type and add the factory to @plugin.
 204  *
 205  * Returns: %TRUE, if the registering succeeded, %FALSE on error
 206  */
 207 gboolean
 208 gst_element_register (GstPlugin * plugin, const gchar * name, guint rank,
 209     GType type)
 210 {
 211   GstPluginFeature *existing_feature;
 212   GstRegistry *registry;
 213   GstElementFactory *factory;
 214   GType *interfaces;
 215   guint n_interfaces, i;
 216   GstElementClass *klass;
 217   GList *item;
 218
 219   g_return_val_if_fail (name != NULL, FALSE);
 220   g_return_val_if_fail (g_type_is_a (type, GST_TYPE_ELEMENT), FALSE);
 221
 222   registry = gst_registry_get ();
 223
 224   /* check if feature already exists, if it exists there is no need to update it
 225    * when the registry is getting updated, outdated plugins and all their
 226    * features are removed and readded.
 227    */
 228   existing_feature = gst_registry_lookup_feature (registry, name);
 229   if (existing_feature && existing_feature->plugin == plugin) {
 230     GST_DEBUG_OBJECT (registry, "update existing feature %p (%s)",
 231         existing_feature, name);
 232     factory = GST_ELEMENT_FACTORY_CAST (existing_feature);
 233     factory->type = type;
 234     existing_feature->loaded = TRUE;
 235     g_type_set_qdata (type, __gst_elementclass_factory, factory);
 236     gst_object_unref (existing_feature);
 237     return TRUE;
 238   } else if (existing_feature) {
 239     gst_object_unref (existing_feature);
 240   }
 241
 242   factory = g_object_new (GST_TYPE_ELEMENT_FACTORY, NULL);
 243   gst_plugin_feature_set_name (GST_PLUGIN_FEATURE_CAST (factory), name);
 244   GST_LOG_OBJECT (factory, "Created new elementfactory for type %s",
 245       g_type_name (type));
 246
 247   /* provide info needed during class structure setup */
 248   g_type_set_qdata (type, __gst_elementclass_factory, factory);
 249   klass = GST_ELEMENT_CLASS (g_type_class_ref (type));
 250
 251   CHECK_METADATA_FIELD (klass, name, GST_ELEMENT_METADATA_LONGNAME);
 252   CHECK_METADATA_FIELD (klass, name, GST_ELEMENT_METADATA_KLASS);
 253   CHECK_METADATA_FIELD (klass, name, GST_ELEMENT_METADATA_DESCRIPTION);
 254   CHECK_METADATA_FIELD (klass, name, GST_ELEMENT_METADATA_AUTHOR);
 255
 256   factory->type = type;
 257   factory->metadata = gst_structure_copy ((GstStructure *) klass->metadata);
 258
 259   for (item = klass->padtemplates; item; item = item->next) {
 260     GstPadTemplate *templ = item->data;
 261     GstStaticPadTemplate *newt;
 262     gchar *caps_string = gst_caps_to_string (templ->caps);
 263
 264     newt = g_slice_new (GstStaticPadTemplate);
 265     newt->name_template = g_intern_string (templ->name_template);
 266     newt->direction = templ->direction;
 267     newt->presence = templ->presence;
 268     newt->static_caps.caps = NULL;
 269     newt->static_caps.string = g_intern_string (caps_string);
 270     factory->staticpadtemplates =
 271         g_list_append (factory->staticpadtemplates, newt);
 272
 273     g_free (caps_string);
 274   }
 275   factory->numpadtemplates = klass->numpadtemplates;
 276
 277   /* special stuff for URI handling */
 278   if (g_type_is_a (type, GST_TYPE_URI_HANDLER)) {
 279     GstURIHandlerInterface *iface = (GstURIHandlerInterface *)
 280         g_type_interface_peek (klass, GST_TYPE_URI_HANDLER);
 281
 282     if (!iface || !iface->get_type || !iface->get_protocols)
 283       goto urierror;
 284     if (iface->get_type)
 285       factory->uri_type = iface->get_type (factory->type);
 286     if (!GST_URI_TYPE_IS_VALID (factory->uri_type))
 287       goto urierror;
 288     if (iface->get_protocols) {
 289       const gchar *const *protocols;
 290
 291       protocols = iface->get_protocols (factory->type);
 292       factory->uri_protocols = g_strdupv ((gchar **) protocols);
 293     }
 294     if (!factory->uri_protocols)
 295       goto urierror;
 296   }
 297
 298   interfaces = g_type_interfaces (type, &n_interfaces);
 299   for (i = 0; i < n_interfaces; i++) {
 300     __gst_element_factory_add_interface (factory, g_type_name (interfaces[i]));
 301   }
 302   g_free (interfaces);
 303
 304   if (plugin && plugin->desc.name) {
 305     GST_PLUGIN_FEATURE_CAST (factory)->plugin_name = plugin->desc.name;
 306     GST_PLUGIN_FEATURE_CAST (factory)->plugin = plugin;
 307     g_object_add_weak_pointer ((GObject *) plugin,
 308         (gpointer *) & GST_PLUGIN_FEATURE_CAST (factory)->plugin);
 309   } else {
 310     GST_PLUGIN_FEATURE_CAST (factory)->plugin_name = "NULL";
 311     GST_PLUGIN_FEATURE_CAST (factory)->plugin = NULL;
 312   }
 313   gst_plugin_feature_set_rank (GST_PLUGIN_FEATURE_CAST (factory), rank);
 314   GST_PLUGIN_FEATURE_CAST (factory)->loaded = TRUE;
 315
 316   gst_registry_add_feature (registry, GST_PLUGIN_FEATURE_CAST (factory));
 317
 318   return TRUE;
 319
 320   /* ERRORS */
 321 urierror:
 322   {
 323     GST_WARNING_OBJECT (factory, "error with uri handler!");
 324     gst_element_factory_cleanup (factory);
 325     return FALSE;
 326   }
 327
 328 detailserror:
 329   {
 330     gst_element_factory_cleanup (factory);
 331     return FALSE;
 332   }
 333 }
 334
 335 static gboolean
 336 gst_element_factory_property_valist_to_array (const gchar * first,
 337     va_list properties, GType object_type, guint * n, const gchar ** names[],
 338     GValue ** values)
 339 {
 340   GObjectClass *class;
 341   const gchar *name;
 342   guint n_params = 0;
 343   guint n_params_alloc = 16;
 344   GValue *values_array;
 345   const gchar **names_array;
 346
 347   if (!first)
 348     return FALSE;
 349
 350   g_return_val_if_fail (G_TYPE_IS_OBJECT (object_type), FALSE);
 351
 352   class = g_type_class_ref (object_type);
 353   if (!class)
 354     return FALSE;
 355
 356   name = first;
 357   names_array = g_new0 (const gchar *, n_params_alloc);
 358   values_array = g_new0 (GValue, n_params_alloc);
 359
 360   do {
 361     gchar *error = NULL;
 362     GParamSpec *pspec;
 363
 364     pspec = g_object_class_find_property (class, name);
 365     if (!pspec)
 366       goto cleanup;
 367
 368     if (G_UNLIKELY (n_params == n_params_alloc)) {
 369       n_params_alloc *= 2u;
 370       names_array =
 371           g_realloc (names_array, sizeof (const gchar *) * n_params_alloc);
 372       values_array = g_realloc (values_array, sizeof (GValue) * n_params_alloc);
 373       memset (&values_array[n_params], 0,
 374           sizeof (GValue) * (n_params_alloc - n_params));
 375     }
 376
 377     names_array[n_params] = name;
 378
 379     G_VALUE_COLLECT_INIT (&values_array[n_params], pspec->value_type,
 380         properties, 0, &error);
 381
 382     if (error) {
 383       g_critical ("%s", error);
 384       g_free (error);
 385       goto cleanup;
 386     }
 387
 388     ++n_params;
 389     name = va_arg (properties, const gchar *);
 390   } while (name);
 391
 392   *n = n_params;
 393   *names = names_array;
 394   *values = values_array;
 395   g_type_class_unref (class);
 396   return TRUE;
 397
 398 cleanup:
 399   g_free (names_array);
 400   g_free (values_array);
 401   g_type_class_unref (class);
 402   return FALSE;
 403 }
 404
 405 /**
 406  * gst_element_factory_create_with_properties:
 407  * @factory: factory to instantiate
 408  * @n: count of properties
 409  * @names: (nullable): array of properties names
 410  * @values: (nullable): array of associated properties values
 411  *
 412  * Create a new element of the type defined by the given elementfactory.
 413  * The supplied list of properties, will be passed at object construction.
 414  *
 415  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 416  *     if the element couldn't be created
 417  *
 418  * Since: 1.20
 419  */
 420 GstElement *
 421 gst_element_factory_create_with_properties (GstElementFactory * factory,
 422     guint n, const gchar * names[], const GValue values[])
 423 {
 424   GstElement *element;
 425   GstElementClass *oclass;
 426   GstElementFactory *newfactory;
 427
 428   g_return_val_if_fail (factory != NULL, NULL);
 429
 430   newfactory =
 431       GST_ELEMENT_FACTORY (gst_plugin_feature_load (GST_PLUGIN_FEATURE
 432           (factory)));
 433
 434   if (newfactory == NULL)
 435     goto load_failed;
 436
 437   factory = newfactory;
 438
 439   GST_INFO ("creating element \"%s\"", GST_OBJECT_NAME (factory));
 440
 441   if (factory->type == 0)
 442     goto no_type;
 443
 444   element = (GstElement *) g_object_new_with_properties (factory->type, n,
 445       names, values);
 446
 447   if (G_UNLIKELY (element == NULL))
 448     goto no_element;
 449
 450   /* fill in the pointer to the factory in the element class. The
 451    * class will not be unreffed currently.
 452    * Be thread safe as there might be 2 threads creating the first instance of
 453    * an element at the same moment
 454    */
 455   oclass = GST_ELEMENT_GET_CLASS (element);
 456   if (!g_atomic_pointer_compare_and_exchange (&oclass->elementfactory,
 457           (GstElementFactory *) NULL, factory))
 458     gst_object_unref (factory);
 459   else
 460     /* This ref will never be dropped as the class is never destroyed */
 461     GST_OBJECT_FLAG_SET (factory, GST_OBJECT_FLAG_MAY_BE_LEAKED);
 462
 463   if (!g_object_is_floating ((GObject *) element)) {
 464     /* The reference we receive here should be floating, but we can't force
 465      * it at our level. Simply raise a critical to make the issue obvious to bindings
 466      * users / developers */
 467     g_critical ("The created element should be floating, "
 468         "this is probably caused by faulty bindings");
 469   }
 470
 471
 472   GST_DEBUG ("created element \"%s\"", GST_OBJECT_NAME (factory));
 473
 474   return element;
 475
 476   /* ERRORS */
 477 load_failed:
 478   {
 479     GST_WARNING_OBJECT (factory, "loading plugin returned NULL!");
 480     return NULL;
 481   }
 482 no_type:
 483   {
 484     GST_WARNING_OBJECT (factory, "factory has no type");
 485     gst_object_unref (factory);
 486     return NULL;
 487   }
 488 no_element:
 489   {
 490     GST_WARNING_OBJECT (factory, "could not create element");
 491     gst_object_unref (factory);
 492     return NULL;
 493   }
 494 }
 495
 496 /**
 497  * gst_element_factory_create_valist:
 498  * @factory: factory to instantiate
 499  * @first: (nullable): name of the first property
 500  * @properties: (nullable): list of properties
 501  *
 502  * Create a new element of the type defined by the given elementfactory.
 503  * The supplied list of properties, will be passed at object construction.
 504  *
 505  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 506  *     if the element couldn't be created
 507  *
 508  * Since: 1.20
 509  */
 510 GstElement *
 511 gst_element_factory_create_valist (GstElementFactory * factory,
 512     const gchar * first, va_list properties)
 513 {
 514   GstElementFactory *newfactory;
 515   GstElement *element;
 516   const gchar **names = NULL;
 517   GValue *values = NULL;
 518   guint n = 0;
 519
 520   g_return_val_if_fail (factory != NULL, NULL);
 521
 522   newfactory =
 523       GST_ELEMENT_FACTORY (gst_plugin_feature_load (GST_PLUGIN_FEATURE
 524           (factory)));
 525
 526   g_return_val_if_fail (newfactory != NULL, NULL);
 527   g_return_val_if_fail (newfactory->type != 0, NULL);
 528
 529   factory = newfactory;
 530
 531   if (!first) {
 532     element =
 533         gst_element_factory_create_with_properties (factory, 0, NULL, NULL);
 534     goto out;
 535   }
 536
 537   if (!gst_element_factory_property_valist_to_array (first, properties,
 538           factory->type, &n, &names, &values)) {
 539     GST_ERROR_OBJECT (factory, "property parsing failed");
 540     element = NULL;
 541     goto out;
 542   }
 543
 544   element = gst_element_factory_create_with_properties (factory, n, names,
 545       values);
 546
 547   g_free (names);
 548   while (n--)
 549     g_value_unset (&values[n]);
 550   g_free (values);
 551
 552 out:
 553   gst_object_unref (factory);
 554   return element;
 555 }
 556
 557 /**
 558  * gst_element_factory_create_full:
 559  * @factory: factory to instantiate
 560  * @first: (nullable): name of the first property
 561  * @...: (nullable): %NULL terminated list of properties
 562  *
 563  * Create a new element of the type defined by the given elementfactory.
 564  * The supplied list of properties, will be passed at object construction.
 565  *
 566  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 567  *     if the element couldn't be created
 568  *
 569  * Since: 1.20
 570  */
 571 GstElement *
 572 gst_element_factory_create_full (GstElementFactory * factory,
 573     const gchar * first, ...)
 574 {
 575   GstElement *element;
 576   va_list properties;
 577
 578   va_start (properties, first);
 579   element = gst_element_factory_create_valist (factory, first, properties);
 580   va_end (properties);
 581
 582   return element;
 583 }
 584
 585 /**
 586  * gst_element_factory_create:
 587  * @factory: factory to instantiate
 588  * @name: (nullable): name of new element, or %NULL to automatically create
 589  *    a unique name
 590  *
 591  * Create a new element of the type defined by the given elementfactory.
 592  * It will be given the name supplied, since all elements require a name as
 593  * their first argument.
 594  *
 595  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 596  *     if the element couldn't be created
 597  */
 598 GstElement *
 599 gst_element_factory_create (GstElementFactory * factory, const gchar * name)
 600 {
 601   if (name)
 602     return gst_element_factory_create_full (factory, "name", name, NULL);
 603   else
 604     return gst_element_factory_create_with_properties (factory, 0, NULL, NULL);
 605 }
 606
 607 /**
 608  * gst_element_factory_make_with_properties:
 609  * @factoryname: a named factory to instantiate
 610  * @n: count of properties
 611  * @names: (nullable): array of properties names
 612  * @values: (nullable): array of associated properties values
 613  *
 614  * Create a new element of the type defined by the given elementfactory.
 615  * The supplied list of properties, will be passed at object construction.
 616  *
 617  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 618  *     if the element couldn't be created
 619  *
 620  * Since: 1.20
 621  */
 622 GstElement *
 623 gst_element_factory_make_with_properties (const gchar * factoryname,
 624     guint n, const gchar * names[], const GValue values[])
 625 {
 626   GstElementFactory *factory;
 627   GstElement *element;
 628
 629   g_return_val_if_fail (factoryname != NULL, NULL);
 630   g_return_val_if_fail (gst_is_initialized (), NULL);
 631
 632   GST_LOG ("gstelementfactory: make \"%s\"", factoryname);
 633
 634   factory = gst_element_factory_find (factoryname);
 635   if (factory == NULL)
 636     goto no_factory;
 637
 638   GST_LOG_OBJECT (factory, "found factory %p", factory);
 639   element = gst_element_factory_create_with_properties (factory, n, names,
 640       values);
 641   if (element == NULL)
 642     goto create_failed;
 643
 644   gst_object_unref (factory);
 645
 646   return element;
 647
 648   /* ERRORS */
 649 no_factory:
 650   {
 651     GST_WARNING ("no such element factory \"%s\"!", factoryname);
 652     return NULL;
 653   }
 654 create_failed:
 655   {
 656     GST_INFO_OBJECT (factory, "couldn't create instance!");
 657     gst_object_unref (factory);
 658     return NULL;
 659   }
 660 }
 661
 662 /**
 663  * gst_element_factory_make_valist:
 664  * @factoryname: a named factory to instantiate
 665  * @first: (nullable): name of first property
 666  * @properties: (nullable): list of properties
 667  *
 668  * Create a new element of the type defined by the given element factory.
 669  * The supplied list of properties, will be passed at object construction.
 670  *
 671  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 672  * if unable to create element
 673  *
 674  * Since: 1.20
 675  */
 676 GstElement *
 677 gst_element_factory_make_valist (const gchar * factoryname,
 678     const gchar * first, va_list properties)
 679 {
 680   GstElementFactory *factory;
 681   GstElement *element;
 682
 683   g_return_val_if_fail (factoryname != NULL, NULL);
 684   g_return_val_if_fail (gst_is_initialized (), NULL);
 685
 686   GST_LOG ("gstelementfactory: make \"%s\"", factoryname);
 687
 688   factory = gst_element_factory_find (factoryname);
 689   if (factory == NULL)
 690     goto no_factory;
 691
 692   GST_LOG_OBJECT (factory, "found factory %p", factory);
 693   element = gst_element_factory_create_valist (factory, first, properties);
 694   if (element == NULL)
 695     goto create_failed;
 696
 697   gst_object_unref (factory);
 698
 699   return element;
 700
 701   /* ERRORS */
 702 no_factory:
 703   {
 704     GST_WARNING ("no such element factory \"%s\"!", factoryname);
 705     return NULL;
 706   }
 707 create_failed:
 708   {
 709     GST_INFO_OBJECT (factory, "couldn't create instance!");
 710     gst_object_unref (factory);
 711     return NULL;
 712   }
 713 }
 714
 715 /**
 716  * gst_element_factory_make_full:
 717  * @factoryname: a named factory to instantiate
 718  * @first: (nullable): name of first property
 719  * @...: (nullable): %NULL terminated list of properties
 720  *
 721  * Create a new element of the type defined by the given element factory.
 722  * The supplied list of properties, will be passed at object construction.
 723  *
 724  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 725  * if unable to create element
 726  *
 727  * Since: 1.20
 728  */
 729 GstElement *
 730 gst_element_factory_make_full (const gchar * factoryname,
 731     const gchar * first, ...)
 732 {
 733   GstElement *element;
 734   va_list properties;
 735
 736   va_start (properties, first);
 737
 738   element = gst_element_factory_make_valist (factoryname, first, properties);
 739
 740   va_end (properties);
 741   return element;
 742 }
 743
 744 /**
 745  * gst_element_factory_make:
 746  * @factoryname: a named factory to instantiate
 747  * @name: (nullable): name of new element, or %NULL to automatically create
 748  *    a unique name
 749  *
 750  * Create a new element of the type defined by the given element factory.
 751  * If name is %NULL, then the element will receive a guaranteed unique name,
 752  * consisting of the element factory name and a number.
 753  * If name is given, it will be given the name supplied.
 754  *
 755  * Returns: (transfer floating) (nullable): new #GstElement or %NULL
 756  * if unable to create element
 757  */
 758 GstElement *
 759 gst_element_factory_make (const gchar * factoryname, const gchar * name)
 760 {
 761   if (name)
 762     return gst_element_factory_make_full (factoryname, "name", name, NULL);
 763   else
 764     return gst_element_factory_make_with_properties (factoryname, 0, NULL,
 765         NULL);
 766 }
 767
 768 void
 769 __gst_element_factory_add_static_pad_template (GstElementFactory * factory,
 770     GstStaticPadTemplate * templ)
 771 {
 772   g_return_if_fail (factory != NULL);
 773   g_return_if_fail (templ != NULL);
 774
 775   factory->staticpadtemplates =
 776       g_list_append (factory->staticpadtemplates, templ);
 777   factory->numpadtemplates++;
 778 }
 779
 780 /**
 781  * gst_element_factory_get_element_type:
 782  * @factory: factory to get managed #GType from
 783  *
 784  * Get the #GType for elements managed by this factory. The type can
 785  * only be retrieved if the element factory is loaded, which can be
 786  * assured with gst_plugin_feature_load().
 787  *
 788  * Returns: the #GType for elements managed by this factory or 0 if
 789  * the factory is not loaded.
 790  */
 791 GType
 792 gst_element_factory_get_element_type (GstElementFactory * factory)
 793 {
 794   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), 0);
 795
 796   return factory->type;
 797 }
 798
 799 /**
 800  * gst_element_factory_get_metadata:
 801  * @factory: a #GstElementFactory
 802  * @key: a key
 803  *
 804  * Get the metadata on @factory with @key.
 805  *
 806  * Returns: (nullable): the metadata with @key on @factory or %NULL
 807  * when there was no metadata with the given @key.
 808  */
 809 const gchar *
 810 gst_element_factory_get_metadata (GstElementFactory * factory,
 811     const gchar * key)
 812 {
 813   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 814
 815   return gst_structure_get_string ((GstStructure *) factory->metadata, key);
 816 }
 817
 818 /**
 819  * gst_element_factory_get_metadata_keys:
 820  * @factory: a #GstElementFactory
 821  *
 822  * Get the available keys for the metadata on @factory.
 823  *
 824  * Returns: (transfer full) (element-type utf8) (array zero-terminated=1) (nullable):
 825  * a %NULL-terminated array of key strings, or %NULL when there is no
 826  * metadata. Free with g_strfreev() when no longer needed.
 827  */
 828 gchar **
 829 gst_element_factory_get_metadata_keys (GstElementFactory * factory)
 830 {
 831   GstStructure *metadata;
 832   gchar **arr;
 833   gint i, num;
 834
 835   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 836
 837   metadata = (GstStructure *) factory->metadata;
 838   if (metadata == NULL)
 839     return NULL;
 840
 841   num = gst_structure_n_fields (metadata);
 842   if (num == 0)
 843     return NULL;
 844
 845   arr = g_new (gchar *, num + 1);
 846   for (i = 0; i < num; ++i) {
 847     arr[i] = g_strdup (gst_structure_nth_field_name (metadata, i));
 848   }
 849   arr[i] = NULL;
 850   return arr;
 851 }
 852
 853 /**
 854  * gst_element_factory_get_num_pad_templates:
 855  * @factory: a #GstElementFactory
 856  *
 857  * Gets the number of pad_templates in this factory.
 858  *
 859  * Returns: the number of pad_templates
 860  */
 861 guint
 862 gst_element_factory_get_num_pad_templates (GstElementFactory * factory)
 863 {
 864   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), 0);
 865
 866   return factory->numpadtemplates;
 867 }
 868
 869 /**
 870  * __gst_element_factory_add_interface:
 871  * @elementfactory: The elementfactory to add the interface to
 872  * @interfacename: Name of the interface
 873  *
 874  * Adds the given interfacename to the list of implemented interfaces of the
 875  * element.
 876  */
 877 void
 878 __gst_element_factory_add_interface (GstElementFactory * elementfactory,
 879     const gchar * interfacename)
 880 {
 881   g_return_if_fail (GST_IS_ELEMENT_FACTORY (elementfactory));
 882   g_return_if_fail (interfacename != NULL);
 883   g_return_if_fail (interfacename[0] != '\0');  /* no empty string */
 884
 885   elementfactory->interfaces =
 886       g_list_prepend (elementfactory->interfaces,
 887       (gpointer) g_intern_string (interfacename));
 888 }
 889
 890 /**
 891  * gst_element_factory_get_static_pad_templates:
 892  * @factory: a #GstElementFactory
 893  *
 894  * Gets the #GList of #GstStaticPadTemplate for this factory.
 895  *
 896  * Returns: (transfer none) (element-type Gst.StaticPadTemplate): the
 897  *     static pad templates
 898  */
 899 const GList *
 900 gst_element_factory_get_static_pad_templates (GstElementFactory * factory)
 901 {
 902   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 903
 904   return factory->staticpadtemplates;
 905 }
 906
 907 /**
 908  * gst_element_factory_get_uri_type:
 909  * @factory: a #GstElementFactory
 910  *
 911  * Gets the type of URIs the element supports or #GST_URI_UNKNOWN if none.
 912  *
 913  * Returns: type of URIs this element supports
 914  */
 915 GstURIType
 916 gst_element_factory_get_uri_type (GstElementFactory * factory)
 917 {
 918   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), GST_URI_UNKNOWN);
 919
 920   return factory->uri_type;
 921 }
 922
 923 /**
 924  * gst_element_factory_get_uri_protocols:
 925  * @factory: a #GstElementFactory
 926  *
 927  * Gets a %NULL-terminated array of protocols this element supports or %NULL if
 928  * no protocols are supported. You may not change the contents of the returned
 929  * array, as it is still owned by the element factory. Use g_strdupv() to
 930  * make a copy of the protocol string array if you need to.
 931  *
 932  * Returns: (transfer none) (array zero-terminated=1): the supported protocols
 933  *     or %NULL
 934  */
 935 const gchar *const *
 936 gst_element_factory_get_uri_protocols (GstElementFactory * factory)
 937 {
 938   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 939
 940   return (const gchar * const *) factory->uri_protocols;
 941 }
 942
 943 /**
 944  * gst_element_factory_has_interface:
 945  * @factory: a #GstElementFactory
 946  * @interfacename: an interface name
 947  *
 948  * Check if @factory implements the interface with name @interfacename.
 949  *
 950  * Returns: %TRUE when @factory implement the interface.
 951  */
 952 gboolean
 953 gst_element_factory_has_interface (GstElementFactory * factory,
 954     const gchar * interfacename)
 955 {
 956   GList *walk;
 957
 958   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), FALSE);
 959
 960   for (walk = factory->interfaces; walk; walk = g_list_next (walk)) {
 961     gchar *iname = (gchar *) walk->data;
 962
 963     if (!strcmp (iname, interfacename))
 964       return TRUE;
 965   }
 966   return FALSE;
 967 }
 968
 969
 970 typedef struct
 971 {
 972   GstElementFactoryListType type;
 973   GstRank minrank;
 974 } FilterData;
 975
 976
 977 /**
 978  * gst_element_factory_list_is_type:
 979  * @factory: a #GstElementFactory
 980  * @type: a #GstElementFactoryListType
 981  *
 982  * Check if @factory is of the given types.
 983  *
 984  * Returns: %TRUE if @factory is of @type.
 985  */
 986 gboolean
 987 gst_element_factory_list_is_type (GstElementFactory * factory,
 988     GstElementFactoryListType type)
 989 {
 990   gboolean res = FALSE;
 991   const gchar *klass;
 992
 993   klass =
 994       gst_element_factory_get_metadata (factory, GST_ELEMENT_METADATA_KLASS);
 995
 996   if (klass == NULL) {
 997     GST_ERROR_OBJECT (factory, "element factory is missing klass identifiers");
 998     return res;
 999   }
1000
1001   /* Filter by element type first, as soon as it matches
1002    * one type, we skip all other tests */
1003   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_SINK))
1004     res = (strstr (klass, "Sink") != NULL);
1005
1006   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_SRC))
1007     res = (strstr (klass, "Source") != NULL);
1008
1009   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_DECODER))
1010     res = (strstr (klass, "Decoder") != NULL);
1011
1012   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_ENCODER))
1013     res = (strstr (klass, "Encoder") != NULL);
1014
1015   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_MUXER))
1016     res = (strstr (klass, "Muxer") != NULL);
1017
1018   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_DEMUXER))
1019     res = (strstr (klass, "Demux") != NULL);
1020
1021   /* FIXME : We're actually parsing two Classes here... */
1022   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_PARSER))
1023     res = ((strstr (klass, "Parser") != NULL)
1024         && (strstr (klass, "Codec") != NULL));
1025
1026   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_DEPAYLOADER))
1027     res = (strstr (klass, "Depayloader") != NULL);
1028
1029   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_PAYLOADER))
1030     res = (strstr (klass, "Payloader") != NULL);
1031
1032   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_FORMATTER))
1033     res = (strstr (klass, "Formatter") != NULL);
1034
1035   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_DECRYPTOR))
1036     res = (strstr (klass, "Decryptor") != NULL);
1037
1038   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_ENCRYPTOR))
1039     res = (strstr (klass, "Encryptor") != NULL);
1040
1041   if (!res && (type & GST_ELEMENT_FACTORY_TYPE_HARDWARE))
1042     res = (strstr (klass, "Hardware") != NULL);
1043
1044   /* Filter by media type now, we only test if it
1045    * matched any of the types above or only checking the media
1046    * type was requested. */
1047   if ((res || !(type & (GST_ELEMENT_FACTORY_TYPE_MAX_ELEMENTS - 1)))
1048       && (type & (GST_ELEMENT_FACTORY_TYPE_MEDIA_AUDIO |
1049               GST_ELEMENT_FACTORY_TYPE_MEDIA_VIDEO |
1050               GST_ELEMENT_FACTORY_TYPE_MEDIA_IMAGE |
1051               GST_ELEMENT_FACTORY_TYPE_MEDIA_SUBTITLE |
1052               GST_ELEMENT_FACTORY_TYPE_MEDIA_METADATA)))
1053     res = ((type & GST_ELEMENT_FACTORY_TYPE_MEDIA_AUDIO)
1054         && (strstr (klass, "Audio") != NULL))
1055         || ((type & GST_ELEMENT_FACTORY_TYPE_MEDIA_VIDEO)
1056         && (strstr (klass, "Video") != NULL))
1057         || ((type & GST_ELEMENT_FACTORY_TYPE_MEDIA_IMAGE)
1058         && (strstr (klass, "Image") != NULL)) ||
1059         ((type & GST_ELEMENT_FACTORY_TYPE_MEDIA_SUBTITLE)
1060         && (strstr (klass, "Subtitle") != NULL)) ||
1061         ((type & GST_ELEMENT_FACTORY_TYPE_MEDIA_METADATA)
1062         && (strstr (klass, "Metadata") != NULL));
1063
1064   return res;
1065 }
1066
1067 static gboolean
1068 element_filter (GstPluginFeature * feature, FilterData * data)
1069 {
1070   gboolean res;
1071
1072   /* we only care about element factories */
1073   if (G_UNLIKELY (!GST_IS_ELEMENT_FACTORY (feature)))
1074     return FALSE;
1075
1076   res = (gst_plugin_feature_get_rank (feature) >= data->minrank) &&
1077       gst_element_factory_list_is_type (GST_ELEMENT_FACTORY_CAST (feature),
1078       data->type);
1079
1080   return res;
1081 }
1082
1083 /**
1084  * gst_element_factory_list_get_elements:
1085  * @type: a #GstElementFactoryListType
1086  * @minrank: Minimum rank
1087  *
1088  * Get a list of factories that match the given @type. Only elements
1089  * with a rank greater or equal to @minrank will be returned.
1090  * The list of factories is returned by decreasing rank.
1091  *
1092  * Returns: (transfer full) (element-type Gst.ElementFactory): a #GList of
1093  *     #GstElementFactory elements. Use gst_plugin_feature_list_free() after
1094  *     usage.
1095  */
1096 GList *
1097 gst_element_factory_list_get_elements (GstElementFactoryListType type,
1098     GstRank minrank)
1099 {
1100   GList *result;
1101   FilterData data;
1102
1103   /* prepare type */
1104   data.type = type;
1105   data.minrank = minrank;
1106
1107   /* get the feature list using the filter */
1108   result = gst_registry_feature_filter (gst_registry_get (),
1109       (GstPluginFeatureFilter) element_filter, FALSE, &data);
1110
1111   /* sort on rank and name */
1112   result = g_list_sort (result, gst_plugin_feature_rank_compare_func);
1113
1114   return result;
1115 }
1116
1117 /**
1118  * gst_element_factory_list_filter:
1119  * @list: (transfer none) (element-type Gst.ElementFactory): a #GList of
1120  *     #GstElementFactory to filter
1121  * @caps: a #GstCaps
1122  * @direction: a #GstPadDirection to filter on
1123  * @subsetonly: whether to filter on caps subsets or not.
1124  *
1125  * Filter out all the elementfactories in @list that can handle @caps in
1126  * the given direction.
1127  *
1128  * If @subsetonly is %TRUE, then only the elements whose pads templates
1129  * are a complete superset of @caps will be returned. Else any element
1130  * whose pad templates caps can intersect with @caps will be returned.
1131  *
1132  * Returns: (transfer full) (element-type Gst.ElementFactory): a #GList of
1133  *     #GstElementFactory elements that match the given requisites.
1134  *     Use #gst_plugin_feature_list_free after usage.
1135  */
1136 GList *
1137 gst_element_factory_list_filter (GList * list,
1138     const GstCaps * caps, GstPadDirection direction, gboolean subsetonly)
1139 {
1140   GQueue results = G_QUEUE_INIT;
1141
1142   GST_DEBUG ("finding factories");
1143
1144   /* loop over all the factories */
1145   for (; list; list = list->next) {
1146     GstElementFactory *factory;
1147     const GList *templates;
1148     GList *walk;
1149
1150     factory = (GstElementFactory *) list->data;
1151
1152     GST_DEBUG ("Trying %s",
1153         gst_plugin_feature_get_name ((GstPluginFeature *) factory));
1154
1155     /* get the templates from the element factory */
1156     templates = gst_element_factory_get_static_pad_templates (factory);
1157     for (walk = (GList *) templates; walk; walk = g_list_next (walk)) {
1158       GstStaticPadTemplate *templ = walk->data;
1159
1160       /* we only care about the sink templates */
1161       if (templ->direction == direction) {
1162         GstCaps *tmpl_caps;
1163
1164         /* try to intersect the caps with the caps of the template */
1165         tmpl_caps = gst_static_caps_get (&templ->static_caps);
1166
1167         /* FIXME, intersect is not the right method, we ideally want to check
1168          * for a subset here */
1169
1170         /* check if the intersection is empty */
1171         if ((subsetonly && gst_caps_is_subset (caps, tmpl_caps)) ||
1172             (!subsetonly && gst_caps_can_intersect (caps, tmpl_caps))) {
1173           /* non empty intersection, we can use this element */
1174           g_queue_push_tail (&results, gst_object_ref (factory));
1175           gst_caps_unref (tmpl_caps);
1176           break;
1177         }
1178         gst_caps_unref (tmpl_caps);
1179       }
1180     }
1181   }
1182   return results.head;
1183 }
1184
1185 #ifdef TIZEN_PROFILE_TV
1186 /**
1187  * gst_element_factory_pool_push:
1188  *
1189  * Pushes the element to the pool. This function increase the refcount of @element.
1190  * And the pool will take a reference forever.
1191  * MT safe.
1192  */
1193 static gboolean
1194 gst_element_factory_pool_push (GstElement * element)
1195 {
1196   gboolean ret = FALSE;
1197   g_return_val_if_fail (element != NULL, FALSE);
1198   g_return_val_if_fail (GST_IS_ELEMENT (element) == TRUE, FALSE);
1199   g_return_val_if_fail (GST_IS_BIN (element) == FALSE, FALSE);
1200   g_return_val_if_fail (GST_IS_PIPELINE (element) == FALSE, FALSE);
1201
1202   g_mutex_lock (&pool_mutex);
1203   if (!g_list_find (pool, (gconstpointer) element)) {
1204     gst_object_ref (element);
1205     pool = g_list_prepend (pool, element);
1206     ret = TRUE;
1207   }
1208   //GST_INFO("ret[ %d ], [ %s / %p ] - refcount[ %d ], state[ %d ]", ret, GST_ELEMENT_NAME(element), element, GST_OBJECT_REFCOUNT(element), GST_STATE (element));
1209   g_mutex_unlock (&pool_mutex);
1210   return ret;
1211 }
1212
1213 static gint
1214 is_available_element (gconstpointer data, gconstpointer factory_)
1215 {
1216   GstElement *element = GST_ELEMENT_CAST (data);
1217   const GstElementFactory *factory = (const GstElementFactory *) factory_;
1218   gboolean found = FALSE;
1219   if (gst_element_get_factory (element) == factory
1220       && GST_ELEMENT_PARENT (element) == NULL
1221       && GST_OBJECT_REFCOUNT (element) == 1
1222       && (GST_STATE (element) == GST_STATE_NULL
1223           || GST_STATE (element) == GST_STATE_VOID_PENDING)) {
1224     found = TRUE;
1225   }
1226   //GST_DEBUG("PARENT[ %p ], [ %s / %p ] - refcount[ %d ], state[ %d ]", GST_ELEMENT_PARENT(element), GST_ELEMENT_NAME(element), element, GST_OBJECT_REFCOUNT(element), GST_STATE (element));
1227
1228   if (found)
1229     return 0;
1230
1231   return -1;
1232 }
1233
1234 /**
1235  * gst_element_factory_pool_get:
1236  *
1237  * Get a element which is created by given @factoryname
1238  * You can search any element by this API before you use gst_element_factory_create.
1239  * Returns: (transfer full): a pointer to the #GstElement.
1240  *         This function guarantee that the refcount of returned #GstElement is 1,
1241  *         and it's state is NULL-STATE.
1242  *
1243  * MT safe.
1244  */
1245 static GstElement *
1246 gst_element_factory_pool_get (GstElementFactory * factory,
1247     const gchar * new_element_name)
1248 {
1249   GstElement *element = NULL;
1250   GList *found = NULL;
1251   g_return_val_if_fail (factory != NULL, NULL);
1252   g_return_val_if_fail (pool != NULL, NULL);
1253
1254   g_mutex_lock (&pool_mutex);
1255   found = g_list_find_custom (pool, factory, is_available_element);
1256   if (found) {
1257     element = GST_ELEMENT_CAST (found->data);
1258     gst_object_ref (element);
1259     if (new_element_name)
1260       gst_element_set_name (element, new_element_name);
1261   }
1262   g_mutex_unlock (&pool_mutex);
1263   return element;
1264 }
1265
1266 /* First, Try to get element from pool. */
1267 GstElement *
1268 gst_element_factory_get (GstElementFactory * factory, const gchar * name)
1269 {
1270   GstElement *element = NULL;
1271   g_return_val_if_fail (factory != NULL, NULL);
1272   element = gst_element_factory_pool_get (factory, name);
1273   if (!element) {
1274     element = gst_element_factory_create (factory, name);
1275     if (!element) {
1276       GST_ERROR ("[ %s / %p ],  new element name[ %s ]",
1277           GST_OBJECT_NAME (factory), factory, name);
1278       return NULL;
1279     }
1280     gst_element_factory_pool_push (element);
1281   } else {
1282     gst_set_family_id_to_child (element, 0);
1283   }
1284
1285   //GST_INFO("[ %s / %p ] - refcount[ %d ], state[ %d ]", GST_ELEMENT_NAME(element), element, GST_OBJECT_REFCOUNT(element), GST_STATE (element));
1286   return element;
1287 }
1288 #endif