OpenVDB: VolumeExecutable Class Reference

OpenVDB 9.0.0

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>`

## Public Types
enum class | Streaming { ON , OFF , AUTO }
| The streaming type of active tiles during execution. More...
enum class | 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 | 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
openvdb::v9_0::ax::VolumeExecutable::Ptr
std::shared_ptr< VolumeExecutable > Ptr
Definition: VolumeExecutable.h:78
openvdb::v9_0::ax::VolumeExecutable::IterType::ALL
@ ALL
openvdb::v9_0::ax::VolumeExecutable::VolumeExecutable
VolumeExecutable(const VolumeExecutable &other)
Copy constructor. Shares the LLVM constructs but deep copies the settings. Multiple copies of an exec...

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

## ◆ Ptr

using Ptr = std::shared_ptr<VolumeExecutable>

## Member Enumeration Documentation

## ◆ IterType

enum class IterType
| strong

Enumerator
ON |
OFF |
ALL |

## ◆ Streaming

enum class 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 | ( |  | ) |

## ◆ 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

## ◆ execute() [1/2]

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

## ◆ execute() [2/2]

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

## ◆ getActiveTileStreaming() [1/2]

Streaming getActiveTileStreaming | ( |  | ) | const

Returns
  The current stream behaviour.

## ◆ getActiveTileStreaming() [2/2]

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

## ◆ getActiveTileStreamingGrainSize()

size_t getActiveTileStreamingGrainSize | ( |  | ) | const

Returns
  The current g2 grain size

See also
  setActiveTileStreamingGrainSize

## ◆ getCreateMissing()

bool getCreateMissing | ( |  | ) | const

Returns
  Whether this executable will generate new grids.

## ◆ getGrainSize()

size_t getGrainSize | ( |  | ) | const

Returns
  The current g1 grain size

See also
  setGrainSize

## ◆ getTreeExecutionLevel() [1/2]

Index getTreeExecutionLevel | ( |  | ) | const

Returns
  The tree execution level.

## ◆ getTreeExecutionLevel() [2/2]

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

## ◆ getValueIterator()

IterType getValueIterator | ( |  | ) | const

Returns
  The current value iterator type

## ◆ setActiveTileStreaming()

void setActiveTileStreaming | ( | const Streaming & | s | ) |

Controls the behaviour of expansion of active tiles.

Parameters

  s | The behaviour to set

## ◆ setActiveTileStreamingGrainSize()

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.

## ◆ setCreateMissing()

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

## ◆ setGrainSize()

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.

## ◆ setTreeExecutionLevel() [1/2]

void setTreeExecutionLevel | ( | const Index | level | ) |

Parameters

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

## ◆ setTreeExecutionLevel() [2/2]

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

## ◆ setValueIterator()

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

## ◆ ::TestVolumeExecutable

friend class ::TestVolumeExecutable
| friend

## ◆ Compiler

friend class Compiler
| friend