0. Who this is for

These guidelines are for users of the AppSDK who want to use it to create a scene for rendering with V-Ray from the data in their host application scene. We will not discuss details on how to write code with the AppSDK here - there are separate docs for this. Rather we will cover what V-Ray plugins to add to the scene, how to link them and what parameters to set.
Note: This document will be updated and extended over time.

1. Introduction

1.1. A note on terminology

• plugin: We use the term plugin a lot. Technically it could mean a plugin DLL for V-Ray (even V-Ray itself is a kind of plugin) or the type defined in it, which is for example a class in the programming sense, or finally an instance of this class which resides in memory and can be saved to a scene file. We will be using the term plugin to refer to plugin instances.
• exporter/translator: We call the piece of software that translates some native scene format to the V-Ray scene format an exporter or a translator, interchangeably. Basically what it does is creating a bunch of V-Ray plugins and setting their parameters. Note that we also use the verb "to export" sometimes in reference to the act of saving out the scene (which was already translated) to a *.vrscene file.

1.2. V-Ray scene contents

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

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, Matrix (3 Vectors), Transform (a Matrix and a Vector for translation)
• Objects: references to other plugin instances
• 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.

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.

1.4. V-Ray scene file format

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 main rules are:

• Each plugin instance is defined on a new line starting with its type name follow 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 our 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.

1.5. Default values

Every parameter has a default value, so even after you create an "empty" plugin instance it is actually fully functional. Of course it might need data, as for example with geometry plugins, but a light will work right away (placed at 0 coordinates). That being said, some plugins have inconvenient default values, which almost always need to be changed (for example some settings plugins, such as the image sampler settings or some shadow parameters). We usually can't fix the defaults, because it would break existing user scenes. Nevertheless, unless you know what you're doing, it is recommended to stick to the default values. You are free to experiment, of course, but don't use values which you don't understand as they may have performance implications or quality implications or they may even break physical plausibility.
Note that when you export (save) a vrscene file it will always contain a bunch of settings plugins, even if you didn't create them. They will have default parameter values. This is how V-Ray always saves files.

1.6. Debugging and help

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.
Another thing to watch out for is V-Ray's errors and warnings, so always implement the DumpMessage callback.

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

The main parameters are:

• fov - The vertical field of view in radians.
• orthographic - Enable to have orthographic projection instead of perspective.
• 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 +Z is pointing up and +Y 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 etc. you will need to enable the physical camera. See the Physical camera subsection in the settings section below for details.

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. Listed below are V-Ray's light plugins, ordered roughly by increasing photorealism. Common parameters are at the end and some specific parameters are described in the Reference at the end of this document. There are even more parameters that we will not mention here.

• LightAmbient - Do not use this one. Ambient lighting is a fake effect.
• LightOmni - A point light source. Has parameters for the rate of decay and casting soft shadows (shadowRadius below).
• LightDirect - Infinite parallel light. Does not originate from its position, so only the rotation matrix matters.
• LightSpot - Conical spot light, such as the light coming from a flashlight.
• LightRectangle - Rectangular area light. Option for rounding to a disc shape. Can be textured.
• LightSphere - Spherical area light. The geometric detail is parametrized by number of segments.
• LightMesh - Turn a geometry plugin into a light source. Can be textured.
• LightDome - A light emitting dome encompassing the scene at infinity. Usually used for HDR image based lighting (IBL) with a spherical texture file.
• LightIES - Measured real world lights defined through an .IES file. Shape can be overriden.
• SunLight - Mathematically approximated model of our Sun. The light varies according to its elevation. Usually coupled with a TexSky environment texture. See the Environment settings section below for details.

Some of these plugins have versions from 3dsMax with additional parameters, such as LightOmniMax, LightSpotMax etc.

Common light parameters:

• enabled - Enabled by default. Use to turn lights on/off without having to recreate and reset parameters.
• transform - Position and orientation. See notes on camera position above. Some lights can also be scaled.
• color - The color of emitted light. Default is white (1.0, 1.0, 1.0). The value can be above 1 for larger intensity, but most lights have a separate intensity parameter for this. Some lights such as rectangular and mesh lights can have textured color through additional parameters. For example you can make a stained glass window this way. The Sun light doesn't have this parameter, but it has others for color control.
• shadows - Enabled by default. Set to false to cast no shadows. Not recommended.

Other parameters common to many, but not all of the lights (check respective parameter lists):

• shadowRadius - Can be used to make simple light sources like omni, spot, direct behave as area lights, casting soft shadows.
• intensity (intensity_tex) - Multiplier for the intensity of the light.
• invisible - False by default. Enable to make the area light invisible to the camera. This includes the back side of rectangle lights for example.
• units - Physical units for the intensity of photometric lights. Possible values are: 0 - default, 1 - lumens, 2 - lm/m/m/sr, 3 - Watts, 4 - W/m/m/sr

4. Creating geometry

4.1. The Node plugin

Before we get to defining your actual geometry data, there is a top-level plugin for non-light-emitting objects called Node. It links the geometry data (geometry parameter) with a material plugin (material parameter) and positions it in the world (transform parameter). You could reference the same geometry in different nodes with different positions.

4.2. Geometry sources

V-Ray works 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.

Lets look at the main geometry source plugins (we will ignore some others):

• GeomStaticMesh - The basic fixed geometry descriptor that you will use in most cases. Requires vertex and normal data plus optional UVW texture mapping coordinates.
• 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.

4.3. Instancing

TODO: Instancer, Instancer2

5. Creating materials

5.1. Material and BRDF plugins

5.2. Textures and UVW generators

6. Scene and render settings

6.1. Image and region size

6.2. Image sampling and filtering

6.3. Global illumination

