OpenVDB: nanovdb/NanoVDB.h File Reference

OpenVDB 9.0.0

Classes | Namespaces | Macros | Typedefs | Enumerations | Functions
NanoVDB.h File Reference

Implements a light-weight self-contained VDB data-structure in a single file! In other words, this is a significantly watered-down version of the OpenVDB implementation, with few dependencies - so a one-stop-shop for a minimalistic VDB data structure that run on most platforms! More...

`#include <stdlib.h>`
`#include <stdint.h>`
`#include <stddef.h>`
`#include <cassert>`
`#include <cstdio>`
`#include <cmath>`
`#include <limits>`

Go to the source code of this file.

## Classes
class | ValueMask
| Dummy type for a voxel with a binary mask value, e.g. the active state. More...
class | Half
| Dummy type for a 16 bit floating point values. More...
class | Fp4
| Dummy type for a 4bit quantization of float point values. More...
class | Fp8
| Dummy type for a 8bit quantization of float point values. More...
class | Fp16
| Dummy type for a 16bit quantization of float point values. More...
class | FpN
| Dummy type for a variable bit quantization of floating point values. More...
struct | is_same< T1, T2 >
| C++11 implementation of std::is_same. More...
struct | is_same< T, T >
struct | enable_if< bool, T >
| C++11 implementation of std::enable_if. More...
struct | enable_if< true, T >
struct | is_floating_point< T >
| C++11 implementation of std::is_floating_point. More...
struct | is_specialization< AnyType, TemplateType >
| Metafunction used to determine if the first template parameter is a specialization of the class template given in the second template parameter. More...
struct | is_specialization< TemplateType< Args... >, TemplateType >
struct | BuildToValueMap< T >
| Maps one type (e.g. the build types above) to other (actual) types. More...
struct | BuildToValueMap< ValueMask >
struct | BuildToValueMap< Half >
struct | BuildToValueMap< Fp4 >
struct | BuildToValueMap< Fp8 >
struct | BuildToValueMap< Fp16 >
struct | BuildToValueMap< FpN >
class | Rgba8
| 8-bit red, green, blue, alpha packed into 32 bit unsigned int More...
class | Version
| Bit-compacted representation of all three version numbers. More...
struct | Tolerance< float >
struct | Tolerance< double >
struct | Delta< float >
struct | Delta< double >
struct | Maximum< T >
| Maximum floating-point values. More...
class | Coord
| Signed (i, j, k) 32-bit integer coordinate class, similar to openvdb::math::Coord. More...
class | Vec3< T >
| A simple vector class with three double components, similar to openvdb::math::Vec3. More...
class | Vec4< T >
| A simple vector class with three double components, similar to openvdb::math::Vec4. More...
struct | TensorTraits< T, 0 >
struct | TensorTraits< T, 1 >
struct | FloatTraits< T, int >
struct | FloatTraits< T, 8 >
struct | FloatTraits< bool, 1 >
struct | FloatTraits< ValueMask, 1 >
struct | BaseBBox< Vec3T >
struct | BBox< Vec3T, true >
| Partial template specialization for floating point coordinate types. More...
struct | BBox< CoordT, false >
| Partial template specialization for integer coordinate types. More...
class | BBox< CoordT, false >::Iterator
| Iterator over the domain covered by a BBox. More...
class | Mask< LOG2DIM >
| Bit-mask to encode active states and facilitate sequential iterators and a fast codec for I/O compression. More...
class | Mask< LOG2DIM >::Iterator
struct | Map
| Defines an affine transform and its inverse represented as a 3x3 matrix and a vec3 translation. More...
struct | GridBlindMetaData
struct | NodeTrait< GridOrTreeOrRootT, 0 >
struct | NodeTrait< const GridOrTreeOrRootT, 0 >
struct | NodeTrait< GridOrTreeOrRootT, 1 >
struct | NodeTrait< const GridOrTreeOrRootT, 1 >
struct | NodeTrait< GridOrTreeOrRootT, 2 >
struct | NodeTrait< const GridOrTreeOrRootT, 2 >
struct | NodeTrait< GridOrTreeOrRootT, 3 >
struct | NodeTrait< const GridOrTreeOrRootT, 3 >
struct | GridData
| Struct with all the member data of the Grid (useful during serialization of an openvdb grid) More...
class | Grid< TreeT >
| Highest level of the data structure. Contains a tree and a world->index transform (that currently only supports uniform scaling and translation). More...
struct | TreeData< ROOT_LEVEL >
struct | GridTree< GridT >
| defines a tree type from a grid type while perserving constness More...
struct | GridTree< const GridT >
class | Tree< RootT >
| VDB Tree, which is a thin wrapper around a RootNode. More...
struct | RootData< ChildT >
| Struct with all the member data of the RootNode (useful during serialization of an openvdb RootNode) More...
struct | RootData< ChildT >::Tile
class | RootNode< ChildT >
| Top-most node of the VDB tree structure. More...
struct | InternalData< ChildT, LOG2DIM >
| Struct with all the member data of the InternalNode (useful during serialization of an openvdb InternalNode) More...
union | InternalData< ChildT, LOG2DIM >::Tile
class | InternalNode< ChildT, Log2Dim >
| Internal nodes of a VDB treedim(),. More...
struct | LeafData< ValueT, CoordT, MaskT, LOG2DIM >
| Stuct with all the member data of the LeafNode (useful during serialization of an openvdb LeafNode) More...
struct | LeafFnBase< CoordT, MaskT, LOG2DIM >
| Base-class for quantized float leaf nodes. More...
struct | LeafData< Fp4, CoordT, MaskT, LOG2DIM >
| Stuct with all the member data of the LeafNode (useful during serialization of an openvdb LeafNode) More...
struct | LeafData< Fp8, CoordT, MaskT, LOG2DIM >
struct | LeafData< Fp16, CoordT, MaskT, LOG2DIM >
struct | LeafData< FpN, CoordT, MaskT, LOG2DIM >
struct | LeafData< bool, CoordT, MaskT, LOG2DIM >
struct | LeafData< ValueMask, CoordT, MaskT, LOG2DIM >
class | LeafNode< BuildT, CoordT, MaskT, Log2Dim >
| Leaf nodes of the VDB tree. (defaults to 8x8x8 = 512 voxels) More...
struct | LeafNode< BuildT, CoordT, MaskT, Log2Dim >::ChildNodeType
struct | NanoNode< BuildT, 0 >
struct | NanoNode< BuildT, 1 >
struct | NanoNode< BuildT, 2 >
struct | NanoNode< BuildT, 3 >
class | ReadAccessor< BuildT, -1, -1, -1 >
| A read-only value accessor with three levels of node caching. This allows for inverse tree traversal during lookup, which is on average significantly faster than calling the equivalent method on the tree (i.e. top-down traversal). More...
struct | ReadAccessor< BuildT, -1, -1, -1 >::NodeInfo
class | ReadAccessor< BuildT, LEVEL0, -1, -1 >
| Node caching at a single tree level. More...
class | ReadAccessor< BuildT, LEVEL0, LEVEL1, -1 >
class | ReadAccessor< BuildT, 0, 1, 2 >
| Node caching at all (three) tree levels. More...
class | GridMetaData
| This is a convenient class that allows for access to grid meta-data that are independent of the value type of a grid. That is, this class can be used to get information about a grid without actually knowing its ValueType. More...
class | PointAccessor< AttT >
| Class to access points at a specific voxel location. More...

## Namespaces
namespace | nanovdb

## Macros
#define | NANOVDB_MAGIC_NUMBER 0x304244566f6e614eUL
#define | NANOVDB_MAJOR_VERSION_NUMBER 32
#define | NANOVDB_MINOR_VERSION_NUMBER 3
#define | NANOVDB_PATCH_VERSION_NUMBER 3
#define | USE_SINGLE_ROOT_KEY
#define | NANOVDB_FPN_BRANCHLESS
#define | NANOVDB_DATA_ALIGNMENT 32
#define | NANOVDB_ALIGN(n) alignas(n)
#define | NANOVDB_ASSERT(x) assert(x)
#define | __hostdev__
#define | NANOVDB_HOSTDEV_DISABLE_WARNING
#define | NANOVDB_OFFSETOF(CLASS, MEMBER) ((int)(size_t)((char*)&((CLASS*)0)->MEMBER - (char*)0))

## Typedefs
using | PackedRGBA8 = Rgba8
using | Vec3R = Vec3< double >
using | Vec3d = Vec3< double >
using | Vec3f = Vec3< float >
using | Vec3i = Vec3< int >
using | Vec4R = Vec4< double >
using | Vec4d = Vec4< double >
using | Vec4f = Vec4< float >
using | Vec4i = Vec4< int >
using | CoordBBox = BBox< Coord >
using | BBoxR = BBox< Vec3R >
template<typename BuildT >
using | DefaultReadAccessor = ReadAccessor< BuildT, 0, 1, 2 >
template<typename BuildT >
using | NanoLeaf = LeafNode< BuildT, Coord, Mask, 3 >
| Template specializations to the default configuration used in OpenVDB: Root -> 32^3 -> 16^3 -> 8^3. More...
template<typename BuildT >
using | NanoLower = InternalNode< NanoLeaf< BuildT >, 4 >
template<typename BuildT >
using | NanoUpper = InternalNode< NanoLower< BuildT >, 5 >
template<typename BuildT >
using | NanoRoot = RootNode< NanoUpper< BuildT > >
template<typename BuildT >
using | NanoTree = Tree< NanoRoot< BuildT > >
template<typename BuildT >
using | NanoGrid = Grid< NanoTree< BuildT > >
using | FloatTree = NanoTree< float >
using | DoubleTree = NanoTree< double >
using | Int32Tree = NanoTree< int32_t >
using | UInt32Tree = NanoTree< uint32_t >
using | Int64Tree = NanoTree< int64_t >
using | Vec3fTree = NanoTree< Vec3f >
using | Vec3dTree = NanoTree< Vec3d >
using | Vec4fTree = NanoTree< Vec4f >
using | Vec4dTree = NanoTree< Vec4d >
using | Vec3ITree = NanoTree< Vec3i >
using | MaskTree = NanoTree< ValueMask >
using | BoolTree = NanoTree< bool >
using | FloatGrid = Grid< FloatTree >
using | DoubleGrid = Grid< DoubleTree >
using | Int32Grid = Grid< Int32Tree >
using | UInt32Grid = Grid< UInt32Tree >
using | Int64Grid = Grid< Int64Tree >
using | Vec3fGrid = Grid< Vec3fTree >
using | Vec3dGrid = Grid< Vec3dTree >
using | Vec4fGrid = Grid< Vec4fTree >
using | Vec4dGrid = Grid< Vec4dTree >
using | Vec3IGrid = Grid< Vec3ITree >
using | MaskGrid = Grid< MaskTree >
using | BoolGrid = Grid< BoolTree >

