libnoise/
lib.rs

1//! A simple, performant, and customizable procedural noise generation library.
2//!
3//! Libnoise provides utilities to generate coherent noise and customize them
4//! by applying a variety of operations which modify and combine generators.
5//! With a focus on customizability, the library allows users to create custom
6//! generators and modifiers.
7//!
8//! Most immediately relevant documentation can be found in [`Source`] and
9//! [`Generator`].
10//!
11//! # Quickstart
12//!
13//! To get started easily, create a source generator using one of the many
14//! sources found in [`Source`], and apply adapters documented in [`Generator`].
15//!
16//! ```
17//! use libnoise::prelude::*;
18//!
19//! // build a simplex noise generator seeded with 42
20//! let generator = Source::simplex(42);
21//!
22//! // sample the generator for input point [0.2, 0.5]
23//! let value = generator.sample([0.2, 0.5]);
24//! ```
25//!
26//! Note how the dimensionality, which is internally represented as a constant
27//! generic argument, is automatically inferred by sampling the generator with
28//! a 2-dimensional input point.
29//!
30//! Naturally, we can create more interesting complex generators:
31//!
32//! ```
33//! use libnoise::prelude::*;
34//!
35//! // build a generator
36//! let generator = Source::simplex(42)                 // start with simplex noise
37//!     .fbm(5, 0.013, 2.0, 0.5)                        // apply fractal brownian motion
38//!     .blend(                                         // apply blending...
39//!         Source::worley(43).scale([0.05, 0.05]),     // ...with scaled worley noise
40//!         Source::worley(44).scale([0.02, 0.02]))     // ...controlled by other worley noise
41//!     .lambda(|f| (f * 2.0).sin() * 0.3 + f * 0.7);   // apply a closure to the noise
42//!
43//! // sample the generator for input point [0.2, 0.5]
44//! let value = generator.sample([0.2, 0.5]);
45//! ```
46//!
47//! We can also use [`NoiseBuffer`] for efficiently filling n-dimensional arrays
48//! with noise. The above generator produces the following image, when sampled for
49//! every pixel position:
50//!
51//! ![image](https://raw.githubusercontent.com/cookiephone/libnoise-rs/master/images/doc_image_000_f7049b4.png)
52//!
53//! It is common to interpret the 3rd or 4th dimension as time, allowing us to
54//! produce space-time noise such as:
55//!
56//! ![image](https://raw.githubusercontent.com/cookiephone/libnoise-rs/master/images/doc_image_001_f7049b4.gif)
57//!
58#![cfg_attr(
59    feature = "image",
60    doc = "[`Visualizer`] allows us to get such a visual representation of a given generator when using the `image` feature."
61)]
62
63mod core;
64pub mod prelude;
65pub use crate::core::adapters::*;
66#[cfg(feature = "dev-tools")]
67pub use crate::core::devtools;
68pub use crate::core::generator::*;
69pub use crate::core::source::Source;
70pub use crate::core::sources::*;
71pub use crate::core::utils::noisebuf::NoiseBuffer;
72pub use crate::core::utils::ptable::Seed;
73#[cfg(feature = "image")]
74pub use crate::core::utils::visualizer::Visualizer;