V-Ray standalone scene format description (.vrscene)

General

File structure

Parameter types

Including .vrscene files

Animated parameters

The interpolate() statement

The #time directive

Expressions

General

The .vrscene file format is used by the standalone version of V-Ray to describe the scene that must be rendered. The file contains all the necessary geometry, material descriptions, camera view and render settings.

File structure

The .vrscene file is a normal text file, which contains descriptions of plugin objects. Those objects can be triangle meshes, materials, textures, render settings etc. Each object has a type, a name and one or more parameters:

 

// This is some comment

ObjectType object_name {

param1=value1;

param2=value2;

...

}

 

The object type is actually the name of a plugin class. This is the same name as returned by the getName() method of the plugin descriptor for the class.

 

The name of the object follows the rules for identifiers in most programming languages - it must start with a letter or underscore, and can contain letters, digits and the underscore character '_'.

 

All object types, names and parameter names are case-sensitive.

 

The parameters of the object are specific for each object type. You can view the parameters of any V-Ray plugin using the plgparams command line tool, for example:

 

d:\sdk\vraysdk\bin>plgparams LightDirect

Parameters for plugin 'LightDirect'

color: color = Color(1, 1, 1)
transform: transform
shadowBias: float = 0
photonSubdivs: integer = 500
causticSubdivs: integer = 1000
beamRadius: float = 1

d:\sdk\vraysdk\bin>

Parameter types

Each parameter has a type and a default value. Parameters can be of the following type:

Including .vrscene files

You can include one .vrscene file inside another by using a C-style #include declaration:

 

#include "mygeometry.vrscene"

 

The standalone version of V-Ray will look for the specified file in the same folder as the input .vrscene file. If the file is not found there, V-Ray will look for it in the additional folders specified with the -include command-line switch.

Animated parameters

The .vrscene file format can describe animated parameters. This allows more compact representation of animated scenes than generating a new .vrscene file for each frame, since typically only some objects change during an animation.

 

To describe an animated parameter, you need to provide its values at several different moments of time (keyframes). This can be done in two ways.

The interpolate() statement

The first method is to use an interpolate() statement, for example:

 

MtlDiffuse material {

diffuse=interpolate(

(0,   Color(0.2, 0.2, 0.2)),

(0.5, Color(1, 1, 1)),

(1,   Color(0, 0, 0))

);

}

 

The interpolate() statement consists of pairs (timeValue, paramValue) in brackets, separated by commas, which specify the value of the parameter at a given moment of time. The exact relation between the time values and frames depends on the V-Ray settings and is typically specified in a SettingsOutput object. The interpolate() statement can be used for any parameter type, including lists of values, for example:

 

