Object that encapsulates compiled AX code which can be executed on a collection of VDB volume grids. Executables are created by the compiler and hold the final immutable JIT compiled function and context. More...

#include <openvdb_ax/compiler/VolumeExecutable.h>

Public Types
enum	Streaming { ON, OFF, AUTO }
	The streaming type of active tiles during execution. More...

enum	IterType { ON, OFF, ALL }

using	Ptr = std::shared_ptr< VolumeExecutable >

Public Member Functions
	~VolumeExecutable ()

	VolumeExecutable (const VolumeExecutable &other)
	Copy constructor. Shares the LLVM constructs but deep copies the settings. Multiple copies of an executor can be used at the same time safely. More...

void	setCreateMissing (const bool flag)
	Set the behaviour when missing grids are accessed. Default behaviour is true, which creates them with default transforms and background values. More...

bool	getCreateMissing () const

void	setTreeExecutionLevel (const Index min, const Index max)
	Set the execution level for this executable. This controls what nodes are processed when execute is called. Possible values depend on the OpenVDB configuration in use, however a value of 0 will always correspond to the lowest level (leaf-level). By default, the min level is zero (LeafNodeType::LEVEL) and the max level is the root node's level (RootNodeType::LEVEL). In other words, the default execution level settings process the whole of the tree. More...

void	setTreeExecutionLevel (const Index level)

void	getTreeExecutionLevel (Index &min, Index &max) const
	Get the tree execution levels. More...

void	setActiveTileStreaming (const Streaming &s)
	Controls the behaviour of expansion of active tiles. More...

Streaming	getActiveTileStreaming () const

Streaming	getActiveTileStreaming (const std::string &name, const ast::tokens::CoreType &type) const

void	setValueIterator (const IterType &iter)
	Set the value iterator type to use with this executable. Options are ON, OFF, ALL. Default is ON. More...

IterType	getValueIterator () const

Index	getTreeExecutionLevel () const

void	setAttributeBindings (const AttributeBindings &bindings)
	Set attribute bindings. More...

const AttributeBindings &	getAttributeBindings () const


void	execute (openvdb::GridPtrVec &grids) const
	Run this volume executable binary on target volumes. More...

void	execute (openvdb::GridBase &grids) const
	Run this volume executable binary on target volumes. More...


void	setGrainSize (const size_t g1)
	Set the threading grain sizes used when iterating over nodes in a VDB. More...

void	setActiveTileStreamingGrainSize (const size_t g2)
	Set the threading grain sizes used when iterating over nodes in a VDB. More...

size_t	getGrainSize () const

size_t	getActiveTileStreamingGrainSize () const

Friends
class	Compiler

class	::TestVolumeExecutable

Detailed Description

Object that encapsulates compiled AX code which can be executed on a collection of VDB volume grids. Executables are created by the compiler and hold the final immutable JIT compiled function and context.

The VolumeExecutable is returned from the ax::Compiler when compiling AX code for volume execution. The class represents a typical AX executable object; immutable except for execution settings and implements 'execute' functions which can be called multiple times for arbitrary sets of inputs. The intended usage of these executables is to configure their runtime arguments and then call VolumeExecutable::execute with your VDBs. For example:

VolumeExecutable::Ptr exe = compiler.compile<VolumeExecutable>("@a += 1");
exe->setTreeExecutionLevel(0); // only process leaf nodes
exe->setValueIterator(VolumeExecutable::IterType::ALL); // process all values
exe->execute(vdbs); // run on a set of vdbs
exe->execute(grid); // run on a single vdb

The Volume executable is initialised with specific configurable settings:

Iteration Level: min=0, max=RootNode::Level. By default, processes the entire VDB tree hierarchy.
See also
setTreeExecutionLevel
Iteration Type: ON By default, processes ACTIVE values.
See also
setValueIterator
Active Tile Streaming: ON, OFF or AUTO depending on AX code. By default, if AX detects that the AX program may produce unique values for leaf level voxels that would otherwise comprise a given active tile, this setting is set to ON or AUTO. Otherwise it is set to OFF.
See also
setActiveTileStreaming
Grain sizes: 1:32 The default grain sizes passed to the tbb partitioner for leaf level processing and active tile processing.
See also
setGrainSize

