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:
- For the plugin DLL
(this is the actual shader): working knowledge of C++, extensive
knowledge of writing VRay shaders with the main VRay SDK. Familiarity
with the VRay plugin and parameter object model; basic understanding of
the XSI C++ development model will help
- For the bridge DLL
(this serves as the export translator): working knowledge of C++,
familiarity with the overall architecture of VRay shaders, excellent
understanding of the VRay plugin and parameter object model (including
understanding how animated parameters work), advanced
understanding of the XSI C++ development model
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
- SITexInvert.dsp as MyComp_TexWonder.dsp
- SITexInvert.spdl as MyComp_TexWonder.spdl (or you may
choose to create the spdl file
from within Softimage if you have good familiarity with the "New plugin
in C++ code" wizard)
- si_tex_invert.cpp as MyComp_tex_wonder.cpp
- SITextInvert_pluginexp.h as MyComp_tex_wonder_exp.h (optional)
- SITexInvert_bridge.dsp as MyComp_tex_wonder_bridge.dsp
- bridge_tex_invert.cpp as bridge_mycomp_tex_wonder.cpp
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:
- In the solution SPDL file, generate and modify new GUID for the Reference option. Modify MetaShader -> Name to hold the final shader name
(as presented to end users). Install the SPDL file locally within
Softimage and always be sure to keep the "original" and the "installed"
SPDL files in sync. Restart Softimage and invoke "Regenerate Presets"
every time you change something in the SPDL.
- Find the #define
MyComp_TexWonder_PluginID declaration within the .cpp file for
the VRay plugin DLL, and change the LARGE_CONST
definition to a unique value. We recommend the format yyyymmddxxx (using today's date and
an arbitrary value for xxx). This value should not change over the
lifetime of the project, but must be unique among all plugins on the
system (including ones provided by Chaos Group or third parties)
- Put a proper description in the SIMPLE_PLUGIN_LIBRARY
macro invokation on the line immediately following the #define
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:
- The _Params structure
derived from VRayParameterListDesc
in the plugin DLL
- The constructor code for the _Params
structure (addParamXXX calls)
- The constructor code for the plugin class (paramList->setParamCache calls)
- Throughout the getTexColor
and getTexColorBounds methods
in the plugin class. This is where the "real" shading takes place
- In the implementation of ExportTexture
in the bridge DLL (as method calls to CreateXXXParam
or instantiations of classes for more complex and/or animated
parameters)
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:
- Prepare a VRay plugin parameter of a type matching the type
expected by your plugin DLL. The bridge service provider implements a
number of CreateXXXParam methods that will instatiate a specific class for you. Use them instead of a native C++ "new DefXXXParam()" call so VRay can track these parameters during their lifetime.
- For non-animatable parameters, pass in an appropriate value for
the parameter. This will typically come as a result of calling the XSI
texture's GetParameterValue method but
for more complex scenarios, you may need to provide constant values or
perform value combining / conversion. This is dependent on how well the
SPDL-defined parameters for the XSI plugin "match" the parameters of
the VRay plugin DLL
- For animatable parameters, call C++ new with an appropriately implemented subclass of AnimatedParameterInterface and MyInterpolatingInterface.
Immediately after that, register the parameter with VRay by calling
RegisterUserCreatedParam so VRay can track the instance during its
lifetime and destroy it when appropriate.
- Instantiate a new VRay plugin of a class implemented by (one of
your) plugin DLL(s). This must not be done directly, but instead you
should call CreatePlugin method of the
service provider. This will help VRay keep track of plugins created for
different materials and geometries, and destroy / recreate them as
necessary as the end user makes changes to the scene.
- Assign the parameters from the previous steps to the new plugin
instance (by calling setParameter), then return the plugin pointer in
the outExportedTexture field of the CallContext structure passed by
VRay.
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.