This class manages a linear array of pointers to a given tree's leaf nodes, as well as optional auxiliary buffers (one or more per leaf) that can be swapped with the leaf nodes' voxel data buffers. More...

#include <LeafManager.h>

Classes
class	LeafRange

Public Types
using	TreeType = TreeT

using	ValueType = typename TreeT::ValueType

using	RootNodeType = typename TreeT::RootNodeType

using	NonConstLeafType = typename TreeType::LeafNodeType

using	LeafType = typename CopyConstness< TreeType, NonConstLeafType >::Type

using	LeafNodeType = LeafType

using	LeafIterType = typename leafmgr::TreeTraits< TreeT >::LeafIterType

using	NonConstBufferType = typename LeafType::Buffer

using	BufferType = typename CopyConstness< TreeType, NonConstBufferType >::Type

using	RangeType = tbb::blocked_range< size_t >

Public Member Functions
	LeafManager (TreeType &tree, size_t auxBuffersPerLeaf=0, bool serial=false)
	Constructor from a tree reference and an auxiliary buffer count. More...

	LeafManager (TreeType &tree, LeafType begin, LeafType end, size_t auxBuffersPerLeaf=0, bool serial=false)
	Construct directly from an existing array of leafnodes. More...

	LeafManager (const LeafManager &other)

void	rebuild (bool serial=false)
	(Re)initialize by resizing (if necessary) and repopulating the leaf array and by deleting existing auxiliary buffers and allocating new ones. More...

void	rebuildAuxBuffers (size_t auxBuffersPerLeaf, bool serial=false)
	Change the number of auxiliary buffers. More...

void	removeAuxBuffers ()
	Remove the auxiliary buffers, but don't rebuild the leaf array. More...

void	rebuildLeafArray (bool serial=false)
	Remove the auxiliary buffers and rebuild the leaf array. More...

size_t	auxBufferCount () const
	Return the total number of allocated auxiliary buffers. More...

size_t	auxBuffersPerLeaf () const
	Return the number of auxiliary buffers per leaf node. More...

size_t	leafCount () const
	Return the number of leaf nodes. More...

Index64	activeLeafVoxelCount () const
	Return the number of active voxels in the leaf nodes. More...

const TreeType &	tree () const
	Return a const reference to tree associated with this manager. More...

TreeType &	tree ()
	Return a reference to the tree associated with this manager. More...

const RootNodeType &	root () const
	Return a const reference to root node associated with this manager. More...

RootNodeType &	root ()
	Return a reference to the root node associated with this manager. More...

bool	isConstTree () const
	Return `true` if the tree associated with this manager is immutable. More...

LeafType &	leaf (size_t leafIdx) const
	Return a pointer to the leaf node at index leafIdx in the array. More...

BufferType &	getBuffer (size_t leafIdx, size_t bufferIdx) const
	Return the leaf or auxiliary buffer for the leaf node at index leafIdx. If bufferIdx is zero, return the leaf buffer, otherwise return the nth auxiliary buffer, where n = bufferIdx - 1. More...

RangeType	getRange (size_t grainsize=1) const
	Return a `tbb::blocked_range` of leaf array indices. More...

LeafRange	leafRange (size_t grainsize=1) const
	Return a TBB-compatible LeafRange. More...

bool	swapLeafBuffer (size_t bufferIdx, bool serial=false)
	Swap each leaf node's buffer with the nth corresponding auxiliary buffer, where n = bufferIdx. More...

bool	swapBuffer (size_t bufferIdx1, size_t bufferIdx2, bool serial=false)
	Swap any two buffers for each leaf node. More...

bool	syncAuxBuffer (size_t bufferIdx, bool serial=false)
	Sync up the specified auxiliary buffer with the corresponding leaf node buffer. More...

bool	syncAllBuffers (bool serial=false)
	Sync up all auxiliary buffers with their corresponding leaf node buffers. More...

template<typename LeafOp >
void	foreach (const LeafOp &op, bool threaded=true, size_t grainSize=1)
	Threaded method that applies a user-supplied functor to each leaf node in the LeafManager. More...

