OpenVDB 12.1.0

Loading...
Searching...
No Matches
PointExecutable Class Reference

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

`#include <openvdb_ax/compiler/PointExecutable.h>`

## Classes
struct | CLI
| Command Line Interface handling for the PointExecutable. More...
struct | Settings

## Public Types
using | Ptr = std::shared_ptr<PointExecutable>

## Public Member Functions
| ~PointExecutable ()
| PointExecutable (const PointExecutable &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 (points::PointDataGrid &grid) const
| Run this point executable binary on a target PointDataGrid.
void | setGroupExecution (const std::string &name)
| Set a specific point group to execute over. The default is none, which corresponds to all points. Note that this can also be compiled into the AX function using the ingroup("mygroup") method.
const std::string & | getGroupExecution () const
void | setCreateMissing (const bool flag)
| Set the behaviour when missing point attributes are accessed. Default behaviour is true, which creates them with default initial values. If false, a missing attribute runtime error will be thrown on missing accesses.
bool | getCreateMissing () const
void | setGrainSize (const size_t grain)
| Set the threading grain size. Default is 1. A value of 0 has the effect of disabling multi-threading.
size_t | getGrainSize () const
void | setAttributeBindings (const AttributeBindings &bindings)
| Set attribute bindings.
const AttributeBindings & | getAttributeBindings () const
void | setSettingsFromCLI (const CLI &cli)
| Intialize the Settings of this executables from the CLI object.

## Friends
class | Compiler
struct | ::TestPointExecutableAcc

## Detailed Description

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

The PointExecutable is returned from the ax::Compiler when compiling AX code for point 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 PointExecutable::execute with your VDBs. For example:

PointExecutable::Ptr exe = compiler.compile<PointExecutable>("@a += 1");
exe->setCreateMissing(false); // fail on missing attributes
exe->setGroupExecution("group1"); // only process points in group1
exe->execute(vdbs); // run on a set of vdb point data grids
exe->execute(points); // run on a single point data grid
openvdb::v12_1::ax::PointExecutable::Ptr
std::shared_ptr< PointExecutable > Ptr
Definition PointExecutable.h:78
openvdb::v12_1::ax::PointExecutable::PointExecutable
PointExecutable(const PointExecutable &other)
Copy constructor. Shares the LLVM constructs but deep copies the settings. Multiple copies of an exec...
openvdb::v12_1::points
Definition AttributeArray.h:42

The setCreateMissing is initialised with specific configurable settings:

- Create Missing: True By default, create any missing attributes that were accessed
  See also
    setCreateMissing
- Group Execution: All By default, process all points regardless of their group membership
  See also
    setGroupExecution
- Grain size: 1 The default grain sizes passed to the tbb partitioner for leaf level processing.
  See also
    setGrainSize
  For more in depth information, see the Executables documentation.

## Member Typedef Documentation

## ◆ Ptr

using Ptr = std::shared_ptr<PointExecutable>

## Constructor & Destructor Documentation

## ◆ ~PointExecutable()

~PointExecutable | ( |  | ) |

## ◆ PointExecutable()

PointExecutable | ( | const PointExecutable & | 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()

void execute | ( | points::PointDataGrid & | grid | ) | const

Run this point executable binary on a target PointDataGrid.

This method reads from the stored settings on the executable to determine certain behaviour and runs the JIT compiled function across every valid point. Point attributes may be created, deleted collapsed or expanded, and points themselves may be added, deleted or moved.

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

Parameters

  grid | The PointDataGrid to process

## ◆ getAttributeBindings()

const AttributeBindings & getAttributeBindings | ( |  | ) | const

Returns
  The current attribute bindings map

## ◆ getCreateMissing()

bool getCreateMissing | ( |  | ) | const

Returns
  Whether this executable will generate new point attributes.

## ◆ getGrainSize()

size_t getGrainSize | ( |  | ) | const

Returns
  The current grain size

## ◆ getGroupExecution()

const std::string & getGroupExecution | ( |  | ) | const

Returns
  The points group to be processed. Default is empty, which is all points.

## ◆ setAttributeBindings()

void setAttributeBindings | ( | const AttributeBindings & | bindings | ) |

Set attribute bindings.

Parameters

  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 point attributes 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 point attribute 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 point attributes 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.

## ◆ setCreateMissing()

void setCreateMissing | ( | const bool | flag | ) |

Set the behaviour when missing point attributes are accessed. Default behaviour is true, which creates them with default initial values. If false, a missing attribute runtime error will be thrown on missing accesses.

Parameters

  flag | Enables or disables the creation of missing attributes

## ◆ setGrainSize()

void setGrainSize | ( | const size_t | grain | ) |

Set the threading grain size. Default is 1. A value of 0 has the effect of disabling multi-threading.

Parameters

  grain | The grain size

## ◆ setGroupExecution()

void setGroupExecution | ( | const std::string & | name | ) |

Set a specific point group to execute over. The default is none, which corresponds to all points. Note that this can also be compiled into the AX function using the ingroup("mygroup") method.

Warning
  If the group does not exist during execute, a runtime error will be thrown.

Parameters

  name | The name of the group to execute over

## ◆ setSettingsFromCLI()

void setSettingsFromCLI | ( | const CLI & | cli | ) |

Intialize the Settings of this executables from the CLI object.

Parameters

  cli | The CLI object

## Friends And Related Symbol Documentation

## ◆ ::TestPointExecutableAcc

friend struct ::TestPointExecutableAcc
| friend

## ◆ Compiler

friend class Compiler
| friend