GeomStaticMesh pCubeShape1 {

vertices = interpolate(

(1, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003F0000003F0000003F0000003F0000003F000000BF0000003F000000BF0000003F0000003F000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(2, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003F0000003F0000003F0000003F0000003F000000BF0000003F000000BF0000003F0000003F000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(3, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003FF6B4533F0000003F0000003FF6B4533F000000BF0000003F000000BF0000003F0000003F000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(4, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003FF6B4933F0000003F0000003FF6B4933F000000BF998D2C3F000000BF0000003F998D2C3F000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(5, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003F728FBD3F0000003F0000003F728FBD3F000000BF9E348F3F000000BF0000003F9E348F3F000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(6, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003FED69E73F0000003F0000003FED69E73F000000BF98EFDB3F000000BF0000003F98EFDB3F000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(7, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003F34A208400000003F0000003F34A20840000000BFEECE1640000000BF0000003FEECE1640000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(8, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003F728F1D400000003F0000003F728F1D40000000BFC6B23A40000000BF0000003FC6B23A40000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(9, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003FAF7C32400000003F0000003FAF7C3240000000BFC6B23A40000000BF0000003FC6B23A40000000BF000000BF000000BF000000BF0000003F000000BF000000BF")),

(10, ListVectorHex("000000BF000000BF0000003F0000003F000000BF0000003F000000BF0000003FAF7C32400000003F0000003FAF7C3240000000BFC6B23A40000000BF0000003FC6B23A40000000BF000000BF000000BF000000BF0000003F000000BF000000BF"))

);

faces=ListIntHex("000000000100000002000000010000000300000002000000020000000300000004000000030000000500000004000000040000000500000006000000050000000700000006000000060000000700000000000000070000000100000000000000010000000700000003000000070000000500000003000000060000000000000004000000000000000200000004000000");

}

 

If the value of an interpolated parameter is requested for a time moment that is not explicitly specified in the interpolate() statement, it will be linearly interpolated from the values at the two nearest moments of time. Note that for list values, this is only possible if they have the same number and type of elements.

 

You can also split the interpolate() statements, if, for example, the animation is exported frame by frame and not all the data about a given parameter is available immediately:

 

MtlDiffuse material {

diffuse=interpolate((0,   Color(0.2, 0.2, 0.2)));

}

 

............

 

MtlDiffuse material {

diffuse=interpolate((0.5,   Color(1, 1, 1)));

}

 

............

 

MtlDiffuse material {

diffuse=interpolate((1,   Color(0, 0, 0)));

}


The #time directive

The other method for specifying an animated parameter is using the #time directive. This directive sets the current frame time for the object parameters that are created. In this way, the above material example can be specified as follows:

 

#time 0.0

MtlDiffuse material {

diffuse=Color(0.2, 0.2, 0.2);

}

 

............

 

#time 0.5

MtlDiffuse material {

diffuse=Color(1, 1, 1);

}

 

............

 

#time 1.0

MtlDiffuse material {

diffuse=Color(0, 0, 0);

}

 

Note that once you specify an object for the first time, there is no need to repeat non-animated parameters after every #time directive. You should only specify those parameters that are different for the frame in question.

 

The final result of the interpolate() statement and the #time directive is exactly the same. In fact, the scene parser will assemble the different #time directives into interpolate() statements internally.

Expressions

The .vrscene supports simple expressions for parameter values. Basic arithmetic operations are supported on numbers, vectors, colors, matrices and transformations; some built-in functions are also provided. An expression can reference other properties in the .vrscene, including access to list properties, which can be indexed starting from 0.

 

For example, one can create the following .vrscene file:

 

Node firstNode {

transform=Transform(Matrix(Vector(1, 0, 0), Vector(0, 1, 0), Vector(0, 0, 0)), Vector(1, 2, 3));

}

 

Node secondNode {

// The transform of this node is equal to the transform of firstNode plus some time-dependent value

transform=firstNode.transform+Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, time(), 0));

}

 

Node thirdNode {

// The transform of this node is equal to the transform of secondNode plus some fixed offset

transform=secondNode.transform+Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(1, 0, 0));

}

 

In this example, the transformation of secondNode is offset relative to firstNode based on the current animation time, and the transformation of thirdNode is offset relative to secondNode by some fixed amount.

 

The '+' operator can also be used to concatenate lists - either generic lists through the List() expression, or specific floating-point, integer, vector and color lists through the ListFloat(), ListInt(), ListVector() and ListColor() expressions:

 

Node firstNode {

lights=List(light1, light2);

}

 

Node secondNode {

lights=List(light3);

}

 

LightDome domeLight {}

 

Node thirdNode {

// The lights list for this node is light1, light2, light3, domeLight

lights=firstNode.lights+secondNode.lights+domeLight;

}

 

Here is a list of the supported built-in functions.

 

Built-in function Description
time() Return the current animation time as a floating-point number.
random() Return a random number between 0.0 and 1.0. The separate random() calls within a single .vrscene file all return different values from each other, however a specific random call will always return the same value to ensure consistency across multiple renders.
pi() Return the number pi (3.14159...). This is useful when dealing with trigonometric functions.
sqr(x) Return the square of the floating-point number x, i.e. x*x.
sqrt(x) Return the square root of the floating-point number x.
sin(x) Return the sine of the angle x in radians.
cos(x) Return the cosine of the angle x in radians.
length(a) Return the length of the vector a.
noise(a) Return a noise function in the range [-1, 1] based on the given vector a.
pow(x,y) Return the floating-point number x raised to the power y.
cross(a,b) Return the cross product of two vectors a and b.
uniform(x,y) Return a uniformly distributed floating-point number between x and y. The separate uniform() calls within a single .vrscene file all return different values from each other, however a specific random call will always return the same value to ensure consistency across multiple renders.