The APIs in the Unity.Mathematics namespace are a Burst-compilable C# math library that provides vector types and math functions that have a shader-like
syntax, similar to Single Instruction, Multiple Data (SIMD) or High-Level Shading Language (HLSL).
Unity Mathematics offers a Burst-compilable alternative to Unity’s standard Unity Engine math APIs. Unity Mathematics implements vector and matrix types such as float3, quaternion, float3×3, and float4×4. It also includes elementary functions such as min, max, fabs, sin, cos, sqrt, normalize, dot, and cross.
To use Unity Mathematics, add using Unity.Mathematics to your code.
Prefer Unity Mathematics APIs over Unity Engine math APIs in Burst-compiled code. For code that isn’t Burst compiled, prefer Unity Engine math APIs.
In C# int and float are built-in types. The Burst compiler extends this set of built-in types to also include vectors, matrices, and quaternionsUnity’s standard way of representing rotations as data. When writing code that deals with rotations, you should usually use the Quaternion class and its methods. More info
See in Glossary. The Burst compiler already has implementations of these types, and can use them to generate better code than for custom types.
To signify that these types are built-in, their type names are in all lower case. The operators on these built-in types in Unity.Mathematics.math are intrinsics and are always in lower case. This convention has the added benefit of making the library highly compatible with shaderA program that runs on the GPU. More info
See in Glossary code and makes porting or sharing code between the two easier.
To create a 4×4 transformation matrix, use the constructors in float4x4 to assign one value to all elements of the matrix, or individually set all 16 elements directly:
// Unity Mathematics example
void Build4x4UnityMathematics()
{
var c0 = new float4(1.0f, 0.0f, 0.0f, 0.0f);
var c1 = new float4(0.0f, 1.0f, 0.0f, 0.0f);
var c2 = new float4(0.0f, 0.0f, 1.0f, 0.0f);
var c3 = new float4(0.0f, 0.0f, 0.0f, 1.0f);
var m = new float4x4(c0, c1, c2, c3);
}
The Unity.Mathematics and UnityEngine APIs define the * operator differently. The * operator for float4x4 implements componentwise multiplication. If you multiply a float4x4 of all 1s with 0.5 on the diagonal, you get back the half identity because the upper and lower triangles of the matrix are multiplied by the respective zero entries from f4x4_HalfIdentity:
// Unity Mathematics example
void OperatorMultiply4x4UnityMathematics()
{
float4x4 result = f4x4_Ones * f4x4_HalfIdentity;
// result:
// 0.5, 0.0, 0.0, 0.0,
// 0.0, 0.5, 0.0, 0.0,
// 0.0, 0.0, 0.5, 0.0,
// 0.0, 0.0, 0.0, 0.5
}
Use the math.mul method to multiply a 4×4 matrix and a 4D vector. If you supply a float4x4 as the first parameter and a float4 as the second, it performs a 4×4 matrix multiplication with a 4×1 column vector, which returns a 4×1 column vector as a float4.
math.mul can also multiply a 1×4 row vector by a 4×4 matrix to produce a 1×4 row vector by taking a float4 as the first parameter and a float4×4 as the second. Unity Mathematics stores the row vector in a float4 and it isn’t treated as a separate type.
// Unity Mathematics example
void Multiply4x4AndVector4UnityMathematics()
{
float4 result1 = math.mul(f4x4, f4); // 4x4 * 4x1 = 4x1
float4 result2 = math.mul(f4, f4x4); // 1x4 * 4x4 = 1x4
}
To multiply vectors, use the * operator:
// Unity Mathematics example
void ComponentwiseVectorMultiplyUnityMathematics()
{
var v0 = new float4(2.0f, 4.0f, 6.0f, 8.0f);
var v1 = new float4(1.0f, -1.0f, 1.0f, -1.0f);
var result = v0 * v1;
// result == new float4(2.0f, -4.0f, 6.0f, -8.0f).
}
This is a common way of writing SIMD code, which applies a single instruction to multiple data elements. Other operators such as addition, subtraction, and division work in the same way.
To rotate a quaternion, use the AxisAngle method. You need to specify the axis of rotation and the angle of rotation, in that order. All are in radians rather than degrees. math.mul multiplies the quaternion, just as with matrices and vectors.
// Unity Mathematics example
void QuaternionMultiplicationUnityMathematics()
{
var axis = new float3(0.0f, 1.0f, 0.0f);
var q = quaternion.AxisAngle(axis,math.radians(45.0f));
var orientation = quaternion.Euler(
math.radians(45.0f),
math.radians(90.0f),
math.radians(180.0f));
var result = math.mul(q, orientation);
}
To generate random numbers, you must create and manage the random number generator state yourself with the Random struct. You can control the random number generator state explicitly, which is useful if you’re using parallel code, or if you want to make sure that one source of random numbers is seeded differently than another source. You can also have as many Random instances as you like.
Once you set up the state, use NextFloat to get random floats. By default it returns random numbers between [0, 1), exclusive:
// Unity Mathematics example
void RandomNumberUnityMathematics()
{
// Choose some non-zero seed and set up the random number generator state.
uint seed = 1;
Unity.Mathematics.Random rng = new Unity.Mathematics.Random(seed);
// [0, 1) exclusive
float randomFloat1 = rng.NextFloat();
// [-5, 5) exclusive
float randomFloat2 = rng.NextFloat(-5.0f, 5.0f);
}