6.4. Environment

6.5. Units (scale)

6.6. Physical camera

6.7. Color mapping

6.8. Stereo rendering

6.9. Miscellaneous

6.10. RT Engine

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.

A. Brief plugin reference

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

LightSphere

• noDecay - If set to true, light intensity will not fall off with distance. By default the inverse square law applies.
• radius - Radius of the generated sphere in scene units.
• sphere_segments - Number of flat segments composing the sphere. Increase from the default 20 if you want a smoother shape.

LightMesh

• 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 triangles.
• geometry - A geometry plugin that will define the shape of the light. Note that complex geometries may make mesh lights slower and noisier.
• tex - A texture plugin to map onto the geometry for light color. This requires that the geometry plugin has valid UV data.
• use_tex - You also have to set this to true to actually use the tex parameter.
• tex_resolution - The texture is actually resampled at this resolution. The default is 256, so even if you have a high resolution image, it may look pixelated if you don't increase this. This will consume more memory.

LightDome

• dome_spherical - Set to true to extend the dome to a full sphere. By default it is only a half-dome centered at the scene zenith. SettingsUnitsInfo::scene_upDir needs to be properly set.
• dome_tex - A texture plugin to use for IBL. Note that this usually requires spherical mapping.
• use_dome_tex - You also have to set this to true to use the dome_tex.
• 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.

LightIES

• ies_file - Path to the file describing the light source
• filter_color - Use to tint the light. The default is white (1.0, 1.0, 1.0). Light color is defined by color temperature in the IES file.
• soft_shadows - Set to 0 (default) to cast hard shadows as point light; 1 to use the shape of the light for shadows; 2 to also use the shape for illumination
• power - Overrides the power specified in the file if > 0. The unit is lumens.
• ies_light_shape - Overrides the shape in the file if set to >= 0. Possible enumerated values: see table below.
• ies_light_width - Used if ies_light_shape override is on.
• ies_light_length - Used if ies_light_shape override is on.
• ies_light_height - Used if ies_light_shape override is on.

• ies_light_diameter - Used if ies_light_shape override is on.

  shape	width	length	height	diameter
  0=point	0	0	0	0
  1=rectangle	>= 0	>= 0	0	0
  2=circle	0	0	0	< 0
  3=sphere	0	0	0	< 0
  4=vertical cylinder	0	0	> 0	< 0
  5=horizontal cylinder (length)	0	> 0	0	< 0
  6=horizontal cylinder (width)	> 0	0	0	< 0
  7=ellipse (length)	< 0	> 0	0	0
  8=ellipse (width)	> 0	< 0	0	0
  9=ellipsoid (length)	< 0	> 0	< 0	0
  10=ellipsoid (width)	> 0	< 0	< 0	0

SunLight

• 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 VRaySun
• ozone - See VRaySun
• water_vapour - See VRaySun
• size_multiplier - See VRaySun
• color_mode - See VRaySun. 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.

Geometry plugins

Node

• transform - World transformation applied to the geometry vertices which are defined in object space.
• geometry - Reference to a geometry source plugin, such as GeomStaticMesh for example.
• material - Reference to a material plugin. This should almost always be a MtlSingleBRDF.
• visible - Set to false to disable the object. It will not be included in the raytracing intersection tree.

GeomStaticMesh

• vertices - VectorList with the vertex coordinates in object space.
• faces - IntList with indices in the vertices array. Every three indices make a triangle. The same vertex index may be used multiple times (for the different triangles it is part of).
• normals - VectorList with normal vectors in object space. These can have a different count from vertices.
• faceNormals - IntList with indices in the normals array. Every index defines the normal for the corresponding vertex in the faces array.
• map_channels - An optional list of lists, where each inner list is generic and has three elements. The first element is the channel index (usually starting from 1), followed by a VectorList with UVW coordinates (leave W at 0.0 when you're only mapping 2D). The third element is an IntList with indices in the UVW array. Each index corresponds to a vertex defined in the faces array.
• map_channels_names - An optional list of strings with names for the corresponding elements of the map_channels list.
• face_mtlIDs - An optional IntList with material indices for each triangle. The number of indices is equal to the length of the faces array divided by 3.
• dynamic_geometry - If set to true, the geometry will not become part of the static intersection tree. Only its bounding box will be used and if that's intersected a separate local tree will be intersected. This may boost performance for real-time rendering of moving objects.

GeomStaticNURBS

• cvs - List of lists of Vectors. Each inner lists contains the control vertices for one NURBS
• weights - Lists of lists of floats with weights for each CV in the corresponding cvs list.
• uKnots - List of floats with knot values in the U direction.
• vKnots - List of floats with knot values in the V direction.
• generateStatic - Set to true to generate explicit static triangles in memory instead of the implicit NURBS surface.

GeomStaticSmoothedMesh

• mesh - The base mesh, usually a GeomStaticMesh.
• static_subdiv - 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 to subdivide to in pixels. Otherwise it is in scene units.
• max_subdivs - If use_globals is false, the maximum number of triangle subdivisions for this mesh.

GeomDisplacedMesh

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

GeomParticleSystem

• mesh - A mesh plugin to use for some types of instances, depending on render_type.
• render_type - 3=multipoints; 4=multistreak; 6=points; 7=spheres; 8=sprites; 9=streak. The default is 7.
• colors - ColorList with a color for each particle.
• positions - VectorList with the particle positions.
• velocities - VectorList with velocities for motion blur. The values are in world units per frame.
  For the rest of the parameters for particular particle types, check the parameter list as described in Debugging and help.

Material and BRDF plugins

Textures and UVWGenerators

A.2. Other plugins

CameraDome

EffectLens

Volumetric plugins

VRayClipper