Extending neuray with plugins

This topic introduces:

Important interfaces and the required steps to add functionality and package it as a plugin:
- Implementing a plugin
- Loading a plugin
The programs plugin.cpp and example_plugins.cpp, which demonstrate how to provide additional functionality as plugins. This example extends the user-defined classes described in Extending the database with user-defined classes. The functionality of the IMy_class interface is provided to the main application by using a plugin. Therefore, the main application only needs the definition of the interface IMy_class and the compiled plugin, but not the source code of the implementation.

Implementing a plugin

To implement a plugin you need to provide an implementation of the mi::neuraylib::IPlugin interface. An example implementation of such a class is shown in the code below. The most important part is the implementation of the mi::neuraylib::IPlugin::init() method which has to register all user-defined classes.

Finally you need to provide a factory function called mi_plugin_factory() that creates an instance of your implementation of mi::neuraylib::IPlugin. Again, using the example implementation as shown in the code below is fine.

You need to compile the implementation of your interfaces, your implementation of mi::neuraylib::IPlugin, and the factory function, and to create a DSO from the object code. Using g++ you can use commands similar to the following:

g++ -I$NEURAY_ROOT/include -fPIC -c plugin.cpp -o plugin.o
g++ -shared -export-dynamic --whole-archive plugin.o -o libplugin.so

Loading a plugin

You can load plugins by passing the filename to the method mi::neuraylib::IPlugin_configuration::load_plugin_library(). After the plugin has been loaded (in a way similar to the loading of the DSO for the Iray API itself), the method mi::neuraylib::IPlugin::init() is called. In this method you need to register all user-defined classes.

Using the user-defined class works the same way as for all other classes. In particular there is no difference to user-defined classes defined in the main application as described in Extending the database with user-defined classes.

plugin.cpp

Plain text

001 /******************************************************************************
002  * © 1986, 2014 NVIDIA Corporation. All rights reserved.
003  *****************************************************************************/
004 
005 #include <mi/neuraylib.h>
006 #include "my_class.h"
007 
008 // Implementation of the IPlugin interface
009 class Plugin_impl : public mi::neuraylib::IPlugin
010 {
011 public:
012     // Virtual destructor
013     virtual ~Plugin_impl() { }
014 
015     // Returns the name of the plugin
016     const char* get_name() const { return "example plugin"; }
017 
018     // Returns the type of the plugin
019     const char* get_type() const { return MI_NEURAYLIB_PLUGIN_TYPE; }
020 
021     // Returns the version of the plugin
022     mi::Sint32 get_version() const { return 1; }
023 
024     // Returns the compiler used to compile the plugin
025     const char* get_compiler() const { return "unknown"; }
026 
027     // Releases the plugin giving back all allocated resources
028     void release() { delete this; }
029 
030     // Initializes the plugin
031     bool init( mi::neuraylib::IPlugin_api* plugin_api)
032     {
033         mi::base::Handle<mi::neuraylib::ILogging_configuration> logging_configuration(
034             plugin_api->get_api_component<mi::neuraylib::ILogging_configuration>());
035         mi::base::Handle<mi::base::ILogger> logger(
036             logging_configuration->get_forwarding_logger());
037         logger->message( mi::base::MESSAGE_SEVERITY_INFO, "PLUGIN",
038             "Plugin_impl::init() called");
039         mi::base::Handle<mi::neuraylib::IExtension_api> extension_api(
040             plugin_api->get_api_component<mi::neuraylib::IExtension_api>());
041         if( ! extension_api.is_valid_interface())
042             return false;
043         return extension_api->register_class<My_class>( "My_class") == 0;
044     }
045 
046     // Exits the plugin
047     bool exit( mi::neuraylib::IPlugin_api* plugin_api)
048     {
049         mi::base::Handle<mi::neuraylib::ILogging_configuration> logging_configuration(
050             plugin_api->get_api_component<mi::neuraylib::ILogging_configuration>());
051         mi::base::Handle<mi::base::ILogger> logger(
052             logging_configuration->get_forwarding_logger());
053         logger->message( mi::base::MESSAGE_SEVERITY_INFO, "PLUGIN",
054             "Plugin_impl::exit() called");
055         return true;
056     }
057 };
058 
059 // Factory to create an instance of Plugin_impl
060 extern "C"
061 MI_DLL_EXPORT
062 mi::base::Plugin* mi_plugin_factory(
063     mi::Sint32 index,         // index of the plugin
064     void* context)            // context given to the library, ignore
065 {
066     if( index != 0)
067         return 0;
068     return new Plugin_impl;
069 }

example_plugins.cpp