V-Ray for Maya translator SDK

General

Samples

Geometry primitives

Creating the V-Ray plugin

Creating the Maya plugin

V-Ray plugin parameters

Shaders

Creating the V-Ray plugin

Creating the Maya plugin

Creating the shader description file

Automatic generation of shader nodes

Loading V-Ray plugins

General

The SDK for the V-Ray for Maya translator allows you to extend V-Ray for Maya with new shaders and geometry objects. Note that V-Ray for Maya also includes a Python API for access to the translated scene - check out the V-Ray for Maya help files for more details.

 

The necessary header files for the V-Ray for Maya SDK are located in the include folder of the V-Ray SDK. On Windows, this would be for example "C:\Program Files\Chaos Group\V-Ray\Maya 2012 for x64\include" and on Linux - "/usr/ChaosGroup/V-Ray/Maya2012-x64/include".

Sample files

There are three sample projects provided with the V-Ray for Maya translator SDK. One is the vrayplane project, which creates an infinite plane primitive with the Maya plugin based on class MPxNode, another is the vraysphere project with the Maya plugin based on class MPxSurfaceShape, which creates a perfect sphere primitive, and the vrayblinnmtl project, which creates a new material.

Geometry primitives

Creating a new geometric primitive consists of two parts. The first is the creation of a V-Ray plugin that renders the primitive. This plugin will be used both when rendering inside Maya, and when rendering with V-Ray Standalone. The second part is the creation of a corresponding Maya plugin that handles the representation of the primitive in the Maya viewports, Attribute editor and so on, allows a material to be attached to the primitive, and handles the translation to the respective V-Ray plugin.

Creating the V-Ray plugin

The V-Ray plugin may be created either as a completely separate V-Ray plugin, or it can be implemented as part of the Maya plugin itself. The first approach allows the new primitive to be rendered with V-Ray Standalone. The second approach allows your primitive to use the Maya API to access various parts of the Maya scene, if necessary, but in that case, rendering with V-Ray Standalone will not be possible.

 

The V-Ray plugin must meet the following conditions:

See the section Loading V-Ray plugins for information how to load the plugin in V-Ray for Maya and V-Ray Standalone.

 

You can also use one of the already existing V-Ray plugins - for example, if you want to generate a mesh, you can directly create the V-Ray plugin GeomStaticMesh and just set its relevant parameters to define the mesh (vertices, faces, mapping channels etc), or, if you want to create hair you can directly create a GeomMayaHair plugin and pass to it the description of the hair strands.

Creating the Maya plugin

Once you have the V-Ray plugin, you must create a corresponding Maya plugin to handle user interaction with the new primitive and to tell the V-Ray for Maya translator how to export it to the V-Ray plugin.

 

The Maya plugin must meet the following conditions:

During scene translation, the V-Ray for Maya translator will perform the following steps to export the custom plugin:

V-Ray plugin parameters

If you are creating a separate V-Ray plugin, then passing data from the Maya plugin to the V-Ray plugin must be done through one or more V-Ray plugin parameters. This will also allow the parameters to be written to a .vrscene file, and later on passed to the V-Ray plugin when rendering with V-Ray Standalone.

 

The parameters can be passed to the V-Ray plugin using its setParameter() method. The actual parameter objects must be members of the Maya plugin class. You can use either some of the predefined classes from the defparams.h file of the V-Ray SDK, or you can create your own parameters derived from class VRayPluginParameter if you need to export animated parameters to the .vrscene file produced by the translator.

 

The V-Ray plugin can accesse the data by calling the various getXXXX() (e.g. getInt(), getFloat() etc) methods of class VRayPluginParameter for the various frames of the animation.

 

To make animated parameters work when rendering inside Maya, it is enough to make their getXXXX() methods to take into account the passed time values to these methods. However, the V-Ray for Maya translator will not know that these parameters are animated and will not export their animation if you create a .vrscene file.

 

