Skip to main content

quick_noise/api/grid/
interface.rs

1use std::marker::PhantomData;
2
3use crate::Combiner;
4use crate::api::configs::GridConfig;
5use crate::api::grid::builder::GridNoiseBuilder;
6use crate::api::grid::octaves_builder::OctaveGridNoiseBuilder;
7use crate::api::octave::Octave;
8use crate::math::random::Random;
9use crate::simd::{Arch, StaticArch};
10
11/// Handles raw parameters for grid noise generators
12#[derive(Copy, Clone, PartialEq, Debug)]
13#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
14pub struct GridNoiseParams<const D: usize> {
15    pub seed: u32,
16    #[cfg_attr(feature = "serde", serde(with = "serde_arrays"))]
17    pub grid_size: [usize; D],
18    #[cfg_attr(feature = "serde", serde(with = "serde_arrays"))]
19    pub position: [f64; D],
20    #[cfg_attr(feature = "serde", serde(with = "serde_arrays"))]
21    pub frequency: [f32; D],
22    pub weight: f32,
23    pub magnification: f32,
24    #[cfg_attr(feature = "serde", serde(with = "serde_arrays"))]
25    pub tiling: [Option<u32>; D],
26}
27
28pub trait GridGenerator<const D: usize>: Default + Copy + Clone + PartialEq {
29    /// Generates noise for a grid region.
30    ///
31    /// # Type Parameters
32    /// - `C`: Type of combiner used to layer noise
33    /// - `INIT`: Whether or not the generator should initialize dst
34    /// - `FINAL`: Whether or not the generator should finalize the final octave
35    ///
36    /// # Runtime Parameters
37    /// - `params`: Config specifying general noise parameters
38    /// - `combiner_config`: Config specifying combiner parameters
39    /// - `state`: Buffer containing sample information across octaves
40    /// - `dst`: Buffer to insert the results into
41    fn sample_grid<A: Arch, C: Combiner, const INIT: bool, const FINAL: bool>(
42        params: GridNoiseParams<D>,
43        combiner_config: C::Config,
44        state: &mut [f32],
45        dst: &mut [f32],
46    );
47}
48
49/// Static struct for sampling grid noise.
50pub struct GridNoise<const D: usize, C: Combiner, G: GridGenerator<D>> {
51    _fractal: PhantomData<C>,
52    _sampler: PhantomData<G>,
53}
54
55/// An interface struct for creating grid noise.
56///
57/// # Type Parameters
58/// * `D: NoiseDimension` - Determines how many dimensions the grid has.
59///
60/// # Example
61/// ```
62/// use quick_noise::Grid;
63///
64/// // Subject to change.
65/// let grid = Grid::<2>::new(32, 32)
66///     .grid_position(0.0, 0.0)
67///     .seed(1);
68/// ```
69
70#[derive(Default, Clone, Copy, Debug, PartialEq)]
71pub struct Grid<const D: usize, A: Arch = StaticArch> {
72    pub(crate) config: GridConfig<D>,
73    pub(crate) _arch: PhantomData<A>,
74}
75
76impl<const D: usize, A: Arch> Grid<D, A> {
77    /// Determines the psuedo-random values used in noise generation called
78    /// on this grid. Different seeds produce different noise.
79    pub fn seed(mut self, seed: i64) -> Self {
80        self.config.grid_seed = Random::mix_u64(seed as u64);
81        self
82    }
83}
84
85impl<A: Arch> Grid<2, A> {
86    /// Creates an anchor for a grid region that can be used for call noise.
87    ///
88    /// # Parameters
89    /// -`x`: Length of the grid region along the x-axis
90    /// -`y`: Length of the grid region along the y-axis
91    pub fn new(x: usize, y: usize) -> Self {
92        let config = GridConfig {
93            grid_size: [x, y],
94            ..Default::default()
95        };
96        Self {
97            config,
98            _arch: PhantomData::<A>,
99        }
100    }
101
102    /// Determines the position values provided to noise calls. This value represents
103    /// the position of this grid region in grid units determined by its grid_size.
104    /// A 32x32 grid at position `{ 1, 2 }` covers samples in the range `{ 32..64, 64..96 }`.
105    ///
106    /// # Default:
107    /// `0.0`: x
108    /// `0.0`: y
109    pub fn grid_position(mut self, x: f64, y: f64) -> Self {
110        self.config.position = [
111            x * self.config.grid_size[0] as f64,
112            y * self.config.grid_size[1] as f64,
113        ];
114        self
115    }
116
117    /// Determines the position values provided to noise calls. This value represents
118    /// the position of first sample in each dimension. A 32x32 given the sample position
119    /// `{ 32, 16 }` covers samples in the range `{ 32..64, 16..48 }`.
120    ///
121    /// # Default:
122    /// `0.0`: x
123    /// `0.0`: y
124    pub fn sample_position(mut self, x: f64, y: f64) -> Self {
125        self.config.position = [x, y];
126        self
127    }
128
129    /// Determines the distance the sample space has until it starts repeating noise
130    /// seamlessly. When values are left as None, noise does not repeat.
131    ///
132    /// # Default:
133    /// - `x`: None
134    /// - `y`: None
135    pub fn tiling(mut self, x: Option<u32>, y: Option<u32>) -> Self {
136        self.config.tiling = [x, y];
137        self
138    }
139}
140
141impl<A: Arch> Grid<3, A> {
142    /// Creates an anchor for a grid region that can be used for call noise.
143    ///
144    /// # Parameters
145    /// -`x`: Length of the grid region along the x-axis
146    /// -`y`: Length of the grid region along the y-axis
147    /// -`z`: Length of the grid region along the z-axis
148    pub fn new(x: usize, y: usize, z: usize) -> Self {
149        let config = GridConfig {
150            grid_size: [x, y, z],
151            ..Default::default()
152        };
153        Self {
154            config,
155            _arch: PhantomData::<A>,
156        }
157    }
158
159    /// Determines the position values provided to noise calls. This value represents
160    /// the position of this grid region in grid units determined by its grid_size.
161    /// A 32x32x32 grid at position `{ 1, 2, 3 }` covers samples in the range
162    /// `{ 32..64, 64..96, 96..128 }`.
163    ///
164    /// # Default:
165    /// `0.0`: x
166    /// `0.0`: y
167    /// `0.0`: z
168    pub fn grid_position(mut self, x: f64, y: f64, z: f64) -> Self {
169        self.config.position = [
170            x * self.config.grid_size[0] as f64,
171            y * self.config.grid_size[1] as f64,
172            z * self.config.grid_size[2] as f64,
173        ];
174        self
175    }
176
177    /// Determines the position values provided to noise calls. This value represents
178    /// the position of first sample in each dimension. A 32x32x32 given the sample position
179    /// `{ 32, 16, 0 }` covers samples in the range `{ 32..64, 16..48, 0..32 }`.
180    ///
181    /// # Default:
182    /// `0.0`: x
183    /// `0.0`: y
184    /// `0.0`: z
185    pub fn sample_position(mut self, x: f64, y: f64, z: f64) -> Self {
186        self.config.position = [x, y, z];
187        self
188    }
189
190    /// Determines the distance the sample space has until it starts repeating noise
191    /// seamlessly. When values are left as None, noise does not repeat.
192    ///
193    /// # Default:
194    /// - `x`: None
195    /// - `y`: None
196    /// - `z`: None
197    pub fn tiling(mut self, x: Option<u32>, y: Option<u32>, z: Option<u32>) -> Self {
198        self.config.tiling = [x, y, z];
199        self
200    }
201}
202
203impl<const D: usize, A: Arch> Grid<D, A> {
204    /// Loads a config a config to create a grid.
205    pub fn from_config(config: GridConfig<D>) -> Self {
206        Self {
207            config,
208            _arch: PhantomData::<A>,
209        }
210    }
211
212    /// Creates a new builder to easily configure a grid region of noise.
213    ///
214    /// # Type Parameters
215    /// - `C`: The algorithm to combine separate noise passes (octaves) together.
216    /// - `G`: The algorithm to sample noise with.
217    pub fn builder<C: Combiner, G: GridGenerator<D>>(&self) -> GridNoiseBuilder<D, C, G, A> {
218        GridNoiseBuilder::from_config(self.config)
219    }
220
221    /// Creates a new builder using a custom octave list to configure
222    /// a grid region of noise.
223    ///
224    /// # Type Parameters
225    /// - `C`: The algorithm to combine separate noise passes (octaves) together.
226    /// - `G`: The algorithm to sample noise with.
227    pub fn builder_with_octaves<'a, C: Combiner, G: GridGenerator<D>>(
228        &self,
229        octave_list: &'a [Octave<D>],
230    ) -> OctaveGridNoiseBuilder<'a, D, C, G, A> {
231        OctaveGridNoiseBuilder::new(self.config, octave_list)
232    }
233}