OpenVDB  8.2.0
ax.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 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 (pasrsing, 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 
21 #include <openvdb/openvdb.h>
22 #include <openvdb/version.h>
23 
24 namespace openvdb {
26 namespace OPENVDB_VERSION_NAME {
27 namespace ax {
28 
29 /// @brief Initializes OpenVDB AX and subsequent LLVM components.
30 /// @details Must be called before any AX compilation or execution is performed.
31 /// Can be safely called from multiple threads. Cannot be called after
32 /// uninitialize has been called.
33 void initialize();
34 
35 /// @brief Check to see if OpenVDB AX components have been initialized.
36 /// @note Can be safely called from multiple threads.
38 
39 /// @brief Uninitialize and deregister OpenVDB AX.
40 /// @details This has the important function of shutting down LLVM and
41 /// correctly freeing statically allocated LLVM types. Should be
42 /// called on application termination. Can be safely called from
43 /// multiple threads.
44 void uninitialize();
45 
46 ////////////////////////////////////////
47 ////////////////////////////////////////
48 
49 /// @brief Run a full AX pipeline (parse, compile and execute) on a single
50 /// OpenVDB Grid.
51 /// @details This method wraps the parsing, compilation and execution of AX
52 /// code for a single OpenVDB grid of any standard grid type
53 /// (including OpenVDB Points Grids). Provided AX code is expected to
54 /// only refer to the provided single grid. On success, the grid will
55 /// have its voxels or point data modified as dictated by the provided
56 /// AX code.
57 /// @note Various defaults are applied to this pipeline to provide a simple
58 /// run signature. For OpenVDB Numerical grids, only active voxels are
59 /// processed. For OpenVDB Points grids, all points are processed. Any
60 /// warnings generated by the parser, compiler or executable will be
61 /// ignored.
62 /// @note Various runtime errors may be thrown from the different AX pipeline
63 /// stages. See Exceptions.h for the possible different errors.
64 /// @param ax The null terminated AX code string to parse and compile
65 /// @param grid The grid to which to apply the compiled AX function
66 void run(const char* ax, openvdb::GridBase& grid);
67 
68 /// @brief Run a full AX pipeline (parse, compile and execute) on a vector of
69 /// OpenVDB numerical grids OR a vector of OpenVDB Point Data grids.
70 /// @details This method wraps the parsing, compilation and execution of AX
71 /// code for a vector of OpenVDB grids. The vector must contain either
72 /// a set of any numerical grids supported by the default AX types OR
73 /// a set of OpenVDB Points grids. On success, grids in the provided
74 /// grid vector will be iterated over and updated if they are written
75 /// to.
76 /// @warning The type of grids provided changes the type of AX compilation. If
77 /// the vector is empty, this function immediately returns with no
78 /// other effect.
79 /// @note Various defaults are applied to this pipeline to provide a simple
80 /// run signature. For numerical grids, only active voxels are processed
81 /// and missing grid creation is disabled. For OpenVDB Points grids, all
82 /// points are processed. Any warnings generated by the parser, compiler
83 /// or executable will be ignored.
84 /// @note Various runtime errors may be thrown from the different AX pipeline
85 /// stages. See Exceptions.h for the possible different errors.
86 /// @param ax The null terminated AX code string to parse and compile
87 /// @param grids The grids to which to apply the compiled AX function
88 void run(const char* ax, openvdb::GridPtrVec& grids);
89 
90 } // namespace ax
91 } // namespace OPENVDB_VERSION_NAME
92 } // namespace openvdb
93 
94 #endif // OPENVDB_AX_AX_HAS_BEEN_INCLUDED
95 
Abstract base class for typed grids.
Definition: Grid.h:78
void run(const char *ax, openvdb::GridPtrVec &grids)
Run a full AX pipeline (parse, compile and execute) on a vector of OpenVDB numerical grids OR a vecto...
void initialize()
Initializes OpenVDB AX and subsequent LLVM components.
bool isInitialized()
Check to see if OpenVDB AX components have been initialized.
void uninitialize()
Uninitialize and deregister OpenVDB AX.
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:514
Definition: Exceptions.h:13
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:116
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:180