V-Ray shade map format description (.vrst)

General

Common file structure

File header

Data chunk common format

Data chunks detailed description

TLD Image Header

TAG Channel Info

TLD Tile Data

TLD Tile Map

TLD Camera Transformation

TLD Meta Info

TAG End

Tile data

Uncompressed tile

Compressed tile

Meta info type

Channel data type

Channel aliases

General

The .vrst format is used to store deep shade map images with a variable sized list of samples for every pixel. Each sample in the image contains fixed number of data channels.
The deep image is composed of rectangle tiles. All tiles in the image have the same dimensions.

 

Common file structure

The .vrst file contains file header and several data chunks.

File header

The header is eight bytes long and is located at the start of a .vrst file.

 

Field name Field size Description
File ID 4 bytes Contains the four ASCII symbols 'VRST' used to recognize the files.
file version 4 bytes One 32-bit unsigned integer with the file version (currently 0x00000201)

 

Data chunk common format

Every data chunk begins with tag that identifies the chunk contents. Every tag is four bytes long.
There are two tag types, referred in this document as TAG (tag with data) and TLD (Tag with data Length and Data).
The tag type is determined by the most significant bit of the tag value. This bit is 1 for TLD and 0 for TAG.

TLD

A chunk, starting with TLD contains data length information and its data field could be skipped during file parsing, using Seek() operation.
This could be done for several reasons:

Field name Field size Description
TLD 4 bytes One 32-bit unsigned integer with the most significant bit set to 1; This value identifies the chunk data contents.
Data length (L) 8 bytes One 64-bit unsigned integer with the length of the remaining chunk data in bytes
Chunk data L bytes Additional data in the chunk

 

TAG

A chunk, starting with TAG should be fully parsed to determine the next chunk location.

 

Field name Field size Description
TAG 4 bytes One 32-bit unsigned integer with the most significant bit set to 0; This value identifies the chunk data contents.
Chunk data varying Additional data in the chunk

 

Data chunks detailed description

TLD Image Header

This chunk describes global image properties - image size, tile size and tile compression type.
The TLD Image Header chunk should be present exactly once in the .vrst file.

 

Field name Field size Description
TLD 4 bytes TLD=0x80000001
Data length (L) 8 bytes Chunk data size. Data length = 20 bytes for the current version
Image_width 4 bytes Width of the image in pixels
Image_height 4 bytes Height of the image in pixels
Tile_width 4 bytes Width of the tiles in pixels
Tile_height 4 bytes Height of the tiles in pixels
Compression type 4 bytes Type of the compression used to store tile data.
There are currently two valid values for this field:
  • 0 - no compression used
  • 1 - zlib compression

 

All tiles within an image does have the same dimensions.
The number of tiles in the image could be determined using the following calculations:

 

width_in_tiles = (Image_width - 1)/Tile_width + 1
height_in_tiles = (Image_height - 1)/Tile_height + 1
total_tiles = width_in_tiles*height_in_tiles

 

Even if a part of some tile is laying outside the image rectangle, the tile is fully stored in the file.
For example, if the image size is 100x50 and the tile size is 30x40, the image consists of 4x2 full tiles, actually representing 120x80 pixels.
The pixels outside the image rectangle should be ignored when reading the image.
Note that future versions may extend this data chunk with more values (e.g. display window size) so the parser should actually read the data length value and skip any extra data bytes.

 

TAG Channel Info

This chunk describes the data channels, stored in every sample in the pixel's sample list.
Chunk's data field contains the number of channels and description of every channel.
Every sample in the pixel's sample list consists of data bytes for all channels.
The total size of sample data is equal to the summation of all channel sizes:

sample_size=Σ channel_size


VRay performs sanity checks for consistency between the data type, data size and channel alias.
If an inconsistency is detected, the channel data is ignored in the samples.
While VRay generates channel names, it mostly ignores them during reading and they don't affect any calculations.
The TAG Channel Info chunk should be present exactly once in the .vrst file.

 

Repeats Field name Field size Description
1 TAG 4 bytes TAG=0x55555551
Number of channels (N) 4 bytes Number of data channels in every sample
N Channel alias 4 bytes Alias of the channel (VRay specific channel identifier)
Channel type (VRay specific data type) 4 bytes Type of the channel data
Channel data size 4 bytes Size of the channel data in bytes
Channel name length (L) 4 bytes Length of the channel name in bytes
Channel name L bytes Name of the channel (ASCII)

 

TLD Tile Data

This chunk contains the tiles of the image with no particular tile order.
Note that the image may be partial and some tiles may be missing. In case of missing tiles, it is assumed that no samples are stored in the tile's area.
Refer to Tile data for detailed description of the tile data format.
The TLD Tile Data chunk should be present exactly once in the .vrst file.

 

Field name Field size Description
TLD 4 bytes TLD=0x80000003
Data length (L) 8 bytes Chunk data size.
Chunk data L bytes Data for all tiles in the image, ordered consecutively and without any particular order.

 

TLD Tile Map

This chunk contains map with the location of every tile in the file.
An array of offsets for every tile is written here. The array size should be equal to the image size in tiles. Refer to TLD Image Header for more information.
Every offset is 64-bit unsigned value, representing the number of bytes from the beginning of file.
Some files may not be actually present in the .vrst file. For such tiles, the offset value should be equal to zero.
The tile offsets are stored by tile coordinates in progressive scan order - left to right and top to bottom.
The TLD Tile Map chunk should be present exactly once in the .vrst file.

 

