OpenVDB: openvdb_ax/ax.h Source File

OpenVDB 12.1.0

Loading...
Searching...
No Matches
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
21#include <openvdb_ax/compiler/AttributeBindings.h>
22#include <openvdb/openvdb.h>
23#include <openvdb/version.h>
24
25
26namespace openvdb {
27 OPENVDB_USE_VERSION_NAMESPACE
28namespace 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.
35 OPENVDB_AX_API void initialize();
36
37/// @brief Check to see if OpenVDB AX components have been initialized.
38/// @note Can be safely called from multiple threads.
39 OPENVDB_AX_API bool isInitialized();
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.
46 OPENVDB_AX_API void uninitialize();
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.
73 OPENVDB_AX_API
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.
102 OPENVDB_AX_API
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
AttributeBindings.h
The Attribute Bindings class is used by the compiled Executables to handle the mapping of AX Attribut...
OPENVDB_AX_API
#define OPENVDB_AX_API
Definition Platform.h:312
openvdb::v12_1::GridBase
Abstract base class for typed grids.
Definition Grid.h:78
openvdb::v12_1::ax::AttributeBindings
This class wraps an interface for a map of attribute bindings. These map attributes in AX code to con...
Definition AttributeBindings.h:37
openvdb::v12_1::ax
Definition ax.h:29
openvdb::v12_1::ax::isInitialized
OPENVDB_AX_API bool isInitialized()
Check to see if OpenVDB AX components have been initialized.
openvdb::v12_1::ax::initialize
OPENVDB_AX_API void initialize()
Initializes OpenVDB AX and subsequent LLVM components.
openvdb::v12_1::ax::uninitialize
OPENVDB_AX_API void uninitialize()
Uninitialize and deregister OpenVDB AX.
openvdb::v12_1::ax::run
OPENVDB_AX_API void run(const char *ax, openvdb::GridBase &grid, const AttributeBindings &bindings={})
Run a full AX pipeline (parse, compile and execute) on a single OpenVDB Grid.
openvdb::v12_1::GridPtrVec
std::vector< GridBase::Ptr > GridPtrVec
Definition Grid.h:508
openvdb
Definition Exceptions.h:13
openvdb.h
OPENVDB_VERSION_NAME
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition version.h.in:121
OPENVDB_USE_VERSION_NAMESPACE
#define OPENVDB_USE_VERSION_NAMESPACE
Definition version.h.in:218