template<typename LeafOp >
void	reduce (LeafOp &op, bool threaded=true, size_t grainSize=1)
	Threaded method that applies a user-supplied functor to each leaf node in the LeafManager. Unlike foreach (defined above) this method performs a reduction on all the leaf nodes. More...

size_t	getPrefixSum (size_t *&offsets, size_t &size, size_t grainSize=1) const
	Generate a linear array of prefix sums of offsets into the active voxels in the leafs. So offsets[n]+m is the offset to the mth active voxel in the nth leaf node (useful for user-managed value buffers, e.g. in tools/LevelSetAdvect.h). More...

void	operator() (const RangeType &r) const
	Used internally by tbb::parallel_for() - never call it directly! More...


void	rebuild (size_t auxBuffersPerLeaf, bool serial=false)
	Repopulate the leaf array and delete and reallocate auxiliary buffers. More...

void	rebuild (TreeType &tree, bool serial=false)
	Repopulate the leaf array and delete and reallocate auxiliary buffers. More...

void	rebuild (TreeType &tree, size_t auxBuffersPerLeaf, bool serial=false)
	Repopulate the leaf array and delete and reallocate auxiliary buffers. More...

Static Public Attributes
static const Index	DEPTH = 2

static const bool	IsConstTree = leafmgr::TreeTraits<TreeT>::IsConstTree

Detailed Description

template<typename TreeT>
class openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >

This class manages a linear array of pointers to a given tree's leaf nodes, as well as optional auxiliary buffers (one or more per leaf) that can be swapped with the leaf nodes' voxel data buffers.

The leaf array is useful for multithreaded computations over leaf voxels in a tree with static topology but varying voxel values. The auxiliary buffers are convenient for temporal integration. Efficient methods are provided for multithreaded swapping and sync'ing (i.e., copying the contents) of these buffers.

Note: Buffer index 0 denotes a leaf node's internal voxel data buffer. Any auxiliary buffers are indexed starting from one.

Definition at line 84 of file LeafManager.h.

Member Typedef Documentation

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::BufferType = typename CopyConstness<TreeType, NonConstBufferType>::Type

Definition at line 95 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::LeafIterType = typename leafmgr::TreeTraits<TreeT>::LeafIterType

Definition at line 93 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::LeafNodeType = LeafType

Definition at line 92 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::LeafType = typename CopyConstness<TreeType, NonConstLeafType>::Type

Definition at line 91 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::NonConstBufferType = typename LeafType::Buffer

Definition at line 94 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::NonConstLeafType = typename TreeType::LeafNodeType

Definition at line 90 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::RangeType = tbb::blocked_range<size_t>

Definition at line 96 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::RootNodeType = typename TreeT::RootNodeType

Definition at line 89 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::TreeType = TreeT

Definition at line 87 of file LeafManager.h.

template<typename TreeT>

using openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::ValueType = typename TreeT::ValueType

Definition at line 88 of file LeafManager.h.

Constructor & Destructor Documentation

template<typename TreeT>

openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::LeafManager	(	TreeType &	tree,
		size_t	auxBuffersPerLeaf = `0`,
		bool	serial = `false`
	)

inline

Constructor from a tree reference and an auxiliary buffer count.

Note: The default is no auxiliary buffers

Definition at line 192 of file LeafManager.h.

template<typename TreeT>

openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::LeafManager	(	TreeType &	tree,
		LeafType **	begin,
		LeafType **	end,
		size_t	auxBuffersPerLeaf = `0`,
		bool	serial = `false`
	)

inline

Construct directly from an existing array of leafnodes.

Warning: The leafnodes are implicitly assumed to exist in the input tree.

Definition at line 204 of file LeafManager.h.

template<typename TreeT>

openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::LeafManager ( const LeafManager< TreeT > & other )

inline

Shallow copy constructor called by tbb::parallel_for() threads

Note: This should never get called directly

Definition at line 222 of file LeafManager.h.

Member Function Documentation

template<typename TreeT>

Index64 openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::activeLeafVoxelCount ( ) const

inline

Return the number of active voxels in the leaf nodes.

Note: Multi-threaded for better performance than Tree::activeLeafVoxelCount

Definition at line 291 of file LeafManager.h.

template<typename TreeT>

size_t openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::auxBufferCount ( ) const

inline

Return the total number of allocated auxiliary buffers.

Definition at line 282 of file LeafManager.h.

template<typename TreeT>

size_t openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::auxBuffersPerLeaf ( ) const

inline

Return the number of auxiliary buffers per leaf node.

Definition at line 284 of file LeafManager.h.

template<typename TreeT>

template<typename LeafOp >

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::foreach	(	const LeafOp &	op,
		bool	threaded = `true`,
		size_t	grainSize = `1`
	)

inline

Threaded method that applies a user-supplied functor to each leaf node in the LeafManager.

The user-supplied functor needs to define the methods required for tbb::parallel_for.

Parameters

op	user-supplied functor, see examples for interface details.
threaded	optional toggle to disable threading, on by default.
grainSize	optional parameter to specify the grainsize for threading, one by default.

Warning: The functor object is deep-copied to create TBB tasks. This allows the function to use non-thread-safe members like a ValueAccessor.

Example:: // Functor to offset a tree's voxel values with values from another tree.

template<typename TreeType>

struct OffsetOp

{

using Accessor = tree::ValueAccessor<const TreeType>;

OffsetOp(const TreeType& tree): mRhsTreeAcc(tree) {}

template <typename LeafNodeType>

void operator()(LeafNodeType &lhsLeaf, size_t) const

{

const LeafNodeType *rhsLeaf = mRhsTreeAcc.probeConstLeaf(lhsLeaf.origin());

if (rhsLeaf) {

typename LeafNodeType::ValueOnIter iter = lhsLeaf.beginValueOn();

for (; iter; ++iter) {

iter.setValue(iter.getValue() + rhsLeaf->getValue(iter.pos()));

}

}

}

Accessor mRhsTreeAcc;

};

// usage:

tree::LeafManager<FloatTree> leafNodes(lhsTree);

leafNodes.foreach(OffsetOp<FloatTree>(rhsTree));

// A functor that performs a min operation between different auxiliary buffers.

template<typename LeafManagerType>

struct MinOp

{

using BufferType = typename LeafManagerType::BufferType;

MinOp(LeafManagerType& leafNodes): mLeafs(leafNodes) {}

template <typename LeafNodeType>

void operator()(LeafNodeType &leaf, size_t leafIndex) const

{

// get the first buffer

BufferType& buffer = mLeafs.getBuffer(leafIndex, 1);

// min ...

}

LeafManagerType& mLeafs;

};

Definition at line 483 of file LeafManager.h.

template<typename TreeT>

BufferType& openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::getBuffer	(	size_t	leafIdx,
		size_t	bufferIdx
	)		const

inline

Return the leaf or auxiliary buffer for the leaf node at index leafIdx. If bufferIdx is zero, return the leaf buffer, otherwise return the nth auxiliary buffer, where n = bufferIdx - 1.

Note: For performance reasons no range checks are performed on the inputs (other than assertions)! Since auxiliary buffers, unlike leaf buffers, might not exist, be especially careful when specifying the bufferIdx.; For const trees, this method always returns a reference to a const buffer. It is safe to const_cast and modify any auxiliary buffer (bufferIdx > 0), but it is not safe to modify the leaf buffer (bufferIdx = 0).

Definition at line 330 of file LeafManager.h.

template<typename TreeT>

size_t openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::getPrefixSum	(	size_t *&	offsets,
		size_t &	size,
		size_t	grainSize = `1`
	)		const

inline

Generate a linear array of prefix sums of offsets into the active voxels in the leafs. So offsets[n]+m is the offset to the mth active voxel in the nth leaf node (useful for user-managed value buffers, e.g. in tools/LevelSetAdvect.h).

Returns: The total number of active values in the leaf nodes

