Page History
...
AnchorBucketEvents BucketEvents
VII. Bucket Events
BucketEvents | |
BucketEvents |
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
AnchorProgressiveImageUpdated ProgressiveImageUpdated
VIII. Progressive Events
ProgressiveImageUpdated | |
ProgressiveImageUpdated |
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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 AppSDK.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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 AppSDK. The next example demonstrates how a new light can be added to the scene.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
Automatic commit of property changes
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
Anchor | ||||
---|---|---|---|---|
|
XII. Property Types
The following are the types recognized for property types:
Fancy Bullets |
---|
|
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 AppSDK 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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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:
Fancy Bullets |
---|
|
The next code snippet demonstrates how VRayServer can be instantiated and used to start a server process.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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 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 (also known as render slaves). All render modes support distributed 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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
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.
Tabs Container | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|