[gst-devel] plugin breakage

[Benjamin Otte]

Hallo my poor little helpers,

I've got a job for you.

As you may know I rewrote quite a bit of the plugin initialization part
in HEAD.
This unfortunately requires adapting every single plugin manually. And
since I'm as lazy as anyone I'll just not fix gst-plugins all by myself
but leave that up to you.
So until all plugins are fixed, make in gst-plugins won't work.

What changed and what do you need to do? (examples ripped from mad plugin)

1)
the plugin_desc structure got more fields and must now be initialized with
a macro. The reason for the macro is to make sure that the struct padding
is initialized as 0 bytes and to make sure that every field is
initialized. There are macros to be used for the default fields as seen in
the example. Missing in the example is GST_LICENSE which should be used
for plugins that use GStreamer's license. These macros are defined in
config.h.
old code:
GstPluginDesc plugin_desc = {
   GST_VERSION_MAJOR,
   GST_VERSION_MINOR,
   "mad",
  plugin_init
};
new code:
GST_PLUGIN_DEFINE (
   GST_VERSION_MAJOR,
   GST_VERSION_MINOR,
   "mad",
  "mp3 decoding based on the mad library",
  plugin_init,
  VERSION,
  "GPL",
  GST_COPYRIGHT,
  GST_PACKAGE,
  GST_ORIGIN
)

2)
The prototype of the plugin_init function changed and doesn't include the
module anymore. If you require access to the GModule in the plugin_init
function (nothing I know does, but just in case) use
gst_plugin_get_module.
old code:
typedef gboolean (*GstPluginInitFunc) (GModule *module, GstPlugin
*plugin);
new code:
typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin);

3)
Pad templates and element details are added to the element's class
structure in the base_init function. You must use the base_init function
and not the class_init function for this, because the class_init function
is only called once, not once per subclass as the base_init.
The functions are called gst_element_class_add_padtemplate and
gst_element_class_set_details. This was formerly done in the plugin_init
function but had to be changed because they are needed for subclassing.

4)
The GstElementDetails struct contains less fields than before. Those
fields got moved into the plugin_desc structure, because they don't make
sense on a per-element basis. The GstElementDetails structure must be
initialised with a macro now, too for the same reasons as the plugin
description.
old code:
/* elementfactory information */
static GstElementDetails gst_mad_details = {
  "mad mp3 decoder",
  "Codec/Audio/Decoder",
  "GPL",
  "Uses mad code to decode mp3 streams",
  VERSION,
  "Wim Taymans <wim.taymans at chello.be>",
  "(C) 2001",
};
new code:
/* elementfactory information */
static GstElementDetails gst_mad_details = GST_ELEMENT_DETAILS (
  "mad mp3 decoder",
  "Codec/Audio/Decoder",
  "Uses mad code to decode mp3 streams",
  "Wim Taymans <wim.taymans at chello.be>"
);

5)
the rank enum naming got changed because ranks are used in all plugin
features and aren't element specific.
So it's GST_RANK_PRIMARY instead of GST_ELEMENT_RANK_PRIMARY now.

6)
Elements are initialized now with one function:
gboolean gst_element_register (GstPlugin *plugin, const gchar *name,
                               guint rank, GType element_type);
Since all other information is added in the base_init function,
gst_element_register extracts it from there automatically.
Elemets that didn't have a rank before should use GST_RANK_NONE.
old code:
  GstElementFactory *factory;

  /* create an elementfactory for the mad element */
  factory = gst_element_factory_new ("mad", GST_TYPE_MAD,
&gst_mad_details);
  g_return_val_if_fail (factory != NULL, FALSE);
  gst_element_factory_add_pad_template (factory,
                 GST_PAD_TEMPLATE_GET (mad_sink_template_factory));
  gst_element_factory_add_pad_template (factory,
                 GST_PAD_TEMPLATE_GET (mad_src_template_factory));
  gst_element_factory_set_rank (factory, GST_ELEMENT_RANK_PRIMARY);
  gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (factory));
new code:
  if (!gst_element_register (plugin, "mad", GST_RANK_PRIMARY, GST_TYPE_MAD))
    return FALSE;

7)
gst_type_find_factory_register got renamed to gst_type_find_register and
returns a gboolean now to match the register functions.

8)
The plugin loader now makes sure that no 2 plugins with the same name get
loaded. If there already is a plugin with that name, loading the new
plugin will fail. This makes sure no plugin is loaded twice.

9)
There is a list of valid licenses in gst/gstplugin.c now. If the license
of a plugin doesn't match one of those, it won't be loaded. If the license
isn't listed there, either add it and make sure people can read that
license somewhere (add the URL in the comments if the license isn't
common) or use GST_LICENSE_UNKNOWN.
This might be changed in the future to check if a plugin LICENSE matches
an application's license btw if some legal team donates that code, so only
write free plugins :)


I hope I didn't forget anything and didn't break too much while doing
this. I wasn't too motivated unfortunately because it was boring stuff.

Benjamin