V-Ray standalone scene format description (.vrscene)

General

File structure

Parameter types

Including .vrscene files

Animated parameters

The interpolate() statement

The #time directive

 

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.