RedOwl.Noise

A high-performance, deterministic noise generation library for .NET with a clean, composable API. Generate procedural noise for terrain, textures, effects, and more.

Features

• Multiple Noise Types: Gradient (Perlin-style), Value, Voronoi, and Fractal variants (Billow, Ridge, Pink)
• Composable API: Combine and modify noise generators using intuitive operators and extension methods
• Deterministic: Seed-based generation ensures consistent results across platforms (IEEE 754 compliant)
• Thread-Safe: All generators are stateless and safe for concurrent use
• High Performance: Optimized for speed with minimal allocations in hot paths
• Texture Synthesis: Built-in support for generating textures from noise
• Flexible Interpolation: Choose from Linear, Cubic, Quintic, or Cosine interpolation curves

Installation

dotnet add package RedOwl.Noise

Quick Start

using RedOwl;

// Create a simple gradient noise generator
var noise = new Noise.Gradient(seed: 42);

// Sample noise at a 3D point
float value = noise.GetValue(1.5f, 2.3f, 0.8f);

// Compose multiple noise generators
var combined = noise * 0.5f + new Noise.Gradient(seed: 100);

Noise Types

Basic Noise Generators

Gradient (Perlin-style)

Smooth, natural-looking noise using gradient vectors. Perfect for terrain, clouds, and organic patterns.

var gradient = new Noise.Gradient(seed: 42);
var gradientWithCurve = new Noise.Gradient(seed: 42, curve: Noise.SCurve.Quintic);

Properties:

• Period (int): Wraps noise coordinates for tiling (0 = no wrapping)

Value

Simple value-based noise with smoother interpolation than pure random values.

var value = new Noise.Value(seed: 42);
var valueWithCurve = new Noise.Value(seed: 42, sCurve: Noise.SCurve.Cosine);

Properties:

• Period (int): Wraps noise coordinates for tiling

Voronoi Noise

Voronoi noise creates cellular patterns based on distance to control points.

VoronoiPits

Returns the distance to the nearest Voronoi cell.

var pits = new Noise.VoronoiPits(seed: 42);
pits.Frequency = 2.0f; // Control cell density

VoronoiValleys

Returns the difference between 2nd and 1st nearest distances, creating valley-like patterns.

var valleys = new Noise.VoronoiValleys(seed: 42);

VoronoiCells

Returns the value of the nearest Voronoi cell. Useful for creating tile-like patterns.

var cells = new Noise.VoronoiCells(seed: 42);
// Or with custom cell value function
var customCells = new Noise.VoronoiCells(seed: 42, 
    cellValueSource: (x, y, z) => (x + y + z) % 10);

Properties (all Voronoi types):

• Frequency (float): Controls cell density (default: 1.0)
• Period (int): Wraps coordinates for tiling

Fractal Noise

Fractal noise combines multiple octaves of base noise for rich, detailed patterns.

Billow

Creates billowy, cloud-like patterns by using absolute values of noise.

var billow = new Noise.Billow(seed: 42);
billow.OctaveCount = 6;
billow.Lacunarity = 2.17f;
billow.Frequency = 1.0f;
billow.Persistence = 0.5f;

Ridge

Creates ridged, mountain-like patterns by inverting and squaring noise values.

var ridge = new Noise.Ridge(seed: 42);
ridge.OctaveCount = 6;
ridge.Exponent = 1.0f;
ridge.Offset = 1.0f;
ridge.Gain = 2.0f;

Pink

Creates pink noise (1/f noise) with equal energy per octave.

var pink = new Noise.Pink(seed: 42);
pink.Persistence = 0.5f;

Properties (all Fractal types):

• OctaveCount (int): Number of octaves to combine (default: 6)
• Lacunarity (float): Frequency multiplier between octaves (default: 2.17)
• Frequency (float): Base frequency (default: 1.0)
• Persistence (float): Amplitude multiplier between octaves (Billow, Pink)

Custom Source: All fractal types can use a custom noise source instead of the default Gradient:

var customSource = new Noise.Value(seed: 100);
var billow = new Noise.Billow(customSource);

Procedural Patterns

Planes

Creates repeating planar patterns along the X-axis.

var planes = new Noise.Planes(step: 1.0f);

Cylinders

Creates cylindrical patterns in the XY plane.

var cylinders = new Noise.Cylinders(radius: 2.0f);

Spheres

Creates spherical patterns in 3D space.

var spheres = new Noise.Spheres(radius: 1.5f);

Operations and Modifiers

Arithmetic Operations

Combine noise generators using standard operators:

var noise1 = new Noise.Gradient(seed: 42);
var noise2 = new Noise.Gradient(seed: 100);

// Addition
var added = noise1 + noise2;
var addedConstant = noise1 + 0.5f;

// Subtraction
var subtracted = noise1 - noise2;
var subtractedConstant = noise1 - 0.3f;

// Multiplication
var multiplied = noise1 * noise2;
var scaled = noise1 * 2.0f;

// Division
var divided = noise1 / noise2;
var dividedConstant = noise1 / 2.0f;

// Negation
var negated = -noise1;

Extension Methods

Use extension methods for more complex operations:

// Blend two noise generators
var blended = noise1.Blend(noise2, weight: 0.7f);

// Clamp values
var minClamped = noise1.Min(min: -0.5f);
var maxClamped = noise1.Max(max: 0.5f);

// Transformations
var translated = noise1.Translate(x: 10f, y: 5f, z: 2f);
var rotated = noise1.Rotate(x: 45f, y: 30f, z: 0f); // Degrees
var scaled = noise1.Scale(x: 2f, y: 1f, z: 2f);

// Curve adjustments
var biased = noise1.Bias(value: 0.3f);  // -1 to 1
var gained = noise1.Gain(value: 0.5f);  // -1 to 1

// Threshold
var binarized = noise1.Binarize(threshold: 0.0f);

// Turbulence
var turbulent = noise1.Turbulence(seed: 200);

// Custom modification
var modified = noise1.Modify(value => value * value); // Square the output

Interpolation Curves

Control how noise values are interpolated between grid points:

// Available curves
Noise.SCurve.Linear   // No smoothing
Noise.SCurve.Cubic    // Default, smooth
Noise.SCurve.Quintic  // Smoother
Noise.SCurve.Cosine   // Very smooth

// Use with Gradient or Value noise
var smoothNoise = new Noise.Gradient(seed: 42, curve: Noise.SCurve.Quintic);

Texture Synthesis

Generate textures from noise using the TextureMaker class:

// Implement ITextureWriter for your texture system
public class MyTextureWriter : Noise.ITextureWriter
{
    public void SetPixel(int x, int y, byte r, byte g, byte b, byte a)
    {
        // Set pixel in your texture
    }
}

var noise = new Noise.Gradient(seed: 42);
var writer = new MyTextureWriter();

// Generate alpha texture
Noise.TextureMaker.AlphaTexture(width: 512, height: 512, noise, writer);

// Generate monochrome texture
Noise.TextureMaker.MonochromeTexture(width: 512, height: 512, noise, writer);

// Generate texture from color ramp
var ramp = /* your ITextureReader */;
Noise.TextureMaker.RampTexture(width: 512, height: 512, noise, ramp, writer);

// Generate bump/normal map
Noise.TextureMaker.BumpMap(width: 512, height: 512, noise, writer);

Examples

Terrain Generation

// Create base terrain noise
var baseNoise = new Noise.Ridge(seed: 42);
baseNoise.OctaveCount = 8;
baseNoise.Frequency = 0.01f;

// Add detail with higher frequency
var detailNoise = new Noise.Billow(seed: 100);
detailNoise.Frequency = 0.05f;
detailNoise.OctaveCount = 4;

// Combine
var terrain = baseNoise + detailNoise * 0.3f;

// Sample at world coordinates
float height = terrain.GetValue(worldX, worldY, worldZ);

Layered Noise

var layer1 = new Noise.Gradient(seed: 42).Scale(1f, 1f, 1f);
var layer2 = new Noise.Gradient(seed: 100).Scale(2f, 2f, 2f) * 0.5f;
var layer3 = new Noise.Gradient(seed: 200).Scale(4f, 4f, 4f) * 0.25f;

var layered = layer1 + layer2 + layer3;

Cellular Patterns

var cells = new Noise.VoronoiCells(seed: 42);
cells.Frequency = 5.0f; // Higher frequency = more cells

// Use for tile-based generation
float cellValue = cells.GetValue(x, y, z);

Animated Noise

var noise = new Noise.Gradient(seed: 42);

// Animate by varying the Z coordinate over time
for (float time = 0; time < 10; time += 0.1f)
{
    float value = noise.GetValue(x, y, time);
    // Use value for animation
}

Thread Safety

All noise generators are thread-safe and stateless. You can safely:

• Use the same generator instance from multiple threads
• Create generators on different threads
• Sample noise concurrently without synchronization

var noise = new Noise.Gradient(seed: 42);

Parallel.For(0, 1000, i =>
{
    float value = noise.GetValue(i, i, i);
    // Process value...
});

Performance Tips

1. Reuse Generators: Create generators once and reuse them
2. Cache Results: If sampling the same coordinates repeatedly, cache the results
3. Use Appropriate Octave Count: More octaves = more detail but slower performance
4. Consider Period: Using Period for coordinate wrapping to create repeating patterns

API Reference

Core Interface

public interface INoise
{
    float GetValue(float x, float y, float z);
}

All noise generators implement INoise and inherit from Noise.Generator, which provides:

• Operator overloads (+, -, *, /, unary -)
• Extension methods to give builder pattern for transformations and modifications
• Implicit conversion from float to Constant generator

License

See LICENSE file for details.

---

Made with ❤️ by Red Owl Games