Class NoiseGenerator

Generates coherent noise values using configurable algorithms and fractal layering. Instance-based: holds a seed for deterministic output.

Inheritance

object

NoiseGenerator

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.Noise

Assembly: ScyllaCore.dll

Syntax

public sealed class NoiseGenerator

Remarks

Supports OpenSimplex2, Improved Perlin, Value, and Value-Cubic noise algorithms, with optional fractal layering (FBM, Turbulence, Ridged multifractal, PingPong) for natural-looking patterns.

All sampling methods are allocation-free after initialization. The Perlin permutation table (512 ints = 2KB) is allocated lazily on first Perlin evaluation. Hash-based algorithms (OpenSimplex2, Value, Value-Cubic) require zero additional memory.

This class is NOT thread-safe. Each thread should use its own NoiseGenerator instance, or access must be externally synchronized. The lazy Perlin permutation table initialization is not atomic; concurrent first-use from multiple threads may cause a redundant allocation (benign for correctness, as both produce identical results).

Constructors

NoiseGenerator(IRandomSource)

Creates a new NoiseGenerator by deriving a seed from an IRandomSource.

Declaration

public NoiseGenerator(IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source to derive the seed from.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng is null.

NoiseGenerator(long)

Creates a new NoiseGenerator with the specified seed.

Declaration

public NoiseGenerator(long seed = 0)

Parameters

Type	Name	Description
long	seed	The seed value for deterministic noise generation. Default is 0.

Properties

Seed

The seed that drives all noise evaluations on this instance. Two generators with the same seed will produce identical output for identical inputs. The seed is set at construction time and cannot be changed.

Declaration

public long Seed { get; }

Property Value

Type	Description
long

Methods

Evaluate2D(float, float, NoiseAlgorithm)

Evaluates 2D noise at the given coordinates using the specified algorithm. Returns a single-octave value in the approximate range [-1, 1].

Declaration

public float Evaluate2D(float x, float y, NoiseAlgorithm algorithm = NoiseAlgorithm.OpenSimplex2)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
NoiseAlgorithm	algorithm	The noise algorithm to use.

Returns

Type	Description
float	Noise value in the approximate range [-1, 1].

Evaluate3D(float, float, float, NoiseAlgorithm)

Evaluates 3D noise at the given coordinates using the specified algorithm. Returns a single-octave value in the approximate range [-1, 1].

Declaration

public float Evaluate3D(float x, float y, float z, NoiseAlgorithm algorithm = NoiseAlgorithm.OpenSimplex2)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
float	z	Z coordinate.
NoiseAlgorithm	algorithm	The noise algorithm to use.

Returns

Type	Description
float	Noise value in the approximate range [-1, 1].

EvaluateCellular2D(float, float, CellularSettings)

Evaluates 2D cellular (Worley) noise at the given coordinates using the specified settings. Returns a single-octave cellular value; for multi-octave layering use FractalCellular2D(float, float, CellularSettings).

Declaration

public float EvaluateCellular2D(float x, float y, CellularSettings settings)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
CellularSettings	settings	Cellular noise configuration. The Frequency field scales the coordinates before evaluation. Fractal fields are ignored by this method.

Returns

Type	Description
float	Noise value whose range depends on ReturnType and DistanceType. F1 Euclidean returns approximately [0, 1]; F2MinusF1 returns approximately [0, 0.7]. Values are not normalized to [-1, 1].

EvaluateCellular3D(float, float, float, CellularSettings)

Evaluates 3D cellular (Worley) noise at the given coordinates using the specified settings. Returns a single-octave cellular value; for multi-octave layering use FractalCellular3D(float, float, float, CellularSettings).

Declaration

public float EvaluateCellular3D(float x, float y, float z, CellularSettings settings)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
float	z	Z coordinate.
CellularSettings	settings	Cellular noise configuration. The Frequency field scales the coordinates before evaluation. Fractal fields are ignored by this method.

Returns

Type	Description
float	Noise value whose range depends on ReturnType and DistanceType. F1 Euclidean returns approximately [0, 1]; F2MinusF1 returns approximately [0, 0.7]. Values are not normalized to [-1, 1].

Fill2D(float[], int, int, NoiseSettings, float, float)

Fills a flat row-major array with 2D fractal (or single-octave) noise values, sampling integer grid coordinates offset by offsetX and offsetY. This is the preferred bulk-fill path; it avoids per-call delegate allocation compared to calling Fractal2D(float, float, NoiseSettings) in a loop.

Declaration

public void Fill2D(float[] output, int width, int height, NoiseSettings settings, float offsetX = 0, float offsetY = 0)

Parameters

Type	Name	Description
float[]	output	The output array to fill with noise values. Must have at least width * height elements. Element at column col, row row is written to index row * width + col.
int	width	Number of columns (X axis). Must be at least 1.
int	height	Number of rows (Y axis). Must be at least 1.
NoiseSettings	settings	Noise configuration. When Fractal is None or Octaves is 1, a single-octave evaluation is used per cell; otherwise the full fractal accumulator is used. See Fractal2D(float, float, NoiseSettings) for output range details.
float	offsetX	X coordinate offset applied to every sample. Use to tile or shift the sampling window (e.g., pass chunkX * chunkWidth for seamless chunk-based generation).
float	offsetY	Y coordinate offset applied to every sample.

Exceptions

Type	Condition
ArgumentNullException	Thrown if output is null.
ArgumentException	Thrown if the array length is less than width * height.
ArgumentOutOfRangeException	Thrown if width or height is less than 1.

Fill3D(float[], int, int, int, NoiseSettings, float, float, float)

Fills a flat row-major array with 3D fractal (or single-octave) noise values, sampling integer grid coordinates offset by the provided offsets. This is the preferred bulk-fill path for volumetric data such as 3D terrain or fog density fields.

Declaration

public void Fill3D(float[] output, int width, int height, int depth, NoiseSettings settings, float offsetX = 0, float offsetY = 0, float offsetZ = 0)

Parameters

Type	Name	Description
float[]	output	The output array to fill with noise values. Must have at least width * height * depth elements. Element at column col, row row, slice slice is written to index slice * (width * height) + row * width + col.
int	width	Number of columns (X axis). Must be at least 1.
int	height	Number of rows (Y axis). Must be at least 1.
int	depth	Number of slices (Z axis). Must be at least 1.
NoiseSettings	settings	Noise configuration. When Fractal is None or Octaves is 1, a single-octave evaluation is used per cell; otherwise the full fractal accumulator is used. See Fractal3D(float, float, float, NoiseSettings) for output range details.
float	offsetX	X coordinate offset applied to every sample. Use to tile or shift the sampling window.
float	offsetY	Y coordinate offset applied to every sample.
float	offsetZ	Z coordinate offset applied to every sample.

Exceptions

Type	Condition
ArgumentNullException	Thrown if output is null.
ArgumentException	Thrown if the array length is less than width * height * depth.
ArgumentOutOfRangeException	Thrown if width, height, or depth is less than 1.

FillCellular2D(float[], int, int, CellularSettings, float, float)

Fills a flat row-major array with 2D cellular (Worley) noise values, sampling integer grid coordinates offset by offsetX and offsetY. Fractal layering is applied when Fractal is set and Octaves is greater than 1.

Declaration

public void FillCellular2D(float[] output, int width, int height, CellularSettings settings, float offsetX = 0, float offsetY = 0)

Parameters

Type	Name	Description
float[]	output	The output array to fill with noise values. Must have at least width * height elements. Element at column col, row row is written to index row * width + col.
int	width	Number of columns (X axis). Must be at least 1.
int	height	Number of rows (Y axis). Must be at least 1.
CellularSettings	settings	Cellular noise configuration including return type, distance metric, jitter, frequency, and optional fractal parameters.
float	offsetX	X coordinate offset applied to every sample.
float	offsetY	Y coordinate offset applied to every sample.

Exceptions

Type	Condition
ArgumentNullException	Thrown if output is null.
ArgumentException	Thrown if the array length is less than width * height.
ArgumentOutOfRangeException	Thrown if width or height is less than 1.

FillCellular3D(float[], int, int, int, CellularSettings, float, float, float)

Fills a flat row-major array with 3D cellular (Worley) noise values, sampling integer grid coordinates offset by the provided offsets. Fractal layering is applied when Fractal is set and Octaves is greater than 1.

Declaration

public void FillCellular3D(float[] output, int width, int height, int depth, CellularSettings settings, float offsetX = 0, float offsetY = 0, float offsetZ = 0)

Parameters

Type	Name	Description
float[]	output	The output array to fill with noise values. Must have at least width * height * depth elements. Element at column col, row row, slice slice is written to index slice * (width * height) + row * width + col.
int	width	Number of columns (X axis). Must be at least 1.
int	height	Number of rows (Y axis). Must be at least 1.
int	depth	Number of slices (Z axis). Must be at least 1.
CellularSettings	settings	Cellular noise configuration including return type, distance metric, jitter, frequency, and optional fractal parameters.
float	offsetX	X coordinate offset applied to every sample.
float	offsetY	Y coordinate offset applied to every sample.
float	offsetZ	Z coordinate offset applied to every sample.

Exceptions

Type	Condition
ArgumentNullException	Thrown if output is null.
ArgumentException	Thrown if the array length is less than width * height * depth.
ArgumentOutOfRangeException	Thrown if width, height, or depth is less than 1.

Fractal2D(float, float, NoiseSettings)

Evaluates 2D fractal noise at the given coordinates using the specified settings. Combines multiple octaves according to the fractal type configured in settings.

Declaration

public float Fractal2D(float x, float y, NoiseSettings settings)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
NoiseSettings	settings	Noise configuration including algorithm selection, fractal type, base frequency, octave count, lacunarity, and persistence.

Returns

Type	Description
float	Noise value whose range depends on the fractal type: FBM - approximately [-1, 1]. PingPong - approximately [-1, 1]. Turbulence - [0, 1]. Ridged - approximately [0, 2], unnormalized, always non-negative. None or Octaves <= 1 - single-octave result with the fractal transform applied (see remarks).

Remarks

When Fractal is None or Octaves is 1, the multi-octave loop is bypassed and a single scaled evaluation is returned. Turbulence, Ridged, and PingPong transforms are still applied to the single sample so the output type remains consistent.

Fractal3D(float, float, float, NoiseSettings)

Evaluates 3D fractal noise at the given coordinates using the specified settings. Combines multiple octaves according to the fractal type configured in settings.

Declaration

public float Fractal3D(float x, float y, float z, NoiseSettings settings)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
float	z	Z coordinate.
NoiseSettings	settings	Noise configuration including algorithm selection, fractal type, base frequency, octave count, lacunarity, and persistence.

Returns

Type	Description
float	Noise value whose range depends on the fractal type: FBM - approximately [-1, 1]. PingPong - approximately [-1, 1]. Turbulence - [0, 1]. Ridged - approximately [0, 2], unnormalized, always non-negative. None or Octaves <= 1 - single-octave result with the fractal transform applied (see remarks).

Remarks

When Fractal is None or Octaves is 1, the multi-octave loop is bypassed and a single scaled evaluation is returned. Turbulence, Ridged, and PingPong transforms are still applied to the single sample so the output type remains consistent.

FractalCellular2D(float, float, CellularSettings)

Evaluates 2D fractal cellular noise at the given coordinates. Combines multiple octaves of cellular noise according to the fractal type in settings.

Declaration

public float FractalCellular2D(float x, float y, CellularSettings settings)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
CellularSettings	settings	Cellular noise configuration including fractal parameters.

Returns

Type	Description
float	Noise value whose range depends on the return type, distance metric, and fractal type. FBM and PingPong normalize by total amplitude; Turbulence uses absolute values; Ridged is unnormalized and always non-negative.

FractalCellular3D(float, float, float, CellularSettings)

Evaluates 3D fractal cellular noise at the given coordinates. Combines multiple octaves of cellular noise according to the fractal type in settings.

Declaration

public float FractalCellular3D(float x, float y, float z, CellularSettings settings)

Parameters

Type	Name	Description
float	x	X coordinate.
float	y	Y coordinate.
float	z	Z coordinate.
CellularSettings	settings	Cellular noise configuration including fractal parameters.

Returns

Type	Description
float	Noise value whose range depends on the return type, distance metric, and fractal type. FBM and PingPong normalize by total amplitude; Turbulence uses absolute values; Ridged is unnormalized and always non-negative.

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)