Page History

...

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

...

The following are the types recognized in a V-Ray scene (think .vrscene file). They have corresponding types in the different AppSDK App SDK 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 App SDK are IntList, FloatList, ColorList, VectorList, TransformList and VectorList PluginList.
• Generic heterogeneous lists: The In C++, the App SDK uses a generic type class called Value for items in a generic list. In C#, Python and Node.js, native language types are used (lists or arrays). 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).
  In App SDK output parameters are represented by the PluginRef type which combines a plugin reference and an output name.

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.

...

Apart from documentation included with the App SDK and SDK and this guide, the help pages for 3dsMax and Maya on docs.chaosgroupchaos.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.

1.7. "subdivs" parameters

1.7. "subdivs" parameters

You will see subdivs (subdivisions) parameters on many light and BRDF plugins. They control the number of new rays spawned for You will see subdivs (subdivisions) parameters on many light and BRDF plugins. They control the number of new rays spawned for calculating glossy and diffuse effects on materials or the number of light and shadow evaluations and so on. The number of actual rays is proportional to the square of the parameter value. These can be used to increase or decrease sampling for the respective light or material, but we highly recommend leaving these at default values. We also recommend disabling local subdivs values altogether - see the DMC sampler section for details. Some of the settings plugins also have subdivs parameters which are ok to change, like the Irradiance Map and Light Cache for example.

Note: The reason the renderer uses the square of the parameter value is the property of the Monte Carlo integration method that to reduce noise (variance) by half (1/2 noise), you need four times as many samples (4x), to get 1/10 the variance you need 100x more samples... This way we get linear results from linear increases in the subdivs parameters.

2. Defining camera position

One of the first things you'd want to do is control your camera. This is done through the RenderView plugin. You will always want to create and setup this plugin, exactly one, in your scenes. (The exception is when you are baking textures - then you'd use BakeView.)

...