To tell the exporter that a parameter is animated and to specify its keyframes, you need to modify your parameter to support the MyInterpolatingInterface interface, which is defined in the vraypluginsexporter.h file. That is, your parameter class must also derive from class MyInterpolatingInterface, and in its newInterface() method, must return a pointer to a MyInterpolatingInterface object when the passed interface ID is EXT_INTERPOLATING, for example:

 

class MyAnimatedIntParam: public VR::VRayPluginParameter, public VR::MyInterpolatingInterface interface {

public:

PluginInterface* newInterface(InterfaceID id) {

if (id==EXT_INTERPOLATING) return static_cast<VR::MyInterpolatingInterface*>(this);

return VR::VRayPluginParameter::newInterface(id);

}

 

virtual int getNumKeyFrames(void) { ... }

virtual double getKeyFrameTime(int index) { ... }

 

virtual int getInt(int index=0, double time) { ... }

virtual const tchar* getName(void) { ... }

};

 

Shaders

A custom shader consists of three parts - a V-Ray plugin, a Maya plugin, and a shader description file that tells the V-Ray for Maya translator how to translate the Maya plugin into the V-Ray plugin. However, the Maya plugin and the shader description can be omitted - V-Ray for Maya is able to automatically generate user interface for a shader based on the V-Ray plugin only. To create a shader that does not have a corresponding Maya plugin, you can use the menu commands Create > V-Ray > Create V-Ray material from plugin and Create > V-Ray > Create texture from V-Ray plugin for materials and textures respectively. The advantage of having a separate Maya node is that you can control the user interface layout for the attributes of the shader, and that it will appear in the Maya Create render node menu as a separate material/texture.

Creating the V-Ray Plugin

The V-Ray plugin can be derived from class VRayMaterial, class VRayBSDF, or any of the texture classes (class VRayTexture, class VRayTextureFloat etc) and implement the required methods. There are many examples for materials, BRDFs and textures in the V-Ray SDK. Texture plugins can have more than one output parameters.

 

See the section Loading V-Ray plugins for information how to load the plugin in V-Ray for Maya and V-Ray Standalone.

 

You can also use one of the existing V-Ray plugins, similar to how this is done in the VRayBlinnMtl example.

Creating the Maya plugin

In contrast with custom geometry, it is not required to create a custom Maya plugin for the shader. However, having a plugin gives you control over the user interface, and also will show the material in the Maya Create Render Node dialog. Newer versions of V-Ray for Maya can automatically generate shader nodes based on the shader description file, but you can also create this node yourself. For more information on automatic shading node generation, check the relevant section below

 

If you decide to implement the Maya shading node plugin yourself, the Maya plugin must meet the following conditions:

V-Ray ignores the result from the compute() method of the node (the corresponding V-Ray plugin is used for rendering); however you can implement a suitable representation of the material for the Maya software renderer, if you wish.

Creating the shader description file

If you create a Maya plugin counterpart for your shader, you must tell V-Ray how to translate the Maya plugin into the corresponding V-Ray plugin. In contrast to custom geometry, this is not done with a C++ API. Instead, a shader description file is used to tell the V-Ray for Maya translator how to convert the parameters of the Maya plugin into parametes for the V-Ray plugin.

 

The shader description file must have the .txt file extension, and the path to it - listed in the VRAY_FOR_MAYA_SHADERS environment variable. Multiple paths are separated with ';' on Windows, and ':' on Linux and Mac OS X. The actual name of the .txt file does not matter.

 

You can look at the [maya_root]/vray/shaders/desc.txt file included with V-Ray for Maya for examples on how the V-Ray for Maya translator itself uses shader description files to translate many of the Maya shader nodes to their corresponding V-Ray plugins.

 

The format of the shader description file is as follows:

 

vray_plugin_name maya_shader_name {

"V-Ray parameter name" vray_parameter_type "Maya attribute name" maya_attribute_type INOUTFLAG

...

}

 

