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}