Loading...
Searching...
No Matches
ValueAccessor< _TreeType, IsSafe, CacheLevels, MutexType > Class Template Reference

`#include <openvdb/tree/ValueAccessor.h>`

Inheritance diagram for ValueAccessor< _TreeType, IsSafe, CacheLevels, MutexType >:

## Public Types

using | TreeType = _TreeType
using | RootNodeT = typename TreeType::RootNodeType
using | LeafNodeT = typename TreeType::LeafNodeType
using | ValueType = typename RootNodeT::ValueType
using | BaseT = ValueAccessorBase<TreeType, IsSafe>
using | LockT = typename MutexType::scoped_lock

## Public Member Functions

| ValueAccessor (TreeType &tree)
| ValueAccessor (const ValueAccessor &other)
ValueAccessor & | operator= (const ValueAccessor &other)
| ~ValueAccessor () override=default
bool | isCached (const Coord &xyz) const
| Return `true` if nodes along the path to the given voxel have been cached.
const ValueType & | getValue (const Coord &xyz) const
| Return the value of the voxel at the given coordinates.
bool | isValueOn (const Coord &xyz) const
| Return the active state of the voxel at the given coordinates.
bool | probeValue (const Coord &xyz, ValueType &value) const
| Return the active state of the voxel as well as its value.
int | getValueDepth (const Coord &xyz) const
bool | isVoxel (const Coord &xyz) const
void | setValue (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as active.
void | setValueOn (const Coord &xyz, const ValueType &value)
void | setValueOnly (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinate but don't change its active state.
void | setValueOff (const Coord &xyz, const ValueType &value)
| Set the value of the voxel at the given coordinates and mark the voxel as inactive.
template<typename ModifyOp>
void | modifyValue (const Coord &xyz, const ModifyOp &op)
| Apply a functor to the value of the voxel at the given coordinates and mark the voxel as active.
template<typename ModifyOp>
void | modifyValueAndActiveState (const Coord &xyz, const ModifyOp &op)
| Apply a functor to the voxel at the given coordinates.
void | setActiveState (const Coord &xyz, bool on=true)
| Set the active state of the voxel at the given coordinates but don't change its value.
void | setValueOn (const Coord &xyz)
| Mark the voxel at the given coordinates as active but don't change its value.
void | setValueOff (const Coord &xyz)
| Mark the voxel at the given coordinates as inactive but don't change its value.
template<typename NodeType>
NodeType * | getNode ()
| Return the cached node of type NodeType. [Mainly for internal use].
template<typename NodeType>
void | insertNode (const Coord &xyz, NodeType &node)
template<typename NodeType>
void | eraseNode ()
void | addLeaf (LeafNodeT *leaf)
| Add the specified leaf to this tree, possibly creating a child branch in the process. If the leaf node already exists, replace it.
void | addTile (Index level, const Coord &xyz, const ValueType &value, bool state)
| Add a tile at the specified tree level that contains voxel (x, y, z), possibly deleting existing nodes or creating new nodes in the process.
LeafNodeT * | touchLeaf (const Coord &xyz)
| Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, create one, but preserve the values and active states of all voxels.
template<typename NodeT>
NodeT * | probeNode (const Coord &xyz)
| Return a pointer to the node of the specified type that contains voxel (x, y, z), or `nullptr` if no such node exists.
template<typename NodeT>
const NodeT * | probeConstNode (const Coord &xyz) const
template<typename NodeT>
const NodeT * | probeNode (const Coord &xyz) const
LeafNodeT * | probeLeaf (const Coord &xyz)
| Return a pointer to the leaf node that contains voxel (x, y, z), or `nullptr` if no such node exists.
const LeafNodeT * | probeConstLeaf (const Coord &xyz) const
const LeafNodeT * | probeLeaf (const Coord &xyz) const
void | clear () override
| Remove all nodes from this cache, then reinsert the root node.
_TreeType * | getTree () const
| Return a pointer to the tree associated with this accessor.
_TreeType & | tree () const
| Return a reference to the tree associated with this accessor.

## Static Public Member Functions

static Index | numCacheLevels ()
| Return the number of cache levels employed by this accessor.
static bool | isSafe ()
| Return true if this accessor is safe, i.e. registered by the tree from which it is constructed. Un-registered accessors can in rare cases be faster because it avoids the (small) overhead of registration, but they are unsafe if the tree is modified. So unless you're an expert it is highly recommended to set IsSafe = true (which is the default).

## Static Public Attributes

static constexpr bool | BypassLeafAPI
static const bool | IsConstTree

## Protected Attributes

_TreeType * | mTree

## Friends

template<typename>
class | RootNode
template<typename, Index>
class | InternalNode
template<typename, Index>
class | LeafNode
template<typename>
class | Tree

## Detailed Description

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
class openvdb::v10_0::tree::ValueAccessor< _TreeType, IsSafe, CacheLevels, MutexType >

When traversing a grid in a spatially coherent pattern (e.g., iterating over neighboring voxels), request a `ValueAccessor` from the grid (with Grid::getAccessor()) and use the accessor's `getValue()` and `setValue()` methods. These will typically be significantly faster than accessing voxels directly in the grid's tree.

A ValueAccessor caches pointers to tree nodes along the path to a voxel (x, y, z). A subsequent access to voxel (x', y', z') starts from the cached leaf node and moves up until a cached node that encloses (x', y', z') is found, then traverses down the tree from that node to a leaf, updating the cache with the new path. This leads to significant acceleration of spatially-coherent accesses.

Parameters

  _TreeType | the type of the tree to be accessed [required]
  IsSafe | if IsSafe = false then the ValueAccessor will not register itself with the tree from which it is constructed (see warning).
  CacheLevels | the number of nodes to be cached, starting from the leaf level and not including the root (i.e., CacheLevels < DEPTH), and defaulting to all non-root nodes
  MutexType | the type of mutex to use (see note)

Warning
  If IsSafe = false then the ValueAccessor will not register itself with the tree from which it is constructed. While in some rare cases this can lead to better performance (since it avoids the small overhead of insertion on creation and deletion on destruction) it is also unsafe if the tree is modified. So unless you're an expert it is highly recommended to set IsSafe = true, which is the default. However if you know that the tree is no being modifed for the lifespan of the ValueAccessor AND the work performed per ValueAccessor is small relative to overhead of registering it you should consider setting IsSafe = false. If this improves performance you should really rewrite your code so as to better amortize the construction of the ValueAccessor, i.e. reuse it as much as possible!

Note
  If `MutexType` is a TBB-compatible mutex, then multiple threads may safely access a single, shared accessor. However, it is highly recommended that, instead, each thread be assigned its own, non-mutex-protected accessor.

## Member Typedef Documentation

## BaseT

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

using BaseT = ValueAccessorBase<TreeType, IsSafe>

## LeafNodeT

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

using LeafNodeT = typename TreeType::LeafNodeType

## LockT

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

using LockT = typename MutexType::scoped_lock

## RootNodeT

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

using RootNodeT = typename TreeType::RootNodeType

## TreeType

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

using TreeType = _TreeType

## ValueType

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

using ValueType = typename RootNodeT::ValueType

## Constructor & Destructor Documentation

## ValueAccessor() [1/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

ValueAccessor | ( | TreeType & | tree | ) |

inline

## ValueAccessor() [2/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

ValueAccessor | ( | const ValueAccessor< _TreeType, IsSafe, CacheLevels, MutexType > & | other | ) |

inline

## ~ValueAccessor()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

~ValueAccessor | ( |  | ) |

override default

## Member Function Documentation

## addLeaf()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void addLeaf | ( | LeafNodeT * | leaf | ) |

inline

Add the specified leaf to this tree, possibly creating a child branch in the process. If the leaf node already exists, replace it.

## addTile()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void addTile | ( | Index | level,
|  | const Coord & | xyz,
|  | const ValueType & | value,
|  | bool | state )

inline

Add a tile at the specified tree level that contains voxel (x, y, z), possibly deleting existing nodes or creating new nodes in the process.

## clear()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void clear | ( |  | ) |

inline override virtual

Remove all nodes from this cache, then reinsert the root node.

Implements ValueAccessorBase< _TreeType, true >.

## eraseNode()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename NodeType>

void eraseNode | ( |  | ) |

inline

If a node of the given type exists in the cache, remove it, so that isCached(xyz) returns `false` for any voxel (x, y, z) contained in that node. [Mainly for internal use]

## getNode()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename NodeType>

NodeType * getNode | ( |  | ) |

inline

Return the cached node of type NodeType. [Mainly for internal use].

## getTree()

_TreeType * getTree | ( |  | ) | const

inline inherited

Return a pointer to the tree associated with this accessor.

The pointer will be null only if the tree from which this accessor was constructed was subsequently deleted (which generally leaves the accessor in an unsafe state).

## getValue()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

const ValueType & getValue | ( | const Coord & | xyz | ) | const

inline

Return the value of the voxel at the given coordinates.

## getValueDepth()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

int getValueDepth | ( | const Coord & | xyz | ) | const

inline

Return the tree depth (0 = root) at which the value of voxel (x, y, z) resides, or -1 if (x, y, z) isn't explicitly represented in the tree (i.e., if it is implicitly a background voxel).

## insertNode()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename NodeType>

void insertNode | ( | const Coord & | xyz,
|  | NodeType & | node )

inline

Cache the given node, which should lie along the path from the root node to the node containing voxel (x, y, z). [Mainly for internal use]

## isCached()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

bool isCached | ( | const Coord & | xyz | ) | const

inline

Return `true` if nodes along the path to the given voxel have been cached.

## isSafe()

bool isSafe | ( |  | ) |

inline static inherited

Return true if this accessor is safe, i.e. registered by the tree from which it is constructed. Un-registered accessors can in rare cases be faster because it avoids the (small) overhead of registration, but they are unsafe if the tree is modified. So unless you're an expert it is highly recommended to set IsSafe = true (which is the default).

## isValueOn()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

bool isValueOn | ( | const Coord & | xyz | ) | const

inline

Return the active state of the voxel at the given coordinates.

## isVoxel()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

bool isVoxel | ( | const Coord & | xyz | ) | const

inline

Return `true` if the value of voxel (x, y, z) resides at the leaf level of the tree, i.e., if it is not a tile value.

## modifyValue()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename ModifyOp>

void modifyValue | ( | const Coord & | xyz,
|  | const ModifyOp & | op )

inline

Apply a functor to the value of the voxel at the given coordinates and mark the voxel as active.

See Tree::modifyValue() for details.

## modifyValueAndActiveState()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename ModifyOp>

void modifyValueAndActiveState | ( | const Coord & | xyz,
|  | const ModifyOp & | op )

inline

Apply a functor to the voxel at the given coordinates.

See Tree::modifyValueAndActiveState() for details.

## numCacheLevels()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

Index numCacheLevels | ( |  | ) |

inline static

Return the number of cache levels employed by this accessor.

## operator=()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

ValueAccessor & operator= | ( | const ValueAccessor< _TreeType, IsSafe, CacheLevels, MutexType > & | other | ) |

inline

## probeConstLeaf()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

const LeafNodeT * probeConstLeaf | ( | const Coord & | xyz | ) | const

inline

## probeConstNode()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename NodeT>

const NodeT * probeConstNode | ( | const Coord & | xyz | ) | const

inline

## probeLeaf() [1/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

LeafNodeT * probeLeaf | ( | const Coord & | xyz | ) |

inline

Return a pointer to the leaf node that contains voxel (x, y, z), or `nullptr` if no such node exists.

## probeLeaf() [2/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

const LeafNodeT * probeLeaf | ( | const Coord & | xyz | ) | const

inline

## probeNode() [1/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename NodeT>

NodeT * probeNode | ( | const Coord & | xyz | ) |

inline

Return a pointer to the node of the specified type that contains voxel (x, y, z), or `nullptr` if no such node exists.

## probeNode() [2/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename NodeT>

const NodeT * probeNode | ( | const Coord & | xyz | ) | const

inline

## probeValue()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

bool probeValue | ( | const Coord & | xyz,
|  | ValueType & | value ) const

inline

Return the active state of the voxel as well as its value.

## setActiveState()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void setActiveState | ( | const Coord & | xyz,
|  | bool | on = true )