where vray_plugin_name is the name of your V-Ray plugin, as specified in the PLUGIN_DESC macro; maya_shader_name is the name of the Maya plugin as specified in its outApiType attribute. Inside the braces {}, you must list the parameters of the V-Ray plugin and how they are linked to the corresponding attributes of the Maya plugin.

 

"V-Ray parameter name" (quotes must be included) is the name of a parameter of the V-Ray plugin. It may be empty ("") if there is no corresponding V-Ray parameter - this is used to specify the default output from the V-Ray texture plugin.

 

vray_parameter_type specifies the type of the V-Ray parameter and can be one of the following:

 

Value Description
"texture" A color or color texture parameter.
"texture_red" Used only for output parameters to specify that the red component of the specified V-Ray color texture output parameter corresponds to the given Maya output child attribute.
"texture_green" Used only for output parameters to specify that the green component of the specified V-Ray color texture output parameter corresponds to the given Maya output child attribute.
"texture_blue" Used only for output parameters to specify that the blue component of the specified V-Ray color texture output parameter corresponds to the given Maya output child attribute.
"texture_alpha" Used only for output parameters to specify that the alpha component of the specified V-Ray color texture output parameter corresponds to the given Maya output child attribute.
"vector" A vector or vector texture parameter.
"vector_x" Used only for output parameters to specify that the x component of the specified V-Ray texture output parameter corresponds to the given Maya output child attribute.
"vector_y" Used only for output parameters to specify that the y component of the specified V-Ray texture output parameter corresponds to the given Maya output child attribute.
"vector_z" Used only for output parameters to specify that the z component of the specified V-Ray texture output parameter corresponds to the given Maya output child attribute.
"number" An integer or floating point number or texture.
"uvwgen" A uvw generator. The corresponding maya_attribute_type must be "plugin" and usually connected to a 2d or 3d placement node.
"material" A material. The corresponding maya_attribute_type must be "material" too and usually connected to a Maya material.
"brdf" A BRDF plugin. The corresponding maya_attribute_type must be "brdf" too and usually connected to a Maya material.
"transform" A transformation matrix or a transformation matrix texture.

 

"Maya attribute name" (quotes must be included) is the name of the corresponding Maya attribute, and maya_attribute_type specifies its type:

 

Value Description
"texture" A color attribute.
"number" A floating-point number attribute.
"integer" An integer number.
"vector" A vector attribute.
"vector_x" The x child attribute of an output vector attribute.
"vector_y" The y child attribute of an output vector attribute.
"vector_z" The z child attribute of an output vector attribute.
"transform" A transformation matrix.
"plugin" Another Maya object; used mostly for "uvwgen" V-Ray parameters to specify a Maya 2d or 3d placement node.
"material" Another Maya material. Must be used when the V-Ray parameter type is "material"
"brdf" Another Maya material as BRDF. Must be used when the V-Ray parameter type is "brdf"
"boolean" A boolean attribute.
"string" A string attribute.
"value" A constant; in this case, "Maya attribute name" specifies the value of this constant, enclosed in quotes. Only integer and floating-point numbers are accepted. The corresponding vray_parameter_type must be "boolean", "float" or "int". The corresponding V-Ray parameter is always set to the specified constant value.
"3darray" A list of textures (in the form of a 3D array plug)
"array" A list of float textures (in the form of a float array plug)

 

The INOUTFLAG can be INPUT or OUTPUT and specifies if the Maya parameter is an input or an output one. If an output Maya parameter corresponds to the default output of a V-Ray texture, then "V-Ray parameter name" can be an empty string.

Automatic generation of shading nodes

Newer versions of V-Ray for Maya allow the automatic generation of shading nodes based on their description file. To enable automatic shading node generation for a particular shader, it must have a parameter with a name "plugin_id" that specifies the Maya plugin ID for the shading node, and a parameter named "classification" that specifies the category of the shader node in the Hypershade. For example:

 