setActiveTileStreamingGrainSize
For more in depth information, see the Executables documentation.

Member Typedef Documentation

using Ptr = std::shared_ptr<VolumeExecutable>

Member Enumeration Documentation

enum IterType

strong

Enumerator
ON
OFF
ALL

enum Streaming

strong

The streaming type of active tiles during execution.

Parameters

ON	active tiles are temporarily densified (converted to leaf level voxels) on an "as needed" basis and the subsequent voxel values are processed. The temporarily densified node is added to the tree only if a non constant voxel buffer is produced. Otherwise a child tile may be created or the original tile's value may simply be modified.
OFF	tile topologies are left unchanged and their single value is processed.
AUTO	the volume executable analyzes the compiled kernel and attempts to determine if expansion of active tiles would lead to different, non-constant values in the respective voxels. This is done on a per grid basis; ultimately each execution will be set to ON or OFF. This option will always fall back to ON if there is any chance the kernel may produce child nodes

Note: The volume executable always runs an AUTO check on creation and will set itself to ON (if all grids always need child nodes), OFF (if grids never need child nodes) or remains as AUTO (if this depends on which grid is being processed).

When an AX kernel is run over coarser levels of the tree (i.e. not leaf voxels), it is often desirable to densify these areas into unique voxels such that they can each receive a unique value. For example, consider the following AX code which assigns a vector volume to the world space position of each voxel:

v@v = getvoxelpws();

Active tiles hold a single value but comprise an area greater than that of a single voxel. As the above kernel varies with respect to a nodes position, we'd need to replace these tiles with leaf voxels to get unique per node values. The stream flag is initialised to ON in this case.

This behaviour, however, is not always desirable .i.e:

v@v = {1,2,3};

In this instance, all values within a volume receive the same value and are not dependent on any spatially or iteratively varying metrics. The stream flag is set to OFF.

The AUTO flag is set in cases where the runtime access pattern of the inputs determines streaming:

f@density = f@mask;

f@mask = 0;

In this instance, the runtime topology and values of @mask determines whether child topology needs to be created in @density, but @mask itself does not need streaming. Streaming will be set to ON for density but OFF for mask.

Note: This behaviour is only applied to active tiles. If the value iterator is set to OFF, this option is ignored.

Warning: This option can generate large amounts of leaf level voxels. It is recommended to use a good concurrent memory allocator (such as jemalloc) for the best performance.

Enumerator
ON
OFF
AUTO

Constructor & Destructor Documentation

~VolumeExecutable ( )

VolumeExecutable ( const VolumeExecutable & other )

Copy constructor. Shares the LLVM constructs but deep copies the settings. Multiple copies of an executor can be used at the same time safely.

Member Function Documentation

void execute ( openvdb::GridPtrVec & grids ) const

Run this volume executable binary on target volumes.

This method reads from the stored settings on the executable to determine certain behaviour and runs the JIT compiled function across every valid VDB value. Topology may be changed, deleted or created.

This method is thread safe; it can be run concurrently from the same VolumeExecutable instance on different inputs.

Parameters

grids The VDB Volumes to process

void execute ( openvdb::GridBase & grids ) const

Run this volume executable binary on target volumes.

This method reads from the stored settings on the executable to determine certain behaviour and runs the JIT compiled function across every valid VDB value. Topology may be changed, deleted or created.

This method is thread safe; it can be run concurrently from the same VolumeExecutable instance on different inputs.

Parameters

grids The VDB Volumes to process

Streaming getActiveTileStreaming ( ) const

Returns: The current stream behaviour.

Streaming getActiveTileStreaming	(	const std::string &	name,
		const ast::tokens::CoreType &	type
	)		const

Returns: The current stream behaviour for a particular grid. This is either ON or OFF.

Parameters

name	The name of the grid to query
type	The grids type

size_t getActiveTileStreamingGrainSize ( ) const

Returns: The current g2 grain size

See also: setActiveTileStreamingGrainSize

const AttributeBindings& getAttributeBindings ( ) const

