V-Ray plugins

This article describes the V-Ray plugin system.

 

General

Interface programming

Plugin management system

Loading and creating plugins

V-Ray-specific plugins

Plugin parameters

Parameter caching

Setting plugin parameters

Types of V-Ray plugins

General

The V-Ray plugin system is primarily designed to allow extensions of the standalone version of V-Ray, as well as providing a means of reusing V-Ray extensions on different V-Ray implementations. For example, you can use many of the plugins (i.e. shaders) written for the standalone version in your specific V-Ray implementation and vice versa.

 

Many examples for V-Ray plugins are included with the SDK. We recommend studying these examples carefully.

 

Note that the V-Ray plugin system is not directly connected in any way to the V-Ray core API. You are not required to use the plugin system in your own V-Ray implementations. Also, the V-Ray plugin system is designed on top of an independent plugin management system, which is not directly related to V-Ray.

Interface programming

The plugin system used in V-Ray is designed around the concept of interface programming, where a single class can support different interfaces, which allow it to be processed in different ways. An example of this is a V-Ray area light plugin. It is treated both as a light object that can be called to illuminate surfaces and emit photons, and as a geometric object which can generate geometry and be visible in the scene.

 

The base class from which all interface-supporting classes must be derived is class PluginBase. This class has only two methods, newInterface() and deleteInterface(), which are called to request a certain interface from the object. If this interface is supported, a pointer to the corresponding PluginInterface class is returned. If the interface is not supported, NULL must be returned. When the interface is no longer needed, deleteInterface() is called to release it. Very often, returning an interface is as simple as casting the base class to the specific interface class, in which case deleteInterface() doesn't have to do anything.

 

An interface must be derived from class PluginInterface and must implement some informational methods, like returning the ID of the interface etc.

 

Here is a small example of a class that supports two separate interfaces:

 

#include "plugman.h"

 

//**********************************************

// The definition of the first interface

//**********************************************

 

#define INTERFACE_ONE_ID 0x1000000

 

class InterfaceOne: public PluginInterface {

public:

// Methods from PluginInterface

InterfaceID getInterfaceID(void) { return INTERFACE_ONE_ID; }

tchar* getInterfaceName(void) { return "InterfaceOne"; }

 

// The specific interface methods

void myFunc1(void) { printf("MyFunc1\n"); }

};

//**********************************************

// The definition of the second interface

//**********************************************

 

#define INTERFACE_TWO_ID 0x2000000

 

class InterfaceTwo: public PluginInterface {

public:

// Methods from PluginInterface

InterfaceID getInterfaceID(void) { return INTERFACE_TWO_ID; }

tchar* getInterfaceName(void) { return "InterfaceTwo"; }

 

// The specific interface methods

void myFunc2(void) { printf("MyFunc2\n"); }

};

 

//**********************************************

// The definition of a plugin class that supports

// the two interfaces

//**********************************************

 

class MyPlugin: public PluginBase, public InterfaceOne, public InterfaceTwo {

public:

// Methods from PluginBase

PluginInterface *newInterface(InterfaceID id) {

if (id==INTERFACE_ONE_ID) return (InterfaceOne*) this;

if (id==INTERFACE_TWO_ID) return (InterfaceTwo*) this;

return NULL;

}

void deleteInterface(void) {}

 

// Methods from PluginInterface

PluginBase* getPlugin(void) { return (PluginBase*) this; }

};

 

Interface programming allows the plugin system to be easily extensible in the future - new interfaces can be added without breaking the old ones.

Plugin management system

The plugin management system is designed to support dynamic loading of plugin classes at run-time. The base class from which dynamic plugins are derived is class Plugin. Each plugin class must have a unique PluginID, and must provide a description in the form of a PluginDesc class.

 

All plugins are managed by a PluginManager. The plugin manager has methods for loading, creating and destroying plugins.

 

Under the Windows operating system, plugins are compiled in the form of a DLL file. The DLL file must provide a description of the plugins it contains. This can be done with the EXPORT_PLUGIN_LIBRARY macro:

 

MyLibDesc libDesc;

EXPORT_PLUGIN_LIBRARY(libDesc);

 

This macro exports a function called "getLibDesc" from the DLL. The plugin manager uses the returned instance of class PluginLibDesc to obtain information about the plugins contained in the library.

 

A single DLL can contain multiple plugins. For each of those plugins, it must provide an instance of class PluginDesc. This is used to create new instances of the plugin class and to provide information about the plugin class name, supported interfaces etc.

 

Here is an example of a simple plugin library which exports the MyPlugin class defined above. For this purpose, MyPlugin is derived from class Plugin, instead of PluginBase. The only difference is the additional getPluginDesc() method, which returns the PluginDesc for the plugin.

 