Repeats Field name Field size Description
1 TLD 4 bytes TLD=0x80000004
Data length (L) 8 bytes Chunk data size. For this version it is equal to 8*N, where N is the total number of tiles in the image.
N Tile offset 8 bytes Offset of the tile data from the beginning of file (or zero for tiles that aren't present)

 

TLD Camera Transformation

This chunk contains the camera transformation during the image creation.
TLD Camera Transformation is an optional chunk - may be present zero or one times in the .vrst file.

 

Field name Field size Description
TLD 4 bytes TLD=0x80000002
Data length (L) 8 bytes Chunk data size=12*8=96 bytes.
Chunk data 12*8=96 bytes Twelve double values, representing the camera transformation matrix and offset in world space coordinates.

 

TLD Meta Info

This chunk contains additional information about the image and may be present many times. Every occurrence defines one data key with name and value.
If the key type is not known or there is an inconsistency between the key type and key length, the key should be ignored.
TLD Meta Info Key is an optional chunk - may be present zero or may times in the .vrst file.

 

Field name Field size Description
TLD 4 bytes TLD=0x80000005
Data length (L) 8 bytes Chunk data size=4 + K + 4 + 4 + N bytes.
Key name length (K) 4 bytes The length of the key name in bytes.
Key name K bytes The key name (ASCII).
Key data type 4 bytes Type of the key data.
Key data length (N) 4 bytes Size of the key data in bytes.
Key data N bytes Key data.

 

TAG End

This chunk contains just the TAG itself and no additional data.
It is supposed to define the end of file. No data should be read after this chunk.
This chunk should be present exactly once in the .vrst file.

 

Field name Field size Description
TAG 4 bytes TAG=0x7FFFFFFF

 

Tile data

The tile data consist of sample count and sample data for every pixel in the tile.
Pixels are stored by pixel coordinates in progressive scan order - left to right and top to bottom.
Every tile contains Tile_width*Tile_height pixels.

Uncompressed tile data

The uncompressed tile data consists of two parts:

Every sample array consists of 0 or more samples. Every sample consists of sample_size bytes, representing every channel in the sample. Refer to TAG Channel Info for sample_size calculation.

 

Repeats Field name Field size Description
Tile_width*Tile_height SampleCnt [x,y] 4 bytes Number of samples in the pixel
SampleCnt [x,y] SampleArray [x,y] SampleCnt [x,y]*sample_size bytes Array of data samples for every pixel

Compressed tile data

Compressed tile data begins with header and then continues with the same structure, as in the uncompressed data but stored using ZLIB compression.

 

Field name Field size Description
Compressed tile size (N) 4 bytes Size of the compressed data in bytes
Decompressed size 4 bytes Size of the data after decompression, in bytes
Compressed data N bytes Compressed tile data.

 

Meta info type

 

Value Type name Data size Description
0 ASCII string >=0 sequence of ASCII characters
1 Int 4 bytes 32 bit signed integer number
2 Int array 4*N bytes Array of 32 bit signed integer numbers. The number of array elements is equal to data_size/4
3 Single 4 bytes 32 bit IEEE-754 number
4 Single array 4*N bytes Array of 32 bit IEEE-754 numbers. The number of array elements is equal to data_size/4
5 Double 8 bytes 64 bit IEEE-754 number
6 Double array 8*N bytes Array of 64 bit IEEE-754 numbers. The number of array elements is equal to data_size/8

 

Channel data type

All floating point values could be represented using IEEE 754 Half (16-bit) or Single (32-bit) precision.
The correct type (half or single) is determined by the data size. If the data size does not match the data type, VRay ignores this channel in the samples.

 

Value Type name Data size Description
1 FLOAT 2 / 4 bytes Floating point value
2 FLOAT3 3*2 / 3*4 bytes Three consecutive floating point values that typically represents R, G, B color value.
2 FLOAT2 2*2 / 2*4 bytes Two consecutive floating point values, e.g. uv coordinates.
3 INT 4 bytes 32 bit signed integer number
2 FLOAT3_SIGNED 3*2 / 3*4 bytes Three consecutive floating point values that typically represent coordinates.

 

Channel aliases

 

VRay recognizes some special channels by alias, data type and data size. There three values should be consistent in order to be recognized as a special channel.

 

Alias Data type Data size Name1 Description Generated2
1 FLOAT3 3*4 or 3*2 COLOR Sample color SD
2 FLOAT3 3*4 or 3*2 ALPHA SD
3 FLOAT3 3*4 or 3*2 TRANSPARENCY SD
8 FLOAT3 3*4 or 3*2 REG_CHAN_FRAG_ALPHATRANSP SD
5 FLOAT 4 or 2 ZDepth Distance from the camera SD
6 INT 4 RenderID SD
138 FLOAT 4 or 2 DEEP_MIN This channel may occur more than once.
The first occurrence in the channel list is DEEP_MIN (disance between the camera plane and front side of the sample).
D
138 FLOAT 4 or 2 DEEP_MAX This channel may occur more than once.
The second occurrence in the channel list is DEEP_MAX (disance between the camera plane and back side of the sample).
If there is not second occurrence, DEEP_MAX is equal to DEEP_MIN.
D
10 FLOAT 4 or 2 WEIGHT D
10 FLOAT3 3*4 or 3*2 FILTER D

1 A human readable name that VRay generate but does not use to recognize the channel

2 Operations that generate the particular channel data: