SIMDNoise

repository·master·Indexed 42 days ago

https://github.com/verpeteren/rust-simd-noise

A high-performance Rust library for generating SIMD-accelerated noise, including Simplex, Fbm, and Voronoi. Version 3.1.7 features runtime detection for SSE2, SSE41, and AVX2 instruction sets. It provides a high-level NoiseBuilder API for generating scaled or unscaled noise blocks and a low-level intrinsics module for specialized use cases.

Tokens: 9.2K
Snippets: 33
Records: 42
Agent score: 51%

What's inside SIMDNoise

How NoiseBuilder works and its configuration options
master
The NoiseBuilder follows a builder pattern to configure noise parameters before generation.
Supported Noise Types:
- Gradient Noise (Simplex/Perlin): 1D, 2D, 3D, 4D
- Fractal Noise: Fractal Brownian Motion (Fbm), Ridge, and Turbulence
- Cellular Noise (Voronoi): 2D, 3D
Configuration Methods:
- .with_freq_3d(x, y, z): Sets the frequency for 3D noise.
- .with_octaves(n): Sets the number of octaves.
- .with_gain(g): Sets the gain.
- .with_seed(s): Provides a seed value to randomize the noise result.
- .with_lacunarity(l): Sets the lacunarity.
- .wrap(): Converts the builder into a noise_setting object that can be passed to low-level intrinsic functions.
https://github.com/verpeteren/rust-simd-noise/blob/master/README.md
Build the simdnoise-example executable
master
To build the example application, use Cargo with the --release flag to ensure optimal performance. The resulting executable can generate five different types of noise variants: cellular, fbm, ridge, turbulence, and gradient.
```
Cargo build --release
./target/release/simdnoise-example --help
```
https://github.com/verpeteren/rust-simd-noise/blob/master/example/README.md
Generate blocks of noise using NoiseBuilder
master
The recommended way to generate noise is using the NoiseBuilder API. By default, the library uses runtime detection to select the fastest available instruction set (SSE2, SSE41, or AVX2) for your CPU.
You can generate noise in two ways:
1. Scaled noise: Use .generate_scaled(min, max) to ensure the output values are mapped to a specific range (e.g., [0.0, 1.0]).
2. Unscaled noise: Use .generate() to get the raw noise values along with the actual min and max values found in the generated block.
```
// Get a block of 2d fbm noise with default settings, 100 x 100, with values scaled to the range [0,1]
let noise = NoiseBuilder::fbm_2d(100, 100).generate_scaled(0.0, 1.0);

// Get a block of 3d ridge noise, custom settings, 32x32x32 unscaled
let (noise, min, max) = NoiseBuilder::ridge_3d(32, 32, 32)
    .with_freq_3d(0.05, 0.04, 0.01)
    .with_octaves(5)
    .with_gain(2.0)
    .with_seed(1337)
    .with_lacunarity(0.5)
    .generate();
```
https://github.com/verpeteren/rust-simd-noise/blob/master/README.md
Configure CellReturnType for cellular noise
master
When generating cellular noise, the CellReturnType enum determines the visual output of each cell. You can choose between returning a solid color or a gradient based on the distance to the cell edge.
```
// Possible variants for CellReturnType:
// CellValue: Returns solid colors in each cell.
// Distance: Returns a gradient as you approach the edge of the cell.
```
https://github.com/verpeteren/rust-simd-noise/blob/master/src/noise/cell_return_type.rs
Configure the distance function for cellular noise
master
When generating cellular noise, you can specify how the distance between cell centers is calculated using the CellDistanceFunction enum. This determines the shape and characteristics of the resulting cells.
Available variants:
- Euclidean: Calculates the actual straight-line distance.
- Manhattan: Calculates the sum of the X and Y distances (often resulting in diamond-like patterns).
- Natural: A combination of Manhattan and Euclidean distances.
```
// Example usage of CellDistanceFunction variants
let distance_func = CellDistanceFunction::Euclidean;
```
https://github.com/verpeteren/rust-simd-noise/blob/master/src/noise/cell_distance_function.rs
Generate noise blocks using NoiseBuilder
master
The NoiseBuilder provides a high-level, fluent API to generate blocks of noise with automatic runtime SIMD detection (picking the best available instruction set like SSE2, SSE41, or AVX2). You can specify dimensions, noise types (FBM, Ridge, Cellular, etc.), and parameters like frequency, octaves, gain, and seed.
Use .generate_scaled(min, max) to get a Vec<f32> with values mapped to a specific range, or .generate() to get the raw noise values along with the calculated min and max values found in the block.
```
use simdnoise::*;

// Get a block of 2d fbm noise with default settings, 100 x 100, with values scaled to the range [0,1]
let noise = NoiseBuilder::fbm_2d(100, 100).generate_scaled(0.0, 1.0);

// Get a block of 4d ridge noise, custom settings, 32x32x32x32 unscaled
let (noise, min, max) = NoiseBuilder::ridge_4d(32, 32, 32, 32)
    .with_freq(0.05)
    .with_octaves(5)
    .with_gain(2.0)
    .with_seed(1337)
    .with_lacunarity(0.5)
    .generate();
```
https://github.com/verpeteren/rust-simd-noise/blob/master/src/lib.rs

Call noise functions directly via intrinsics

master

For specialized use cases where you need to bypass the standard block generation (e.g., calculating points on a sphere) or want to force a specific instruction set (like SSE41 even if AVX2 is available), you can use the simdnoise::intrinsics module.

Note: These functions are unsafe and require you to manage SIMD types (like __m128 or __m256) and manual memory/register handling.

let noise_setting = NoiseBuilder::ridge_3d(32, 32, 32)
    .with_freq_3d(0.05, 0.04, 0.01)
    .with_octaves(5)
    .with_gain(2.0)
    .with_lacunarity(0.5)
    .wrap();

// get a block of noise with the sse41 version, using the above settings
let (noise, min, max) = unsafe { simdnoise::intrinsics::sse41::get_2d_noise(&noise_setting) };

// send your own SIMD x,y values to the noise functions directly
unsafe {
    // sse2 simplex noise
    let x = _mm_set1_ps(5.0);
    let y = _mm_set1_ps(10.0);
    let f: __m128 = simdnoise::intrinsics::sse2::simplex_2d(x, y);

    // avx2 turbulence
    let x = _mm256_set1_ps(5.0);
    let y = _mm256_set1_ps(10.0);
    let freq = _mm256_set1_ps(1.0);
    let lacunarity = _mm256_set1_ps(0.5);
    let gain = _mm256_set1_ps(2.0);
    let octaves = 3;
    let seed = 1337;
    let f_turbulence: __m256 = simdnoise::intrinsics::avx2::turbulence_2d(x, y, lacunarity, gain, octaves, seed);
}

Reference: Global options for simdnoise-example

master

These options are available across most commands in the simdnoise-example CLI.

Options:
  -w, --width <WIDTH>          The width of the generated image [default: 1920]
      --height <HEIGHT>        The height of the generated image [default: 1080]
      --depth <DEPTH>          The z dimension of the generated image [default: 1]
      --time <TIME>            The w dimension of the generated image [default: 5]
      --dimension <DIMENSION>  The number of dimensions of the generated noise [default: three] [possible values: one, two, three, four]
      --seed <SEED>            The initial seed value [default: 8]
      --offset-x <OFFSET_X>    Use an offset for the first dimension
      --offset-y <OFFSET_Y>    Use an offset for the second dimension
      --offset-z <OFFSET_Z>    Use an offset for the third dimension
      --offset-w <OFFSET_W>    Use an offset for the fourth dimension
  -h, --help                   Print help
  -V, --version                Print version

Reference: FBM noise options

master

Specific options for the fbm command.

Options:
  -f, --frequency <FREQUENCY>    [default: 1.2]
  -w, --width <WIDTH>            The width of the generated image [default: 1920]
      --height <HEIGHT>          The height of the generated image [default: 1080]
  -l, --lacunarity <LACUNARITY>  [default: 0.5]
      --depth <DEPTH>          The z dimension of the generated image [default: 1]
  -g, --gain <GAIN>              [default: 2]
  -o, --octaves <OCTAVES>        [default: 3]
      --time <TIME>              The w dimension of the generated image [default: 5]
      --dimension <DIMENSION>    The number of dimensions of the generated noise [default: three] [possible values: one, two, three, four]
      --seed <SEED>              The initial seed value [default: 8]
      --offset-x <OFFSET_X>      Use an offset for the first dimension
      --offset-y <OFFSET_Y>      Use an offset for the second dimension
      --offset-z <OFFSET_Z>      Use an offset for the third dimension
      --offset-w <OFFSET_W>      Use an offset for the fourth dimension
  -h, --help                     Print help

Reference: Ridge noise options

master

Specific options for the ridge command.

Options:
  -f, --frequency <FREQUENCY>    [default: 1.2]
  -w, --width <WIDTH>            The width of the generated image [default: 1920]
      --height <HEIGHT>          The height of the generated image [default: 1080]
  -l, --lacunarity <LACUNARITY>  [default: 0.5]
      --depth <DEPTH>          The z dimension of the generated image [default: 1]
  -g, --gain <GAIN>              [default: 2]
  -o, --octaves <OCTAVES>        [default: 3]
      --dimension <DIMENSION>    The number of dimensions of the generated noise [default: three] [possible values: one, two, three, four]
      --seed <SEED>              The initial seed value [default: 8]
      --offset-x <OFFSET_X>      Use an offset for the first dimension
      --offset-y <OFFSET_Y>      Use an offset for the second dimension
      --offset-z <OFFSET_Z>      Use an offset for the third dimension
      --offset-w <OFFSET_W>      Use an offset for the fourth dimension
  -h, --help                     Print help

Reference: Cellular noise options

master

Specific options for the cellular command.

Options:
      --distance <DISTANCE>    The distance function [default: euclidean] [possible values: euclidean, manhattan, natural]
  -w, --width <WIDTH>          The width of the generated image [default: 1920]
  -f, --frequency <FREQUENCY>  [default: 1.2]
      --height <HEIGHT>          The height of the generated image [default: 1080]
      --depth <DEPTH>          The z dimension of the generated image [default: 1]
      --time <TIME>              The w dimension of the generated image [default: 5]
      --dimension <DIMENSION>  The number of dimensions of the generated noise [default: three] [possible values: one, two, three, four]
      --seed <SEED>            The initial seed value [default: 8]
      --offset-x <OFFSET_X>    Use an offset for the first dimension
      --offset-y <OFFSET_Y>    Use an offset for the second dimension
      --offset-z <OFFSET_Z>    Use an offset for the third dimension
      --offset-w <OFFSET_W>    Use an offset for the fourth dimension
  -h, --help                   Print help

Reference: Turbulence noise options

master

Specific options for the turbulence command.

Options:
  -f, --frequency <FREQUENCY>    [default: 1.2]
  -w, --width <WIDTH>            The width of the generated image [default: 1920]
      --height <HEIGHT>          The height of the generated image [default: 1080]
  -l, --lacunarity <LACUNARITY>  [default: 0.5]
      --depth <DEPTH>          The z dimension of the generated image [default: 1]
  -g, --gain <GAIN>              [default: 2]
  -o, --octaves <OCTAVES>        [default: 3]
      --time <TIME>              The w dimension of the generated image [default: 5]
      --dimension <DIMENSION>    The number of dimensions of the generated noise [default: three] [possible values: one, two, three, four]
      --seed <SEED>              The initial seed value [default: 8]
      --offset-x <OFFSET_X>      Use an offset for the first dimension
      --offset-y <OFFSET_Y>      Use an offset for the second dimension
      --offset-z <OFFSET_Z>      Use an offset for the third dimension
      --offset-w <OFFSET_W>      Use an offset for the fourth dimension
  -h, --help                     Print help