//**********************************************

// A uniqie plugin identifier

//**********************************************

 

#define MY_PLUGIN_ID 0x8000000

 

//**********************************************

// The definition of the plugin class.

// This is the same as above, but derives from class Plugin

// and has an additional getPluginDesc() method.

//**********************************************

 

class MyPlugin: public Plugin, public InterfaceOne, public InterfaceTwo {

public:

// Methods from PluginBase

PluginInterface *newInterface(InterfaceID id) {

if (id==INTERFACE_ONE_ID) return (InterfaceOne*) this;

if (id==INTERFACE_TWO_ID) return (InterfaceTwo*) this;

return NULL;

}

void deleteInterface(void) {}

 

// Methods from PluginInterface

PluginBase* getPlugin(void) { return (PluginBase*) this; }

 

// Methods from Plugin

PluginDesc* getPluginDesc(void);

};

 

//**********************************************

// The description of our plugin. This provides information

// like the plugin id, name, supported interfaces etc.

//**********************************************

 

class MyPluginDesc: public PluginDesc {

public:

PluginID getPluginID(void) { return MY_PLUGIN_ID; }

Plugin* newPlugin(void) { return new MyPlugin; }

void deletePlugin(Plugin *plugin) { delete (MyPlugin*) plugin; }

bool supportsInterface(InterfaceID id) { return (id==INTERFACE_ONE_ID) || (id==INTERFACE_TWO_ID); }

tchar* getName(void) { return "MyPlugin"; }

} pluginDesc;

 

//**********************************************

// Implementation of the getPluginDesc() method

//**********************************************

 

PluginDesc* MyPlugin::getPluginDesc(void) { return &pluginDesc; }

 

//**********************************************

// The description of the library; this provides

// information about all the plugins in the library

//**********************************************

 

class MyLibDesc: public PluginLibDesc {

public:

tchar* getName(void) { return "MyPluginLib"; }

tchar* getText(void) { return "This is a simple plugin library test."; }

int numPlugins(void) { return 1; }

PluginDesc* getPluginDesc(int i) { return &pluginDesc; }

} libDesc;

 

//**********************************************

// A function for exporting the library description

//**********************************************

 

__declspect(dllexport) PluginLibDesc* getLibDesc(void) { return &libDesc; }

 

 

Loading and creating plugins

In order to load and create plugins, you must use an instance of class PluginManager. You can obtain a default plugin manager by calling the global method newDefaultPluginManager(). After you finish work with it, call deleteDefaultPluginManager() to destroy it. An example for this can be found in the sample renderer provided with the V-Ray SDK, which loads different plugin shaders at run-time. Here is an example code, which loads all plugins in the current folder, and tries to create an instance of class MyPlugin defined above:

 

#include "plugman.h"

 

PluginManager *plugman;

 

int main(void) {

// First create a default plugin manager

plugman=newDefaultPluginManager();

 

// Load all plugin DLLs in the current folder

plugman->loadLibrary("./*.dll");

 

// Create a new instance of class MyPlugin

MyPlugin* myPlugin=plugman->newPlugin("MyPlugin");

if (!myPlugin) {

printf("Error: could not create plugin.\n");

} else {

// Get a pointer to an InterfaceOne from the plugin

InterfaceOne *iface1=myPlugin->newInterface(INTERFACE_ONE_ID);

if (iface1) {

iface1->myFunc1();

myPlugin->deleteInterface(iface1);

}

 

// Get a pointer to an InterfaceTwo from the plugin

InterfaceTwo *iface2=myPlugin->newInterface(INTERFACE_TWO_ID);

if (iface2) {

iface2->myFunc2();

myPlugin->deleteInterface(iface2);

}

 

// Delete the plugin

plugman->deletePlugin(myPlugin);

}

 

// Destroy the plugin manager

deleteDefaultPluginManager(plugman);

}

 

Note that classes can be created either by PluginID, or simply by their name. In this example, the plugin is created by name. This is the same string returned from the MyPluginDesc::getName() method.

V-Ray-specific plugins

The plugin system as discussed above is not related in any way to V-Ray and can be used without it. However, plugins designed specifically for V-Ray must follow some additional guidelines.

 

All V-Ray-specific plugins must be derived from class VRayPlugin. This class automatically includes support for the VRayPluginInterface interface. This interface includes methods for working with plugin parameters, and has methods that are called at various stages of the rendering to prepare the plugin. The VRayPlugin class also provides an implementation of the getPluginDesc() method.

 

Additionally, the plugin descriptors of V-Ray plugins must be derived from class VRayPluginDesc. This class has automatic support for passing parameters to the plug-in.

 

