Loading...
Searching...
No Matches
ax.h
Go to the documentation of this file.
// Copyright Contributors to the OpenVDB Project
// SPDX-License-Identifier: MPL-2.0
/// @file ax.h
///
/// @author Nick Avramoussis
///
/// @brief Single header include which provides methods for initializing AX and
/// running a full AX pipeline (parsing, compiling and executing) across
/// standard OpenVDB Grid types.
///
/// @details These methods wrap the internal components of OpenVDB AX to
/// provide easier and quick access to running AX code. Users who wish to
/// further optimise and customise the process may interface with these
/// components directly. See the body of the methods provided in this file for
/// example implementations.
#ifndef OPENVDB_AX_AX_HAS_BEEN_INCLUDED
#define OPENVDB_AX_AX_HAS_BEEN_INCLUDED
#include <openvdb_ax/compiler/AttributeBindings.h>
#include <openvdb/openvdb.h>
#include <openvdb/version.h>
namespace openvdb {
OPENVDB_USE_VERSION_NAMESPACE
namespace OPENVDB_VERSION_NAME {
namespace ax {
/// @brief Initializes OpenVDB AX and subsequent LLVM components.
/// @details Must be called before any AX compilation or execution is performed.
/// Can be safely called from multiple threads. Cannot be called after
/// uninitialize has been called.
OPENVDB_AX_API void initialize();
/// @brief Check to see if OpenVDB AX components have been initialized.
/// @note Can be safely called from multiple threads.
OPENVDB_AX_API bool isInitialized();
/// @brief Uninitialize and deregister OpenVDB AX.
/// @details This has the important function of shutting down LLVM and
/// correctly freeing statically allocated LLVM types. Should be
/// called on application termination. Can be safely called from
/// multiple threads.
OPENVDB_AX_API void uninitialize();
////////////////////////////////////////
////////////////////////////////////////
/// @brief Run a full AX pipeline (parse, compile and execute) on a single
/// OpenVDB Grid.
/// @details This method wraps the parsing, compilation and execution of AX
/// code for a single OpenVDB grid of any standard grid type
/// (including OpenVDB Points Grids). Provided AX code is expected to
/// only refer to the provided single grid. On success, the grid will
/// have its voxels or point data modified as dictated by the provided
/// AX code.
/// @note Various defaults are applied to this pipeline to provide a simple
/// run signature. For OpenVDB Numerical grids, only active voxels are
/// processed. For OpenVDB Points grids, all points are processed. Any
/// warnings generated by the parser, compiler or executable will be
/// ignored.
/// @note Various runtime errors may be thrown from the different AX pipeline
/// stages. See Exceptions.h for the possible different errors.
/// @param ax The null terminated AX code string to parse and compile
/// @param grid The grid to which to apply the compiled AX function
/// @param bindings An attribute bindings object mapping names in the AX string to
/// names of the point attributes/grids (points/volumes resp.)
/// This can be initialized as a vector of pairs of strings e.g.
/// {{"axname0","dataname0"}, {"axname1","dataname1"}} see
/// AttributeBindings.h for details.
OPENVDB_AX_API
void run(const char* ax, openvdb::GridBase& grid,
const AttributeBindings& bindings = {});
/// @brief Run a full AX pipeline (parse, compile and execute) on a vector of
/// OpenVDB numerical grids OR a vector of OpenVDB Point Data grids.
/// @details This method wraps the parsing, compilation and execution of AX
/// code for a vector of OpenVDB grids. The vector must contain either
/// a set of any numerical grids supported by the default AX types OR
/// a set of OpenVDB Points grids. On success, grids in the provided
/// grid vector will be iterated over and updated if they are written
/// to.
/// @warning The type of grids provided changes the type of AX compilation. If
/// the vector is empty, this function immediately returns with no
/// other effect.
/// @note Various defaults are applied to this pipeline to provide a simple
/// run signature. For numerical grids, only active voxels are processed
/// and missing grid creation is disabled. For OpenVDB Points grids, all
/// points are processed. Any warnings generated by the parser, compiler
/// or executable will be ignored.
/// @note Various runtime errors may be thrown from the different AX pipeline
/// stages. See Exceptions.h for the possible different errors.
/// @param ax The null terminated AX code string to parse and compile
/// @param grids The grids to which to apply the compiled AX function
/// @param bindings An attribute bindings object mapping names in the AX string to
/// names of the point attributes/grids (points/volumes resp.)
/// This can be initialized as a vector of pairs of strings e.g.
/// {{"axname0","dataname0"}, {"axname1","dataname1"}} see
/// AttributeBindings.h for details.
OPENVDB_AX_API
void run(const char* ax, openvdb::GridPtrVec& grids,
const AttributeBindings& bindings = {});
} // namespace ax
} // namespace OPENVDB_VERSION_NAME
} // namespace openvdb
#endif // OPENVDB_AX_AX_HAS_BEEN_INCLUDED
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:272
openvdb::v10_0::GridBase
Abstract base class for typed grids.
Definition Grid.h:78
openvdb::v10_0::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::v10_0::ax
Definition ax.h:29
openvdb::v10_0::ax::isInitialized
OPENVDB_AX_API bool isInitialized()
Check to see if OpenVDB AX components have been initialized.
openvdb::v10_0::ax::initialize
OPENVDB_AX_API void initialize()
Initializes OpenVDB AX and subsequent LLVM components.
openvdb::v10_0::ax::uninitialize
OPENVDB_AX_API void uninitialize()
Uninitialize and deregister OpenVDB AX.
openvdb::v10_0::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::v10_0::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:212