ltmx / unity.mathx

An Extension Library for Unity.Mathematics - Extension Methods, New Syntax, Optimized Functions, and more !

Unity.mathx

Extension Library for Unity.Mathematics & quality of life improvements !

Package name

com.ltmx.mathematics.mathx

⬇️ Install

Method 1 :

1. Copy Git Package URL : https://github.com/LTMX/Unity.mathx.git
2. In Unity : Window > Package Manager > Add Package From Git URL

Method 2 :

1. Download the package in releases
2. Unity : Window > Package Manager > Add Package From Disk
3. Select the package.json file inside the unzipped package

#️⃣ Usage

using static Unity.Mathematics.mathx;

♾ Linq-Style Syntax

return anyVector.length().clamp(0, 10).cos().sq().cube().sum().cmul().rotate(anyQuaternion).clint().div(3.2f).rcp();

📈 A Few Neat Features

// Example
float3 x = new float3(1,1,1);

// here x is set before computing lengthsq()
var x = x.mult(4.2f).shuffle().set(out x).lengthsq() + x;

// we would have to write two lines instead
x = x.div(4.2f).shuffle();
x = x.lengthsq() + x;

bool4.any(); // returns true if any component is true // or-gate
bool4.all(); // returns trye if all components are true // and-gate

🏛 Roadmap

• Fast Functions
• Constants (PI, HPI, EULER, TAU, and many scientific constants
• Mathf function implementations missing from Unity.Mathematics
• Random Extensions (Random.range and others)
• Component based functions (cmax, cmin, cmul, cmaxAxis, cminAxis, sum)
• Signed Distance Functions
• Component based logic (any, all, select, approx, odd, even, isnan, anynan)
• Multidimentional Array data accessors => anyfloat4[,,].Get(anyInt3)
• Interpolation Functions (InOutCubic, smoothstep, smoothstep11, smoothstep9, and others)
• smoothmin, smoothmax
• Shorthands (3D Directions, 2D Directions, and others)
• Data Construction (append, float2.xyzw(), matrix construction, etc)
• Data Conversion (anyColortArray.tofloat4Array(), and others)
• Noise Functions WIP (Simplex, Perlin, Whorley, Layered, Voronoi)
• Documentation 80% Complete
• Job Helpers WIP
• Burst Compiled Function Pointers WIP 50%
• Function Iterators (prevents nested loops) WIP 50%
• Hashing Functions WIP 80%
• Vector Function Builders WIP 50%
• Generic Jobs WIP 50%
• Mesh Processing WIP 0%

🎇 Structs

struct bounds; // UnityEngine translation compatible with Unity.Mathematics (implicit cast to "UnityEngine.Bounds")
struct ray;    // UnityEngine translation compatible with Unity.Mathematics (implicit cast to "UnityEngine.Ray")
struct color;  // UnityEngine translation compatible with Unity.Mathematics (implicit cast to "UnityEngine.Color")
struct byte4;  // Useful for Color32 to byte conversion, Useful for image file export (implicit cast to "UnityEngine.Color32") //For Unity.QOI
struct byte3;  // For Unity.QOI
struct byte2;
struct byte1;

Method List 1.3.6

// most methods have at least a dozen overloads
fcos() veryFastCos() ultraFastCos() CosLoop() SinLoop() sfcos() fsqrt()
fdistance() flength() log2int() fastmodinv() fexp() sfastsine() sfastcosine()
fastsine() fastcosine() anglerad() angledeg() fastangle() straightsignedangle()
preciseangle() signedangle() fastatan2() sign() abs() mod() frac() csum() cmul()
inv() neg() rcp() pow() sq() cube() pow4() pow5() sqrt() cbrt() rcbrt() rsqrt()
m2n1() add() sub() div() cycle() saturate() snap() bitwave() bitwave2()
triwave() set() Array() toColorArray() tocolorArray() tofloat4List()
tofloat3List() tofloat4Array() tofloat3Array() toVectorArray() tofloatArray()
CopyFrom() asint() asbool() asfloat() asdouble() asuint() ascolor() asColor()
asfloat4() asfloat3() cast() List() toVectorList() tofloatList() toColorList()
tocolorList() toVectorIE() tofloatIE() xx() xxx() xxxx() dim() exp() nexp()
exp2() exp10() ln() log2() log10() f4() f3() f2() append() y() z() yz() w() zw()
yzw() xyzw() xyz() xy() x() smootherstep() smoothstepcos() eerp() uneerp()
smoothstep() unlerp() lerp() lerpAngle() remap() step() arc() arch2() linstep()
sine01() smin() smax() smax_exp() smax_exp2() smax_expOP() smin_exp() smin_pow()
smin_root() smin_polynomial() smin_quadratic() smin_cubic() smin_factor()
smin_cubic_factor() smin_N_factor() mix() smoothstart() smoothstop() xfade()
easeInSine() easeOutSine() easeInOutSine() easeInQuad() easeOutQuad()
easeInOutQuad() easeInCubic() easeOutCubic() easeInOutCubic() easeInQuart()
easeOutQuart() easeInOutQuart() easeInQuint() easeOutQuint() easeInOutQuint()
easeInExpo() easeOutExpo() easeInOutExpo() easeInCirc() easeOutCirc()
easeInOutCirc() easeInBack() easeOutBack() easeInOutBack() easeInElastic()
easeOutElastic() easeInOutElastic() easeInBounce() easeOutBounce()
easeInOutBounce() smooth() smoothstepD() smooth5() smooth5D() smooth7()
smooth7D() smooth9() smooth9D() smooth11() smooth11D() smoothD() smoother7D()
any() all() select() approx() odd() even() isnan() anynan() isinf() isfinite()
greater() less() lesseq() greatereq() eq() neq() isgreatest() isshortest() get()
pingpong() SampleParabola() movetowards() repeat() smoothdamp() b4x4() b4x3()
b4x2() b3x4() b3x3() b3x2() b2x4() b2x3() b2x2() d4x4() d4x3() d4x2() d3x4()
d3x3() d3x2() d2x4() d2x3() d2x2() mul() dot() lengthsq() mult() transpose()
f4x4() f4x3() f4x2() f3x4() f3x3() f3x2() f2x4() f2x3() f2x2() i4x4() i4x3()
i4x2() i3x4() i3x3() i3x2() i2x4() i2x3() i2x2() u4x4() u4x3() u4x2() u3x4()
u3x3() u3x2() u2x4() u2x3() u2x2() init() randf() randf2() randf3() randf4()
seedrand() seedrand2() seedrand3() seedrand4() randmax() setseed() hash()
hashwide() varyrand() addrand() rand() randomint() randomInSphere()
randomInCircle() randomDir3D() randomDir2D() randomrotation() rotate()
rotateAxisAngle() rotateRad() rotateDeg() quaternion() rotateAround() round()
rint() clamp() min() max() ceil() clint() floor() flint() sat() npsat() limp()
limn() under1() cmax() cmin() acmax() acmin() sin() cos() tan() sec() cot()
csc() asin() acos() atan() atan2() acot() asec() acsc() sin2() cos2() tan2()
sec2() deg() rad() cossin() sincos() mod360() mod2PI() sinh() cosh() tanh()
sech() coth() csch() acosh() asinh() atanh() acoth() asech() acsch() norm()
normsafe() distance() distancesq() length() reflect() refract() project()
projectsafe() manhattan() minkowski() chebyshev() cross() perp() exterior()
orthonorm() cdistance() cdistancesq() ccross() cdot() hashnp01() Hash()
GradientNoise() GenerateGradient() randdir() unity_gradientNoise() hashx()
openSimplex2_ImproveXY() openSimplex2SDerivatives_ImproveXY() sdSphere() sdBox()
sdRoundBox() sdBoxFrame() sdTorus() sdCappedTorus() sdLink() sdCylinder()
sdCone() sdConeBound() sdPlane() sdHexPrism() sdTriPrism() sdCapsule()
sdVerticalCapsule() sdCappedCylinder() sdRoundedCylinder() sdCappedCone()
sdSolidAngle() sdCutSphere() sdCutHollowSphere() sdDeathStar() sdRoundCone()
sdEllipsoid() sdbEllipsoid_2() sdaEllipsoid_3() sdRhombus() sdOctahedron()
sdOctahedronBound() sdPyramid() udTriangle() udQuad() _length2() _length6()
_length8() byte1() byte2() byte3() byte4() color() gammatolinear()
lineartogama() Erf() Erfc() ErfInv() ErfcInv() GammaLn() Gamma() DiGamma()
DiGammaInv() conjugate() inverse() unitexp() unitlog() log() nlerp() slerp()
forward() matrix() float3x4() rotation() translation() transform() up() right()
scale() projectplane() apply() GetFunctionPointerDelegate()

🌱 Contribute !

👉 Guidelines

• All methods should exist in the Unity.Mathematics.mathx class (To prevent multiple using declarations)
• All Methods should follow a lower case syntax (shader like syntax)
• All methods names should be as short as possible while conserving their meaning or naming convension
• Everything must be Open Source
• Credits should (if the author can be found) figure above code snipets or in the file header (if reusing existing code)
• file mames should follow this convention : mathx.. Example : mathx.interpolation.common (common methods for interpolation) or mathx.logix.floatx (float type related logic functions)
  • File names for base types such as bounds or byte2 should only have their type as a title : bounds.cs // byte2.cs
• Every method should be static (if applicable)
• Dependencies should not exist if applicable
  • Code must be rewritten and optimized for Unity.Mathematics, compatibility checked
  • Unification is key : if some functions are already available in math or Unity.Mathematics.math (sometimes under another name), use them !
• Documentation should be inherited from Unity.Mathematics.math methods for direct extension method translations

📜 LICENSING

This project is licensed under the MIT License (License)

unity.mathx's Issues

float3 movetowards(this float3, float3, float) is recursive and loops infinitely.

The implementation of float3 movetowards(this float3, float3, float) simply calls itself and creates an infinite loop.

All the other float* movetowards() functions seem alright. It is just that one variant.

Vector Function Builders

Benchmark mix() vs lerp() vs xfade() ... all doing the exact same thing

Mesh Generaction & Processing

Hashing Functions

See implementation such as :
https://github.com/keijiro/Skinner/blob/4f1b8656985d89c92f31d20e93ca1b1446c4640e/Assets/Klak/Math/XXHash.cs

Benchmark bitwave() against bitwave2()

[MethodImpl(IL)] public static float4 bitwave(float4 x) => floor(math.fmod(x, 2));
[MethodImpl(IL)] public static float4 bitwave2(float4 x) => (int4)x & 1;

[HELP Needed] docfx documentation using DocFxForUnity

Followed instructions here : https://github.com/NormandErwan/DocFxForUnity
documentation doesn't seem to compile properly, no documentation pages are generated.

Hosted Documentation

Setup Github Actions :
https://blog.taranissoftware.com/document-your-net-code-with-docfx-and-github-actions

Noise Functions

Simplex, Perlin, Whorley, Layered, Voronoi

Burst Compiled Function Pointers

Easings

Implement easings like nebukam's package : https://github.com/Nebukam/com.nebukam.easing

Compilation error on version 1.4.8

Describe the bug
FunctionPointers.p_smax_exp() has been commented out but it is still being used in mathx.interpolation.common.cs thus causes compilation error.

To Reproduce
Install version 1.4.8, this error will be reported

Library\PackageCache\[email protected]\Runtime\mathx.interpolation.common.cs(298,96): error CS0117: 'FunctionPointers' does not contain a definition for 'p_smax_exp'

Expected behavior
No compilation error.