The Unity.Mathematics library includes a variety of noise functions, but the package documentation does not provide any information on what these methods do or what their parameters are (and the naming conventions used by these methods are non-obvious). I tried searching for documentation on the methods, but I couldn’t find any good references (at one-point @5argon had written a blog post on the topic but that no longer seems to be available). As a result, I ended up digging through the source for the library and found that there are fairly extensive comments documenting the functions. I’ve attempted to consolidate the information from the comments and posted it here so that it can be easily searched for by anyone else looking for this information in the future.
Please note that the information below is based strictly on my reading of the comments, and not on an analysis of the source code. If the comments included in the files were not maintained to reflect changes made to the code, then some of the information may be inaccurate. The information is based on the comments in the source code for version 1.2.1 of the Unity.Mathematics package and may be different for future versions of the package.
Overview
There are four groups of methods that belong to “noise” class:
- The “cellular” methods, which provide cellular/Worley noise functions (see Worley noise - Wikipedia).
- The “cnoise” and “pnoise” methods, which provide classic perlin noise and a periodic/tiling variant (see Perlin noise - Wikipedia).
- The “snoise” methods, which provide 2D simplex noise (see Simplex noise - Wikipedia).
- The “{p}sr{d}noise” methods, which also provide another implementation of 2D simplex noise, with variants for tiling, rotating gradients, and analytical derivatives.
Cellular Noise Functions
float2 cellular (float2 p) – A 2D cellular noise function returning F1 and F2 in the float2. It takes a 2D point as a parameter. Uses a 3x3 search window to ensure good F1 and F2 values.
float2 cellular2x2 (float2 p) – A 2D cellular noise function returning F1 and F2 in a float2. It takes a 2D point as a parameter. This is a faster variant, which uses a 2x2 search window instead of a 3x3 window. This sacrifices quality for speed. It introduces some strong pattern artifacts. The F2 is often wrong and has sharp discontinuities. If a smooth F2 is required, use the 3x3 variant. F1 is sometimes wrong, but OK for most purposes.
float3 cellular3D (float3 p) – A 3D cellular noise function, returning F1 and F2 in a float2. It takes a 3D point as a parameter. Uses a 3x3x3 search window to ensure good F2 values everywhere, but it is significantly slower than the 2x2x2 variant.
float3 cellular2x2x2 (float3 p) – A 3D cellular noise function, returning F1 and F2 in a float2. It takes a 3D point as a parameter. This is a faster variant, which uses a 2x2x2 search window instead of a 3x3x3 window. This sacrifices quality for speed. It introduces some pattern artifacts. F2 is often wrong and has sharp discontinuities. If you require a good F2, you’ll need to use the (slower) 3x3x3 variant.
Classic Perlin Noise Functions
float cnoise (float2 p) – 2D Perlin noise. Takes a 2D point and returns a noise value as a float.
float pnoise (float2 p, float2 rep) – 2D periodic (tiling) Perlin noise. This takes a 2D point (p) and period (rep).
float cnoise (float3 p) – 3D Perlin noise. Takes a 3D point and returns a noise value as a float.
float pnoise (float3 p, float3 rep) – 3D periodic (tiling) Perlin noise. This takes a 3D point (p) and period (rep).
float cnoise (float4 p) – 4D Perlin noise. Takes a 4D point and returns a noise value as a float.
float pnoise (float4 p, float4 rep) – 4D periodic (tiling) Perlin noise. This takes a 4D point (p) and period (rep).
Textureless 2D Simplex Noise Functions
float snoise (float2 v) – 2D Simplex noise. Takes a 2D point (v) and returns a noise value.
float snoise (float3 v) – 3D Simplex noise. Takes a 3D point (v) and returns a noise value.
float snoise (float3 v, out float3 gradient) – 3D Simplex noise with gradient. Takes a 3D point (v) and return a noise value. Also provides the gradient as an output parameter.
float snoise (float4 v) – 4D Simplex noise. Takes a 4D point (v) and returns a noise value.
Additional 2D Simplex Nose Functions
According to the comments, these methods use the following naming convention:
- Variants without a “d” in the name lack the analytical derivative.
- Variants without a “p” in the name are not periodic (i.e., they do not tile)
- Variants without an “r” in the name do not use a rotating gradient – NOTE: this convention is not followed. All method names include an “r”, regardless of whether they are rotating. You can tell the methods without a rotating gradient apart because they do not take a “rot” parameter as an argument.
The comments state that these are additional variants on Simplex noise, similar to the versions presented by Ken Perlin (however the grid is axis-aligned and stretched along the y-axis to permit rectangular tiling).
The periodic (“p”) variants can be made to tile seamlessly for any integer period x and any even integer period y. Odd periods can be specified for y, but the tiling period will be twice that number.
The rotating gradients (those variants that have a “rot” parameter) give the appearance of a swirling motion. This can serve a similar purpose for animation as motion along z in the 3D noise. Rotating gradients in conjunction with the analytic derivatives can make “flow noise” effects as presented by Perlin and Neyret in 2001 (see https://hal.inria.fr/inria-00537499/document and https://mrl.cs.nyu.edu/flownoise/ for more information).
Possible method arguments
- “pos” – always present. The 2D input coordinates.
- “per” – only for periodic variants. The x and y period values, where x is a positive integer and y is a positive even integer.
- “rot” – only for rotating gradient variants. The amount to rotate the gradients, where 0 is no rotation and 1.0 is one full rotation.
Possible method return types
- float – variants that return a float just return the noise value for the given parameters.
- float3 – variants that return a float3 return the noise value and analytical derivatives for the given parameters. The x value is the noise value, and y and z values correspond to the x and y analytical derivatives.
Method Variants
float3 psrdnoise (float2 pos, float2 per, float rot) – 2D periodic (tiling) simplex noise with rotating gradients and analytical derivatives.
float3 psrdnoise (float2 pos, float2 per) – 2D periodic (tiling) simplex noise with fixed gradients and analytical derivatives. This is a wrapper for the rotating gradients variant, equivalent to calling: psrdnoise (pos, per, 0).
float psrnoise (float2 pos, float2 per, float rot) – 2D periodic (tiling) simplex noise with rotating gradients. This variant does not include analytical derivatives, which makes it faster.
float psrnoise (float2 pos, float2 per) – 2D periodic (tiling) simplex noise with fixed gradients. This variant does not include analytical derivatives, which makes it faster. This is a wrapper for the rotating gradients variant, equivalent to calling psrnoise (pos, per, 0).
float3 srdnoise (float2 pos, float rot) – 2D non-periodic (non-tiling) simplex noise with rotating gradients and analytical derivatives.
float3 srdnoise (float2 pos) – 2D non-periodic (non-tiling) simplex noise with fixed gradients and analytical derivatives. This is a wrapper for the rotating gradients variant, equivalent to calling srdnoise (pos, 0).
float srnoise (float2 pos, float rot) – 2D non-periodic (non-tiling) simplex noise with rotating gradients. This variant does not include analytical derivatives, which makes it faster.
float srnoise (float2 pos) – 2D non-periodic (non-tiling) simplex noise with fixed gradients. This variant does not include analytical derivatives, which makes it faster. This is a wrapper for the rotating gradients variant, equivalent to calling srnoise (pos, 0). NOTE: the comments state that there are other, more efficient implementations of this type of noise, this implementation is merely included for completeness and compatibility with the other functions following this naming convention.