TexNoiseMax VRayNoiseTexMax {

"plugin_id" number "value" 1115346 INPUT

"classification" string "value" texture/2d:rendernode/vray/texture/2d:swatch/VRayTextureSwatchGen INPUT

.....

}

 

V-Ray will automatically create attributes for the shading node based on the parameters in the description file. It is possible to specify additional properties of these attributes - minimum, maximum and default values. It is also possible to specify enum parameters.

 

For color/texture/vector parameters, you can specify a default value:

"some_color" texture "someColor" texture INPUT default:(0.2,0.3,1.0)

 

For scalar parameters (float or integer), you can specify a default value, minimum, maximum, soft minimum and soft maximum values:

"some_number" number "someNumber" number INPUT default:0.0 min:-1.0 max:10.0 softMin:-0.5 softMax:0.5

 

For boolean parameters you can specify a default value (0 for false and 1 for true):

"some_bool" boolean "someBool" boolean INPUT default:1

 

You can also specify integer parameters as enums. This can be done in two different variants, which cannot be mixed. The first variant allows you to specify the enum indices manually:

"some_enum" enum "someEnum" enum INPUT values:("asd",1) ("xyz",2) ("gfd",3) default:3

 

The second variant just lists all the enum values and they are assigned consecutive indices starting from 0:

"someEnum" enum "someEnum" enum INPUT values:"asd" "xyz" "gfd" default:0

 

In both variants, if a default value is not specified, the first enum value is assumed as default. If a default is specified, it must be specified as an index, and not as a string.

 

Here is an example of the description needed to generate a shading node for the TexNoiseMax V-Ray plugin. Note the use of the "uvwgen" parameter - if it is present, V-Ray for Maya will automatically create the attributes needed to connect a 2D placement node to the resulting shader.

TexNoiseMax VRayNoiseTexMax {

"plugin_id" number "value" 1115346 INPUT

"classification" string "value" texture/2d:rendernode/vray/texture/2d:swatch/VRayTextureSwatchGen INPUT

 

"compatibility_with" enum "compatibilityWith" enum INPUT values:("3ds Max",0) ("Maya",1) default:0

"alpha_from_intensity" enum "alphaSource" enum INPUT values:"Normal""Intensity/Luminance" "Solid" default:0

"invert" boolean "invert" boolean INPUT default:0

"invert_alpha" boolean "invertAlpha" boolean INPUT default:1

"color_mult" texture "colorGain" texture INPUT default:(1,1,1)

"color_offset" texture "colorOffset" texture INPUT default:(0,0,0)

"alpha_mult" number "alphaGain" number INPUT default:1

"alpha_offset" number "alphaOffset" number INPUT default:0

"nouvw_color" texture "defaultColor" texture INPUT default:(0.5,0.5,0.5)

"wrap" boolean "wrap" boolean INPUT default:1

 

"uvwgen" uvwgen "uvCoord" plugin INPUT

 

"color1" texture "testVector" vector INPUT default:(1.0,0.0,0.0)

 

"" texture "outColor" texture OUTPUT

"" texture "oc" texture OUTPUT

}

 

Note how the UVW generator is defined. For 2D textures, the Maya parameter name must be "uvCoord". For 3D textures, the Maya parameter name must be "placementMatrix" and the classification string must include "texture/3d". The corresponding parameter name of the V-Ray plugin must be always "uvwgen".

 

Loading V-Ray plugins

In order for a V_Ray plugin to be found and loaded by the V-Ray for Maya translator, you need to add the path to it to the VRAY_FOR_MAYAnnnn_PLUGINS_pp environment variable where nnnn is the Maya version (2011, 2012 etc) and pp is the architecture (x86 or x64), for example, VRAY_FOR_MAYA2012_PLUGINS_x64. Paths can be separated by ';' on Windows and ':' on Linux/Mac OS X.

 

In order for the plugin to be loaded by V-Ray Standalone, you need to add the path to it to the VRAY_PLUGINS_pp environment variable where pp is the architecture (x86 or x64).