Page History

...

We could informally define three kinds of plugins that build up a V-Ray scene.
One would be the so called "top-level" plugins, which can exist on their own, without being part of some plugin tree. Lights are top-level plugins for example. They can also receive input from other plugins of course, but they do not output values to other plugins.
The plugins which are not top-level serve as input for parameter slots which require a plugin of certain type. For example a material plugin may require an optional texture input and you'd reference a texture plugin there. The texture plugin may receive input from a UVW generator and so on.
The third kind would be a special type of top-level plugins which only have one instance. These are basically settings plugins. Most of them have "Settings" in their name, but a few don't. The V-Ray camera is also defined by such a singleton settings plugin.

There is an example tiny scene in section 7. Its contents should become understandable by reading the following sections.

1.3. Parameter types

The following are the types recognized in a V-Ray scene (think .vrscene file). They have corresponding types in the different AppSDK language bindings. The SDK uses the respective basic language types wherever possible and defines custom type classes for the rest.

• 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 AppSDK are IntList, FloatList, ColorList and VectorList.
• Generic heterogenous lists: The AppSDK 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. For example the TexAColorOp plugin plugin (described in section 5.2) can be referenced directly as a texture, resulting in its default color texture output, but you can also refer to any of its other outputs, like sum, difference, maximum etc. for different results (Note: in some cases connecting an output parameter to an input parameter may not work directly, so you'd have to make the connection through a wrapper plugin like TexAColor or TexFloat).

Parameter polymorphism is an important feature of V-Ray. Texture parameters accept simple (basic) values, so instead of creating an additional texture plugin which generates a single color you just set a Color value to the texture slot. Same goes for float textures and single float values etc. You can also set the value of a texture parameter to an output parameter as described above.

...

V-Ray uses a text based scene file format (.vrscene). It is quite simple which makes it convenient to debug and modify by hand. The format is case-sensitive and a little similar to JSON. Large data values, such as geometry definitions can be compressed (and text encoded). The file contains consecutive plugin instance definitions: type, instance names, parameter list. Nesting is not supported.
The main rules are:

• Each plugin instance is defined on a new line starting with its type name follow followed by a space, an instance name, another space and an opening curly brace.
• Each parameter is written on a new line with its name, an equals sign with no whitespace on both sides and a value. The line ends with a semicolon. A parameter definition line may be split into multiple lines for long values such as lists.
• References to other plugins are defined by writing out their instance names without quotation. Output parameters are specified the same way with additional double colon and parameter name (instance_name::out_param_name).
• The end of the plugin definition is marked with a closing brace on a new line.
• C++ style single line comments are supported.
• Files can be stitched together with an #include "another.vrscene" directive like in C.
• References can be made to plugins which will be defined further down the file.
• The parser is indifferent to indentation and empty lines. The only whitespace rule is no whitespace around the value assignment operator (=) for parameters.

Scene files are supposed to be created by V-Ray. You shouldn't try to write them yourself, but you are of course free to modify them by hand.

It is important to note that the order of definition of plugin instances generally does not matter. This also applies to a scene created in memory, even when you don't export it to a file. There are a few exceptions such as camera related settings plugins, which may not work correctly if V-Ray doesn't process them in a particular order.

...

Apart from documentation included with the AppSDK and this guide, the help pages for 3dsMax and Maya on docs.chaosgroup.com are a good source of parameter information and examples, although they use the user-friendly UI names for things and not the actual scene parameter names.
A very useful tool for basic parameter information is plgparams.exe included in the binary folder of the SDK. It lists all parameters for the specified plugin (or all plugins with -list) and their types, default values and text comments. Similar information can be obtained using the ListAllPluginsAndProperties example in the C++ folder (or equivalent code for another language).
It is often useful to save out your scene to a file to inspect if you did everything properly. For example you may have failed to set some parameter properly and you will see this in the file as a missing or incorrect value, although you can also check the result of the set operation in your code. You can try to pinpoint problems by deleting parts of the scene (parameters or whole plugins) and re-rendering.
It can be very helpful if you have a V-Ray for 3dsMax or Maya and use it to export vrscene files to see what plugins and parameters are written out. The exporters for 3dsMax and Maya can be considered "ground truth" (even though they may have an occasional bug or missing feature).
If you're getting a black render make sure your camera is positioned and oriented properly and not inside an object. Keep in mind the default up-axis is Z, but it can be set to something else, usually Y. You might also get invisible or black objects if something is wrong with the attached material. In this case you can still the object in the alpha channel, especially if there is nothing behind it.
Another thing to watch out for is V-Ray's errors and warnings, so always implement the DumpMessage callback.

...

These are controlled from the SettingsOutput plugin, but it is one of the few exceptions where you should not touch the plugin directly. The AppSDK has APIs for setting image and region size (i.e. renderer.setRenderRegion, depends on language).

6.2. Image sampling and filtering

...

• trace_depth - The maximum depth for tracing reflection and refraction rays. Defaults to 5.
• gi_depth - The maximum depth for tracing diffuse GI rays. Defaults to 3. Lower if you need faster rendering and the scene is exterior. For interiors you may need to increase to get enough lighting, otherwise the scene may remain too dark.
• coherent_tracing - Experimental grouping of rays for coherency (disabled by default). This can improve performance on GPUs because they handle non-divergent code better. The first few sampling passes will have lots of artifacts, because entire groups of rays move together. Over time this should disappear and the final result should converge to the same image as when this is turned off. This option is only useful for interiors with lots of GI on GPU.
• cpu_bundle_size - A performance-related parameter. This is the number of rays that get processed together. The default value of 64 for CPU is good.
• cpu_samples_per_pixel - Number of samples to take for each pixel at one sampling pass. If you set lower, you will get images more often, which is good for interactivity. If you set it higher, you may reach final quality a tiny bit faster, because of the fewer back-and-forth sampling passes, but you will have to wait more between images and it may feel unresponsive when trying to change something in the scene.
• gpu_bundle_size - Analogous to cpu_bundle_size, but for GPU mode. The default is 256 and changing it may improve performance. The optimal value depends on GPU architecture and model, so you need to experiment. It may be below or above 256, but the default shouldn't be too far from the optimal performance.
• gpu_samples_per_pixel - Analogous to cpu_samples_per_pixel, but values can be set higher, because GPUs have better performance. You can still set it to 1 for maximum interactivity.
• progressive_samples_per_pixel - If set to true, set the samples per pixel to 1 for the first pass and double that number on each consecutive pass until cpu/gpu_samples_per_pixel is reached. This lets you get some faster feedback initially, because the image difference between the first passes is larger.
• undersampling - When enabled, return results before even 1 sample per pixel is accumulated. This gives you images at 1:8 resolution and then 1:4 and 1:2. This is for faster feedback, but the images are highly pixelated.
• max_sample_level - If set above zero, stop rendering when this amount of samples per pixels is reached. This is set through the renderer object's constructor.
• max_render_time - If set above zero, stop after this many minutes (float number) have passed. This is set through the renderer object's constructor.
• noise_threshold - If set above zero, stop rendering when the noise difference between neighboring pixels falls below this threshold for all pixels. The unit used is defined by the internal noise-calculating algorithm (same as the thresholds in SettingsImageSampler). Values are usually between 0.001 and 0.1. This is set through the renderer object's constructor.
• max_draw_interval - Controls partial image updates if set above (the default) zero. This is the maximum time in milliseconds between image updates. So you get a potentially partial image update every time this time elapses. This lets the user see preliminary results earlier. The value in V-Ray for 3dsMax and Maya is 150.
• min_draw_interval - This is the minimum time between image updates. Set above zero if you want to limit the amount of drawing in the VFB or your own viewport. This may help with CPU and memory usage utilization when the rendering is very fast. The value in V-Ray for 3dsMax and Maya is 50.
• opencl_texsize - Despite the name, applies to both OpenCL and CUDA mode. This is the resolution to which textures are re-sampled if opencl_resizeTextures is true and the texture is larger than that. This is intended to help with limited GPU memory, but you may increase it from the default 512 to avoid losing detail if you have enough memory.
• opencl_resizeTextures - If true, apply opencl_texsize.
• opencl_textureFormat - Determines bit-depth of textures after reading into memory. 0=32-bit float, 1=16-bit float, 2=8-bit. Default is 16-bit.
• disable_render_elements - False by default. If set to true, no render elements will be calculated, which may save some computation and memory.

...

• gi_dontRenderImage - Set to 1 if you're baking a GI prepass (Irradiance Map or Light Cache) file and want to skip the actual rendering.
• mtl_maxDepth - The maximum number of bounces to trace for reflections and refractions. Defaults to 5. Only increase if you need to. In RT mode set SettingsRTEngine::trace_depth instead.
• misc_transferAssets - Try to transfer missing assets in distributed rendering (DR) from the client to the render server. Disabled by default.

• misc_abortOnMissingAsset - Fail DR if an asset can't be found. Disabled by default.

• ray_max_intensity and ray_max_intensity_on - If you enable it with ray_max_intensity_on, ray_max_intensity clamps the values of some very bright samples to avoid the hard to clean up "firefly" artefacts at the cost of slightly wrong overall image brightness.
• num_probabilistic_lights and probabilistic_lights_on - (experimental) The number of lights to sample for probabilistic lighting if probabilistic_lights_on is true. Probabilistic lighting improves render speeds with hundreds and thousands of lights by only sampling a few of the "important" light sources.
• misc_lowThreadPriority - Render with low thread priority to improve multitasking. Disabled by default.

...