OpenVDB: FunctionTypes.h File Reference

OpenVDB 8.1.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 <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 <unordered_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< 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::v8_1
| openvdb::v8_1::ax
| openvdb::v8_1::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...
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:

- Ensure C Binding dependencies have been correctly mapped.
- Avoid calling B.CreateAlloca inside of IR functions - instead rely on the utility method insertStaticAlloca() where possible.
- Ensure both floating point and integer argument signatures are provided if you wish to avoid floats truncating.
- Array arguments (vectors/matrices) are always passed by pointer. Scalar arguments are always passed by copy.
- Ensure array arguments which will not be modified are marked as readonly. Currently, only array arguments can be passed by "reference".
- Ensure function bodies, return types and parameters and marked with desirable llvm attributes.