Linkage

Here we will discuss how to properly link and load the App SDK and V-Ray dynamic libraries.

There are four DLL files or groups that need to be loaded at various stages:

In most cases this is done with just one line of code, but the API allows for custom file layouts through additional settings.

C++

There is no binding DLL because the binding is header only. There are two ways to link the main SDK library described in the following subsections:

Link VRaySDKLibrary at compile-time

In this case you need to use the VRaySDKLibrary.lib import library when building on Windows and the -lVRaySDKLibrary linker switch on Linux/macOS. The VRaySDKLibrary dynamic library will have to be on the system paths for loading dynamic libraries before you run the application: PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS. You don't need to define additional preprocessor macros.

Link VRaySDKLibrary at runtime

To avoid having to modify the system search paths you may load the library dynamically at runtime. Exactly one of your source files has to define the VRAY_RUNTIME_LOAD_PRIMARY macro before including vraysdk.hpp. The rest of the sources have to define VRAY_RUNTIME_LOAD_SECONDARY before including the header. The VRAY_RUNTIME_LOAD_PRIMARY source file should create a VRayInit instance that lasts for the lifetime of the application. It takes an optional path to VRaySDKLibrary.dll, including the filename.

The runtime loading version of VRayInit also provides a getSDKLibraryErrorString() method for diagnosing failures.

.Net

The .Net binding is implemented in two assemblies: VRaySDK.Net.dll and VRaySDK.Net.Plugins.dll that your application has to reference. The second assembly can be omitted if you don't need the concrete Plugin classes, but usually it is needed.

Python

The Python binding is implemented in vray.pyd on Windows or vray.so on Linux and macOS. It should either be installed in your site-packages directory or you would have to add its location to the PYTHONPATH environment variable.

Node.js

The Node.js binding is implemented in the VRay.node binary file, but should be loaded through the vray.js script which adds a few helpers to it.

VRaySDKLibrary runtime loading: .Net, Python, Node.js

You can use a static method to add a search path for VRaySDKLibrary.dll if it is not in the system PATH. You have to do this before calling any other App SDK methods.

.Net

Use Globals.SetSDKLibraryPath(search_path).

Python and Node.js

When you import or require the vray module, it will try to load VRaySDKLibrary.dll. It may fail. You can call vray.setSDKLibraryPath(search_path) to specify a search path and force VRaySDKLibrary.dll (re)loading. The function returns 'true' on success. You can get extended info by calling vray.getSDKLibraryErrorString().

V-Ray engine

The directory containing vray.dll and the other DLLs from the original App SDK bin directory needs to be on the system library search path (PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH). The VRAY_PATH environment variable can be set to an alternative location.

IMPORTANT: The VRAY_PATH variable may be set on the user system from another V-Ray install (such as V-Ray Standalone). Don't rely on it being empty! It can cause crashes due to loading mismatched DLLs. You should also make sure PATH/LD_LIBRARY_PATH/DYLD_LIBRARY_PATH does not contain other V-Ray paths on the system or that your path is at the front.

This is how the render plugins are loaded: 1. A string containing semicolon separated paths is constructed from the optional RendererOptions::pluginLibraryPath parameter - this is usually empty, but allows for overriding the defaults. 2. The value of the VRAY_PATH environment variable is appended with "/plugins" and this is appended to the list. If the variable is not set, the path of VRaySDKLibrary is appended instead (again appended with "/plugins"). 3. The path list is passed to the V-Ray plugin manager to load the plugin classes from vray_*.dll or libvray_*.so.

Custom V-Ray plugins

If you have third party V-Ray render plugins (textures, geometry or anything) you should either copy them in the same plugins directory or add their directory to the RendererOptions::pluginLibraryPath parameter as described above. The file names should match the template vray_*.dll or libvray_*.so.

GPU engine

The RendererOptions::pluginLibraryPath parameter could be optionally set to a path, which contains the rt_cuda.dll/so and rt_opencl.dll/so libraries if they are not at their default location next to vray.dll and VRaySDKLibrary.dll.

C/C++ Runtime

You should make sure that the respective runtime or a compatible one is available where you deploy the SDK. Currently the App SDK is built using:

Normal usage example

# The directory containing the vray shared object - vray.pyd/so - should be present in the PYTHONPATH environment variable
import vray
renderer = vray.VRayRenderer()

// link against VRaySDKLibrary.lib or with -lVRaySDKLibrary and have VRaySDKLibrary accessible through the OS library path
#include "vraysdk.hpp"

void main() {
    VRay::VRayInit init(NULL, true);
    VRay::VRayRenderer renderer;
}

// VRaySDK.Net.dll has a reference in the current .csproj
using VRay;
class Program {
    static void Main(string[] args) {
        VRayRenderer renderer = new VRayRenderer();
    }
} 

// vray.js is in node_modules with the rest of the files from the App SDK package
var vray = require('vray');
var renderer = vray.VRayRenderer(); 

Advanced usage example

# The directory containing the vray shared object - vray.pyd/so - should be present in the PYTHONPATH environment variable
import vray
# These paths are optional. Only pass them if it is necessary for your project
# You have to call this before any other API methods
vray.setSDKLibraryPath("/some/path") # vray.dll should be here or on the OS path
renderer = vray.VRayRenderer(pluginLibraryPath="/some/other/path")

// main.cpp
#define VRAY_RUNTIME_LOAD_PRIMARY
#include "vraysdk.hpp"
 
void main() {
    // These paths are optional. Only pass them if it is necessary for your project
    // You have to call this before any other API methods
    VRay::VRayInit init("C:/some/path/VRaySDKLibrary.dll", true); // vray.dll should be here or on the OS path
    VRay::RendererOptions options;
    options.pluginLibraryPath = "C:/some/other/path";
    VRay::VRayRenderer renderer(options);
}
 
------------------------
// other.cpp
#define VRAY_RUNTIME_LOAD_SECONDARY
#include "vraysdk.hpp"

// VRaySDK.Net.dll has a reference in the current .csproj
using VRay;

class Program {
    static void Main(string[] args) {
        // These paths are optional. Only pass them if it is necessary for your project
        // You have to call this before any other API methods
        Globals.SetSDKLibraryPath("C:/some/path"); // vray.dll should be here or on the OS path
        RendererOptions options = new RendererOptions();
        options.PluginLibraryPath = "C:/some/other/path";
        VRayRenderer renderer = new VRayRenderer(options);
    }
}

// vray.js is in node_modules with the rest of the files from the App SDK package
var vray = require('vray');
// These paths are optional. Only pass them if it is necessary for your project
// You have to call this before any other API methods
vray.setSDKLibraryPath("/some/path"); // vray.dll should be here or on the OS path
var renderer = vray.VRayRenderer({ "pluginLibraryPath": "/some/other/path" });

Removing unnecessary DLLs

You may want to clean up the binary folder to reduce the installation size of your application. You can remove some of the files there if you know for a fact that you will never use the features that require them: