OpenVDB: openvdb_ax/ax.h Source File

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 {
25 OPENVDB_USE_VERSION_NAMESPACE
26namespace 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.
37 bool isInitialized();
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
openvdb::v9_0::GridBase
Abstract base class for typed grids.
Definition: Grid.h:78
openvdb::v9_0::ax::initialize
void initialize()
Initializes OpenVDB AX and subsequent LLVM components.
openvdb::v9_0::ax::uninitialize
void uninitialize()
Uninitialize and deregister OpenVDB AX.
openvdb::v9_0::ax::isInitialized
bool isInitialized()
Check to see if OpenVDB AX components have been initialized.
openvdb::v9_0::ax::run
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...
openvdb::v9_0::GridPtrVec
std::vector< GridBase::Ptr > GridPtrVec
Definition: Grid.h:514
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:116
OPENVDB_USE_VERSION_NAMESPACE
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:202