Getting Started

This page gives a quick overview of the App SDK and introduces you to the general topic of photorealistic rendering.

I. Introduction

The V-Ray Application SDK allows third-party integrators to initiate and control a rendering process that makes use of the V-Ray engine. It provides a high-level API that enables users to render and manipulate a V-Ray scene inside the host process or outside it using distributed rendering. The scene may be created in memory by translating the native format to V-Ray plugins or it could be loaded from a file, potentially exported from another application.

II. Setup

In order to use V-Ray Application SDK, the VRAY_SDK environment variable should be set. To use the Python binding, the python folder must be in the Python module load paths (e.g. by adding it to PYTHONPATH).

The setenv script will set both environment variables. To use it run from the corresponding command line tool:

• setenv.bat (Windows)
• source setenv.sh (Linux/macOS)

When VRAY_SDK is set, the App SDK binding will search for the VRaySDKLibrary binary and its dependencies inside VRAY_SDK/bin. If the directory structure of a product that uses App SDK doesn’t include the binaries inside a /bin folder, VRAY_APPSDK_BIN can be used instead of VRAY_SDK. In that case, the App SDK binding will try to load the binaries directly from the folder that VRAY_APPSDK_BIN points at.

In the case that no environment variables could be used, the App SDK API allows setting the search path at runtime. Please read the API documentation for the corresponding binding.

III. Package Contents

• bin - V-Ray core binaries. Includes the V-Ray Application SDK library
• cpp - C++ header files
• dotnet - .NET Framework 4.0 (Mono) V-Ray Application SDK DLLs
• dotnetcore - .NET Core 3.1 V-Ray Application SDK DLLs
• examples - Code samples for all supported languages
• help - SDK documentation and API guide for offline use
• node - Node.JS and Electron V-Ray Application SDK module/binding
• python - Python V-Ray Application SDK module
• scenes - Sample scenes made by Chaos
• tools - V-Ray tools for viewing/converting assets etc.
• setenv.bat/sh - script that sets up a local environment for running the V-Ray Application SDK. To use it, invoke a script in a command window (in bash use "source setenv.sh"). It will update the environment variables needed by the SDK.

IV. Basic Rendering

The V-Ray Application SDK exposes a VRayRenderer class that initiates and controls any rendering process. The class defines high-level methods for creating or loading a V-Ray scene and rendering it. It hides the inner complexities of the V-Ray engine while keeping its powerful capabilities.

The basic workflow for starting a render process usually consists of the following steps:

• Instantiating the configurable VRayRenderer class
• Either of (or even a combination of):
  • Creating new instances of V-Ray render plugins to translate your native scene description to V-Ray and setting their parameters
  • Loading a scene by specifying a path to a .vrscene file (the V-Ray native format for serializing scenes)
• Invoking the method for rendering
• Waiting for the image to become available
• Cleaning up memory resources by closing the VRayRenderer

All language implementations of the VRayRenderer class offer a method without arguments (start()) that is used to start the rendering of the currently loaded scene. The method is a non-blocking call which internally runs the V-Ray engine in a separate thread. Thus the rendering can conveniently take place as a background process without the need to use language-specific tools for creating threads.

The VRayRenderer class gives access to the current state of the rendered image at any point in time. Whether the render process has finished or not, an image can be extracted to track the progress of the rendering. All language bindings expose a method that returns an image object which holds the rendered image data at the time of the request. This image class can be used for direct display or to save the rendered image to a file in one of several supported popular compression formats.

Python

C++

CSharp

JavaScript

V. Render Modes

The V-Ray Application SDK offers the ability to run the V-Ray engine in two distinct render modes - Production and Interactive.

Production mode is suitable for obtaining the final desired image after the scene has been carefully configured as the render process can take a lot of time before the whole image is available.

Interactive mode on the other hand is very useful for fast image preview and progressive image quality improvement which makes it the perfect choice for experimenting with scene settings and modifying content and receiving fast render feedback.

Each render mode is supported in two flavors - CPU and GPU. The former utilizes the CPU resources while the latter takes advantage of the graphics card computing power. The GPU rendering type is in turn subdivided into two modes - CUDA and Optix (both NVIDIA only) depending on the technology that is used with the GPU.

