OpenVDB  12.0.0
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | Friends | List of all members
ValueAccessorImpl< _TreeType, IsSafe, MutexT, IntegerSequence > Class Template Reference

The Value Accessor Implementation and API methods. The majoirty of the API matches the API of a compatible OpenVDB Tree Node. More...

#include <openvdb/tree/ValueAccessor.h>

Inherits ValueAccessorBase< _TreeType, IsSafe >, ValueAccessorLeafBuffer< _TreeType, IntegerSequence >, and ValueAccessorLock< MutexT >.

Public Types

using BaseT = ValueAccessorBase< _TreeType, IsSafe >
 
using LockT = ValueAccessorLock< MutexT >
 
using LeafCacheT = ValueAccessorLeafBuffer< _TreeType, IntegerSequence >
 
using TreeType = _TreeType
 
using ValueType = typename TreeType::ValueType
 
using RootNodeT = typename TreeType::RootNodeType
 
using LeafNodeT = typename TreeType::LeafNodeType
 
using NodeChainT = typename RootNodeT::NodeChainType
 
using NodeLevelList = typename value_accessor_internal::NodeListBuilder< NodeChainT, RootNodeT::LEVEL, IntegerSequence >::ListT
 A resolved, flattened TypeList of node types which this accessor is caching. The nodes index in this list does not necessarily correspond to the nodes level in the tree. More...
 
using NodePtrList = typename NodeLevelList::template Transform< std::add_pointer_t >
 
template<size_t Level>
using NodeTypeAtLevel = typename NodeLevelList::template Get< Level >
 Return a node type at a particular cache level in the Value accessor. The node type at a given cache level does not necessarily equal the same node type in the TreeType as this depends entirely on which tree levels this Accessor is caching. For example: More...
 
using NodeT0 = typename std::conditional<(NumCacheLevels > 0), NodeTypeAtLevel< 0 >, void >::type
 
using NodeT1 = typename std::conditional<(NumCacheLevels > 1), NodeTypeAtLevel< 1 >, void >::type
 
using NodeT2 = typename std::conditional<(NumCacheLevels > 2), NodeTypeAtLevel< 2 >, void >::type
 

Public Member Functions

 ValueAccessorImpl (TreeType &tree)
 Constructor from a tree. More...
 
 ~ValueAccessorImpl () override final=default
 
 ValueAccessorImpl (const ValueAccessorImpl &)=default
 
ValueAccessorImploperator= (const ValueAccessorImpl &)=default
 
bool isCached (const Coord &xyz) const
 Return true if any of the nodes along the path to the given coordinate have been cached. More...
 
const ValueTypegetValue (const Coord &xyz) const
 Return the value of the voxel at the given coordinates. More...
 
bool isValueOn (const Coord &xyz) const
 Return the active state of the voxel at the given coordinates. More...
 
bool probeValue (const Coord &xyz, ValueType &value) const
 Return the active state of the value at a given coordinate as well as its value. More...
 
int getValueDepth (const Coord &xyz) const
 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). More...
 
bool isVoxel (const Coord &xyz) const
 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. More...
 
void setValueOnly (const Coord &xyz, const ValueType &value)
 Set a particular value at the given coordinate but preserve its active state. More...
 
void setValueOff (const Coord &xyz, const ValueType &value)
 Set a particular value at the given coordinate and mark the coordinate as inactive. More...
 
template<typename ModifyOp >
void modifyValue (const Coord &xyz, const ModifyOp &op)
 Apply a functor to the value at the given coordinate and mark mark the coordinate as active. More...
 
template<typename ModifyOp >
void modifyValueAndActiveState (const Coord &xyz, const ModifyOp &op)
 Apply a functor to the voxel at the given coordinates. More...
 
void setActiveState (const Coord &xyz, bool on=true)
 Set the active state of the voxel at the given coordinates without changing its value. More...
 
void setValueOn (const Coord &xyz)
 Mark the voxel at the given coordinates as active without changing its value. More...
 
void setValueOff (const Coord &xyz)
 Mark the voxel at the given coordinates as inactive without changing its value. More...
 