Returns: The current attribute bindings map

bool getCreateMissing ( ) const

Returns: Whether this executable will generate new grids.

size_t getGrainSize ( ) const

Returns: The current g1 grain size

See also: setGrainSize

void getTreeExecutionLevel	(	Index &	min,
		Index &	max
	)		const

Get the tree execution levels.

Parameters

min	The minimum tree execution level
max	The maximum tree execution level

Index getTreeExecutionLevel ( ) const

Returns: The tree execution level.

IterType getValueIterator ( ) const

Returns: The current value iterator type

void setActiveTileStreaming ( const Streaming & s )

Controls the behaviour of expansion of active tiles.

Parameters

s	The behaviour to set

void setActiveTileStreamingGrainSize ( const size_t g2 )

Set the threading grain sizes used when iterating over nodes in a VDB.

Two grain sizes are provided, the first of which (g1) is used to determine the chunk size of nodes which are not being streamed (see setActiveTileStream). Leaf node execution always uses this grain size. The default value for g1 is 1 which is typically appropriate for most AX kernels. The second grain size is used when streaming execution over active tiles in a VDB. This execution model differs significantly from typical leaf node execution due to the potential for substantially more memory to be allocated. The default value is 32, which works well for the default configuration of OpenVDB. If streaming is disabled, this value has no effect.

Note: Setting g1 or g2 to zero has the effect of disabling multi-threading for the respective node executions. Setting both to zero will disable all multi-threading performed by the execute method.

void setAttributeBindings ( const AttributeBindings & bindings )

Set attribute bindings.

Parameters

attributeBindings A map of attribute bindings to expected names on the geometry to be executed over. By default the AX attributes will be bound to volumes of the same name. Supplying bindings for a subset of the attributes will leave the others unchanged. AX attributes can only bind to a single volume and vice versa. However, in a single set call these can be swapped e.g. a -> b and b -> a. When bindings are overriden through subsequent calls to this function, any dangling volumes will be automatically bound by name. To reset these bindings call get function and create a target set of bindings for each attribute of name -> name.

void setCreateMissing ( const bool flag )

Set the behaviour when missing grids are accessed. Default behaviour is true, which creates them with default transforms and background values.

Parameters

flag	Enables or disables the creation of missing attributes

void setGrainSize ( const size_t g1 )

Set the threading grain sizes used when iterating over nodes in a VDB.

Two grain sizes are provided, the first of which (g1) is used to determine the chunk size of nodes which are not being streamed (see setActiveTileStream). Leaf node execution always uses this grain size. The default value for g1 is 1 which is typically appropriate for most AX kernels. The second grain size is used when streaming execution over active tiles in a VDB. This execution model differs significantly from typical leaf node execution due to the potential for substantially more memory to be allocated. The default value is 32, which works well for the default configuration of OpenVDB. If streaming is disabled, this value has no effect.

Note: Setting g1 or g2 to zero has the effect of disabling multi-threading for the respective node executions. Setting both to zero will disable all multi-threading performed by the execute method.

void setTreeExecutionLevel	(	const Index	min,
		const Index	max
	)

Set the execution level for this executable. This controls what nodes are processed when execute is called. Possible values depend on the OpenVDB configuration in use, however a value of 0 will always correspond to the lowest level (leaf-level). By default, the min level is zero (LeafNodeType::LEVEL) and the max level is the root node's level (RootNodeType::LEVEL). In other words, the default execution level settings process the whole of the tree.

Note: A value larger that the number of levels in the tree (i.e. larger than the root node's level) will cause this method to throw a runtime error.

Parameters

min	The minimum tree execution level to set
max	The maximum tree execution level to set

void setTreeExecutionLevel ( const Index level )

Parameters

level The tree execution level to set. Calls setTreeExecutionLevel with min and max arguments as level.

void setValueIterator ( const IterType & iter )

Set the value iterator type to use with this executable. Options are ON, OFF, ALL. Default is ON.

Parameters

iter	The value iterator type to set

Friends And Related Function Documentation

friend class ::TestVolumeExecutable

friend

friend class Compiler

friend

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation