OpenVDB 10.0.1
Loading...
Searching...
No Matches
PointExecutable.h
Go to the documentation of this file.
1// Copyright Contributors to the OpenVDB Project
2// SPDX-License-Identifier: MPL-2.0
3
4/// @file compiler/PointExecutable.h
5///
6/// @authors Nick Avramoussis, Francisco Gochez, Richard Jones
7///
8/// @brief The PointExecutable, produced by the OpenVDB AX Compiler for
9/// execution over OpenVDB Points Grids.
10///
11
12#ifndef OPENVDB_AX_COMPILER_POINT_EXECUTABLE_HAS_BEEN_INCLUDED
13#define OPENVDB_AX_COMPILER_POINT_EXECUTABLE_HAS_BEEN_INCLUDED
14
15#include "CustomData.h"
16#include "AttributeRegistry.h"
17#include "AttributeBindings.h"
18
19#include <openvdb/openvdb.h>
20#include <openvdb/version.h>
22
23#include <unordered_map>
24
25class TestPointExecutable;
26
27namespace llvm {
28class ExecutionEngine;
29class LLVMContext;
30}
31
32namespace openvdb {
34namespace OPENVDB_VERSION_NAME {
35namespace ax {
36
37class Compiler;
38
39/// @brief Object that encapsulates compiled AX code which can be executed on a
40/// collection of VDB Point Data grids. Executables are created by the
41/// compiler and hold the final immutable JIT compiled function and context.
42/// @details The PointExecutable is returned from the ax::Compiler when
43/// compiling AX code for point execution. The class represents a typical AX
44/// executable object; immutable except for execution settings and implements
45/// 'execute' functions which can be called multiple times for arbitrary sets
46/// of inputs. The intended usage of these executables is to configure their
47/// runtime arguments and then call PointExecutable::execute with your VDBs.
48/// For example:
49/// @code
50/// PointExecutable::Ptr exe = compiler.compile<PointExecutable>("@a += 1");
51/// exe->setCreateMissing(false); // fail on missing attributes
52/// exe->setGroupExecution("group1"); // only process points in group1
53/// exe->execute(vdbs); // run on a set of vdb point data grids
54/// exe->execute(points); // run on a single point data grid
55/// @endcode
56///
57/// The setCreateMissing is initialised with specific configurable settings:
58/// - Create Missing: True
59/// By default, create any missing attributes that were accessed
60/// @sa setCreateMissing
61/// - Group Execution: All
62/// By default, process all points regardless of their group membership
63/// @sa setGroupExecution
64/// - Grain size: 1
65/// The default grain sizes passed to the tbb partitioner for leaf level
66/// processing.
67/// @sa setGrainSize
68///
69/// For more in depth information, see the @ref vdbaxcompilerexe documentation.
71{
72public:
73 using Ptr = std::shared_ptr<PointExecutable>;
75
76 /// @brief Copy constructor. Shares the LLVM constructs but deep copies the
77 /// settings. Multiple copies of an executor can be used at the same time
78 /// safely.
80
81 ////////////////////////////////////////////////////////
82
83 /// @brief Run this point executable binary on a target PointDataGrid.
84 /// @details This method reads from the stored settings on the executable
85 /// to determine certain behaviour and runs the JIT compiled function
86 /// across every valid point. Point attributes may be created, deleted
87 /// collapsed or expanded, and points themselves may be added, deleted
88 /// or moved.
89 ///
90 /// This method is thread safe; it can be run concurrently from the same
91 /// PointExecutable instance on different inputs.
92 ///
93 /// @param grid The PointDataGrid to process
94 void execute(points::PointDataGrid& grid) const;
95
96 ////////////////////////////////////////////////////////
97
98 /// @brief Set a specific point group to execute over. The default is none,
99 /// which corresponds to all points. Note that this can also be compiled
100 /// into the AX function using the ingroup("mygroup") method.
101 /// @warning If the group does not exist during execute, a runtime error
102 /// will be thrown.
103 /// @param name The name of the group to execute over
104 void setGroupExecution(const std::string& name);
105 /// @return The points group to be processed. Default is empty, which is
106 /// all points.
107 const std::string& getGroupExecution() const;
108
109 /// @brief Set the behaviour when missing point attributes are accessed.
110 /// Default behaviour is true, which creates them with default initial
111 /// values. If false, a missing attribute runtime error will be thrown
112 /// on missing accesses.
113 /// @param flag Enables or disables the creation of missing attributes
114 void setCreateMissing(const bool flag);
115 /// @return Whether this executable will generate new point attributes.
116 bool getCreateMissing() const;
117
118 /// @brief Set the threading grain size. Default is 1. A value of 0 has the
119 /// effect of disabling multi-threading.
120 /// @param grain The grain size
121 void setGrainSize(const size_t grain);
122 /// @return The current grain size
123 size_t getGrainSize() const;
124
125 /// @brief Set attribute bindings.
126 /// @param bindings A map of attribute bindings to expected names on
127 /// the geometry to be executed over. By default the AX attributes will be
128 /// bound to point attributes of the same name. Supplying bindings
129 /// for a subset of the attributes will leave the others unchanged.
130 /// AX attributes can only bind to a single point attribute and vice versa.
131 /// However, in a single set call these can be swapped e.g. a -> b and b -> a.
132 /// When bindings are overriden through subsequent calls to this function,
133 /// any dangling point attributes will be automatically bound by name.
134 /// To reset these bindings call get function and create a target set of bindings
135 /// for each attribute of name -> name.
137 /// @return The current attribute bindings map
139
140 ////////////////////////////////////////////////////////
141
142 // foward declaration of settings for this executable
143 template <bool> struct Settings;
144
145 /// @brief Command Line Interface handling for the PointExecutable.
146 /// @details This class wraps the logic for converting commands specific
147 /// to the PointExecutable to the internal Settings. Subsequent
148 /// executables can be initialized from the CLI object that gets created
150 {
154 static CLI create(size_t argc, const char* argv[], bool* used=nullptr);
155 static void usage(std::ostream& os, const bool verbose);
156 private:
157 friend class PointExecutable;
158 CLI();
159 std::unique_ptr<Settings<true>> mSettings;
160 };
161
162 /// @brief Intialize the Settings of this executables from the CLI object
163 /// @param cli The CLI object
164 void setSettingsFromCLI(const CLI& cli);
165
166 ////////////////////////////////////////////////////////
167
168private:
169 friend class Compiler;
170 friend class ::TestPointExecutable;
171
172 /// @brief Private method used in the unit tests
173 bool usesAcceleratedKernel(const points::PointDataTree& tree) const;
174
175 /// @brief Constructor, expected to be invoked by the compiler. Should not
176 /// be invoked directly.
177 /// @param context Shared pointer to an llvm:LLVMContext associated with the
178 /// execution engine
179 /// @param engine Shared pointer to an llvm::ExecutionEngine used to build
180 /// functions. Context should be the associated LLVMContext
181 /// @param attributeRegistry Registry of attributes accessed by AX code
182 /// @param customData Custom data which will be shared by this executable.
183 /// It can be used to retrieve external data from within the AX code
184 /// @param functions A map of function names to physical memory addresses
185 /// which were built by llvm using engine
186 /// @param tree The AST linked to this executable. The AST is not stored
187 /// after compilation, but can be used during construction of the exe to
188 /// infer some pre/post processing optimisations.
189 PointExecutable(const std::shared_ptr<const llvm::LLVMContext>& context,
190 const std::shared_ptr<const llvm::ExecutionEngine>& engine,
191 const AttributeRegistry::ConstPtr& attributeRegistry,
192 const CustomData::ConstPtr& customData,
193 const std::unordered_map<std::string, uint64_t>& functions,
194 const ast::Tree& tree);
195
196private:
197 // The Context and ExecutionEngine must exist _only_ for object lifetime
198 // management. The ExecutionEngine must be destroyed before the Context
199 const std::shared_ptr<const llvm::LLVMContext> mContext;
200 const std::shared_ptr<const llvm::ExecutionEngine> mExecutionEngine;
201 const AttributeRegistry::ConstPtr mAttributeRegistry;
202 const CustomData::ConstPtr mCustomData;
203 const std::unordered_map<std::string, uint64_t> mFunctionAddresses;
204 std::unique_ptr<Settings<false>> mSettings;
205};
206
207} // namespace ax
208} // namespace OPENVDB_VERSION_NAME
209} // namespace openvdb
210
211#endif // OPENVDB_AX_COMPILER_POINT_EXECUTABLE_HAS_BEEN_INCLUDED
212
The Attribute Bindings class is used by the compiled Executables to handle the mapping of AX Attribut...
These classes contain lists of expected attributes and volumes which are populated by compiler during...
Access to the CustomData class which can provide custom user user data to the OpenVDB AX Compiler.
#define OPENVDB_AX_API
Definition Platform.h:272
Attribute-owned data structure for points. Point attributes are stored in leaf nodes and ordered by v...
Container class that associates a tree with a transform and metadata.
Definition Grid.h:571
This class wraps an interface for a map of attribute bindings. These map attributes in AX code to con...
Definition AttributeBindings.h:37
std::shared_ptr< const AttributeRegistry > ConstPtr
Definition AttributeRegistry.h:42
The compiler class. This holds an llvm context and set of compiler options, and constructs executable...
Definition Compiler.h:50
std::shared_ptr< const CustomData > ConstPtr
Definition CustomData.h:38
Object that encapsulates compiled AX code which can be executed on a collection of VDB Point Data gri...
Definition PointExecutable.h:71
const std::string & getGroupExecution() const
void setCreateMissing(const bool flag)
Set the behaviour when missing point attributes are accessed. Default behaviour is true,...
const AttributeBindings & getAttributeBindings() const
std::shared_ptr< PointExecutable > Ptr
Definition PointExecutable.h:73
void execute(points::PointDataGrid &grid) const
Run this point executable binary on a target PointDataGrid.
PointExecutable(const PointExecutable &other)
Copy constructor. Shares the LLVM constructs but deep copies the settings. Multiple copies of an exec...
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.
void setGroupExecution(const std::string &name)
Set a specific point group to execute over. The default is none, which corresponds to all points....
void setSettingsFromCLI(const CLI &cli)
Intialize the Settings of this executables from the CLI object.
void setAttributeBindings(const AttributeBindings &bindings)
Set attribute bindings.
Definition Tree.h:178
Definition Compiler.h:31
Definition Exceptions.h:13
Command Line Interface handling for the PointExecutable.
Definition PointExecutable.h:150
static void usage(std::ostream &os, const bool verbose)
static CLI create(size_t argc, const char *argv[], bool *used=nullptr)
Definition PointExecutable.h:143
A Tree is the highest concrete (non-abstract) node in the entire AX AST hierarchy....
Definition AST.h:562
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition version.h.in:121
#define OPENVDB_USE_VERSION_NAMESPACE
Definition version.h.in:212