OpenVDB  12.0.0
Classes | Public Types | Public Member Functions | Friends | List of all members
VolumeExecutable Class Reference

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>

Classes

struct  CLI
 Command Line Interface handling for the VolumeExecutable. More...
 
struct  Settings
 

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
 
void setAttributeBindings (const AttributeBindings &bindings)
 Set attribute bindings. More...
 
const AttributeBindingsgetAttributeBindings () const
 
Index getTreeExecutionLevel () 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
 
void setSettingsFromCLI (const CLI &cli)
 Intialize the Settings of this executables from the CLI object. More...
 

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:

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
ONactive 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.
OFFtile topologies are left unchanged and their single value is processed.
AUTOthe 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 ( 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
gridsThe 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
gridsThe 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
nameThe name of the grid to query
typeThe 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
minThe minimum tree execution level
maxThe maximum tree execution level
Index getTreeExecutionLevel ( ) const
Returns
The tree execution level.
Deprecated:
"Use getTreeExecutionLevel(Index&, Index&)"
IterType getValueIterator ( ) const
Returns
The current value iterator type
void setActiveTileStreaming ( const Streaming s)

Controls the behaviour of expansion of active tiles.

Parameters
sThe 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
bindingsA 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
flagEnables 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 setSettingsFromCLI ( const CLI cli)

Intialize the Settings of this executables from the CLI object.

Parameters
cliThe CLI object
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
minThe minimum tree execution level to set
maxThe maximum tree execution level to set
void setTreeExecutionLevel ( const Index  level)
Parameters
levelThe 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
iterThe value iterator type to set

Friends And Related Function Documentation

friend class ::TestVolumeExecutable
friend
friend class Compiler
friend