README.md

MaxMath

MaxMath is the most powerful and extensive SIMD math library available to Unity developers. Built on top of Unity.Mathematics and utilizing Unity.Burst, it introduces the following key features:

• Support For All Primitive Data Types: MaxMath adds support for (s)byte, (u)short, and (u)long vectors and matrices. These data types come with optimized overloads for all functions in Unity.Mathematics. Additionally, specialized Random8/16/32/64/128 types are available for efficient pseudo-random number generation.
• Wider Vectors With Full Hardware Support: Vector types are expanded to 256 bits, enabling types like byte32, short16, int8, and float8. This allows you to leverage the full potential of SIMD computation.
• Many Additional Functions: MaxMath includes a massive library of mathematical functions not found in Unity.Mathematics, with about five times as many highly optimized functions at your disposal. Each function is fully documented with XML annotations. A full list is provided further below.
• Exotic Data Types: MaxMath introduces data types such as (U)Int128 (scalar only), 128-bit quadruple precision floats (scalar only), and 8-bit quarter precision floats (in both scalar and vector forms). Additionally, Divider<T> offers highly optimized integer division operations, extending and outperforming specialized libraries like libdivide.
• Written Entirely With Hardware Intrinsics: MaxMath guarantees optimal performance by utilizing specialized CPU instructions for both ARM and x86 ISAs, while abstracting these complexities away from the user entirely.
• Extends The Burst Compiler: MaxMath integrates deeply with Unity.Burst and LLVM, leveraging Unity.Burst.CompilerServices.Constant.IsConstantExpression<T>() to include code typically only found in optimizing compilers. This functionality allows MaxMath to choose more optimized code paths at compile time, and users can influence this behavior via the optional Promise enum parameter available in many functions.
• Easy To Use: MaxMath is just as easy to use as Unity.Mathematics. It supports features like implicit and explicit type conversions, making it seamless for you to use if you expect typical C# behavior of primitive types.
• Extensive Test Coverage: MaxMath is backed by 250,000 lines of unit tests for its 400,000 lines of code, as well as DEBUG only runtime checks where appropriate, together ensuring it is production ready.

How To Use This Library

New Types

Integer

(S)Byte

(U)Short

(U)Int

(U)Long

Floating Point

Float

Half

Quarter (8-bit 1.3.4.-3 IEEE 754 floating point)

Random Number Generators

XOR-Shift

New Functions

Miscellaneous

Arithmetic

Bitwise Operations

Vector Operations

Interpolation and Geometry

Type Conversion

What Kind Of Performance To Expect

Highlights

• Division and modulo operations of (s)byte and (u)short vectors by other vectors are implemented as either a long division algorithm ((s)byte32, (s)byte16 and (s)byte8 if not compiling for Avx2) or reciprocal multiplication after converting the vectors to float vectors (up to (s)byte8, all (u)short vectors) - it is very fast and, of course, 100% accurate!

• This library uses Wojciech Mula's SIMD population count algorithm. You can count the amount of set bits of a contiguous block of memory very efficiently using either the (s)byte32 (Avx2) or (s)byte16 (Ssse3) type

Notes

• It is recommended, just like with Unity.Mathematics, to use vector types that use up an entire SIMD register (128 and 256 bits, respectively). LLVM has a very hard time optimizing code which does not follow this recommendation

How To Install This Library

Disclaimer: I firmly believe in open source - being able to copy/modify/understand other people's code is great :) I also want people to be able to step through code with a debugger. For these reasons I usually don't distribute DLLs.

• Download the package and unzip it into your "LocalPackages" folder, which is located at the root folder of your Unity project (where your "Assets" folder resides at).
• Start up Unity. Usually Unity detects new packages and will generate .meta files for you.
• In case that doesn't work, open up the package manager from within Unity and click on the '+' symbol at the upper left corner of the window, further clicking on "Add package from disk..." - "Add package from git URL" should also work.

• Locate the library's "package.json" file
• DONE!