V-Ray for Softimage bridge SDK

Overview

Components of a VRay Bridge third party extension

Creating a Visual Studio solution

Setting up V-Ray plugin unique ID

Define VRay plugin parameters

Reference

System services

Plugin and static parameter creation

Export helpers

Animated parameter classes

 

Overview

The bridge SDK for V-Ray for Softimage allows developers to extend V-Ray for Softimage with new texture shaders. All bridge SDK - based extensions consist of two separate DLLs (or .so's on Linux). Skills required include:

The necessary header files for the V-Ray for Softimage bridge SDK are located in the include/xsibridge folder of the V-Ray SDK. On Windows, this would be for example "C:\Program Files\Chaos Group\V-Ray\Standalone for x64\include\xsibridge".


It is important to understand that the Softimage bridge SDK does not replace, but instead supplements the "main" V-Ray SDK. The bridge only applies to Autodesk Softimage 2010 (and above), running VRay/Softimage 1.5 SP1 (and above)


Components of a VRay Bridge third party extension

We will be using the SITexInvert sample bridge plug-in throughout this document. You must decide on a plugin name early in the development process. Every VRay plugin must have a unique name (but, a single DLL may hold more than one plugin). We recommend the MyCompany_MyShader naming convention to avoid a name clash.

A single plugin DLL (SITexInvert.dll) may contain one or more VRay texture shaders. A single bridge consumer DLL (SITexInvert_bridge.dll) may serve as the translator, a.k.a. bridge, for one or more plugin DLLs. Please follow the convention of naming the bridge dll as Something_bridge.dll to avoid confusion.

The binaries (compiled DLLs) for 3rd party plugins and bridges must reside in the customplugins folder under the "root" folder of the VRay/Softimage xsi add-on. The typical path to this folder (on Windows) would be

C:\Users\Your Username\Autodesk\Softimage_2012\Addons\V-Ray\customplugins


Here is a breakdown of the different functions assigned to code in the two DLLs:
 
DLL Function Sample APIs
SITexInvert.dll Describes the parameters of the VRay plugin that will perform the rendering, either in the Softimage environment or in a VRay/Standalone setup
struct SITexInvert_Params: VRayParameterListDesc

Contains the VRay plugin class that performs the rendering (under SI or under VRayStd)
struct SITexInvert: VRayTexture

Describes the plugin name, description and unique VRay-style interface ID
SIMPLE_PLUGIN_LIBRARY(...)

Provides a header file that allows the bridge to call into the VRay plugin (but never the other way around). Our sample texture includes a template for this file but it is not used - with simple texture shaders, directly calling into the plugin is not normally required
#include "SITextInvert_pluginexp.h" (as provider)

Consumes header files from the VRay core
#include "vrayplugins.h"
#include "vraytexutils.h"

Calls V-Ray APIs but not Softimage or VRay/Softimage APIs
DLL linkage to vray.dll only
SITexInvert_bridge.dll
Implements the translator function invoked at scene export time to translate from a Softimage texture to VRay-style input parameters
int ExportTexture(...)

Handles initialization (similar to XSILoadPlugin) and deinitialization for the bridge plug-in
int BridgeInitialize(...)
void BridgeUninitialize()
int BridgeRegisterSupportedItems()

Consumes the private header and calls into routines exported by SITexInvert.dll - this part is optional and in many cases not needed
#include "SITextInvert_pluginexp.h" (as consumer)

Consumes header files and link libraries from Softimage and VRay/Softimage
#include "xsibridge/vrayxsibridge.h"
#include "xsibridge/bridgeanimatedparam.h"
#include "systemstuff.h"
#include <xsi_texture.h>

Calls V-Ray APIs (define and create parameters, etc) and Softimage and VRay/Softimage bridge APIs
DLL linkage to vray.dll, to Softimage (sicoresdk.lib sicppsdk.lib) and, indirectly, to routines implemented in vray4xsiNNNN.dll

Creating a Visual Studio solution

We will illustrate setting up a new VS solution named MyComp_TexWonder residing in the C:\MyComp\TexWonderPlugin folder.

Create the folder and copy the following files from <vraysdk>\samples\softimage_plugins\sitexinvert to C:\MyComp\TexWonderPlugin Open up all of these files in a text editor (if you use Vistual Studio, be sure to open the .dsp's as text, not as projects). Do a find and replace on all occurrences of the SITexInvert string with MyComp_TexWonder.

Open MyComp_TexWonder.dsp as a Visual Studio project and follow the prompts to upgrade the project to the version of VS you will be using. Save the project that VS created (along with a new solution). Create a new, x64-based configuration by copying the settings from the Win32 Release config. Inspect the following key items:

General | Output Directory
Set to C:\Users\Your Username\Autodesk\Softimage_2012\Addons\V-Ray\customplugins\ for easy debugging
General | Platform Toolset
Set to v90 or v100 as appropriate. Always use the Microsoft C++ runtime version from your installation of Softimage - your Visual Studio version is irrelevant (as long as it's current enough), plugin DLLs must be compiled against the runtime version matching the Softimage runtimes. This is crucially important, double-check that XSI/plugin/VRay.dll runtimes match!
C/C++ | General | Additional Include Directories
c:\YourVRaySDKLocation\include;%(AdditionalIncludeDirectories)
C/C++ | General | Optimization Optimization: Disabled will be needed for best debugging experience. Of course, when rolling out a production version of your plugins, you will need to turn Optimization back on to a suitable setting (we use full, /Ox)
C/C++ | Preprocessor | Preprocessor Definitions
SIBRIDGE_PLUGIN_DLL;WIN32;NDEBUG;_WINDOWS;%(PreprocessorDefinitions)
Linker | General | Output File
C:\Users\Your Username\Autodesk\Softimage_2012\Addons\V-Ray\customplugins\MyComp_TexWonder.dll
Linker | General | Additional Library Directories
c:\YourVRaySDKLocation\lib\x64\vc9;%(AdditionalLibraryDirectories)

To be on the safe side, you may also want to add the locations of the lib and lib\amd64 folders from Visual Studio that match the versions used with the copy of Softimage you are running. Again: double-check C++ runtime versions!

Make sure the project compiles (resolve any troubles with compiler/linker options at this point). A new .dll should be produced in the customplugins folder of your VRay/Softimage xsiaddon installation location.


Choose Solution -> Add... -> Existing project and add MyComp_tex_wonder_bridge.dsp to the solution. Use Configuration Manager to set up a x64 config for the project, again copying settings from Win32 Release. Inspect the settings and verify all of the following are correct:


General | Output Directory
See previous table
General | Platform Toolset
See previous table
C/C++ | General | Additional Include Directories
c:\YourVRaySDKLocation\include;
c:\YourSoftimageSDKLocation\include;
%(AdditionalIncludeDirectories)

C/C++ | General | Optimization See previous table
C/C++ | Preprocessor | Preprocessor Definitions
SIBRIDGE_CONSUMER_DLL;WIN32;NDEBUG;_WINDOWS;
_CRT_SECURE_NO_WARNINGS;
%(PreprocessorDefinitions)

Linker | General | Output File
C:\Users\Your Username\Autodesk\Softimage_2012\Addons\V-Ray\customplugins\MyComp_TexWonder_bridge.dll
Linker | General | Additional Library Directories
c:\YourVRaySDKLocation\lib\x64\vc9;
.\x64\Release;
c:\YourSoftimageSDKLocation\lib;%(AdditionalLibraryDirectories)


To be on the safe side, you may also want to add the locations of the lib and lib\amd64 folders from Visual Studio that match the versions used with the copy of Softimage you are running. Again: double-check C++ runtime versions!


Make sure the project compiles cleanly and MyComp_TexWonder_bridge.dll appears in the proper output location.

Setting up V-Ray plugin unique ID

A thorough discussion of plugin IDs can be found in the main V-Ray SDK documentation. Here, we will only go through the steps involved:
Recompile and troubleshoot any problems.

Define VRay plugin parameters

Prepare a list of all the parameters your texture plugin will take. Pay special attention to how the Softimage-exposed parameters (the ones described in the associated SPDL) will correspond to the VRay plugin parameters. In a best-case scenario, you would want the two sets to match completely (one-on-one, with the associated datatypes). However, this may not always be possible.

Taking the values of Softimage parameters and assigning values to VRay plugin params is the job of the exporter function (look for int ExportTexture in the bridge cpp file). If you are using an existing VRay plugin (maybe developed for another host application), you may just paste in the code into the non-bridge DLL. You will then need to perform the "matching" in code in the bridge DLL.

V-Ray plugin parameters are normally found / defined in:
Softimage parameters are defined in the plugin's SPDL file and used as "inputs" in ExportTexture so that their values are passed to VRay plugin parameters as appropriate.


Reference

Bridge SDK services are categorized into several groups. Most services are provided as methods of the BridgeProvider class (a unique instance of this class is created by the engine for every distinct bridge consumer DLL). Animated parameter handling is relegated to several base classes plus specific implementations for simple datatypes.

System services

"br" pointer

Every bridge consumer DLL defines a global variable named br of type BridgeProvider* - this variable will be initialized for you (just before the call to BridgeInitialize) with a pointer to a service provider class that you can call at will. This "provider" can be called at anytime between the initialization and deinitialization of your DLL.

Initialization and registration

Each bridge SDK bridge-based plugin will be loaded when VRay/Softimage itself initializes, within the XSILoadPlugin function of VRay. You, as a developer, must supply a body for int BridgeInitialize (...)  Among other parameters, this function will receive a reference to the Softimage plugin registrar object. This allows bridge DLLs to act as regular C++ SI plugins. Just be sure to put any initialization, command registration, custom menu, events etc. in BridgeInitialize.

If something goes wrong during initialization, your function may return an error code to the caller (one of the VR4SIBRIDGE_ERROR_xxx codes, but any negative value will do). This will be regarded as initialization failure by VRay and your module will no longer be called (its services will be unavailable). It is a good practice to inform the user of the specific error details by calling AppLogMessage

If initialization succeeds, VRay will immediately call BridgeRegisterSupportedItems. This function is responsible to "register" any custom textures, shaders, etc. your DLL defines with the VRay bridge infrastructure. Note that every distinct resource (texture, shader etc.) you implement must have a unique integer ID assigned to it. Later, when VRay calls your ExportXXX routines, you can use the value of this ID to distinguish between different resources. The value is not important as long as it is unique within the bridge consumer. Our sample code uses the value 101

When calling RegisterXXXExporter service methods, you pass in a "user data" value. If you do not need any user state data, just pass in NULL. Otherwise, you may use it as a pointer to a structure you define internally; it can store extra data depending on your needs. userData is oblique to VRay; it will just be saved (as a void pointer) and then passed in to ExportXXX functions, and VRay does not try to interperet it in any way.

Unloading VRay/Softimage will cause bridge consumers to also be unloaded. In the process, BridgeUninitialize will be called (corresponding to XSIUnloadPlugin). This is the last chance of your code to free any extra custom resources you require - dynamic buffers, threads, GUI objects if applicable etc.

AppLogMessage

This provider method can be called at any time and will produce a log entry in the Softimage logs just like XSI::Application().LogMessage (in fact, it uses just this API internally). Do not call the XSI logger directly, always use AppLogMessage.

GetBridgeProviderVersion

If you are building a bridge with commercial purposes or for distribution in a large organization, you may want to handle versioning yourself. Essentially, all bridge consumer DLLs will remain binary compatible in future versions of VRay/Softimage and its bridge. Future versions of the BridgeProvider will extend previous functionality. If your module can work with an earlier or a later version of VRay, you may check for the version by calling GetBridgeProviderVersion and act accordingly.

AppIsInteractive

This method matches the functionality of XSI::Application().IsInteractive() but for technical reasons your code should always call the bridge method instead of the native version.

Plugin and static parameter creation

Every time VRay needs to "export" (in other words, translate) a texture implemented by a plugin handled by your bridge DLL, it will call the ExportTexture function. The same applies to shaders and other resource types. Within that function itself, you can distinguish between different textures by checking the ID passed - it will match one of the IDs your code provided in a previous call from within BridgeRegisterSupportedItems.

The typical workflow for any texture export is as follows:
If you need any extra state etc. at this point, you may either use global variables or fetch a value from the userData field of the call context and interpret it as desired, e.g. a pointer to a structure internal to the bridge consumer.

Export helpers

Export helpers are utility methods implemented by the bridge provider that may be called within your ExportXXX function implementation.

ExportColorParamToMaterial will take a reference to a XSI Parameter from your custom XSI texture / shader, will attempt to interpet it as a color value and will export it as a VRay TexXXX node (e.g. TexXSILayered, TexScalarCurve, TexNoise etc.) for textures, or another shader node. Light material assignments will also be handled here (by exporting a BRDFLight plugin). Options include whether to invert the texture, and whether to export only a texture, only a color value, or both texture and color (this is what you typically need for diffuse, reflective and refractive parameter ports)

ExportColorParamToTexture is similar to the previous method, but operates on a higher level: it will also set the common xsi_color animated param and xsi_invert param on a new TexXSIColorMix instance (when working with a pure color, not a texture) if required.

ExportParameterToTexture is the highest-level general parameter exporter. It inspects the SI shader attached to the passed parameter (if any) and exports a node (or an entire subtree) for a shader (standard or 3rd party), a texture, an image clip, or the first item in a texture layer stack. An option controls include whether to invert the texture (only applicable when siTextureID shader is attached to the port)

ExportTextureLayers takes a CRefArray consisting of texture layer references (provided by SI), a target parameter, and an already prepared VRayPlugin* for the base layer. It then produces a plugin node representing the layered textures (if any). The result of this method can be assigned directly to a texture input port (naming convention: if a plugin takes a color parameter named color1 then its corresponding texture parameter should be named color1_tex).

GetUVWChannelForThisTexture should be called for textures that support UVW projections; it will create a UVWGenChannel instance containing the appropriate projection info for the geometry/material pair being exported. You would simply plug this into a plugin parameter (by convention, it should be called uvwgen)

IsObjectAnimated works similarly to IsAnimated method of XSI objects, but is considerably more complex as it only considers "geometry animatable" (from the viewpoint of VRay/Softimage) meshes as truly animated. The method will return proper results even in complex cases e.g. when ICE trees are attached, when mesh deforms are cached in an ICE cache, etc.

ConvertXSItoVRAYTransform is a utility method that will convert an XSI transform matrix to its VRay SDK-style equivalent.

ExportCommonParameter is a useful helper that will export a generic XSI scalar parameter (float, boolean, etc.) to its VRay SDK-style VRayPluginParameter-descended equivalent. This may save you some tedious parameter conversion code in the bridge consumer.

Animated parameter classes

When you need to export an animated parameter, or a custom type of parameter (such as a list of lists) that is not covered by the provider itself (see "Plugin and static parameter creation"), your code will need to implement a class that provides the values of the parameter at different frame times (including non-exact times when motion blur is turned on)

The VRay engine supports animation - i.e. different values - by asking your code to provide a value of the parameter for all defined keyframes. It will then perform a linear interpolation of those values as necessary.

The bridgeanimatedparam.h header file (designed to be #include-d in bridge consumers) defines AnimatedParameterInterface which all animated parameter classes must inherit. Also, it is mandatory that your code implements the virtual methods coming from MyInterpolatedInterface.

The header file already contains pre-made implementations for animated float scalars, int scalars, bool scalars (these are treated just like ints with a value of 0 or 1), and vectors. You can use those implementations out of the box by instating the appropriate class. For all other animated parameter types, provide your own implementation and instantiate it (it already has a virtual destructor so VRay itself can handle destruction)

In both cases, be sure to call RegisterUserCreatedParam after the parameter has been constructed so VRay can manage its lifetime as necessary.

Always instantiate animated parameters (or static parameters, for that matter) only in code executing as part of ExportXXX routines. This is needed because VRay will internally keep notes on which parameter is associated with which material, shader, geometry or other resource.