OpenVDB  12.0.0
Classes | Namespaces | Typedefs | Functions
FunctionTypes.h File Reference

Contains frameworks for creating custom AX functions which can be registered within the FunctionRegistry and used during code generation. The intended and safest way to build a function is to use the FunctionBuilder struct with its addSignature methods. Note that the derived Function classes provided can also be subclassed for more granular control, however may be subject to more substantial API changes. More...

#include "Types.h"
#include "Utils.h"
#include "ConstantFolding.h"
#include <openvdb/version.h>
#include <openvdb/util/Assert.h>
#include <llvm/IR/Constants.h>
#include <llvm/IR/IRBuilder.h>
#include <llvm/IR/Module.h>
#include <algorithm>
#include <functional>
#include <memory>
#include <stack>
#include <type_traits>
#include <map>
#include <vector>

Go to the source code of this file.

Classes

struct  ArgType< T, _SIZE >
 Object to array conversion methods to allow functions to return vector types. These containers provided an interface for automatic conversion of C++ objects to LLVM types as array types. More...
 
struct  LLVMType< ArgType< T, S > >
 
struct  TypeToSymbol< T >
 Type to symbol conversions - these characters are used to build each functions unique signature. They differ from standard AX or LLVM syntax to be as short as possible i.e. vec4d, [4 x double] = d4. More...
 
struct  TypeToSymbol< void >
 
struct  TypeToSymbol< char >
 
struct  TypeToSymbol< uint8_t >
 
struct  TypeToSymbol< uint16_t >
 
struct  TypeToSymbol< uint32_t >
 
struct  TypeToSymbol< uint64_t >
 
struct  TypeToSymbol< int8_t >
 
struct  TypeToSymbol< int16_t >
 
struct  TypeToSymbol< int32_t >
 
struct  TypeToSymbol< int64_t >
 
struct  TypeToSymbol< float >
 
struct  TypeToSymbol< double >
 
struct  TypeToSymbol< codegen::String >
 
struct  TypeToSymbol< T * >
 
struct  TypeToSymbol< T[S]>
 
struct  TypeToSymbol< ArgType< T, S > >
 
struct  TypeToSymbol< math::Vec2< T > >
 
struct  TypeToSymbol< math::Vec3< T > >
 
struct  TypeToSymbol< math::Vec4< T > >
 
struct  TypeToSymbol< math::Mat3< T > >
 
struct  TypeToSymbol< math::Mat4< T > >
 
struct  TypeToSymbol< const T >
 
struct  TypeToSymbol< const T * >
 
struct  ArgumentIterator< SignatureT, I >
 Templated argument iterator which implements various small functions per argument type, resolved at compile time. More...
 
struct  ArgumentIterator< SignatureT, 0 >
 
struct  Function
 The base/abstract representation of an AX function. Derived classes must implement the Function::types call to describe their signature. More...
 
struct  SRetFunction< SignatureT, DerivedFunction >
 Templated interface class for SRET functions. This struct provides the interface for functions that wish to return arrays (vectors or matrices) by internally remapping the first argument for the user. As far as LLVM and any bindings are concerned, the function signature remains unchanged - however the first argument becomes "invisible" to the user and is instead allocated by LLVM before the function is executed. Importantly, the argument has no impact on the user facing AX signature and doesn't affect declaration selection. More...
 
struct  CFunctionBase
 The base class for all C bindings. More...
 
struct  CFunction< SignatureT >
 Represents a concrete C function binding. More...
 
struct  IRFunctionBase
 The base/abstract definition for an IR function. More...
 
struct  IRFunction< SignatureT >
 Represents a concrete IR function. More...
 
struct  CFunctionSRet< SignatureT >
 Represents a concrete C function binding with the first argument as its return type. More...
 
struct  IRFunctionSRet< SignatureT >
 Represents a concrete IR function with the first argument as its return type. More...
 
struct  FunctionGroup
 todo More...
 
struct  FunctionBuilder
 The FunctionBuilder class provides a builder pattern framework to allow easy and valid construction of AX functions. There are a number of complex tasks which may need to be performed during construction of C or IR function which are delegated to this builder, whilst ensuring that the constructed functions are guaranteed to be valid. More...
 
struct  FunctionBuilder::Settings
 

Namespaces

 openvdb
 
 openvdb::v12_0
 
 openvdb::v12_0::ax
 
 openvdb::v12_0::ax::codegen
 

Typedefs

using V2D = ArgType< double, 2 >
 
using V2F = ArgType< float, 2 >
 
using V2I = ArgType< int32_t, 2 >
 
using V3D = ArgType< double, 3 >
 
using V3F = ArgType< float, 3 >
 
using V3I = ArgType< int32_t, 3 >
 
using V4D = ArgType< double, 4 >
 
using V4F = ArgType< float, 4 >
 
using V4I = ArgType< int32_t, 4 >
 
using M3D = ArgType< double, 9 >
 
using M3F = ArgType< float, 9 >
 
using M4D = ArgType< double, 16 >
 
using M4F = ArgType< float, 16 >
 

Functions

template<typename SignatureT >
llvm::Type * llvmTypesFromSignature (llvm::LLVMContext &C, std::vector< llvm::Type * > *types=nullptr)
 Populate a vector of llvm types from a function signature declaration. More...
 
template<typename SignatureT >
llvm::FunctionType * llvmFunctionTypeFromSignature (llvm::LLVMContext &C)
 Generate an LLVM FunctionType from a function signature. More...
 
OPENVDB_AX_API void printSignature (std::ostream &os, const std::vector< llvm::Type * > &types, const llvm::Type *returnType, const char *name=nullptr, const std::vector< const char * > &names={}, const bool axTypes=false)
 Print a function signature to the provided ostream. More...
 

Detailed Description

Contains frameworks for creating custom AX functions which can be registered within the FunctionRegistry and used during code generation. The intended and safest way to build a function is to use the FunctionBuilder struct with its addSignature methods. Note that the derived Function classes provided can also be subclassed for more granular control, however may be subject to more substantial API changes.

Authors
Nick Avramoussis

There are a variety of different ways to build a function which are tailored towards different function types. The two currently supported function implementations are C Bindings and IR generation. Additionally, depending on the return type of the function, you may need to declare your function an SRET (structural return) function.

C Bindings: As the name suggests, the CFunction class infrastructure provides the quickest and easiest way to bind to methods in your host application. The most important thing to consider when choosing this approach is performance. LLVM will have no knowledge of the function body during optimization passes. Depending on the implementation of your method and the user's usage from AX, C bindings may be subject to limited optimizations in comparison to IR functions. For example, a static function which is called from within a loop cannot be unrolled. See the CFunction templated class.

IR Functions: IR Functions expect implementations to generate the body of the function directly into IR during code generation. This ensures optimal performance during optimization passes however can be trickier to design. Note that, in the future, AX functions will be internally supported to provide a better solution for IR generated functions. See the IRFunction templated class.

SRET Functions: Both C Bindings and IR Functions can be marked as SRET methods. SRET methods, in AX, are any function which returns a value which is not a scalar (e.g. vectors, matrices). This follows the same optimization logic as clang which will rebuild function signatures with their return type as the first argument if the return type is greater than a given size. You should never attempt to return alloca's directly from functions (unless malloced).

Some other things to consider: