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.

...

• Basic types: int, bool, float, Color (3 float RGB), AColor (4 float ARGB), Vector (3 float), string, 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: Lists: generic heterogenous lists and concrete typed lists
  The AppSDK uses a generic type class called Value for items in a generic list. Note that generic lists can be nested. The typed lists are IntList, FloatList, ColorList and VectorList.
• Output parameters
  These are additional values generated by a given plugin which may be used as input by others. For example the TexAColorOp plugin 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 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.

...

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, 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.

...

• GeomStaticMesh - The basic fixed geometry descriptor that you will use in most cases. Requires vertex and normal data plus optional UVW texture mapping coordinates.
  V-Ray static meshes work with triangular geometry only, so if you have larger polygons, you will have to triangulate them. The simplest way would be the ear clipping method for convex polygons. The triangle vertex indices are specified in counter-clockwise order in the geometry arrays for V-Ray if you're looking at the front face of the triangle.
• GeomStaticNURBS - Defines a smooth NURBS surface using control vertices and weights.
• GeomStaticSmoothedMesh - References another mesh plugin (usually GeomStaticMesh) and generates a smooth, subdivided version.
• GeomDisplacedMesh - References another mesh plugin (usually GeomStaticMesh) and generates a displaced version using a texture map.
• GeomHair - References another mesh plugin (usually GeomStaticMesh) and generates hair (can be tweaked for fur, grass, shaggy rug etc.) on it. Has many parameters for the size, shape and distribution of strands.
• GeomMeshFile - Loads geometry from a file, a so-called geometry Proxy. The geometry is only loaded on-demand as a ray hits it, so in some cases such as distributed bucket rendering it may prevent unnecessary calculations and memory usage. The currently supported formats are V-Ray's .vrmesh and Alembic .abc. If you have a file in another format, i.e. .obj, you need to convert it with the ply2vrmesh tool.
• GeomParticleSystem - Generates many (usually small) particles.

...

You should always connect a MtlSingleBRDF instance to the Node::material slot. Despite its name, the MtlSingleBRDF::brdf parameter accepts other Mtl plugins, so there is no problem with using any material before finally adding MtlSingleBRDF.

There are some material and BRDF plugins that still exist for compatibility reasons, but we don't recommend you use them. For example instead of connecting MtlDiffuse to a Node, you should create BRDFDiffuse -> MtlSingleBRDF::brdf -> Node::material. Plugins with names ending with "_ASGVIS" can also be ignored. We don't have an exhaustive list of deprecated plugins at the moment.

(see note at the end of this section).

The workhorse of your material setups should The workhorse of your material setups should be BRDFVRayMtl. It combines three types of effects in one plugin - diffuse, reflection and refraction (we have them in separate plugins as BRDFDiffuse, BRDFMirror and BRDFGlass respectively). You can use only one of the layers, though, by setting the colors of the others to black. The plugin splits the incoming light energy according to the colors for the three layers. For example, by default the reflection and refraction have black color, so these layers are skipped. If you set a white reflection color you will get a mirror. If you set a white refraction color you will get glass. The layers are evaluated in this order: reflection, refraction, diffuse. The amount of energy that passes to the next layer is the complementary color to the color of the layer. If you have a (0.2, 0.2, 0.2) reflection color, 20% of light the energy will go into the specular reflection and 80% will pass on to the refraction layer. If your refraction layer has color (1.0, 1.0, 1.0) all of the remaining energy will continue as refracted light, so you will get the effect of a glass material (a little reflection and full refraction of the rest). If the refraction color is (0.5, 0.5, 0.5) instead, 50% of the remaining energy will refract and 50% will scatter off from the diffuse layer. If the diffuse color is white, all of that remaining energy is scattered around the scene and if it's black all of it is absorbed (that would heat the object in the real world). So lets summarize what happens with the incoming energy with a few examples:

...