## Enumerations
enum class | GridType : uint32_t { Unknown = 0 , Float = 1 , Double = 2 , Int16 = 3 , Int32 = 4 , Int64 = 5 , Vec3f = 6 , Vec3d = 7 , Mask = 8 , Half = 9 , UInt32 = 10 , Boolean = 11 , RGBA8 = 12 , Fp4 = 13 , Fp8 = 14 , Fp16 = 15 , FpN = 16 , Vec4f = 17 , Vec4d = 18 , End = 19 }
| List of types that are currently supported by NanoVDB. More...
enum class | GridClass : uint32_t { Unknown = 0 , LevelSet = 1 , FogVolume = 2 , Staggered = 3 , PointIndex = 4 , PointData = 5 , Topology = 6 , VoxelVolume = 7 , End = 8 }
| Classes (defined in OpenVDB) that are currently supported by NanoVDB. More...
enum class | GridFlags : uint32_t { HasLongGridName = 1 << 0 , HasBBox = 1 << 1 , HasMinMax = 1 << 2 , HasAverage = 1 << 3 , HasStdDeviation = 1 << 4 , IsBreadthFirst = 1 << 5 , End = 1 << 6 }
| Grid flags which indicate what extra information is present in the grid buffer. More...
enum class | GridBlindDataClass : uint32_t { Unknown = 0 , IndexArray = 1 , AttributeArray = 2 , GridName = 3 , End = 4 }
| Blind-data Classes that are currently supported by NanoVDB. More...
enum class | GridBlindDataSemantic : uint32_t { Unknown = 0 , PointPosition = 1 , PointColor = 2 , PointNormal = 3 , PointRadius = 4 , PointVelocity = 5 , PointId = 6 , End = 7 }
| Blind-data Semantics that are currently understood by NanoVDB. More...

## Functions
const char * | toStr (GridType gridType)
| Retuns a c-string used to describe a GridType. More...
const char * | toStr (GridClass gridClass)
| Retuns a c-string used to describe a GridClass. More...
const char * | toStr (GridFlags gridFlags)
| Retuns a c-string used to describe a GridFlags. More...
template<typename T1 , typename T2 >
static int64_t | PtrDiff (const T1 *p, const T2 *q)
template<typename DstT , typename SrcT >
static DstT * | PtrAdd (SrcT *p, int64_t offset)
template<typename DstT , typename SrcT >
static const DstT * | PtrAdd (const SrcT *p, int64_t offset)
bool | isFloatingPoint (GridType gridType)
| return true if the GridType maps to a floating point value. More...
bool | isValid (GridType gridType, GridClass gridClass)
| return true if the combination of GridType and GridClass is valid. More...
template<typename Type >
bool | isApproxZero (const Type &x)
template<typename Type >
Type | Min (Type a, Type b)
int32_t | Min (int32_t a, int32_t b)
uint32_t | Min (uint32_t a, uint32_t b)
float | Min (float a, float b)
double | Min (double a, double b)
template<typename Type >
Type | Max (Type a, Type b)
int32_t | Max (int32_t a, int32_t b)
uint32_t | Max (uint32_t a, uint32_t b)
float | Max (float a, float b)
double | Max (double a, double b)
float | Clamp (float x, float a, float b)
double | Clamp (double x, double a, double b)
float | Fract (float x)
double | Fract (double x)
int32_t | Floor (float x)
int32_t | Floor (double x)
int32_t | Ceil (float x)
int32_t | Ceil (double x)
template<typename T >
T | Pow2 (T x)
template<typename T >
T | Pow3 (T x)
template<typename T >
T | Pow4 (T x)
template<typename T >
T | Abs (T x)
template<>
float | Abs (float x)
template<>
double | Abs (double x)
template<>
int | Abs (int x)
template<typename CoordT , typename RealT , template< typename > class Vec3T>
CoordT | Round (const Vec3T< RealT > &xyz)
template<typename CoordT , template< typename > class Vec3T>
CoordT | Round (const Vec3T< float > &xyz)
template<typename CoordT , template< typename > class Vec3T>
CoordT | Round (const Vec3T< double > &xyz)
template<typename CoordT , typename RealT , template< typename > class Vec3T>
CoordT | RoundDown (const Vec3T< RealT > &xyz)
float | Sqrt (float x)
| Return the square root of a floating-point value. More...
double | Sqrt (double x)
template<typename T >
T | Sign (const T &x)
| Return the sign of the given value as an integer (either -1, 0 or 1). More...
template<typename Vec3T >
int | MinIndex (const Vec3T &v)
template<typename Vec3T >
int | MaxIndex (const Vec3T &v)
template<uint64_t wordSize>
uint64_t | AlignUp (uint64_t byteCount)
| round up byteSize to the nearest wordSize, e.g. to align to machine word: AlignUp<sizeof(size_t)(n) More...
template<typename T1 , typename T2 >
Vec3< T2 > | operator* (T1 scalar, const Vec3< T2 > &vec)
template<typename T1 , typename T2 >
Vec3< T2 > | operator/ (T1 scalar, const Vec3< T2 > &vec)
template<typename T1 , typename T2 >
Vec4< T2 > | operator* (T1 scalar, const Vec4< T2 > &vec)
template<typename T1 , typename T2 >
Vec4< T2 > | operator/ (T1 scalar, const Vec3< T2 > &vec)
template<typename BuildT >
GridType | mapToGridType ()
| Maps from a templated value type to a GridType enum. More...
template<typename Vec3T >
Vec3T | matMult (const float *mat, const Vec3T &xyz)
template<typename Vec3T >
Vec3T | matMult (const double *mat, const Vec3T &xyz)
template<typename Vec3T >
Vec3T | matMult (const float *mat, const float *vec, const Vec3T &xyz)
template<typename Vec3T >
Vec3T | matMult (const double *mat, const double *vec, const Vec3T &xyz)
template<typename Vec3T >
Vec3T | matMultT (const float *mat, const Vec3T &xyz)
template<typename Vec3T >
Vec3T | matMultT (const double *mat, const Vec3T &xyz)
template<typename Vec3T >
Vec3T | matMultT (const float *mat, const float *vec, const Vec3T &xyz)
template<typename Vec3T >
Vec3T | matMultT (const double *mat, const double *vec, const Vec3T &xyz)
static uint32_t | FindLowestOn (uint32_t v)
| Returns the index of the lowest, i.e. least significant, on bit in the specified 32 bit word. More...
static uint32_t | FindHighestOn (uint32_t v)
| Returns the index of the highest, i.e. most significant, on bit in the specified 32 bit word. More...
static uint32_t | FindLowestOn (uint64_t v)
| Returns the index of the lowest, i.e. least significant, on bit in the specified 64 bit word. More...
static uint32_t | FindHighestOn (uint64_t v)
| Returns the index of the highest, i.e. most significant, on bit in the specified 64 bit word. More...
uint32_t | CountOn (uint64_t v)
template<int LEVEL0 = -1, int LEVEL1 = -1, int LEVEL2 = -1, typename ValueT = float>
ReadAccessor< ValueT, LEVEL0, LEVEL1, LEVEL2 > | createAccessor (const NanoGrid< ValueT > &grid)
| Free-standing function for convenient creation of a ReadAccessor with optional and customizable node caching. More...
template<int LEVEL0 = -1, int LEVEL1 = -1, int LEVEL2 = -1, typename ValueT = float>
ReadAccessor< ValueT, LEVEL0, LEVEL1, LEVEL2 > | createAccessor (const NanoTree< ValueT > &tree)
template<int LEVEL0 = -1, int LEVEL1 = -1, int LEVEL2 = -1, typename ValueT = float>
ReadAccessor< ValueT, LEVEL0, LEVEL1, LEVEL2 > | createAccessor (const NanoRoot< ValueT > &root)

## Detailed Description

Implements a light-weight self-contained VDB data-structure in a single file! In other words, this is a significantly watered-down version of the OpenVDB implementation, with few dependencies - so a one-stop-shop for a minimalistic VDB data structure that run on most platforms!

Author
  Ken Museth

Date
  January 8, 2020

Note
  It is important to note that NanoVDB (by design) is a read-only sparse GPU (and CPU) friendly data structure intended for applications like rendering and collision detection. As such it obviously lacks a lot of the functionality and features of OpenVDB grids. NanoVDB is essentially a compact linearized (or serialized) representation of an OpenVDB tree with getValue methods only. For best performance use the ReadAccessor::getValue method as opposed to the Tree::getValue method. Note that since a ReadAccessor caches previous access patterns it is by design not thread-safe, so use one instantiation per thread (it is very light-weight). Also, it is not safe to copy accessors between the GPU and CPU! In fact, client code should only interface with the API of the Grid class (all other nodes of the NanoVDB data structure can safely be ignored by most client codes)!

Warning
  NanoVDB grids can only be constructed via tools like openToNanoVDB or the GridBuilder. This explains why none of the grid nodes defined below have public constructors or destructors.

Please see the following paper for more details on the data structure: K. Museth, “VDB: High-Resolution Sparse Volumes with Dynamic Topology”, ACM Transactions on Graphics 32(3), 2013, which can be found here: http://www.museth.org/Ken/Publications_files/Museth_TOG13.pdf

Overview: This file implements the following fundamental class that when combined forms the backbone of the VDB tree data structure:

Coord- a signed integer coordinate Vec3 - a 3D vector Vec4 - a 4D vector BBox - a bounding box Mask - a bitmask essential to the non-root tree nodes Map - an affine coordinate transformation Grid - contains a Tree and a map for world<->index transformations. Use this class as the main API with client code! Tree - contains a RootNode and getValue methods that should only be used for debugging RootNode - the top-level node of the VDB data structure InternalNode - the internal nodes of the VDB data structure LeafNode - the lowest level tree nodes that encode voxel values and state ReadAccessor - implements accelerated random access operations

Semantics: A VDB data structure encodes values and (binary) states associated with signed integer coordinates. Values encoded at the leaf node level are denoted voxel values, and values associated with other tree nodes are referred to as tile values, which by design cover a larger coordinate index domain.

Memory layout:

GridData is always at the very beginning of the buffer immediately followed by TreeData! The remaining nodes and blind-data are allowed to be scattered thoughout the buffer, though in practice they are arranged as:

GridData: 672 bytes (e.g. magic, checksum, major, flags, index, count, size, name, map, world bbox, voxel size, class, type, offset, count)

TreeData: 64 bytes (node counts and byte offsets)

... optional padding ...

RootData: size depends on ValueType (index bbox, voxel count, tile count, min/max/avg/standard deviation)

Array of: RootData::Tile

... optional padding ...

Array of: Upper InternalNodes of size 32^3: bbox, two bit masks, 32768 tile values, and min/max/avg/standard deviation values

... optional padding ...

Array of: Lower InternalNodes of size 16^3: bbox, two bit masks, 4096 tile values, and min/max/avg/standard deviation values

... optional padding ...

Array of: LeafNodes of size 8^3: bbox, bit masks, 512 voxel values, and min/max/avg/standard deviation values

Example layout: ("---" implies it has a custom offset, "..." implies zero or more) [GridData(672B)][TreeData(64B)]—[RootData][N x Root::Tile]—[NodeData<5>]—[ModeData<4>]—[LeafData<3>]—[BLINDMETA...]—[BLIND0]—[BLIND1]—etc.

## Macro Definition Documentation

## ◆ __hostdev__

#define __hostdev__

## ◆ NANOVDB_ALIGN

#define NANOVDB_ALIGN | ( |  | n | ) | alignas(n)

## ◆ NANOVDB_ASSERT

#define NANOVDB_ASSERT | ( |  | x | ) | assert(x)

## ◆ NANOVDB_DATA_ALIGNMENT

#define NANOVDB_DATA_ALIGNMENT 32

## ◆ NANOVDB_FPN_BRANCHLESS

#define NANOVDB_FPN_BRANCHLESS

## ◆ NANOVDB_HOSTDEV_DISABLE_WARNING

#define NANOVDB_HOSTDEV_DISABLE_WARNING

## ◆ NANOVDB_MAGIC_NUMBER

#define NANOVDB_MAGIC_NUMBER 0x304244566f6e614eUL

## ◆ NANOVDB_MAJOR_VERSION_NUMBER

#define NANOVDB_MAJOR_VERSION_NUMBER 32

## ◆ NANOVDB_MINOR_VERSION_NUMBER

#define NANOVDB_MINOR_VERSION_NUMBER 3

## ◆ NANOVDB_OFFSETOF

#define NANOVDB_OFFSETOF | ( |  | CLASS,
|  |  | MEMBER
| ) |  | ((int)(size_t)((char*)&((CLASS*)0)->MEMBER - (char*)0))

## ◆ NANOVDB_PATCH_VERSION_NUMBER

#define NANOVDB_PATCH_VERSION_NUMBER 3

## ◆ USE_SINGLE_ROOT_KEY

#define USE_SINGLE_ROOT_KEY