An Overview of Noise Functions in the Unity.Mathematics Package

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 https://en.wikipedia.org/wiki/Worley_noise).
• The “cnoise” and “pnoise” methods, which provide classic perlin noise and a periodic/tiling variant (see https://en.wikipedia.org/wiki/Perlin_noise).
• The “snoise” methods, which provide 2D simplex noise (see https://en.wikipedia.org/wiki/Simplex_noise).
• 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.

 

Very useful summary, thanks!

Bonus tip: You can use Burst to speed up noise generation even outside of jobs like this.

 

His web page can be down, he's forgetting to pay hosting from time to time. But everything is available on Patreon.
https://medium.com/@5argon/various-noise-functions-76327e056450

 

Thanks! That's great. His posts are always really informative.

 

Also a good post to show that the decision not to adhere to the C# naming convention is rather counterproductive. In general, i think that some low-level naming are badly chosen in some languages.