Introduction
In this chapter we'll cover the main settings plugins in V-Ray. These include SettingsOutput, SettingsRTEngine, SettingsUnitsInfo, SettingsDMCSampler, SettingsDR, SettingsImageSampler, SettingsDMCGI, SettingsIrradianceMap, SettingsLightCache and SettingsColorMapping.
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 will create a SettingsOutput and if the render mode is Interactive 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.
Starting with version 1.09 nightly builds after June 14th 2016, the VRayRenderer class includes the method setImprovedDefaultSettings(). It creates (if necessary) some settings plugin instances and sets several parameters to values different from the plugin defaults. These values match the defaults used in our main products, such as V-Ray for 3dsMax and Maya. The plugin defaults couldn't be changed for compatibility reasons (keep old scenes working as they were). But the UI default values have changed over time. Many of the parameters and respective values that are set by setImprovedDefaultSettings() are mentioned in the paragraphs below. These are just good initial values. Feel free to use them or not, or to overwrite some of them, for example reducing quality to get faster renders.
Image and region size
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).
Image sampling and filtering
V-Ray has several types of image samplers. These are algorithms that determine how many samples to take for each pixel. This is combined with an image filter, which can soften or sharpen the final image.
The image sampler is controlled from SettingsImageSampler. These are the four types for its type parameter:
- type=0, Fixed sampler - It simply uses a fixed number of samples for each pixel. This is controlled by the fixed_subdivs parameter. This sampler type is not recommended.
- type=1, Adaptive sampler
- type=2, Adaptive subdivision sampler. This sampler type is deprecated.
- type=3, Progressive sampler
The progressive sampler produces whole images iteratively, refining them with each pass. The other samplers work on small "buckets" and only return an image when it is complete.
Some of the default values when you create (or if you don't) the SettingsImageSampler plugin are not optimal. They are currently kept for compatibility reasons. Here are some guidelines for changing them:
- 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.
Filters
Most filters have just one size parameter for the kernel radius. Catmull-Rom has no parameters. The available filter plugins are:
- 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. Note: We already covered filters in the topic "Antialiasing Filters".
DMC sampler
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.
Global illumination
By default global illumination (GI) is disabled in an empty scene (with the exception of GPU mode where you can't disable GI). You need to set SettingsGI::on to 1 to enable tracing of secondary rays. Any photorealistic render needs GI, so apart from some kind of debugging, you will always want to enable GI.
Other SettingsGI parameters of interest are:
- primary_engine - The primary GI bounce engine. We don't recommend using Photon Map for either primary or secondary. The possible values are 0=Irradiance Map, 1=Photon Map, 2=Brute Force, 3=Light Cache.
- secondary_engine - The secondary bounce GI engine. The possible values are the same as for primary engine, with the exception of Irradiance Map - if you set this to 0 it will disable secondary bounces.
- ao_on, ao_amount, ao_radius - Keep in mind that ambient occlusion (AO) is not a physically correct/accurate way to get shadows. If you enable ambient occlusion with ao_on, ao_amount is a multiplier for the strength of the effect between 0.0 and 1.0 and ao_radius defines the hemisphere that is evaluated for occlusion.
We don't recommend changing the contrast and saturation parameters.
The choice of GI engines and their parameters is paramount, especially for interiors where most of the illumination is indirect. Bad choices can lead to too much noise or artifacts and/or disproportionate render time for certain image quality. The common setup for interiors is Irradiance Map with Light Cache secondary and for exterior scenes it is often Brute Force primary with BF or LC secondary.
Brute force
The settings for Brute force are in SettingsDMCGI. There are only two parameters:
- subdivs - Controls the number of new rays spawned at each intersection point. We recommend using the default value.
- depth - The number of secondary bounces to trace before stopping. Larger values may increase the brightness of indirect illumination at the cost of render time. The default is 3.
Irradiance map
The Irradiance map is configured through SettingsIrradianceMap.
The main two parameters are:
- subdivs - The default is 50. Higher values can fix spot-like artifacts and lower values should improve render times.
- interp_samples - The default is 20. Setting a lower value may help if surfaces seem too blurry.
Light cache
The Light cache is configured through SettingsLightCache.
There are a lot of parameters for fine tuning and fixing specific problems but the main parameter is:
- subdivs - The default is 1000. Higher values can fix spot-like artifacts and lower values should improve render times.
Environment
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.
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.
TexSky takes its parameters from SunLight if TexSky::sun is set. You can also use a TexSky without a Sun. For parameter details see the reference section at the bottom.
Units (scale)
Some calculations in V-Ray based on physics require accurate scaling of scene units to real world units like meters, Watts, seconds, etc. This is controlled through the SettingsUnitsInfo plugin with the properties listed below. This affects the physical camera, IES lights, volumetric effects, etc.
- meters_scale - Multiplying scene sizes by this value should yield object sizes in meters.
- photometric_scale - Scale for photometric lights.
- seconds_scale - When doing animation, this is the reciprocal of the framerate
- scene_upDir - This needs to be set if the scene has an up-axis different from the default, which is +Z.
- rgb_color_space - Affects Sun/Sky color, color temperatures and dispersion in refractive materials.
Physical camera
Although the name doesn't hint at it, the CameraPhysical plugin is a settings plugin (singleton). It modifies the way camera rays are shot for effects like DoF (depth of field) and distortion and how they are integrated into the image - exposure. The position and orientation of the camera is still defined by RenderView. Many of the parameters are exactly the same as on a real world DSLR or video/movie camera.
We will only add a few things here:
- type - 0=still camera, 1=movie camera, 2=video 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
Color mapping
This is controlled by SettingsColorMapping.
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
Linear workflow
In order for V-Ray to perform mathematically correct calculations, input and output color data should be linear. The results should only be converted to a non-linear color space (such as sRGB) for display. This is called linear workflow.
For proper linear workflow, you need to set the SettingsColorMapping parameters gamma, adaptation_only and linearWorkflow to the values listed above. The parameter linearWorkflow is intended only for compatiblity with old vrscene files and should not be set to 1, despite its misleading name.
By default the VFB (V-Ray Frame Buffer) has its sRGB option enabled, so you will see the original linear image with sRGB applied as a post-process. The actual files you save from the VFB or with VRayRenderer::VFB::saveImage() will be linear like the actual data if saved in a floating point format like EXR or VRIMG. On the other hand, most 8/16-bit integer formats implicitly save their data gamma-encoded (e.g. JPEG applies ~2.2 gamma for dynamic range compression. Applications that read JPEG handle that and display the data in the required color space, gamma-encoded or linear). Saving to such integer file formats with saveImage() or from the VFB button also bakes any color corrections done in the VFB, including the sRGB conversion. So these files will look exactly like you see them in the VFB. This does not apply to EXR and VRIMG.
Bitmaps
There is one more place to control color mapping - BitmapBuffer - for texture file assets. It has two parameters for converting the image file colors - gamma and color_space. The gamma parameter is considered only when color_space=1 and makes texture reads apply inverse gamma to decode gamma-compressed values to linear. Most integer formats will require setting color_space=1 and gamma=0.454545. When color_space=2, sRGB decoding is performed (similar, but not identical to color_space=1 & gamma=0.4545).
Stereo and panorama rendering
For spherical panorama rendering you need to:
- Change the
typeparameter of SettingsCamera to 9. (Note thattype=1is spherical, but not for panoramas.) - Set the field of view to 360 degrees or rather 2pi, because the fov parameter is in radians. You need to do this with the *RenderView plugin and with SettingsCamera - both have an fov parameter. Also if you're using CameraPhysical with
specify_fov=1, set fov there too. - Set the vertical field of view to 180 degrees. This may be a bit confusing: it is set through the height parameter of SettingsCamera. Also the value is not in radians, but in degrees.
For cubic (6x1) panorama rendering you need to:
- Change the type parameter of SettingsCamera to 10.
- Set a resolution with aspect ratio 6:1 (or 12:1 if you are doing stereo). So for a stereo cubic panorama with 1000x1000 pixel cube sides you will render at 12000x1000.
For stereo rendering:
- For CPU (Production or Interactive) rendering you need to create a VRayStereoscopicSettings plugin. It has to be created after SettingsCamera and SettingsOutput or it won't work! It's recommended to change the
VRayStereoscopicSettings::focus_methodparameter to 1 for panorama or 2 for normal camera. - For GPU rendering you need to set
RenderView::stereo_onto 1. You might also want to setRenderView::stereo_eye_distanceto something like 6.5 (average human), instead of the default 1.0. It's recommended to change theRenderView::stereo_focus_methodparameter to 1 for panorama or 2 for normal camera.
Also remember to set a double horizontal resolution for stereo. So if your normal render resolution is 640x480, make that 1280x480. The left half of the image will be the left eye view and the right half is the right eye.
RT Engine (Interactive engine)
If your renderer object was created with Interactive or Interactive GPU mode parameter, you can control Interactive-specific parameters with SettingsRTEngine. Note that GI is always enabled when rendering on the GPU and cannot be disabled. Also note that the parameters starting with "opencl" are valid both for OpenCL and CUDA modes.
- 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 set above 0, start rendering at 1/(2^undersampling) resolution. So for example if the value is 4, sampling will start at 1/16 of the original resolution. When one pass is made at this resolution, the resolution is doubled and this repeats until the full resolution is reached. In our example this will return images sampled at 1:16 resolution and then 1:8, 1:4 and 1:2 (The images have the full resolution, but values are repeated for pixels that haven't been sampled). 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 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.
The render stops when any one of max_sample_level, max_render_time or noise_threshold is reached. If all are zero, the sampling goes on indefinitely.