Skip to main content

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}