Plugins

A note on terminology

• plugin: We use the term plugin a lot. Technically it could mean a plugin DLL for V-Ray (even V-Ray itself is a kind of plugin) or the type defined in it, which is for example a class in the programming sense, or finally an instance of this class which resides in memory and can be saved to a scene file. We will be using the term plugin to refer to plugin instances.
• exporter/translator: We call the piece of software that translates some native scene format to the V-Ray scene format an exporter or a translator, interchangeably. Basically what it does is creating a bunch of V-Ray plugins and setting their parameters. Note that we also use the verb "to export" sometimes in reference to the act of saving out the scene (which was already translated) to a *.vrscene file.

Overview

Plugins are the building blocks in a V-Ray scene. Everything is a plugin - the lights, geometry, materials and settings.

We could informally define three kinds of plugins that build up a V-Ray scene. One would be the so called "top-level" plugins, which can exist on their own, without being part of some plugin tree. Lights are top-level plugins for example. They can also receive input from other plugins of course, but they do not output values to other plugins. The plugins which are not top-level serve as input for parameter slots which require a plugin of certain type. For example a material plugin may require an optional texture input and you'd reference a texture plugin there. The texture plugin may receive input from a UVW generator and so on. The third kind would be a special type of top-level plugins which only have one instance. These are basically settings plugins. Most of them have "Settings" in their name, but a few do not. The V-Ray camera is also defined by such a singleton plugin.

Each of the language bindings has a Plugin class which is a lightweight wrapper for the underlying instance in the V-Ray engine. These objects do not contain the actual property data, so they can be copied around (e.g. passed by value). In the statically typed languages we support - C++ and C# - there are concrete classes for the specific V-Ray plugin types as well as the generic Plugin type. They provide property getters and setters for convenience over the generic methods that use strings to identify the property.

Since Plugin objects are just wrappers, their going out of scope does not remove the actual V-Ray plugin from the scene. It's just a reference. Adding and removing instances is done through methods of the VRayRenderer class.

The default constructor for the Plugin class creates an invalid object. The object can be checked as a boolean value for validity. Some APIs such as getPlugin() return a Plugin object. It can be invalid if for example the requested instance name was not found. It is good practice to check such returned values for validity before using them further.

Getting a plugin reference

There are several ways of obtaining a reference to an existing plugin specific for each language (see also PluginRef in the next chapter). They are demonstrated in the following example:

Python

C++

C#.NET

Node.js

We can retrieve all plugin names or all possible plugin types. We can also retrieve all instances of a given plugin type, e.g. Node.

Python

C++

C#.NET

Node.js

Metadata

All plugins expose info about their properties' names, types, default values, and descriptions. This information we call plugin's metadata. It can be accessed in the following way:

Python

C++

C#.NET

Node.js

• Description is a string that can be placed in the UI.
• Type is a string, denoting one of the possible Property Types
• Default value is an object of type type.
• GPUParamSupport describes the extent to which a property is supported by V-Ray GPU

Creating plugin instances

The following example shows how new plugin instances are created. If the requested instance name is already used, creation will fail.

Python

C++

C#.NET

Node.js

Additionally, there is the getInstanceOrCreate() method, which only creates the instance if one does not already exist. Otherwise, it returns the existing instance. This is useful for settings plugins that should not have more than one instance in the scene. There is also the getInstanceOf() method in C++, GetInstanceOf() in C#, and getInstance() in Python and Node.js that returns the most recently added instance, if one exists.

Removing plugin instances

When a plugin instance is removed from the scene all references to it are reset to null internally. Any Plugin objects you have that reference the deleted plugin instance become invalid, although performing a boolean check on them still returns True. Operations on them will fail. If you're not sure if an instance still exists, get a Plugin reference by name again from the renderer and perform a boolean check on it.

Python

C++

C#.NET

Node.js

Replacing plugin instances

In some cases, you will want to use a new plugin instance in place of another that may be connected to multiple parameter slots. This is typical for changing materials or their textures, for example. To avoid having to set all the connections yourself, use the plugin replacement API. You can also use it to reset connections to null.

Python

C++

C#.NET

Node.js