quick_noise/noise/combiners.rs
1use std::ops::{Index, IndexMut};
2
3use simply_simd::{Arch, Simd};
4
5pub mod billow;
6pub mod fbm;
7pub mod hybrid_multi;
8pub mod multi;
9pub mod ping_pong;
10pub mod ridged;
11pub mod terrace;
12
13pub use billow::Billow;
14pub use fbm::Fbm;
15pub use hybrid_multi::{HybridMulti, HybridMultiConfig};
16pub use multi::Multi;
17pub use ping_pong::{PingPong, PingPongConfig};
18pub use ridged::{Ridged, RidgedConfig};
19pub use terrace::{Terrace, TerraceConfig};
20
21pub trait CombinerState<A: Arch>:
22 Copy + Index<usize, Output = Simd<f32, A>> + IndexMut<usize> + Default
23{
24 const STATE_SIZE: usize;
25}
26
27impl<A: Arch, const N: usize> CombinerState<A> for [Simd<f32, A>; N]
28where
29 [Simd<f32, A>; N]: Default,
30{
31 const STATE_SIZE: usize = N;
32}
33
34pub type CombinerArray<A, const N: usize> = [Simd<f32, A>; N];
35
36pub trait Combiner: Default + Copy + Clone {
37 /// Determines whether or not octave weight parameters are ignored.
38 /// If this is set to false, every octave has a weight of `1.0`.
39 /// If this is set to true, every subsequent octave's weight is multiplied by persistence.
40 const WEIGHT_DECAY: bool;
41
42 /// The type used for expressing State. The type `[ArchSimd<f32>; N]` can be used,
43 /// where N is the number of variables tracked across samples. N does not include
44 /// the running result. The type alias `FractalArray<N>` can also be used.
45 ///
46 /// Each additional variable tracked across samples has a signifcant performance
47 /// penalty when computing grid noise. The impact is minimal for batch noise.
48 type State<A: Arch>: CombinerState<A>;
49
50 /// The config struct that is passed through noise calls to the Fractal's usage.
51 /// This is used for storing new parameters specific to a custom Fractal type.
52 type Config: Copy + Default;
53
54 /// Determines how new noise samples are combined with previous samples.
55 ///
56 /// # Parameters
57 /// - `config`: Parameters for the combiner
58 /// - `state`: An array of values maintained for each sample
59 /// - `current`: Existing noise value from previous samples
60 /// - `output`: New sample output from the current noise pass
61 fn apply_sample<A: Arch>(
62 _config: &Self::Config,
63 state: Self::State<A>,
64 cur_result: Simd<f32, A>,
65 new_sample: Simd<f32, A>,
66 ) -> (Self::State<A>, Simd<f32, A>) {
67 (state, cur_result + new_sample)
68 }
69
70 /// Determines how the first sample is initialized.
71 ///
72 /// For maximum performance and compiler optimization, it is
73 /// recommended to avoid unnecessary instructions such as
74 /// adding to 0.0 and multiplying by 1.0.
75 ///
76 /// # Parameters
77 /// - `config`: Parameters for the combiner
78 /// - `new_sample`: New sample output from the first noise pass
79 #[inline(always)]
80 fn initialize_sample<A: Arch>(
81 config: &Self::Config,
82 new_sample: Simd<f32, A>,
83 ) -> (Self::State<A>, Simd<f32, A>) {
84 Self::apply_sample(config, Default::default(), Default::default(), new_sample)
85 }
86
87 /// Determines how the final noise sample is processed after
88 /// being fully combined. This is after `sample` or `sample_first`
89 /// has been called.
90 ///
91 /// # Parameters
92 /// - `config`: Parameters for the combiner
93 /// - `state`: An array of values maintained for each sample
94 /// - `last`: The final noise sample after prior fractal processing
95 #[inline(always)]
96 fn finalize_sample<A: Arch>(
97 _config: &Self::Config,
98 _state: Self::State<A>,
99 last: Simd<f32, A>,
100 ) -> Simd<f32, A> {
101 last
102 }
103}