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:
|
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:
|
Parameters for plugin 'LightDirect'
color: color = Color(1, 1, 1)
transform: transform
shadowBias: float = 0
photonSubdivs: integer = 500
causticSubdivs: integer = 1000
beamRadius: float = 1
|
Parameter types
Each parameter has a type and a default value. Parameters can be of the following
type:
- Scalar values. These can be one of the following:
- 32-bit integer numbers;
- single precision floating point numbers;
- double precision floating point numbers;
- String values. These are specified as arbitrary text enclosed in quotation
marks, for example "This is some test";
- Compound values. These can be:
- Vectors in 3d space, specified as Vector(x,y,z);
- Colors in RGB color space, specified as Color(r,g,b)
with Color(0,0,0) being black and Color(1,1,1)
being white;
- RGBA colors, specified as AColor(r,g,b,a);
- 3 x 3 matrices, specified as Matrix(vector_x,
vector_y, vector_z);
- 3 x 4 transformations in 3d space, specified as Transform(matrix,
vector_offset);
- Object references. These can be:
- Object references - these specify another object in
the scene by its name. For example, the material for a particular node
in the scene is specified with such a parameter;
- Sub-object references - some plugins serve as containers
for one or more sub-object plugins. For example, TexAColorOp
is a plugin that encapsulates several different texure plugins which share
the same parameters. Specifying the sub-textures is done by following
the object name with double column sign '::' followed by the sub-texture
name, for example:
TexAColorOp blendTex {
color_a=tex1;
mult_a=0.5;
color_b=tex2;
mult_b=0.5;
}
BRDFDiffuse diffuseLayer {
color_tex=blendTex::sum;
} |
- Lists. These can be of the following types:
- General lists - these are lists of any of the above
values, specified as List(value_0, value_1, ...),
for example List(Vector(0,0,1), Color(1,1,1)).
In this form, the list can have elements of different types;
- Specialized lists - these are used for some common
lists - for example lists of 3d vectors. There are several of these: ListVector(),
ListInt(), ListFloat()
and ListColor(). These special lists provide
more compact storage and faster access than the general-purpose List().
For example, ListVector(Vector(0,0,1), Vector(0,1,0)).
In this form, all elements of the list must be of the same type,
which matches the list type;
- Hexadecimal specialized lists - these are used for
performance reasons. They are ListVectorHex(),
ListIntHex(), ListFloatHex()
and ListColorHex(). Each of these takes a single
string enclosed in inverted commas (") as a parameter. The string
represents the memory footprint of the list, where each 2 hexadecimal
digits represent one byte, with the most significant half-byte first.
For example, an integer list with the numbers 1 and 10 will be represented
as ListIntHex("010000000A000000").
For vectors, the components are written in x-y-z order and for colors
- in r-g-b order.
- Compressed hexadecimal lists - these are specified
in the same way as hexadecimal lists, but the string inside the parentheses
starts with the characters "ZIPB", followed by a hex-coded 32-bit integer
value with the length of the uncompressed data, followed by another hex-coded
32-bit integer value with the length of the compressed data. The data
itself is compressed with the zlib library.
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 {
transform=firstNode.transform+Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, time(), 0));
}
Node thirdNode {
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 {
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. |