An important aspect of BRDFVRayMtl is the Fresnel reflection parameter (which is off by default when you create an instance, while it's on by default in V-Ray for 3dsMax). When it's enabled reflection amount depends on the angle of incidence. Glazing angles produce more reflection than looking head-on at the surface. This changes the conclusions we made above about how energy is distributed in the layers of the material. Even with 100% reflection (white color) some of the energy will go through to the reflection refraction and diffuse layer. Fresnel reflections are a must for physically plausible materials. For Fresnel you need to set a correct index of refraction (IOR), even if the material doesn't refract any light. For example metals have very high IORs.

BRDFVRayMtl also has a translucency option, but you should use BRDFSSS2 instead for subsurface scatteringuse BRDFSSS2 instead for subsurface scattering.

Note: There are some material and BRDF plugins that still exist for compatibility reasons, but we don't recommend you use them. For example instead of connecting MtlDiffuse to a Node, you should create BRDFDiffuse -> MtlSingleBRDF::brdf -> Node::material. Plugins with names ending with "_ASGVIS" can also be ignored. We don't have an exhaustive list of deprecated plugins at the moment.

5.1. Material and BRDF plugins

...

• TexAColorOp - One of the most used combination plugins. It has two input AColor textures, two optional multiplier textures, an optional separate alpha channel input texture and a lot of output textures: sum, difference, product, division, min, max, intensity, power and single color channel outputs.
• TexBlend - Blend two input AColor textures using another float texture for weighting (or a constant value, of course).
• TexClamp - Clamp an input texture between some min and max values.
• TexCondition - Switch between two AColor textures depending on some type of comparison between two float textures.
• TexFloatOp - Similar to TexAColorOp for floats.
• TexGradient, TexGradRamp, TexRamp - Gradient textures.
• TexHSVToRGB - Convert HSV input texture to RGB.
• TexInvert - Returns the input texture's complementary color.
• TexLayered - Combine an unlimited number of textures.
• TexLuminance - Returns a single float luminance (0.3R + 0.59G + 0.11B) from input color texture. Note that in V-Ray terms this is different from the "intensity" term, which is (0.33R + 0.33G + 0.33B).
• TexMulti - Similarly to MtlMulti, choose a texture from a list by indexing with face material ID or object ID or randomized.
• TexRaySwitch - Use a different texture for different types of rays: shadow, GI, reflection, refraction and default.
• TexRemap - Remap an input texture color through some kind of user-defined curve.
• TexUserColor and TexUserScalar - Advanced usage with user attributes.

...

• TexChecker - A checkerboard pattern. The two alternating colors are also texturable.
• TexCloth - A weaved cloth pattern (as the one in Autodesk Maya)
• TexCellular - Procedural cellular noise pattern. Different types of cells are supported, including fractal.
• TexCurvature - A value proportional to local curvature at shading point.
• TexDirt - An ambient occlusion effect around concave edges and dents in the geometry (with an inversion option).
• TexDistance - Generates a color gradient according to distance from a specified list of objects.

• TexEdges - Generates wireframe color along polygon edges.

• TexFalloff - Generates a falloff gradient depending on the angle between surface normal and camera view direction or some other axis.

• TexFresnel - Used to generate Fresnel reflection color if you're not using BRDFVRayMtl.

• TexLeather - Procedural leather imitation.
• TexMarble - Procedural marble imitation.
• TexNoise, TexNoiseMax, TexNoiseMaya - Different types of configurable procedural noise.
• TexRock - Procedural stone imitation.
• TexSmoke - Procedural 2d smoke texture.
• TexSnow - Procedural snow imitation. Covers surface in snow color down to some normal vector threshold.
• TexSoftbox - Specialized for use with rectangular lights to simulate real world "softbox" professional lighting.
• TexTiles - Procedural tiles with different layout options.
• TexWater - Procedural wave texture.
• TexWood - Procedural wood imitation.

Finally, the UVW generators:

• UVWGenChannel - Modifier for UVW data coming from the geometry source. Has - Modifier for UVW data coming from the geometry source. The main parameter is uvw_channel - the index of the mapping channel data to use (i.e. GeomStaticMesh::map_channels). The default is 1 as in 3dsMax where indexing starts from 1, but in your application this may be 0 or something else. If you set an index of -1 V-Ray will take the first available channel. This plugin also has transform, wrap and crop parameters as well as the option to get UVW data from another UVWGen plugin.
• UVWGenEnvironment - Used to map spherical, cube, etc. textures on the environment color slot or on dome lights.
• UVWGenExplicit - Define explicit UVW data from a texture.
• UVWGenMayaPlace2dTexture - Similar to UVWGenChannel, but with more options.
• UVWGenObject -
• UVWGenPlanarWorld -

...

• min_shade_rate - Use a value between 6 and 8.
  
  For Adaptive sampler:
• dmc_minSubdivs - Keep at value 1In general, keep at value 1 to avoid unnecessary sampling. There may be some exception cases (such as fog) where 1 is not enough and leads to visual artifacts.
• dmc_maxSubdivs - Start with 24 and increase if noise doesn't go away.
• dmc_threshold - Start with 0.005 and decrease it if increasing dmc_maxSubdivs doesn't help with noise. You could keep it higher like 0.01 of course, if you want fast renders.
  
  Progressive sampler:
• progressive_minSubdivs - Keep at value 1.
• progressive_maxSubdivs - Use between 60 and 100.
• progressive_threshold - Similarly to dmc_threshold, start at 0.005 and reduce if noise persists. Don't go below 0.001.
• progressive_maxTime - This is a render time limit in minutes, so unless you want a safety limit, leave it at 0.

...

You can define environment background, lighting (GI), reflection, refraction colors or textures through the SettingsEnvironment plugin. Usually all slots have the same value. Environment textures use UVWGenEnvironment for spherical, cube etc. mapping.

You can also add scene-wide volumetric effects through the environment_volume list.

...

• 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. 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 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.

...

SettingsRegionsGenerator controls the size and order of generation of buckets in production mode.

• xc and yc - Horizontal and vertical size of the buckets.
• seqtype - The order of generation of new buckets - 0=Top-Bottom; 1=Left-Right; 2=Checker; 3=Spiral; 4=Triangulation; 5=Hilbert curve
• dynbuckets - This is enabled by default. It lets V-Ray create smaller buckets toward the end of the rendering to improve load balancing. Set to 0 if you want your buckets to always have the same size.

...

• gi_dontRenderImage - Set to 1 if you're baking a GI prepass 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.

...

If you want to enable motion blur, set the SettingsMotionBlur plugin on parameter to 1. It also has parameters the geom_samples parameter that affect quality, but may cost a lot of render time if increased - geom_samples and subdivs.

The SettingsLightLinker plugin allows you to define include or exclude lists for lights and objects, so that for example specific lights do not affect some objects etc. Refer to the plugin parameter metadata for explanations.

...