Parameters

offsets	array of prefix sums of offsets to active voxels
size	on input, the size of offsets; on output, its new size
grainSize	optional grain size for threading

If offsets is nullptr or size is smaller than the total number of active voxels (the return value) then offsets is reallocated and size equals the total number of active voxels.

Definition at line 549 of file LeafManager.h.

template<typename TreeT>

RangeType openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::getRange ( size_t grainsize = 1 ) const

inline

Return a tbb::blocked_range of leaf array indices.

Note: Consider using leafRange() instead, which provides access methods to leaf nodes and buffers.

Definition at line 342 of file LeafManager.h.

template<typename TreeT>

bool openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::isConstTree ( ) const

inline

Return true if the tree associated with this manager is immutable.

Definition at line 314 of file LeafManager.h.

template<typename TreeT>

LeafType& openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::leaf ( size_t leafIdx ) const

inline

Return a pointer to the leaf node at index leafIdx in the array.

Note: For performance reasons no range check is performed (other than an assertion)!

Definition at line 318 of file LeafManager.h.

template<typename TreeT>

size_t openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::leafCount ( ) const

inline

Return the number of leaf nodes.

Definition at line 287 of file LeafManager.h.

template<typename TreeT>

LeafRange openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::leafRange ( size_t grainsize = 1 ) const

inline

Return a TBB-compatible LeafRange.

Definition at line 345 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::operator() ( const RangeType & r ) const

inline

Used internally by tbb::parallel_for() - never call it directly!

Definition at line 572 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::rebuild ( bool serial = false )

inline

(Re)initialize by resizing (if necessary) and repopulating the leaf array and by deleting existing auxiliary buffers and allocating new ones.

Call this method if the tree's topology, and therefore the number of leaf nodes, changes. New auxiliary buffers are initialized with copies of corresponding leaf node buffers.

Definition at line 238 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::rebuild	(	size_t	auxBuffersPerLeaf,
		bool	serial = `false`
	)

inline

Repopulate the leaf array and delete and reallocate auxiliary buffers.

Definition at line 245 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::rebuild	(	TreeType &	tree,
		bool	serial = `false`
	)

inline

Repopulate the leaf array and delete and reallocate auxiliary buffers.

Definition at line 250 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::rebuild	(	TreeType &	tree,
		size_t	auxBuffersPerLeaf,
		bool	serial = `false`
	)

inline

Repopulate the leaf array and delete and reallocate auxiliary buffers.

Definition at line 255 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::rebuildAuxBuffers	(	size_t	auxBuffersPerLeaf,
		bool	serial = `false`
	)

inline

Change the number of auxiliary buffers.

If auxBuffersPerLeaf is 0, all existing auxiliary buffers are deleted. New auxiliary buffers are initialized with copies of corresponding leaf node buffers. This method does not rebuild the leaf array.

Definition at line 266 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::rebuildLeafArray ( bool serial = false )

inline

Remove the auxiliary buffers and rebuild the leaf array.

Definition at line 275 of file LeafManager.h.

template<typename TreeT>

template<typename LeafOp >

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::reduce	(	LeafOp &	op,
		bool	threaded = `true`,
		size_t	grainSize = `1`
	)

inline

Threaded method that applies a user-supplied functor to each leaf node in the LeafManager. Unlike foreach (defined above) this method performs a reduction on all the leaf nodes.

The user-supplied functor needs to define the methods required for tbb::parallel_reduce.

Parameters

op	user-supplied functor, see examples for interface details.
threaded	optional toggle to disable threading, on by default.
grainSize	optional parameter to specify the grainsize for threading, one by default.

Warning: The functor object is deep-copied to create TBB tasks. This allows the function to use non-thread-safe members like a ValueAccessor.

Example:: // Functor to count the number of negative (active) leaf values

struct CountOp