LeafNodeTtouchLeaf (const Coord &xyz)
 Returns the leaf node that contains voxel (x, y, z) and if it doesn't exist, create it, but preserve the values and active states of the pre-existing branch. More...
 
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. More...
 
void addTile (Index level, const Coord &xyz, const ValueType &value, bool state)
 Add a tile at the specified tree level that contains the coordinate xyz, possibly deleting existing nodes or creating new nodes in the process. More...
 
template<typename NodeT >
NodeT * getNode ()
 Return the node of type NodeT that has been cached on this accessor. If this accessor does not cache this NodeT, or if no node of this type has been cached, returns a nullptr. More...
 
template<typename NodeT >
void insertNode (const Coord &xyz, NodeT &node)
 Explicitly insert a node of the type NodeT into this Value Accessors cache. More...
 
template<typename NodeT >
void eraseNode ()
 Explicitly remove this Value Accessors cached node of the given NodeT. If this Value Accessor does not support the caching of the provided NodeT, this method does nothing. More...
 
void clear () override final
 Remove all the cached nodes and invalidate the corresponding hash-keys. More...
 
_TreeType * getTree () const
 Return a pointer to the tree associated with this accessor. More...
 
_TreeType & tree () const
 Return a reference to the tree associated with this accessor. More...
 
const _TreeType::ValueType * buffer ()
 
const _TreeType::ValueType * buffer () const
 
void setBuffer (const typename _TreeType::ValueType *b) const
 
auto lock () const
 
void setValue (const Coord &xyz, const ValueType &value)
 Set a particular value at the given coordinate and mark the coordinate as active. More...
 
void setValueOn (const Coord &xyz, const ValueType &value)
 Set a particular value at the given coordinate and mark the coordinate as active. More...
 
template<typename NodeT >
NodeT * probeNode (const Coord &xyz)
 Return a pointer to the node of the specified type that contains the value located at xyz. If no node of the given NodeT exists which contains the value, a nullptr is returned. More...
 
template<typename NodeT >
const NodeT * probeConstNode (const Coord &xyz) const
 Return a pointer to the node of the specified type that contains the value located at xyz. If no node of the given NodeT exists which contains the value, a nullptr is returned. More...
 
LeafNodeTprobeLeaf (const Coord &xyz)
 Return a pointer to the leaf node that contains the voxel coordinate xyz. If no LeafNode exists, returns a nullptr. More...
 
const LeafNodeTprobeLeaf (const Coord &xyz) const
 Return a pointer to the leaf node that contains the voxel coordinate xyz. If no LeafNode exists, returns a nullptr. More...
 
const LeafNodeTprobeConstLeaf (const Coord &xyz) const
 Return a pointer to the leaf node that contains the voxel coordinate xyz. If no LeafNode exists, returns a nullptr. More...
 

Static Public Member Functions

static constexpr Index numCacheLevels ()
 Return the number of cache levels employed by this ValueAccessor. More...
 
static constexpr 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). More...
 

Static Public Attributes

template<typename NodeT >
static constexpr bool IsLeafAndBypassLeafAPI
 Given a node type, return whether this Accessor can perform optimized value buffer accesses. This is only possible for LeafNodes so will always return false for any non LeafNode type. It also depends on the value type - if the value buffer is a contiguous index-able array of values then this returns true. More...
 
static constexpr bool BypassLeafAPI
 Helper alias which is true if the lowest cached node level is a LeafNode type and has a compatible value type for optimized access. More...
 
static constexpr size_t NumCacheLevels = NodeLevelList::Size-1
 The number of node levels that this accessor can cache, excluding the RootNode. More...
 
static constexpr bool IsConstTree
 Returns true if this accessor is operating on a const tree type. More...
 

Protected Member Functions

void release () override final
 Release this accessor from the tree, set the tree to null and clear the accessor cache. After calling this method the accessor will be completely invalid. More...
 
template<typename NodeT >
OPENVDB_FORCE_INLINE void insert ([[maybe_unused]] const Coord &xyz, [[maybe_unused]] const NodeT *node) const
 Insert a node into this ValueAccessor's cache. More...
 
template<typename NodeT >
OPENVDB_FORCE_INLINE bool isHashed ([[maybe_unused]] const Coord &xyz) const
 

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, typename MutexT, typename IntegerSequence>
class openvdb::v12_0::tree::ValueAccessorImpl< _TreeType, IsSafe, MutexT, IntegerSequence >

The Value Accessor Implementation and API methods. The majoirty of the API matches the API of a compatible OpenVDB Tree Node.

Member Typedef Documentation

using BaseT = ValueAccessorBase<_TreeType, IsSafe>
Note
Not strictly the only Base Type but provided for backwards compatibility.
using LeafCacheT = ValueAccessorLeafBuffer<_TreeType, IntegerSequence>
using LeafNodeT = typename TreeType::LeafNodeType
using LockT = ValueAccessorLock<MutexT>
using NodeChainT = typename RootNodeT::NodeChainType
using NodeLevelList = typename value_accessor_internal::NodeListBuilder <NodeChainT, RootNodeT::LEVEL, IntegerSequence>::ListT

A resolved, flattened TypeList of node types which this accessor is caching. The nodes index in this list does not necessarily correspond to the nodes level in the tree.

using NodePtrList = typename NodeLevelList::template Transform<std::add_pointer_t>
using NodeT0 = typename std::conditional<(NumCacheLevels > 0), NodeTypeAtLevel<0>, void>::type
using NodeT1 = typename std::conditional<(NumCacheLevels > 1), NodeTypeAtLevel<1>, void>::type
using NodeT2 = typename std::conditional<(NumCacheLevels > 2), NodeTypeAtLevel<2>, void>::type
using NodeTypeAtLevel = typename NodeLevelList::template Get<Level>

Return a node type at a particular cache level in the Value accessor. The node type at a given cache level does not necessarily equal the same node type in the TreeType as this depends entirely on which tree levels this Accessor is caching. For example:

Example:
// Cache tree levels 0 and 2
using Impl = ValueAccessorImpl<FloatTree, true, void, 0, 2>
using CacheLevel1 = Impl::template NodeTypeAtLevel<1>
using TreeLevel2 = TreeType::RootNodeType::NodeChainType::Get<2>;
static_assert(std::is_same<CacheLevel1, TreeLevel2>::value);
using RootNodeT = typename TreeType::RootNodeType
using TreeType = _TreeType
using ValueType = typename TreeType::ValueType

Constructor & Destructor Documentation

ValueAccessorImpl ( TreeType tree)
inline

Constructor from a tree.

~ValueAccessorImpl ( )
finaloverridedefault
ValueAccessorImpl ( const ValueAccessorImpl< _TreeType, IsSafe, MutexT, IntegerSequence > &  )
default

Member Function Documentation

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.

Parameters
leafThe LeafNode to insert into the tree. Must not be a nullptr.
void addTile ( Index  level,
const Coord &  xyz,
const ValueType value,
bool  state 
)
inline

Add a tile at the specified tree level that contains the coordinate xyz, possibly deleting existing nodes or creating new nodes in the process.

Note
Calling this with a level of 0 will modify voxel values. This function will always densify a tree branch up to the requested level (regardless if the value and active state match).
Parameters
levelThe level of the tree to add a tile. Level 0 refers to voxels (and is similar to ::setValue, except will always density).
xyzThe index space coordinate to add a tile
valueThe value of the tile
stateThe active state to set on the new tile
const _TreeType ::ValueType* buffer ( )
inlineinherited
const _TreeType ::ValueType* buffer ( ) const
inlineinherited
void clear ( )
inlinefinaloverridevirtual

Remove all the cached nodes and invalidate the corresponding hash-keys.

Implements ValueAccessorBase< _TreeType, IsSafe >.

void eraseNode ( )
inline

Explicitly remove this Value Accessors cached node of the given NodeT. If this Value Accessor does not support the caching of the provided NodeT, this method does nothing.

NodeT* getNode ( )
inline

Return the node of type NodeT that has been cached on this accessor. If this accessor does not cache this NodeT, or if no node of this type has been cached, returns a nullptr.