• fov - The horizontal field of view in radians.
• orthographic - Enable to have orthographic projection instead of perspective .(RenderView::fov doesn’t matter in this case, in favor of RenderView::orthographicWidth).
• transform - A transformation (rotation + transform - A transformation (rotation + translation) which defines where the camera is and how it is rotated. The matrix is in column-major format and you will need to calculate it yourself. You can't set rotation angles as in most 3D software. The default camera orientation with identity matrix is so that +Y is pointing up and -Z is the view direction. If your scene uses +Y for up-axis, you will need to set V-Ray's scene up-axis accordingly - see the Units subsection in the settings section below.

For advanced camera effects, such as DoF, exposure, distortion, vignetting, etc. you will need to enable the physical camera in addition to RenderView. See the Physical camera subsection in the settings section below for details. You can also use SettingsCameraDof instead, if you only need depth of field (see 6.11. Miscellaneous).

3. Creating lights

Good lighting is the most important thing for getting good photorealistic renders. It also affects image noise and performance. Some lights (generally the simpler ones, especially the first four in the list) render faster and with less noise than others. Things that may affect noise and performance of lights are: having a texture instead of flat color; having a complex mesh; being an area light with small relative size.

...

• 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. This corresponds to VRayFur in 3dsMax and Maya.
• 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.

4.3. Instancing

...

Instancer and Instancer2 plugins can be used to efficiently instantiate a high number of objects in the scene from other geom source plugins. Often used for particles and vegetation.

• Instancer => N * Node (invisible) => GeomSomething

Instncer2 is also a geometry source and can be connected to a Node plugin:

• Node => Instancer2 => N * Node (invisible) -> GeomSomething
  
  and even
  
  
• Node => Instancer2 => Nodes => Instancer2 => etc.

5. Creating materials

Exporting materials is probably the most complicated part, because it may involve complex shader networks, especially in apps with high artistic control, such as the popular DCC tools from Autodesk. Nevertheless, you can get good results even by using only a few plugins.

...

• MtlSingleBRDF - The main material type that needs to be connected to Node::material.
• Mtl2Sided - Defines a (possibly different) material for the back side of triangles, as well as the front sides.
• MtlMulti - Use this together with GeomStaticMesh::face_mtlIDs to set different materials for subsets of triangles on one geometric object.
• MtlVRmat - Load a V-Ray shader from a .vrmat (formerly .vismat) file. Also supports loading MtlSingleBRDF materials from vrscene files. This is used for transferring materials between different host applications.
• MtlGLSL - Loads a GLSL shader from file and provides some parameters for it.
• MtlOSL - Loads an OSL shader from file and provides some parameters for it.
• MtlRoundEdges - Smooths sharp edges within a given radius by modifying normals.

Some advanced materials:

...

• BRDFVRayMtl - The one BRDF plugin to rule them all. Combines all of the following except Cook-Torrance (not all at the same time - you choose a type). This is the preferred choice for most cases.

  Info
  See VRayMtl page for info on the different BRDF types.

• BRDFBlinn - The Blinn BRDF model for glossy highlights. See See Wikipedia article.
• BRDFCookTorrance - The Cook-Torrance BRDF model for glossy highlights. See Wikipedia.
• BRDFGGX - The new GGX (microfacet GTR) BRDF model for glossy highlights.
• BRDFPhong - The Phong BRDF model for glossy highlights. See Wikipedia article.
• BRDFWard - The Ward BRDF model for glossy highlights. See Wikipedia.
• BRDFDiffuse - A basic diffuse BRDF.
• BRDFGlass - A basic refractive BRDF.
• BRDFGlassGlossy - An extension of BRDFGlass that enables glossy refraction, meaning that rays with equal incoming angle refract at slightly different angles.
• BRDFLight - Self-illumination BRDF. Consider using LightMesh instead.
• BRDFMirror - A basic specular reflection BRDF.
  
  
• BRDFLayered - A weighted combination of any number of BRDF plugins. (This is also known as Blend material in the UI of V-Ray for 3dsMax and Maya.)

...

A general note on settings plugins: when you create a new Renderer object there are no instances of them, so you will need to create them before changing parameters. If you start rendering the AppSDK App SDK will create a SettingsOutput and if the render mode is RT it will create SettingsRTEngine. On the other hand, if you're loading a scene from file, it will have instances of most (but not all) settings plugins and you need to use them. This is because every time V-Ray exports a vrscene file it automatically writes out the settings even if they are at default values.

...

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 App SDK has APIs for setting image and region size (i.e. renderer.setRenderRegion, depends on language).

...

...

• min_shade_rate - Use a value between 6 and 8.
  
  For Adaptive sampler:
• dmc_minSubdivs - In 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.
  dmc_adaptive_method - We recommend you enable this (the default is 0 for the legacy sampler) to use the improved sampling algorithm that samples the image according to noise, leading to an even noise distribution per unit of render time.
  
  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.

...

• FilterBox - All samples within a box with sides 2*size are taken with equal weight.
• FilterArea - All samples within a circle with radius size are taken with equal weight.
• FilterTriangle - Sample weight falls off as a triangular function of off-center distance.
• FilterGaussian - The classical blur filter.
• FilterSinc - Less blurry low-pass filter. See Wikipedia.
• FilterLanczos (currently default in V-Ray for 3dsMax and Maya) - See Wikipedia.
• FilterCatmullRom - A cubic edge-enhancing filter.
• FilterCookVariable
• FilterMitNet - Mitchell-Netravali cubic filter with subjectively optimized compromise of blurring and detail in the additional blur and ringing parameters which correspond to B and C from the original paper.

To apply a filter, just create an instance of one of those plugins. You can use only one at a time.

...

We recommend leaving the parameters of SettingsDMCSampler at their default values, with the exception of use_local_subdivs. Set this to 0, so that only the global subdivs settings are used.

6.4. Global illumination

...

The Irradiance map is configured through SettingsIrradianceMap.

...

The Light cache is configured through SettingsLightCache.

...

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

A special case is the Sun-Sky system. V-Ray has a special procedural texture, TexSky, for these environment slots that is coupled with SunLight. The color of the environment depends on the position of the Sun.

...

• type - 0=still camera, 1=movie camera, 2=video camera   camera   Some parameters only apply for one of these types, because of the different types of shutter mechanism.
• fov - To use the value set here, also set specify_fov=1. Otherwise the fov from SettingsCamera and RenderView is used.
• vignetting - Note that the default value is 1.0. You may want to set to 0.0 to have a uniformly exposed frame.
• white_balance - This color tint may be counter-intuitive. If you set it to blue, you'll get a warm image and so on.
• blades_enable - Set to true to enable bokeh effects.
• bmpaperture_enable - Set to 1 to use the bmpaperture_tex texture.
• use_dof - Disabled by default. Set to 1 for ray-traced DoF. Note that just like in DSLRs the depth of the in-focus field depends on aperture and focus distance.
• use_moblur - Disabled by default. Set to 1 to enable camera motion blur.
• distortion_type - 0=quadratic, 1=cubic, 2=lens file from lens_file parameter; 3=texture from distortion_tex parameter

...

The default values when you create a SettingsColorMapping plugin are different from the recommended values in 3dsMax and Maya for legacy reasons. These are the values you should use for new scenes:

• type=6     // 6=Reinhard mapping (plugin default is 0=linear)
• dark_mult=1   // don't change dark colors additionally
• bright_mult=1   // don't change bright colors additionally
• gamma=2.2   // close to sRGB (plugin default is 1.0)
• subpixel_mapping=0
• clamp_output=0
• clamp_level=1
• adaptation_only=2   // 2=only apply color mapping (plugin default is 0=apply both color mapping and gamma)
• linearWorkflow=0   // this is important - this option exists only for legacy scenes

...

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

If you save the rendered image from the VFB and not from an AppSDK App SDK API, the corresponding Settings{JPEG|PNG|EXR|TIFF} plugin controls compression quality and bits per channel. You may need to change these according to your needs.

If you want to enable motion blur, set the SettingsMotionBlur plugin on parameter to 1. It also has the geom_samples parameter that affect quality, but may cost a lot of render time if increased. It should equal the number of geometry samples in the geometry data if it is non-static. Note that this plugin (SettingsMotionBlur) conflicts with CameraPhysical.

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.

SettingsCaustics can enable improved rendering of caustic effects with photon mapping. This also requires setting some material parameters to make it work.

If you are not using CameraPhysical for depth of field, you can use SettingsCameraDof instead. Note that this plugin (SettingsCameraDof) conflicts with CameraPhysical.

• on - Set to true to enable DoF.
• aperture - The size of the camera aperture in scene units. Note that increasing this number corresponds to decreasing the physical camera's F-number.
• focal_dist - Distance from the camera to the focus plane in scene units.

7. Minimal renderable scene

This is a diagram of the most simple possible scene that will render an object. These are the plugins and parameters you will need to create and set.

Image Removed

A. Brief plugin reference

This reference does not list all of V-Ray's plugins, but most users will rarely need the ones that are not mentioned here.

Also only some of the parameters are explained here. As a general rule, follow the advice in Debugging and help when looking for info on plugins.

A.1. Common plugins

Light plugins (see also section 3 above)

LightOmni

• decay - The exponent for intensity decay. Default value is 2.0 which corresponds to the inverse square law.

LightSpot

• coneAngle - Full cone angle in radians.
• penumbraAngle - The size of an additional partly lit area around the cone in radians. If negative it's inside the cone.
• dropOff - Attenuation proportional to off-axis angle. Larger values dim the light toward the wide angles of the cone.
• falloffType - The type of transition in the penumbra region. 0 - linear; 1 - smooth cubic
• decay - The exponent for intensity decay. Default value is 2.0 which corresponds to the inverse square law.

LightRectangle

The .vrscene can store multiple cameras, where only one can be set as ‘renderable’ at a time. The rest of the cameras can be chosen for rendering, for example in V-Ray Standalone, by using the -camera command flag. This is useful, as oftentimes a project requires rendering different sequences from different cameras, while nothing else changes in the scene - a simple example would be to render two different views of the same visualization and in this way, the same scene can be rendered twice with V-Ray Standalone. An example scene with two cameras would have one them to render by default while the other will have dont_affect_settings flag raised.

In shading setups, textures can be projected from cameras. This can either be the same camera used for rendering, or another camera in the scene, used only for projecting a texture. In both cases, an extra SettingsCamera and RenderView plugin is exported for the camera projection with the dont_affect_settings flag raised. This is similar to the Multiple Cameras setup. In all cases, it’s a good idea to export one camera for rendering, and another one for the texture projection, even if it’s the same camera, as different properties apply for each.

7. Minimal renderable scene

This is a diagram of the most simple possible scene that will render an object. These are the plugins and parameters you will need to create and set.

Image Added

...

A. Brief plugin reference

This reference does not list all of V-Ray's plugins, but most users will rarely need the ones that are not mentioned here.

Also only some of the parameters are explained here. As a general rule, follow the advice in Debugging and help when looking for info on plugins.

A.1. Common plugins

Light plugins (see also section 3 above)

LightOmni

• decay - The exponent for intensity decay. Default value is 2.0 which corresponds to the inverse square law.

LightSpot

• coneAngle - Full cone angle in radians.
• penumbraAngle - The size of an additional partly lit area around the cone in radians. If negative it's inside the cone.
• dropOff - Attenuation proportional to off-axis angle. Larger values dim the light toward the wide angles of the cone.
• falloffType - The type of transition in the penumbra region. 0 - linear; 1 - smooth cubic
• decay - The exponent for intensity decay. Default value is 2.0 which corresponds to the inverse square law.

LightRectangle

• noDecay - If set to true, light intensity will not fall off with distance. By default the inverse square law applies.
• doubleSided - Whether to emit light from the back sides of the rectangle.
• u_size - Width of the light in scene units.
• v_size - Length of the light in scene units.
• directional - Larger values make the light more concentrated along the +W axis in local UVW space.
• is_disc - True to round the rectangle to a disc (ellipse).
• rect_tex - A texture plugin to map onto the rectangle for light color.
• use_rect_tex - You also have to set this to true to actually use the rect_tex parameter.
• tex_resolution - The texture is actually
• noDecay - If set to true, light intensity will not fall off with distance. By default the inverse square law applies.
• doubleSided - Whether to emit light from the back sides of the rectangle.
• u_size - Width of the light in scene units.
• v_size - Length of the light in scene units.
• directional - Larger values make the light more concentrated along the +W axis in local UVW space.
• is_disc - True to round the rectangle to a disc (ellipse).
• rect_tex - A texture plugin to map onto the rectangle for light color.
• use_rect_tex - You also have to set this to true to actually use the rect_tex parameter.
• tex_resolution - The texture is actually resampled at this resolution. The default is 512, so even if you have a high resolution image, it may look pixelated if you don't increase this. This will consume more memory.

...

• transform - Similarly to the direct light plugin, the position doesn't matter as the light comes from infinity. The rotation matrix has to be set correctly, even though in theory the Sun is omnidirectional. The identity matrix results in light directed along the -Z axis, thus a noon Sun.
• target_transform - Currently doesn't make a difference. Don't leave uninitialized - set an identity transform.
• turbidity - See See VRaySun
• ozone - See VRaySunSee VRaySun
• water_vapour - See VRaySunSee VRaySun
• size_multiplier - See VRaySunSee VRaySun
• color_mode - See VRaySunSee VRaySun. Values  Values are 0, 1, 2 respectively for Filter, Direct, Override mode.
• intensity_multiplier - Relative intensity of the Sun (default 1.0). Try setting correct scales in SettingsUnitsInfo first.
• filter_color - Force a color tint. It's probably better to leave this white. See also the color_mode parameter.
• ground_albedo - Sky parameter, unused if there is no sky attached. Account for light reflected off an imaginary ground and scattered back in the sky. Default is (0.2, 0.2, 0.2).
• horiz_illum - Sky parameter, unused if there is no sky attached. Specifies the intensity (in lx) of the illumination on horizontal surfaces coming from the sky if sky_model is 1 or 2.
• sky_model - Sky parameter, unused if there is no sky attached. Selects the mathematical model approximating sky illumination. Values: 0=Preetham et al; 1=CIE Clear; 2=CIE Overcast; 3=Hosek et al.
• up_vector - Set to (0.0, 1.0, 0.0) if your scene up-axis is +Y to have correct lighting.
• invisible - Makes the Sun invisible to the camera and in reflections.

...

• mesh - The base mesh, usually a GeomStaticMesh.
• static_displacement - If set to true, the new generated triangles will be saved in the static rayserver tree. This will increase memory usage.
• use_globals - Whether to use the global settings from SettingsDefaultDisplacement. Default is true.
• view_dep - If use_globals is false, whether the amount of tesselation is view-dependent. The global default is true.
• edge_length - If the view-dependent option is on (globally or locally), this is the target edge size of the generated triangles in pixels. Otherwise it is in scene units.
• max_subdivs - If use_globals is false, the maximum number of triangle subdivisions for one original triangle of this mesh.
  For the rest of the parameters refer to VRayDisplacementMod.
• displacement_tex_color
• displacement_tex_float
• displacement_amount
• displacement_shift
• keep_continuity
• map_channel
• object_space_displacement
• use_bounds
• min_bound
• max_bound
• resolution
• precision

GeomHair

• TODO

GeomMeshFile

• file - Path to the vrmesh or abc file to load.
• object_path - When using Alembic, the starting object path string.

Material and BRDF plugins

MtlSingleBRDF

• TODO

Mtl2Sided

• TODO

MtlMulti

• TODO

MtlVRmat

• TODO

MtlGLSL

• TODO

MtlOSL

• TODO

MtlRoundEdges

• TODO

MtlMaterialID

• TODO

MtlOverride

• TODO

MtlRenderStats

• TODO

MtlWrapper

• TODO

BRDFVRayMtl

• TODO

BRDFBlinn

• TODO

BRDFCookTorrance

• TODO

BRDFGGX

• TODO

BRDFPhong

• TODO

BRDFWard

• TODO

BRDFDiffuse

• TODO

BRDFGlass

• TODO

BRDFGlassGlossy

• TODO

BRDFLight

• TODO

BRDFMirror

• TODO

BRDFCarPaint

• TODO

BRDFFlakes

• TODO

BRDFHair3

• TODO

BRDFLayered

• TODO

BRDFSSS2

• TODO

BRDFSSS2Complex

• TODO

BRDFScanned

• TODO

BRDFSkinComplex

• TODO

BRDFStochasticFlakes

• TODO

BRDFBump

• TODO

BRDFMultiBump

• TODO

• number of triangle subdivisions for one original triangle of this mesh.
  For the rest of the parameters refer to VRayDisplacementMod.
• displacement_tex_color
• displacement_tex_float
• displacement_amount
• displacement_shift
• keep_continuity
• map_channel
• object_space_displacement
• use_bounds
• min_bound
• max_bound
• resolution
• precision

GeomHair

• TODO

GeomMeshFile

• file - Path to the vrmesh or abc file to load.
• object_path - When using Alembic, the starting object path string.

Textures and UVWGenerators

...

VRayClipper

Volumetric plugins

...

The information from this page is also available at User Guide V-Ray Application SDK.