V-Ray App SDK rendering workflow: loading scenes, previews and output

According to Chaos’s documentation, the V-Ray App SDK provides an interface that lets third-party software launch and manage the V-Ray engine. This guide covers how to load a scene and render it through the SDK, monitor an intermediate image and save the result to a file. Since the documentation does not specify a particular SDK version, the information below is based on the general workflow it describes.

What can you use the V-Ray App SDK for?

The SDK lets you create and render a V-Ray scene within another application’s process or independently of that application. You can build a scene in memory by converting it from a native project format to V-Ray plugins, or load it from a .vrscene file, V-Ray’s scene format. Distributed rendering is also among the documented use cases.

This setup is relevant for developers who want to connect rendering to their own tools or automation workflows. The SDK is not a standard user-interface guide for 3ds Max or other modeling software; it is an API for building integrations with the V-Ray engine. As a result, its direct value to architecture firms depends on whether their software has an integration built with the SDK.

From setup to image output: step by step

1. Set up the SDK paths. The documentation requires the VRAY_SDK environment variable to be set. If you’re using the Python binding, add the SDK’s python folder to Python’s module search path. The documentation gives setenv.bat for Windows and source setenv.sh for Linux and macOS as examples. These scripts set the relevant environment variables.

2. Verify the library location. Once VRAY_SDK is set, the SDK binding looks for the required binaries and dependencies under VRAY_SDK/bin. If the product’s folder structure has no bin directory, you can use VRAY_APPSDK_BIN; in that case, the search takes place in the specified folder. The documentation also notes that if you can’t use an environment variable, you can set the library search path at runtime.

3. Create a renderer and load a scene. VRayRenderer is the main class for starting and controlling the render process. You can create a scene using new plugin objects and parameters, or load a .vrscene file. Both approaches can also be combined. When developing an integration, decide at this stage how scene data will be provided.

4. Choose a rendering mode and start rendering. The default mode in the documentation is Interactive (CPU). The start() call runs asynchronously, so the application can perform other tasks while rendering continues in a separate thread. Being able to retrieve an intermediate image during rendering helps track progress in a preview workflow. The final image is ready when rendering completes.

5. Retrieve the image and release resources. The SDK provides the current render image as an image object, which can be displayed or saved to a file in supported formats. Closing the renderer and clearing the memory resources in use when the job is finished are the final steps in the basic workflow described in the documentation.

A short example from the Python documentation showing the call sequence:

import vray

with vray.VRayRenderer() as renderer:
    renderer.load('./intro.vrscene')
    renderer.start()
    renderer.waitForRenderEnd(6000)
    image = renderer.getImage()
    image.save('intro.png')

The filenames here are taken from the example in the documentation. Use the code within an integration that adapts the scene file path and the image output location to your project.

Preview or final render?

The SDK defines two render modes. Interactive mode is suited to quick image previews and getting iterative feedback while adjusting scene settings. Production mode is intended to produce the desired final image once the scene has been carefully prepared; generating the complete image can take longer. You can switch modes between renders without recreating the renderer or reloading the scene.

For GPU rendering, the documentation lists CUDA and OptiX as NVIDIA options, and Metal and MetalRT as Apple options. So hardware compatibility with the rendering technology in use should be checked early in the integration process. Plugin support also varies: some components in the API reference are marked as fully supported, some as partially supported, and some as having no GPU support. This means a particular scene feature cannot be assumed to work with every rendering path.

Impact on architectural and visualization workflows

For architectural visualization teams, the SDK’s value lies in its ability to connect repetitive rendering steps to an application. A project tool could load a .vrscene file, provide a preview, track render status and save the image. Distributed rendering is also covered in the SDK documentation, but which software and hardware configuration teams can use for it depends on their own integrations.

Choosing a render mode can simplify the workflow: use Interactive for material, lighting and camera-framing tests, and Production for the final output of an approved scene. However, the SDK documentation provides no numerical comparisons for render times, hardware requirements or licensing terms. Firms should therefore test compatibility and hardware with real project scenes in their own environments.

Common mistakes

• Skipping environment variables: If VRAY_SDK is not defined, the binding may not find the required libraries. The Python module path must also be set up separately.

• Ignoring the asynchronous workflow: start() launches rendering in the background. The documentation states that you should not modify the scene or renderer while the renderer is in the PREPARING state; such attempts may be rejected.

• Confusing preview and final modes: Interactive is intended for quick feedback, while Production is intended for prepared images. Using the two modes at different stages of the job creates a more consistent workflow.

• Assuming plugin compatibility: GPU support in the API reference can vary by plugin. Integration testing should verify that the scene components in use are compatible with the intended rendering path.

The workflow in this guide is based on the general usage described in Chaos’s V-Ray App SDK documentation, which does not specify a particular software version.