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:

• The binding library
• The main SDK library - VRaySDKLibrary.dll
• The rendering core - vray.dll (with a few third party dependency DLLs in the same directory)
• The V-Ray render plugin libraries in the plugins/ subdirectory

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:

• The Visual Studio 2017 runtime on Windows (vcruntime140.dll, msvcp140.dll)
• glibc 2.17 on Linux
• macOS SDK 10.9 (macOS x64)
• macOS SDK 11.1 (macOS universal, with support for macOS 10.14 and higher)

Normal usage example

Python

C++

C#.NET

Node.js

Advanced usage example

Python

C++

C#.NET

Node.js

Removing unnecessary DLLs

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

• Some of the plugins/vray_*.dll files are large and potentially unused: MtlMDL (together with libvraymdl and libvrayfreeimage in the parent directory), mtlvrmat, ptexbaker, phxshader (together with field3dio_vray and openvdbio_vray), BRDFScanned, GeomBifrost, SphericalHarmonics, TexXSI, vrsceneloader (this is a plugin for embedding scenes, don't mistake it with the normal scene loading functionality).
• You can remove rt_cuda.dll and/or rt_opencl.dll if you're not going to support GPU rendering. The vray_gpu_device_select application is for GPU selection too.
• The bin/osl* and bin/libosl* files are only needed by OSL materials.