OpenVDB  12.0.0
ax.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: Apache-2.0
3 
4 /// @file ax.h
5 ///
6 /// @author Nick Avramoussis
7 ///
8 /// @brief Single header include which provides methods for initializing AX and
9 /// running a full AX pipeline (parsing, compiling and executing) across
10 /// standard OpenVDB Grid types.
11 ///
12 /// @details These methods wrap the internal components of OpenVDB AX to
13 /// provide easier and quick access to running AX code. Users who wish to
14 /// further optimise and customise the process may interface with these
15 /// components directly. See the body of the methods provided in this file for
16 /// example implementations.
17 
18 #ifndef OPENVDB_AX_AX_HAS_BEEN_INCLUDED
19 #define OPENVDB_AX_AX_HAS_BEEN_INCLUDED
20 
22 #include <openvdb/openvdb.h>
23 #include <openvdb/version.h>
24 
25 
26 namespace openvdb {
28 namespace OPENVDB_VERSION_NAME {
29 namespace ax {
30 
31 /// @brief Initializes OpenVDB AX and subsequent LLVM components.
32 /// @details Must be called before any AX compilation or execution is performed.
33 /// Can be safely called from multiple threads. Cannot be called after
34 /// uninitialize has been called.
36 
37 /// @brief Check to see if OpenVDB AX components have been initialized.
38 /// @note Can be safely called from multiple threads.
40 
41 /// @brief Uninitialize and deregister OpenVDB AX.
42 /// @details This has the important function of shutting down LLVM and
43 /// correctly freeing statically allocated LLVM types. Should be
44 /// called on application termination. Can be safely called from
45 /// multiple threads.
47 
48 ////////////////////////////////////////
49 ////////////////////////////////////////
50 
51 /// @brief Run a full AX pipeline (parse, compile and execute) on a single
52 /// OpenVDB Grid.
53 /// @details This method wraps the parsing, compilation and execution of AX
54 /// code for a single OpenVDB grid of any standard grid type
55 /// (including OpenVDB Points Grids). Provided AX code is expected to
56 /// only refer to the provided single grid. On success, the grid will
57 /// have its voxels or point data modified as dictated by the provided
58 /// AX code.
59 /// @note Various defaults are applied to this pipeline to provide a simple
60 /// run signature. For OpenVDB Numerical grids, only active voxels are
61 /// processed. For OpenVDB Points grids, all points are processed. Any
62 /// warnings generated by the parser, compiler or executable will be
63 /// ignored.
64 /// @note Various runtime errors may be thrown from the different AX pipeline
65 /// stages. See Exceptions.h for the possible different errors.
66 /// @param ax The null terminated AX code string to parse and compile
67 /// @param grid The grid to which to apply the compiled AX function
68 /// @param bindings An attribute bindings object mapping names in the AX string to
69 /// names of the point attributes/grids (points/volumes resp.)
70 /// This can be initialized as a vector of pairs of strings e.g.
71 /// {{"axname0","dataname0"}, {"axname1","dataname1"}} see
72 /// AttributeBindings.h for details.
74 void run(const char* ax, openvdb::GridBase& grid,
75  const AttributeBindings& bindings = {});
76 
77 /// @brief Run a full AX pipeline (parse, compile and execute) on a vector of
78 /// OpenVDB numerical grids OR a vector of OpenVDB Point Data grids.
79 /// @details This method wraps the parsing, compilation and execution of AX
80 /// code for a vector of OpenVDB grids. The vector must contain either
81 /// a set of any numerical grids supported by the default AX types OR
82 /// a set of OpenVDB Points grids. On success, grids in the provided
83 /// grid vector will be iterated over and updated if they are written
84 /// to.
85 /// @warning The type of grids provided changes the type of AX compilation. If
86 /// the vector is empty, this function immediately returns with no
87 /// other effect.
88 /// @note Various defaults are applied to this pipeline to provide a simple
89 /// run signature. For numerical grids, only active voxels are processed
90 /// and missing grid creation is disabled. For OpenVDB Points grids, all
91 /// points are processed. Any warnings generated by the parser, compiler
92 /// or executable will be ignored.
93 /// @note Various runtime errors may be thrown from the different AX pipeline
94 /// stages. See Exceptions.h for the possible different errors.
95 /// @param ax The null terminated AX code string to parse and compile
96 /// @param grids The grids to which to apply the compiled AX function
97 /// @param bindings An attribute bindings object mapping names in the AX string to
98 /// names of the point attributes/grids (points/volumes resp.)
99 /// This can be initialized as a vector of pairs of strings e.g.
100 /// {{"axname0","dataname0"}, {"axname1","dataname1"}} see
101 /// AttributeBindings.h for details.
103 void run(const char* ax, openvdb::GridPtrVec& grids,
104  const AttributeBindings& bindings = {});
105 
106 } // namespace ax
107 } // namespace OPENVDB_VERSION_NAME
108 } // namespace openvdb
109 
110 #endif // OPENVDB_AX_AX_HAS_BEEN_INCLUDED
111 
#define OPENVDB_AX_API
Definition: Platform.h:289
OPENVDB_AX_API void run(const char *ax, openvdb::GridPtrVec &grids, const AttributeBindings &bindings={})
Run a full AX pipeline (parse, compile and execute) on a vector of OpenVDB numerical grids OR a vecto...
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:508
The Attribute Bindings class is used by the compiled Executables to handle the mapping of AX Attribut...
OPENVDB_AX_API bool isInitialized()
Check to see if OpenVDB AX components have been initialized.
OPENVDB_AX_API void uninitialize()
Uninitialize and deregister OpenVDB AX.
Definition: Exceptions.h:13
OPENVDB_AX_API void initialize()
Initializes OpenVDB AX and subsequent LLVM components.
#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:218
Abstract base class for typed grids.
Definition: Grid.h:77
This class wraps an interface for a map of attribute bindings. These map attributes in AX code to con...
Definition: AttributeBindings.h:36