OpenVDB
12.0.0
|
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 AttributeBindings & | getAttributeBindings () 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 |
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:
The Volume executable is initialised with specific configurable settings:
using Ptr = std::shared_ptr<VolumeExecutable> |
|
strong |
|
strong |
The streaming type of active tiles during execution.
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 |
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:
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:
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:
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.
Enumerator | |
---|---|
ON | |
OFF | |
AUTO |
~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.
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.
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.
grids | The VDB Volumes to process |
Streaming getActiveTileStreaming | ( | ) | const |
Streaming getActiveTileStreaming | ( | const std::string & | name, |
const ast::tokens::CoreType & | type | ||
) | const |
name | The name of the grid to query |
type | The grids type |
size_t getActiveTileStreamingGrainSize | ( | ) | const |
const AttributeBindings& getAttributeBindings | ( | ) | const |
bool getCreateMissing | ( | ) | const |
size_t getGrainSize | ( | ) | const |
Get the tree execution levels.
min | The minimum tree execution level |
max | The maximum tree execution level |
Index getTreeExecutionLevel | ( | ) | const |
IterType getValueIterator | ( | ) | const |
void setActiveTileStreaming | ( | const Streaming & | s | ) |
Controls the behaviour of expansion of active tiles.
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.
void setAttributeBindings | ( | const AttributeBindings & | bindings | ) |
Set attribute bindings.
bindings | 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.
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.
void setSettingsFromCLI | ( | const CLI & | cli | ) |
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.
min | The minimum tree execution level to set |
max | The maximum tree execution level to set |
void setTreeExecutionLevel | ( | const Index | level | ) |
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.
iter | The value iterator type to set |
|
friend |
|
friend |