_TreeType * getTree ( ) const
inlineinherited

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).

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

Return the value of the voxel at the given coordinates.

Parameters
xyzThe index space coordinate to query
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).

Note
This is the inverse of the node LEVEL (where the RootNode level is the highest in the tree).
Parameters
xyzThe index space coordinate to query
OPENVDB_FORCE_INLINE void insert ( [[maybe_unused] ] const Coord &  xyz,
[[maybe_unused] ] const NodeT *  node 
) const
inlineprotected

Insert a node into this ValueAccessor's cache.

******************************* WARNING ******************************* Methods here must be force inline otherwise compilers do not optimize out the function call due to recursive templates and performance degradation is significant.


void insertNode ( const Coord &  xyz,
NodeT &  node 
)
inline

Explicitly insert a node of the type NodeT into this Value Accessors cache.

bool isCached ( const Coord &  xyz) const
inline

Return true if any of the nodes along the path to the given coordinate have been cached.

Parameters
xyzThe index space coordinate to query
OPENVDB_FORCE_INLINE bool isHashed ( [[maybe_unused] ] const Coord &  xyz) const
inlineprotected
static constexpr bool isSafe ( )
inlinestaticinherited

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).

bool isValueOn ( const Coord &  xyz) const
inline

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

Parameters
xyzThe index space coordinate to query
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.

Parameters
xyzThe index space coordinate to query
auto lock ( ) const
inlineinherited
void modifyValue ( const Coord &  xyz,
const ModifyOp &  op 
)
inline

Apply a functor to the value at the given coordinate and mark mark the coordinate as active.

See Tree::modifyValue() for details.

Parameters
xyzThe index space coordinate to modify
opThe modify operation
void modifyValueAndActiveState ( const Coord &  xyz,
const ModifyOp &  op 
)
inline

Apply a functor to the voxel at the given coordinates.

See Tree::modifyValueAndActiveState() for details.

Parameters
xyzThe index space coordinate to modify
opThe modify operation
static constexpr Index numCacheLevels ( )
inlinestatic

Return the number of cache levels employed by this ValueAccessor.

Deprecated:
"Use the static NumCacheLevels constant"
ValueAccessorImpl& operator= ( const ValueAccessorImpl< _TreeType, IsSafe, MutexT, IntegerSequence > &  )
default
const LeafNodeT* probeConstLeaf ( const Coord &  xyz) const
inline

Return a pointer to the leaf node that contains the voxel coordinate xyz. If no LeafNode exists, returns a nullptr.

Parameters
xyzThe index space coordinate to query
const NodeT* probeConstNode ( const Coord &  xyz) const
inline

Return a pointer to the node of the specified type that contains the value located at xyz. If no node of the given NodeT exists which contains the value, a nullptr is returned.

This function may return a nullptr even if the coordinate xyz is represented in tree, as it depends on the type NodeT provided. For example, the value may exist as a tile in an InternalNode but note as a LeafNode.

Parameters
xyzThe index space coordinate to query
LeafNodeT* probeLeaf ( const Coord &  xyz)
inline

Return a pointer to the leaf node that contains the voxel coordinate xyz. If no LeafNode exists, returns a nullptr.

Parameters
xyzThe index space coordinate to query
const LeafNodeT* probeLeaf ( const Coord &  xyz) const
inline

Return a pointer to the leaf node that contains the voxel coordinate xyz. If no LeafNode exists, returns a nullptr.

Parameters
xyzThe index space coordinate to query
NodeT* probeNode ( const Coord &  xyz)
inline

Return a pointer to the node of the specified type that contains the value located at xyz. If no node of the given NodeT exists which contains the value, a nullptr is returned.

This function may return a nullptr even if the coordinate xyz is represented in tree, as it depends on the type NodeT provided. For example, the value may exist as a tile in an InternalNode but note as a LeafNode.

Parameters
xyzThe index space coordinate to query
bool probeValue ( const Coord &  xyz,
ValueType value 
) const
inline

Return the active state of the value at a given coordinate as well as its value.

