OpenVDB 9.0.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 (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/openvdb.h>
22#include <openvdb/version.h>
23
24namespace openvdb {
26namespace OPENVDB_VERSION_NAME {
27namespace 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.
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.
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
66void 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
88void 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 initialize()
Initializes OpenVDB AX and subsequent LLVM components.
void uninitialize()
Uninitialize and deregister OpenVDB AX.
bool isInitialized()
Check to see if OpenVDB AX components have been initialized.
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...
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:202