The purpose of a specific plugin is defined by the extentions it supports. For example, plugins that generate geometry in the scene must support the EXT_GEOM_GEN interface. This extention must also be supported by lights that are visible in the scene; material shaders must support the EXT_MATERIAL interface etc. There are many helper base classes for creating specific V-Ray plugins, which can be used instead of deriving directly from class VRayPlugin, for example you can define a surface material plugin by deriving from class VRayMaterial, which automatically adds support for the EXT_MATERIAL and EXT_BRDF interfaces, and only the respective BRDF methods must be defined:

 

class MyMaterial: public VRayMaterial {

public:

BRDFSampler* newBRDF(VRayContext &rc);

void deleteBRDF(VRayContext &rc, BRDFSampler *brdf);

};

 

If a plugin library has only one plugin in it, you can use the SIMPLE_PLUGIN_LIBRARY macro to define the necessary DLL functions, for example:

 

#define MY_PLUGIN_ID 0x8000000

SIMPLE_PLUGIN_LIBRARY(MY_PLUGIN_ID, EXT_MATERIAL, "MyMaterial", "A test material plugin" , MyMaterial, MyMaterial_parameters);

 

This macro creates a plugin and library descriptor for the given plugin, and defines the getLibDesc() function. The macro also automatically creates a parameter list descriptor instance (see below).

 

The parameters are the plugin ID, a primary interface supported by the plugin, the name of the plugin, a short description, the plugin class itself, and the class which describes the plugin parameters.

V-Ray plugin parameters

Typically, each plugin has some work parameters (for example, a diffuse shader has the diffuse surface color as a parameter). V-Ray plugins automatically have support for a mechanism to pass parameters to them.

 

Each VRayPluginDesc class can store a pointer to a VRayParameterListDesc structure, which describes the parameters of the plugin, their types and default values. In the constructor of this structure, you can add all the plugin parameters, for example:

 

struct MyMaterial_parameters: VRayParameterListDesc {

MyMaterial_parameters(void) {

addParamColor("diffuse", Color(0.5f, 0.5f, 0.5f));

addParamTexture("diffuse_tex");

}

} myMaterial_parameters;

 

A pointer to the parameter list descriptor can be passed to the constructor of class VRayPluginDesc:

 

class MyMaterial_pluginDesc: public VRayPluginDesc {

public:

MyMaterial_pluginDesc(void):VRayPluginDesc(&myMaterial_parameters) {}

} myMaterial_pluginDesc;

 

Note that when using the SIMPLE_PLUGIN_LIBRARY macro, you don't need to create an instance of the parameter list descriptor - this will be done by the macro itself.

 

When new instances of V-Ray plugins are created, they will automatically create a new instance of class VRayParameterList, with the same number and type of parameter as in the parameter list descriptor. This list is available to the V-Ray plugin through its paramList member. The plugin can check the respective parameters when necessary, typically in its frameBegin() method.

 

The parameter list does not store the parameter values directly. Instead, it stores pointers to instances of class VRayPluginParameter. This is because parameters may come from a variety of sources - from the text file with the scene description in the standalone version of V-Ray, or they may be computed by some formula from other parameters etc. Using the VRayPluginParameter class also allows the plugin to sample a parameter value at different moments of time, for example when doing motion blur. This would not have been possible if the parameter values were stored directly.

Parameter caching

Instead of checking the parameter values for each parameter in turn, the plugin may define a link between a parameter and a specific memory location (a cache). The parameter list can be made to go through all parameters, get their current values and store them in the specified memory locations. Creating a link between a parameter and a memory location is typically done in the constructor of a plugin, and the caching itself takes place in the frameBegin() method. Note that the default implementation of VRayPluginInterface::frameBegin() automatically calls paramList->cacheParams() with the current frame time in the frame data, so there is no specific need to override this, if you don't do anything else in this method.

 

class MyMaterial: public VRayMaterial {

public:

MyMaterial(void) {

paramList->setParamCache("diffuse", &diffuseColor);

paramList->setParamCache("diffuse_tex", &diffuseTex);

}

void frameBegin(VRayRenderer *vray) {

paramList->cacheParams(vray->getFrameData().t);

}

private:

Color diffuseColor;

TextureInterface *diffuseTex;

};

 

Setting plugin parameters

Plugin parameters are set through a call to the VRayPluginInterface::setParameter() method. An example of this can be seen in the sample renderer provided with the SDK. You can either create your own parameters by deriving from class VRayPluginParameter, or use the simple V-Ray parameters defined in file defparams.h. The simple parameters simply store a value and return it when requested. More complex parameters would take animation into account, or return the parameters from a given scene description.