Parameters
xyzThe index space coordinate to query
valueThe value to get
void release ( )
inlinefinaloverrideprotectedvirtual

Release this accessor from the tree, set the tree to null and clear the accessor cache. After calling this method the accessor will be completely invalid.

Reimplemented from ValueAccessorBase< _TreeType, IsSafe >.

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

Set the active state of the voxel at the given coordinates without changing its value.

Note
This method will densify branches of the tree if the coordinate points to a tile and if the provided activate state flag is different to the tiles
Parameters
xyzThe index space coordinate to modify
onWhether to set the active state to on (true) or off (false)
void setBuffer ( const typename _TreeType ::ValueType *  b) const
inlineinherited
void setValue ( const Coord &  xyz,
const ValueType value 
)
inline

Set a particular value at the given coordinate and mark the coordinate as active.

Note
This method will densify branches of the tree if the coordinate points to a tile and if the provided value or active state is different to the tiles
Parameters
xyzThe index space coordinate to set
valueThe value to set
void setValueOff ( const Coord &  xyz,
const ValueType value 
)
inline

Set a particular value at the given coordinate and mark the coordinate as inactive.

Note
This method will densify branches of the tree if the coordinate points to a tile and if the provided value or active state is different to the tiles
Parameters
xyzThe index space coordinate to set
valueThe value to set
void setValueOff ( const Coord &  xyz)
inline

Mark the voxel at the given coordinates as inactive without changing its value.

Note
This method will densify branches of the tree if the coordinate points to a tile and if the tiles active state is on.
Parameters
xyzThe index space coordinate to modify
void setValueOn ( const Coord &  xyz,
const ValueType value 
)
inline

Set a particular value at the given coordinate and mark the coordinate as active.

Note
This method will densify branches of the tree if the coordinate points to a tile and if the provided value or active state is different to the tiles
Parameters
xyzThe index space coordinate to set
valueThe value to set
void setValueOn ( const Coord &  xyz)
inline

Mark the voxel at the given coordinates as active without changing its value.

Note
This method will densify branches of the tree if the coordinate points to a tile and if the tiles active state is off.
Parameters
xyzThe index space coordinate to modify
void setValueOnly ( const Coord &  xyz,
const ValueType value 
)
inline

Set a particular value at the given coordinate but preserve its active state.

Note
This method will densify branches of the tree if the coordinate points to a tile and if the provided value is different to the tiles
Parameters
xyzThe index space coordinate to set
valueThe value to set
LeafNodeT* touchLeaf ( const Coord &  xyz)
inline

Returns the leaf node that contains voxel (x, y, z) and if it doesn't exist, create it, but preserve the values and active states of the pre-existing branch.

Note
You can use this method to preallocate a static tree topology over which to safely perform multithreaded processing.
Parameters
xyzThe index space coordinate at which to create a LeafNode. Note that if this coordinate is not a LeafNode origin then the LeafNode that would otherwise contain this coordinate is created and returned.
_TreeType & tree ( ) const
inlineinherited

Return a reference to the tree associated with this accessor.

Friends And Related Function Documentation

friend class InternalNode
friend
friend class LeafNode
friend
friend class RootNode
friend
friend class Tree
friend

Member Data Documentation

constexpr bool BypassLeafAPI
static
Initial value:
=
IsLeafAndBypassLeafAPI<NodeTypeAtLevel<0>>

Helper alias which is true if the lowest cached node level is a LeafNode type and has a compatible value type for optimized access.

constexpr bool IsConstTree
staticinherited

Returns true if this accessor is operating on a const tree type.

constexpr bool IsLeafAndBypassLeafAPI
static
Initial value:
=
LeafCacheT::template BypassLeafAPI<NodeT>

Given a node type, return whether this Accessor can perform optimized value buffer accesses. This is only possible for LeafNodes so will always return false for any non LeafNode type. It also depends on the value type - if the value buffer is a contiguous index-able array of values then this returns true.

_TreeType * mTree
protectedinherited
constexpr size_t NumCacheLevels = NodeLevelList::Size-1
static

The number of node levels that this accessor can cache, excluding the RootNode.