{

CountOp() : mCounter(0) {}

CountOp(const CountOp &other) : mCounter(other.mCounter) {}

CountOp(const CountOp &other, tbb::split) : mCounter(0) {}

template <typename LeafNodeType>

void operator()(LeafNodeType &leaf, size_t)

{

typename LeafNodeType::ValueOnIter iter = leaf.beginValueOn();

for (; iter; ++iter) if (*iter < 0.0f) ++mCounter;

}

void join(const CountOp &other) {mCounter += other.mCounter;}

size_t mCounter;

};

// usage:

tree::LeafManager<FloatTree> leafNodes(tree);

MinValueOp min;

leafNodes.reduce(min);

std::cerr << "Number of negative active voxels = " << min.mCounter << std::endl;

Definition at line 532 of file LeafManager.h.

template<typename TreeT>

void openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::removeAuxBuffers ( )

inline

Remove the auxiliary buffers, but don't rebuild the leaf array.

Definition at line 272 of file LeafManager.h.

template<typename TreeT>

const RootNodeType& openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::root ( ) const

inline

Return a const reference to root node associated with this manager.

Definition at line 308 of file LeafManager.h.

template<typename TreeT>

RootNodeType& openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::root ( )

inline

Return a reference to the root node associated with this manager.

Definition at line 311 of file LeafManager.h.

template<typename TreeT>

bool openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::swapBuffer	(	size_t	bufferIdx1,
		size_t	bufferIdx2,
		bool	serial = `false`
	)

inline

Swap any two buffers for each leaf node.

Note: Recall that the indexing of auxiliary buffers is 1-based, since buffer index 0 denotes the leaf node buffer. So buffer index 1 denotes the first auxiliary buffer.

Definition at line 371 of file LeafManager.h.

template<typename TreeT>

bool openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::swapLeafBuffer	(	size_t	bufferIdx,
		bool	serial = `false`
	)

inline

Swap each leaf node's buffer with the nth corresponding auxiliary buffer, where n = bufferIdx.

Returns: true if the swap was successful

Parameters

bufferIdx	index of the buffer that will be swapped with the corresponding leaf node buffer
serial	if false, swap buffers in parallel using multiple threads.

Note: Recall that the indexing of auxiliary buffers is 1-based, since buffer index 0 denotes the leaf node buffer. So buffer index 1 denotes the first auxiliary buffer.

Definition at line 359 of file LeafManager.h.

template<typename TreeT>

bool openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::syncAllBuffers ( bool serial = false )

inline

Sync up all auxiliary buffers with their corresponding leaf node buffers.

Returns: true if the sync was successful

Parameters

serial if false, sync buffers in parallel using multiple threads.

Definition at line 407 of file LeafManager.h.

template<typename TreeT>

bool openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::syncAuxBuffer	(	size_t	bufferIdx,
		bool	serial = `false`
	)

inline

Sync up the specified auxiliary buffer with the corresponding leaf node buffer.

Returns: true if the sync was successful

Parameters

bufferIdx	index of the buffer that will contain a copy of the corresponding leaf node buffer
serial	if false, sync buffers in parallel using multiple threads.

Note: Recall that the indexing of auxiliary buffers is 1-based, since buffer index 0 denotes the leaf node buffer. So buffer index 1 denotes the first auxiliary buffer.

Definition at line 395 of file LeafManager.h.

template<typename TreeT>

const TreeType& openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::tree ( ) const

inline

Return a const reference to tree associated with this manager.

Definition at line 302 of file LeafManager.h.

template<typename TreeT>

TreeType& openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::tree ( )

inline

Return a reference to the tree associated with this manager.

Definition at line 305 of file LeafManager.h.

Member Data Documentation

template<typename TreeT>

const Index openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::DEPTH = 2

static

Definition at line 97 of file LeafManager.h.

template<typename TreeT>

const bool openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >::IsConstTree = leafmgr::TreeTraits<TreeT>::IsConstTree

static

Definition at line 99 of file LeafManager.h.

The documentation for this class was generated from the following file:

openvdb/tree/LeafManager.h

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

template<typename TreeT> class openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename TreeT>
class openvdb::OPENVDB_VERSION_NAME::tree::LeafManager< TreeT >