inline

Set the active state of the voxel at the given coordinates but don't change its value.

## setValue()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void setValue | ( | const Coord & | xyz,
|  | const ValueType & | value )

inline

Set the value of the voxel at the given coordinates and mark the voxel as active.

## setValueOff() [1/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void setValueOff | ( | const Coord & | xyz | ) |

inline

Mark the voxel at the given coordinates as inactive but don't change its value.

## setValueOff() [2/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void setValueOff | ( | const Coord & | xyz,
|  | const ValueType & | value )

inline

Set the value of the voxel at the given coordinates and mark the voxel as inactive.

## setValueOn() [1/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void setValueOn | ( | const Coord & | xyz | ) |

inline

Mark the voxel at the given coordinates as active but don't change its value.

## setValueOn() [2/2]

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void setValueOn | ( | const Coord & | xyz,
|  | const ValueType & | value )

inline

## setValueOnly()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

void setValueOnly | ( | const Coord & | xyz,
|  | const ValueType & | value )

inline

Set the value of the voxel at the given coordinate but don't change its active state.

## touchLeaf()

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

LeafNodeT * touchLeaf | ( | const Coord & | xyz | ) |

inline

Return a pointer to the leaf node that contains voxel (x, y, z). If no such node exists, create one, but preserve the values and active states of all voxels.

Use this method to preallocate a static tree topology over which to safely perform multithreaded processing.

## tree()

_TreeType & tree | ( |  | ) | const

inline inherited

Return a reference to the tree associated with this accessor.

## Friends And Related Symbol Documentation

## InternalNode

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename, Index>

friend class InternalNode

friend

## LeafNode

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename, Index>

friend class LeafNode

friend

## RootNode

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename>

friend class RootNode

friend

## Tree

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>
template<typename>

friend class Tree

friend

## Member Data Documentation

## BypassLeafAPI

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

bool BypassLeafAPI

static constexpr

Initial value:
= CacheLevels >= 1 &&
std::is_same<typename LeafNodeT::Buffer::StorageType, ValueType>::value

## IsConstTree

template<typename _TreeType, bool IsSafe = true, Index CacheLevels = _TreeType::DEPTH-1, typename MutexType = tbb::null_mutex>

const bool IsConstTree

static

## mTree

_TreeType* mTree

protected inherited