forked from NVIDIA/gvdb-voxels
-
Notifications
You must be signed in to change notification settings - Fork 1
/
GVDB_FILESPEC.txt
122 lines (102 loc) · 5.64 KB
/
GVDB_FILESPEC.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
NVIDIA GVDB VOXELS
Copyright 2016 NVIDIA Corporation
SPDX-License-Identifier: Apache-2.0
Created: Rama Hoetzlein, rhoetzlein@nvidia.com, 8/28/2016
Last Revised: 2/1/2021
This file outlines the VBX file format specification.
File Format Versions
====================
1.11 GVDB Release (3/25/2018)
Versions on or after 1.11 save grid transforms to file.
This allows save/load of volumes to render correctly in world space.
1.1 GVDB Release (1/1/2018)
Bitmask flags are optional.
Versions on or after 2.0 save setting to vbx file.
1.0 GVDB Beta Release (10/2/2016)
Grid data types: Only 'f' (float)
Grid components: Only 1
Grid compression: Only 0 (none)
Topology type: Only 2 (gvdb)
Brick layout: Only 0 (atlas layout)
File Format
===============
VBX HEADER
--------------
File Major Version # 1 byte
File Minor Version # 1 byte
Pre-translation 12 byte, vec3f \
XYZ Euler angles 12 byte, vec3f |[a]
Scale 12 byte, vec3f |
Translation 12 byte, vec3f /
# of Grids 4 byte, int
Uses bitmasks 1 byte, bool [b] Only present in GVDB 2.0+ VBX files
Grid offset 0 8 byte, ulong [c]
Grid offset 1 8 byte, ulong
Grid offset .. 8 byte, ulong
Grid offset N 8 byte, ulong
Note [a]: Only present in GVDB 1.11+ VBX files. GVDB applies
pre-translation first, followed by scale, then rotation about
the X, Y, and Z axes sequentially, followed finally by translation.
Note [c]: The grid table is given as a list of file offsets
to allow random access to grids without having to read
the entire VBX file.
FOR EACH GRID...
------------- GRID HEADER
Name 256 bytes [d] Stored as a c-string with a terminal '\0'
Grid Data Type 1 byte, uchar [e] Values are: 'c'=char, 's'=signed int, 'u'=unsigned int, 'f'=float, 'd'=double
Grid Components 1 byte, uchar [f] Gives the number of components for each voxels. e.g. 1=scalar, 3=vector
Grid Compression 1 byte, uchar [g] Compression type. Values are: 0=none, 1=blosc, 2=other
Voxel size 12 byte, vec3f [h] The size of each voxel in world units (since 1.1.1, always )
# of Bricks 4 byte, int [i] Number of bricks stored for this grid
Brick dims 12 byte, vec3i [j] Dimensions of a single brick, not including the apron voxels
Brick apron 4 byte, int [k] Brick apron size (in voxels) stored in the file
Total Atlas Size 8 byte, ulong [l] Total size of the atlas data in bytes
Topology Type? 1 byte, uchar [m] Type of topology. Values: 0=None, 1=Reuse, 2=GVDB, 3=other.
Topology Reuse Grid 4 byte, int [n] Reuse another gvdb grid for topology. No topology section if set.
Brick layout? 1 byte, uchar [o] Layout of bricks. Values: 0=Atlas layout, 1=Brick layout
Atlas leaf count 12 byte, vec3i [p] Atlas leaf count
Atlas res 12 byte, vec3i [q] Atlas resolution (in voxels)
-------- TOPOLOGY SECTION
# of Levels 4 byte, int [r] Number of levels in tree
Root ID 8 byte, int [s] Pool ID of the tree root
FOR EACH LEVEL..
Log2 Level Dim 4 byte, int [t] Log2 dimension of the level
Res 4 byte, int [u] Resolution of the level. Res=2^(Log2 Level Dim)
Range 12 byte, vec3i [v] Range of the node in index-space
Node count 4 byte, int [w] Number of nodes at this level
P0 width 4 byte, int [x] Width of Pool 0 for this level
P1 width 4 byte, int [y] Width of Pool 1 for this level
--- TOPOLOGY POOLS
Topology data is stored next.
If Topology Type = 0 then this section is omitted. This type is useful
for general sparse brick storage without an explicit topology. With this type,
bricks must be stored in "brick layout" ordering.
If Topology Type = 1 then the topology is reused from another grid.
This type is useful when there are multiple channels of data, but all
having the same topology layout. In this case, the Reuse Grid value indicates the grid to be applied.
If Topology Type = 2 then the topology is a GVDB Structure, as follows.
Each pool for each level of the current grid is stored as a table.
The width of each pool is "P0/P1 Width", and the height (# rows) of the table is "Node cnt"
Pool 0 is the node pool, stored first. Each row contains a single node and bitmask.
Pool 1 is the child lists. Each row is a list of children IDs, with padding to the pool width.
The ordering of storage is pool, level, row:
Pool 0, Level 0, Row 0..n
Pool 0, Level 1, Row 0..n
Pool 0, Level ., Row 0..n
Pool 0, Level L, Row 0..n where L = # Levels
Pool 1, Level 0, Row 0..n
Pool 1, Level 1, Row 0..n
Pool 1, Level ., Row 0..n
Pool 1, Level L, Row 0..n where L = # Levels
-------- ATLAS SECTION
Atlas (brick) data is stored next.
When the bricks are stored in "atlas layout", the data is stored
as a single, large, 3D volume with width-height-depth ordering.
Bricks are embedded inside the atlas, and cannot be easily read individually.
The stored size of each voxel in a brick matches the grid data type and number of components.
This layout is ideal for fast, efficient loading directly to the GPU.
When the bricks are stored in "brick layout", the data is stored
as data chunks for each brick, with width-height-depth ordering for each individual brick.
Bricks are written sequentially to the file.
This layout is ideal for out-of-core streaming, where individual bricks are delay loaded.
-------- Next stored GRID starts here