The type of rendering that will be initiated can be chosen easily through the renderMode property of the VRayRenderer object. The default render mode for the VRayRenderer class is Interactive (CPU). The render mode can be changed between renders to avoid having to re-create or re-load the scene. This allows you to work interactively on a scene with V-Ray and then to switch to production mode for final rendering without any overhead.

Python

C++

CSharp

JavaScript

VI. Common Events

During the rendering process that runs in the background in a separate thread V-Ray emits a number of events that are available to App SDK users. You can subscribe to these events through the main VRayRenderer class.

The V-Ray Application SDK provides the means for attaching callbacks that execute custom client logic when an event occurs. The code of the callbacks is executed in a separate thread that is different from the main V-Ray rendering thread. This design allows the V-Ray rendering process to remain fast without additional overhead and ensures that slow operations in client callback code will not affect the total rendering time. Keep in mind that slow user callbacks may delay the execution of other callbacks. Each callback includes a time 'instant' argument that gives you the exact time the event ocurred. The callback itself may be executed at a noticeably different moment due to queueing and being asynchronous.

The events can be broadly classified into three types: events common for all render modes, events specific to bucket rendering and events specific to progressive rendering. This section covers the events that are emitted regardless of the type of sampling.

The common render events occur when:

• The renderer state changes (e.g. starts rendering, stops rendering)
• V-Ray outputs text messages prior to and during rendering
• V-Ray switches the current task (e.g. loading, rendering) and reports progress percentage

State Changed Event

The state change event is emitted every time the renderer transitions from one state to another, such as when starting to render, when the image is done or when an error occurs and it stopped. This is the main point to implement user logic related to initiating and completing renders.

Unless startSync() is used instead of the asynchronous start() method, no changes should be made to the scene and renderer while in the PREPARING state before transitioning out of it. Attempting to make changes will be rejected.

The final image is available when the renderer gets to the IDLE_DONE state. Intermediate images are also available during rendering.

Python

C++

CSharp

JavaScript

Log Message Event

Output messages are produced by the V-Ray engine during scene loading and rendering and they can be captured by subscribing to the message log event. The callback data that becomes available when a message is logged is the text of the message and the log level type (info, warning or error).

Python

C++

CSharp

JavaScript

Progress Event

Progress events are emitted whenever the current task changes and also when the amount of work done increases. They include a short message with the current task name and two numbers for the total amount of work to do and the work that is already complete.

Here are short examples how to report progress in percentage:

Python

C++

CSharp

JavaScript

VII. Bucket Events

There are two types of image sampling in Production mode - "bucket" sampling and progressive sampling. Bucket rendering splits the image into small rectangular sub-images, each processed independently by a different local CPU thread or network server (see the Distributed Rendering section). The sub-images are only returned when completely ready. Progressive rendering works the same way as in Interactive mode - the whole image is sampled and images are returned for each sampling pass, reducing noise with each pass. This section covers the events which are specific to Production bucket rendering only. The progressive sampling mode emits the event described in the Progressive Events section further below.

There are two phases in Production bucket rendering - assigning a bucket to a render host (or local thread) and rendering the assigned region of the image. This is why there are two events that are raised for each bucket of the image - initializing a bucket and receiving the image result. Users of the API can subscribe to the events via the main VRayRenderer class.

In Production bucket mode the image is perceived as a grid of rectangular regions, "buckets". The bucket is uniquely identified by the coordinates of its top left corner and the width and height of its rectangular region. The top left corner of the whole image has coordinates (0, 0).

To enable bucket sampling, the VRayRenderer’s render mode must be production and SettingsImageSampler::type=1.

Bucket Init Event

The bucket init event is raised when the main V-Ray thread assigns a bucket to a network render host or local thread. The callback data that is provided for this event is the bucket size and coordinates as well as the name of the render host (if any) as it appears on the network.

Python

C++

CSharp

JavaScript

Bucket Ready Event

The bucket ready event is raised when the render host that has been assigned a bucket has finished rendering the part of the image and has sent its result to the main V-Ray thread. The returned callback data for the event contains the size and coordinates of the region, the render host name and the produced image.

Python

C++

CSharp

JavaScript

VIII. Progressive Events

When rendering in Interactive mode or in Production with the image sampler set for progressive sampling (instead of buckets), the whole image is sampled at once and the progressiveImageUpdated event is emitted for each sampling pass with a more refined image. The purpose of Interactive mode is to allow users to receive fast feedback for the scene they have configured. Noisy images are quickly available when the Interactive render process starts.

Python

C++

CSharp

JavaScript

IX. V-Ray Images

The VRayImage class provides access to the images rendered by V-Ray. It is used by the VRayRenderer, as well as by some of the arguments of the callbacks invoked when an event occurs. The VRayImage class provides utility functions for manipulating the retrieved binary image data. The binary data is in full 32-bit float per channel format and can be accessed directly, but there are convenience methods that perform compression in several of the most popular 8-bit formats - BMP, JPEG, PNG. Saving EXR and other high dynamic range formats is also possible through another API: VRayRenderer.vfb.saveImage().

The methods that are exposed by the VRayImage class come in two flavors. The first group of methods directly returns the bytes of the compressed image, while the second group compresses the image and saves it to a file.

Python

C++

CSharp

JavaScript

All instances of the VRayImage class must be closed so that memory resources held by the instance are released. It is recommended to always free the resources (close the image) when you have finished working with the image. The platforms that support a garbage collection mechanism will take care of freeing the internally held resources in the event that the user does not close the retrieved image.

Downscaling

In addition to the utility methods for compression, the VRayImage class supports downscale operations that resize the retrieved image to a smaller one. The result of the downscale operations is another VRayImage instance which has all the utility methods of the class.

Python

C++

CSharp

JavaScript

Changing the Image Size

The size of the rendered image can be controlled through the size property of the VRayRenderer class. When a ".vrscene" file is loaded the size defined in this scene file is used unless the VRayRenderer size is set after loading the file to override it.

Python

C++

CSharp

JavaScript

X. Render Elements

V-Ray Render Elements (also known as Render Channels or Arbitrary Output Variables, AOVs) are images containing various types of render data encoded as 3-element color, single floats or integers. Some of them are Z-depth, surface normal, UV coordinates, velocity, lighting, reflections etc. Each V-Ray scene may contain an arbitrary number of render elements (also called channels). Each channel is enabled by a unique plugin, except for the RGB and Alpha channels, which are always enabled.

To access the render elements in the current scene, use the VRayRenderer instance where the scene is loaded. Each render element's data can be taken either as a VRayImage, or as raw data (as byte, integer, or float buffers). Optionally, provide a sub-region of interest to the APIs to get that part of the data.

If the scene does not contain render element plugins, they could be added, as shown in the examples.

Python

C++

CSharp

JavaScript

XI. Plugins

Plugins are the objects that specify the lights, geometry, materials or settings that constitute the 3D scene. Each V-Ray scene consists of a set of plugins instances. The V-Ray Application SDK exposes methods in the main VRayRenderer class that can be used to create plugin instances or list and modify (or delete) the existing ones in the scene.

Plugin objects can be retrieved by instance name. Once the user has obtained a plugin instance its property (a.k.a. parameter) values can be viewed or set to affect the rendered image. The properties of the plugin are accessed by name. In Interactive mode the changes to plugin property values are usually applied immediately during rendering and changes become visible almost instantly, but for each change the image sampling is reset and you get some noisy images initially. In Production mode changes to plugin property values take effect if they are applied before the rendering process is started. The following example demonstrates how the transform for the render view (camera) in a scene can be changed with the App SDK.

Python

C++

CSharp

JavaScript

The call to a method that retrieves the value for a plugin property always returns a copy of the internal value stored in the local V-Ray engine. In order to change the plugin property value so that it affects the rendered image the setter method from the plugin class should be called. Simply modifying the value returned by a getter will not lead to changes in the scene as it is a copy, not a reference.

Adding and removing plugins

Plugin instances can be created and removed dynamically with the App SDK. The next example demonstrates how a new light can be added to the scene.

Python

C++

CSharp

JavaScript

In the following example we remove a sphere plugin by name:

Python

C++

CSharp

JavaScript

Automatic commit of property changes

All changes made to plugin properties should be done before the rendering starts when rendering in Production mode. Any changes after that do not affect the current rendering, but they are not lost. In Interactive mode the changes made after the rendering starts are applied immediately to the scene by default. Alternatively, the user can decide to make a batch of changes to be applied together, usually for better performance. This is done using the autoCommit property of the VRayRenderer class. In the following example we demonstrate how a group of changes are batched and commit is called explicitly to apply them.

Python

C++

CSharp

JavaScript

XII. Property Types

The following are the types recognized for property types:

• Basic types: int, bool, float, Color (3 float RGB), AColor (4 float ARGB), Vector (3 float), string (UTF-8), Matrix (3 Vectors), Transform (a Matrix and a Vector for translation)
• Objects: references to other plugin instances
• Typed lists: The typed lists in App SDK are IntList, FloatList, ColorList and VectorList.
• Generic heterogenous lists: The App SDK uses a generic type class called Value for items in a generic list. Note that generic lists can be nested.
• Output parameters: These are additional values generated by a given plugin which may be used as input by others. The PluginRef type represents a Plugin with specific output parameter.

Detailed documentation about working with each type can be found in the API reference guides as they have some language nuances. All types are in the VRay namespace.

XIII. Animations

V-Ray App SDK supports rendering of animated scenes. Animated scenes contain animated plugin properties. A plugin property is considered animated if it has a sequence of values - each for a specific time or frame number. This defines key frames and in the process of sampling, interpolation is done between the values.

One can obtain the current frame number from the frame property of the VRayRenderer. The renderer gets into the IDLE_FRAME_DONE intermediate state when a frame is done and there are more frames after it. After the final frame it becomes IDLE_DONE.

Python

C++

CSharp

JavaScript

XIV. V-Ray Server

A V-Ray Server is used as a remote render host during the rendering of a scene. The server is a process that listens for render requests on a specific network port and clients such as instances of the VRayRenderer class can connect to the server to delegate part of the image rendering. V-Ray Standalone render servers can also be used. The server cannot be used on its own to start a rendering process but plays an essential role when completing distributed tasks initiated by clients. In order to take advantage of the distributed rendering capabilities of V-Ray, such servers need to be run and be available for requests.

The V-Ray Application SDK allows for easily creating V-Ray server processes that can be used in distributed rendering. The API includes the VRayServer class that exposes methods for starting and stopping server processes. In addition the VRayServer class enables users to subscribe to V-Ray server specific events so that custom logic can be executed upon their occurrence.

Server events occur when:

• The server process starts and is ready to accept render requests
• A render client connects to the server to request a distributed rendering task
• A render client disconnects from the server
• A server text message is produced due to a change in the server status or to track the progress of the current job

The next code snippet demonstrates how VRayServer can be instantiated and used to start a server process.

Python

C++

CSharp

JavaScript

XV. Distributed Rendering

The V-Ray Application SDK allows third party integrators to make full use of the V-Ray distributed rendering engine. Distributed rendering allows you to render parts of the image in parallel on multiple render hosts. The client process which initiates the rendering synchronizes the results produced by the render servers. All render modes support distributed rendering.

Render hosts can be dynamically added and removed at any point in time during the rendering process. The render hosts should have a V-Ray server running on them when the render client tries to add them to its list of active hosts because the client verifies whether a connection can be established for a distributed task at that time.

Each render host is identified by an address:port pair specifying the IP or DNS address of the machine with the V-Ray server and the port on which this server is listening for render requests. The VRayRenderer class exposes methods for dynamic addition and removal of hosts. Regardless of the progress made by the main render process in the client, remote machines can successfully begin to participate in the rendering as long as the they have running V-Ray servers.

Python

C++

CSharp

JavaScript

Removal of render hosts is just as easy as adding them. Even if all remote render hosts disconnect or are deleted from the rendering host list the rendering process will continue on the client machine which has initiated it.

Python

C++

CSharp

JavaScript