Render Automation with V-Ray App SDK: 6 Steps from Scene to Output

V-Ray App SDK provides an API for starting and managing renders with the V-Ray engine, either from within an application or in a separate process. According to Chaos’s official documentation, a scene can be created in memory using V-Ray plugins or loaded from a .vrscene file. This guide explains the basic render loop in App SDK and which render mode is useful at different stages of a scene. Since the documentation does not specify a current software version for App SDK, this overview is based on the general workflow shown in the docs.

1. Prepare the environment

1. Locate the App SDK files. The documentation requires the VRAY_SDK environment variable to be set before the SDK can be used. If you’re using the Python binding, the python folder must be added to Python’s module search paths; the docs show this using PYTHONPATH. This preparation allows the application to find the SDK components.

2. Run the supplied environment script or consider an alternative. The docs show setenv.bat for Windows and source setenv.sh for Linux and macOS. These scripts set the relevant environment variables. If the SDK binaries are not in the product’s /bin folder structure, the docs say you can use the VRAY_APPSDK_BIN variable. When environment variables cannot be used, the API also provides an option to set the search path directly.

At this stage, make sure the folder structure on the computer matches the location where the application looks for the SDK library. The docs do not list requirements for a specific operating system setup or hardware, so installation details should be checked against the API documentation for the binding in use.

2. Create or load a scene

1. Initialize the render controller. The VRayRenderer class in App SDK starts and manages the render process. A scene can be built in memory by creating V-Ray plugin objects and setting their parameters, or by loading a .vrscene file, V-Ray’s scene format. The docs also note that the two methods can be combined.

How you create a scene depends on your existing production pipeline. For example, an application can convert its own scene data into V-Ray plugins, or open a previously exported .vrscene file. App SDK is not designed to require a specific modeling application; its purpose is to enable this kind of integration with the V-Ray render engine.

1. Choose a render mode once the scene is ready. The docs describe two main options:

Both modes support CPU and GPU options. The docs state that CUDA and OptiX are available only for NVIDIA, while Metal and MetalRT are available only for Apple. The render type is selected using the renderMode property of the VRayRenderer object. The docs describe Interactive (CPU) as the class’s default mode, so choose the mode explicitly according to the application’s purpose and available system support.

3. Start the render and retrieve the result

1. Start rendering. The start() method launches the render process on a separate thread and returns without waiting. This lets the application perform other tasks while rendering or remain ready to retrieve progress images. The Python example in the docs loads a scene, starts the render, waits for it to finish and saves the resulting image as a PNG:

import vray

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

The 6000 value in the code example is an example argument passed to waitForRenderEnd in the documentation; it is not presented as a recommended or required duration for every scene. In production code, handle the wait behavior according to the documentation for the API binding in use.

1. Review the image while rendering and release resources. App SDK notes that the current image data can be retrieved before rendering is complete. This can be useful, especially in Interactive mode, for displaying a preview in the application interface or monitoring the process. The docs describe the final image as ready when the renderer reaches the IDLE_DONE state. Once the work is complete, the renderer should be closed; in the Python example, the with block manages this lifecycle.

The docs also explain that you can listen for events when the render state changes, when V-Ray generates a message, or when task and progress information is reported. These notifications help an integration manage application-side behavior during loading, rendering and completion. However, callbacks run on a separate thread; slow user code can delay other callbacks.

What changes in architectural and archviz workflows?

App SDK is useful for teams that want to integrate repetitive render steps into an application or manage a V-Ray scene from another process. Architecture firms and archviz studios can use Interactive mode to test scenes and content, then switch to Production mode for final images. This lets them change how they work between preview and final output while using the same renderer.

However, the sources do not provide a compatibility matrix for specific 3D software, hardware requirements, licensing terms or pricing. When choosing CPU or GPU rendering, you can consider only the options documented and the platform limitations of the relevant GPU technologies; no conclusions can be drawn about performance. Before setting up an application integration, check the API documentation for the language binding in use and the folder structure where the SDK libraries will be located.

Common mistakes

• Starting the SDK binding without setting VRAY_SDK or an appropriate alternative path can prevent the libraries from being found.

• Don’t assume that calling start() means rendering has finished; the docs describe it as an asynchronous call that returns without waiting.

• Changes to the scene or renderer while rendering in the PREPARING state may be rejected. The docs give this warning for cases where start() is used instead of startSync().

• Slow callbacks connected to V-Ray events can delay other callbacks, so review what your event handlers do.

• Treating the wait argument in the sample code as a fixed setting for every project goes beyond what the documentation says.

This documentation explains the fundamentals of loading a scene and managing a render through App SDK, not how to select specific render settings in a user interface. For details on settings within an application, consult the API reference for the relevant binding.