rustfft/
lib.rs

1//! RustFFT is a high-performance FFT library written in pure Rust.
2//!
3//! On X86_64, RustFFT supports the AVX instruction set for increased performance. No special code is needed to activate AVX:
4//! Simply plan a FFT using the FftPlanner on a machine that supports the `avx` and `fma` CPU features, and RustFFT
5//! will automatically switch to faster AVX-accelerated algorithms.
6//!
7//! For machines that do not have AVX, RustFFT also supports the SSE4.1 instruction set.
8//! As for AVX, this is enabled automatically when using the FftPlanner.
9//!
10//! Additionally, there is automatic support for the Neon instruction set on AArch64,
11//! and support for WASM SIMD when compiling for WASM targets.
12//!
13//! ### Usage
14//!
15//! The recommended way to use RustFFT is to create a [`FftPlanner`](crate::FftPlanner) instance and then call its
16//! [`plan_fft`](crate::FftPlanner::plan_fft) method. This method will automatically choose which FFT algorithms are best
17//! for a given size and initialize the required buffers and precomputed data.
18//!
19//! ```
20//! // Perform a forward FFT of size 1234
21//! use rustfft::{FftPlanner, num_complex::Complex};
22//!
23//! let mut planner = FftPlanner::new();
24//! let fft = planner.plan_fft_forward(1234);
25//!
26//! let mut buffer = vec![Complex{ re: 0.0f32, im: 0.0f32 }; 1234];
27//! fft.process(&mut buffer);
28//! ```
29//! The planner returns trait objects of the [`Fft`](crate::Fft) trait, allowing for FFT sizes that aren't known
30//! until runtime.
31//!
32//! RustFFT also exposes individual FFT algorithms. For example, if you know beforehand that you need a power-of-two FFT, you can
33//! avoid the overhead of the planner and trait object by directly creating instances of the [`Radix4`](crate::algorithm::Radix4) algorithm:
34//!
35//! ```
36//! // Computes a forward FFT of size 4096
37//! use rustfft::{Fft, FftDirection, num_complex::Complex, algorithm::Radix4};
38//!
39//! let fft = Radix4::new(4096, FftDirection::Forward);
40//!
41//! let mut buffer = vec![Complex{ re: 0.0f32, im: 0.0f32 }; 4096];
42//! fft.process(&mut buffer);
43//! ```
44//!
45//! For the vast majority of situations, simply using the [`FftPlanner`](crate::FftPlanner) will be enough, but
46//! advanced users may have better insight than the planner into which algorithms are best for a specific size. See the
47//! [`algorithm`](crate::algorithm) module for a complete list of scalar algorithms implemented by RustFFT.
48//!
49//! Users should beware, however, that bypassing the planner will disable all AVX, SSE, Neon, and WASM SIMD optimizations.
50//!
51//! ### Feature Flags
52//!
53//! * `avx` (Enabled by default)
54//!
55//!     On x86_64, the `avx` feature enables compilation of AVX-accelerated code. Enabling it greatly improves performance if the
56//!     client CPU supports AVX and FMA, while disabling it reduces compile time and binary size.
57//!
58//!     On every platform besides x86_64, this feature does nothing, and RustFFT will behave like it's not set.
59//! * `sse` (Enabled by default)
60//!
61//!     On x86_64, the `sse` feature enables compilation of SSE4.1-accelerated code. Enabling it improves performance
62//!     if the client CPU supports SSE4.1, while disabling it reduces compile time and binary size. If AVX is also
63//!     supported and its feature flag is enabled, RustFFT will use AVX instead of SSE4.1.
64//!
65//!     On every platform besides x86_64, this feature does nothing, and RustFFT will behave like it's not set.
66//! * `neon` (Enabled by default)
67//!
68//!     On AArch64 (64-bit ARM) the `neon` feature enables compilation of Neon-accelerated code. Enabling it improves
69//!     performance, while disabling it reduces compile time and binary size.
70//!
71//!     On every platform besides AArch64, this feature does nothing, and RustFFT will behave like it's not set.
72//! * `wasm_simd` (Disabled by default)
73//!
74//!     On the WASM platform, this feature enables compilation of WASM SIMD accelerated code.
75//!
76//!     To execute binaries compiled with `wasm_simd`, you need a [target browser or runtime which supports `fixed-width SIMD`](https://webassembly.org/roadmap/).
77//!     If you run your SIMD accelerated code on an unsupported platform, WebAssembly will specify a [trap](https://webassembly.github.io/spec/core/intro/overview.html#trap) leading to immediate execution cancelation.
78//!
79//!     On every platform besides WASM, this feature does nothing and RustFFT will behave like it is not set.
80//!
81//! ### Normalization
82//!
83//! RustFFT does not normalize outputs. Callers must manually normalize the results by scaling each element by
84//! `1/len().sqrt()`. Multiple normalization steps can be merged into one via pairwise multiplication, so when
85//! doing a forward FFT followed by an inverse callers can normalize once by scaling each element by `1/len()`
86//!
87//! ### Output Order
88//!
89//! Elements in the output are ordered by ascending frequency, with the first element corresponding to frequency 0.
90//!
91//! ### AVX Performance Tips
92//!
93//! In any FFT computation, the time required to compute a FFT of size N relies heavily on the [prime factorization](https://en.wikipedia.org/wiki/Integer_factorization) of N.
94//! If N's prime factors are all very small, computing a FFT of size N will be fast, and it'll be slow if N has large prime
95//! factors, or if N is a prime number.
96//!
97//! In most FFT libraries (Including RustFFT when using non-AVX code), power-of-two FFT sizes are the fastest, and users see a steep
98//! falloff in performance when using non-power-of-two sizes. Thankfully, RustFFT using AVX acceleration is not quite as restrictive:
99//!
100//! - Any FFT whose size is of the form `2^n * 3^m` can be considered the "fastest" in RustFFT.
101//! - Any FFT whose prime factors are all 11 or smaller will also be very fast, but the fewer the factors of 2 and 3 the slower it will be.
102//!     For example, computing a FFT of size 13552 `(2^4*7*11*11)` is takes 12% longer to compute than 13824 `(2^9 * 3^3)`,
103//!     and computing a FFT of size 2541 `(3*7*11*11)` takes 65% longer to compute than 2592 `(2^5 * 3^4)`
104//! - Any other FFT size will be noticeably slower. A considerable amount of effort has been put into making these FFT sizes as fast as
105//!     they can be, but some FFT sizes just take more work than others. For example, computing a FFT of size 5183 `(71 * 73)` takes about
106//!     5x longer than computing a FFT of size 5184 `(2^6 * 3^4)`.
107//!
108//! In most cases, even prime-sized FFTs will be fast enough for your application. In the example of 5183 above, even that "slow" FFT
109//! only takes a few tens of microseconds to compute.
110//!
111//! Some applications of the FFT allow for choosing an arbitrary FFT size (In many applications the size is pre-determined by whatever you're computing).
112//! If your application supports choosing your own size, our advice is still to start by trying the size that's most convenient to your application.
113//! If that's too slow, see if you can find a nearby size whose prime factors are all 11 or smaller, and you can expect a 2x-5x speedup.
114//! If that's still too slow, find a nearby size whose prime factors are all 2 or 3, and you can expect a 1.1x-1.5x speedup.
115
116use std::fmt::Display;
117
118pub use num_complex;
119pub use num_traits;
120
121#[macro_use]
122mod common;
123
124/// Individual FFT algorithms
125pub mod algorithm;
126mod array_utils;
127mod fft_cache;
128mod math_utils;
129mod plan;
130mod twiddles;
131
132use num_complex::Complex;
133use num_traits::Zero;
134
135pub use crate::common::FftNum;
136pub use crate::plan::{FftPlanner, FftPlannerScalar};
137
138/// A trait that allows FFT algorithms to report their expected input/output size
139pub trait Length {
140    /// The FFT size that this algorithm can process
141    fn len(&self) -> usize;
142}
143
144/// Represents a FFT direction, IE a forward FFT or an inverse FFT
145#[derive(Copy, Clone, PartialEq, Eq, Debug)]
146pub enum FftDirection {
147    Forward,
148    Inverse,
149}
150impl FftDirection {
151    /// Returns the opposite direction of `self`.
152    ///
153    ///  - If `self` is `FftDirection::Forward`, returns `FftDirection::Inverse`
154    ///  - If `self` is `FftDirection::Inverse`, returns `FftDirection::Forward`
155    #[inline]
156    pub fn opposite_direction(&self) -> FftDirection {
157        match self {
158            Self::Forward => Self::Inverse,
159            Self::Inverse => Self::Forward,
160        }
161    }
162}
163impl Display for FftDirection {
164    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> Result<(), ::std::fmt::Error> {
165        match self {
166            Self::Forward => f.write_str("Forward"),
167            Self::Inverse => f.write_str("Inverse"),
168        }
169    }
170}
171
172/// A trait that allows FFT algorithms to report whether they compute forward FFTs or inverse FFTs
173pub trait Direction {
174    /// Returns FftDirection::Forward if this instance computes forward FFTs, or FftDirection::Inverse for inverse FFTs
175    fn fft_direction(&self) -> FftDirection;
176}
177
178/// Trait for algorithms that compute FFTs.
179///
180/// This trait has a few methods for computing FFTs. Its most conveinent method is [`process(slice)`](crate::Fft::process).
181/// It takes in a slice of `Complex<T>` and computes a FFT on that slice, in-place. It may copy the data over to internal scratch buffers
182/// if that speeds up the computation, but the output will always end up in the same slice as the input.
183pub trait Fft<T: FftNum>: Length + Direction + Sync + Send {
184    /// Computes a FFT in-place.
185    ///
186    /// Convenience method that allocates a `Vec` with the required scratch space and calls `self.process_with_scratch`.
187    /// If you want to re-use that allocation across multiple FFT computations, consider calling `process_with_scratch` instead.
188    ///
189    /// # Panics
190    ///
191    /// This method panics if:
192    /// - `buffer.len() % self.len() > 0`
193    /// - `buffer.len() < self.len()`
194    fn process(&self, buffer: &mut [Complex<T>]) {
195        let mut scratch = vec![Complex::zero(); self.get_inplace_scratch_len()];
196        self.process_with_scratch(buffer, &mut scratch);
197    }
198
199    /// Divides `buffer` into chunks of size `self.len()`, and computes a FFT on each chunk.
200    ///
201    /// Uses the `scratch` buffer as scratch space, so the contents of `scratch` should be considered garbage
202    /// after calling.
203    ///
204    /// # Panics
205    ///
206    /// This method panics if:
207    /// - `buffer.len() % self.len() > 0`
208    /// - `buffer.len() < self.len()`
209    /// - `scratch.len() < self.get_inplace_scratch_len()`
210    fn process_with_scratch(&self, buffer: &mut [Complex<T>], scratch: &mut [Complex<T>]);
211
212    /// Divides `input` and `output` into chunks of size `self.len()`, and computes a FFT on each chunk.
213    ///
214    /// This method uses both the `input` buffer and `scratch` buffer as scratch space, so the contents of both should be
215    /// considered garbage after calling.
216    ///
217    /// This is a more niche way of computing a FFT. It's useful to avoid a `copy_from_slice()` if you need the output
218    /// in a different buffer than the input for some reason. This happens frequently in RustFFT internals, but is probably
219    /// less common among RustFFT users.
220    ///
221    /// For many FFT sizes, `self.get_outofplace_scratch_len()` returns 0
222    ///
223    /// # Panics
224    ///
225    /// This method panics if:
226    /// - `output.len() != input.len()`
227    /// - `input.len() % self.len() > 0`
228    /// - `input.len() < self.len()`
229    /// - `scratch.len() < self.get_outofplace_scratch_len()`
230    fn process_outofplace_with_scratch(
231        &self,
232        input: &mut [Complex<T>],
233        output: &mut [Complex<T>],
234        scratch: &mut [Complex<T>],
235    );
236
237    /// Returns the size of the scratch buffer required by `process_with_scratch`
238    ///
239    /// For most FFT sizes, this method will return `self.len()`. For a few small sizes it will return 0, and for some special FFT sizes
240    /// (Sizes that require the use of Bluestein's Algorithm), this may return a scratch size larger than `self.len()`.
241    /// The returned value may change from one version of RustFFT to the next.
242    fn get_inplace_scratch_len(&self) -> usize;
243
244    /// Returns the size of the scratch buffer required by `process_outofplace_with_scratch`
245    ///
246    /// For most FFT sizes, this method will return 0. For some special FFT sizes
247    /// (Sizes that require the use of Bluestein's Algorithm), this may return a scratch size larger than `self.len()`.
248    /// The returned value may change from one version of RustFFT to the next.
249    fn get_outofplace_scratch_len(&self) -> usize;
250}
251
252// Algorithms implemented to use AVX instructions. Only compiled on x86_64, and only compiled if the "avx" feature flag is set.
253#[cfg(all(target_arch = "x86_64", feature = "avx"))]
254mod avx;
255
256// If we're not on x86_64, or if the "avx" feature was disabled, keep a stub implementation around that has the same API, but does nothing
257// That way, users can write code using the AVX planner and compile it on any platform
258#[cfg(not(all(target_arch = "x86_64", feature = "avx")))]
259mod avx {
260    pub mod avx_planner {
261        use crate::{Fft, FftDirection, FftNum};
262        use std::sync::Arc;
263
264        /// The AVX FFT planner creates new FFT algorithm instances which take advantage of the AVX instruction set.
265        ///
266        /// Creating an instance of `FftPlannerAvx` requires the `avx` and `fma` instructions to be available on the current machine, and it requires RustFFT's
267        ///  `avx` feature flag to be set. A few algorithms will use `avx2` if it's available, but it isn't required.
268        ///
269        /// For the time being, AVX acceleration is black box, and AVX accelerated algorithms are not available without a planner. This may change in the future.
270        ///
271        /// ~~~
272        /// // Perform a forward Fft of size 1234, accelerated by AVX
273        /// use std::sync::Arc;
274        /// use rustfft::{FftPlannerAvx, num_complex::Complex};
275        ///
276        /// // If FftPlannerAvx::new() returns Ok(), we'll know AVX algorithms are available
277        /// // on this machine, and that RustFFT was compiled with the `avx` feature flag
278        /// if let Ok(mut planner) = FftPlannerAvx::new() {
279        ///     let fft = planner.plan_fft_forward(1234);
280        ///
281        ///     let mut buffer = vec![Complex{ re: 0.0f32, im: 0.0f32 }; 1234];
282        ///     fft.process(&mut buffer);
283        ///
284        ///     // The FFT instance returned by the planner has the type `Arc<dyn Fft<T>>`,
285        ///     // where T is the numeric type, ie f32 or f64, so it's cheap to clone
286        ///     let fft_clone = Arc::clone(&fft);
287        /// }
288        /// ~~~
289        ///
290        /// If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This
291        /// is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing
292        /// setup time. (FFT instances created with one planner will never re-use data and buffers with FFT instances created
293        /// by a different planner)
294        ///
295        /// Each FFT instance owns [`Arc`s](std::sync::Arc) to its internal data, rather than borrowing it from the planner, so it's perfectly
296        /// safe to drop the planner after creating Fft instances.
297        pub struct FftPlannerAvx<T: FftNum> {
298            _phantom: std::marker::PhantomData<T>,
299        }
300        impl<T: FftNum> FftPlannerAvx<T> {
301            /// Constructs a new `FftPlannerAvx` instance.
302            ///
303            /// Returns `Ok(planner_instance)` if this machine has the required instruction sets and the `avx` feature flag is set.
304            /// Returns `Err(())` if some instruction sets are missing, or if the `avx` feature flag is not set.
305            pub fn new() -> Result<Self, ()> {
306                Err(())
307            }
308            /// Returns a `Fft` instance which uses AVX instructions to compute FFTs of size `len`.
309            ///
310            /// If the provided `direction` is `FftDirection::Forward`, the returned instance will compute forward FFTs. If it's `FftDirection::Inverse`, it will compute inverse FFTs.
311            ///
312            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
313            pub fn plan_fft(&mut self, _len: usize, _direction: FftDirection) -> Arc<dyn Fft<T>> {
314                unreachable!()
315            }
316            /// Returns a `Fft` instance which uses AVX instructions to compute forward FFTs of size `len`.
317            ///
318            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
319            pub fn plan_fft_forward(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
320                unreachable!()
321            }
322            /// Returns a `Fft` instance which uses AVX instructions to compute inverse FFTs of size `len.
323            ///
324            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
325            pub fn plan_fft_inverse(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
326                unreachable!()
327            }
328        }
329    }
330}
331
332pub use self::avx::avx_planner::FftPlannerAvx;
333
334// Algorithms implemented to use SSE4.1 instructions. Only compiled on x86_64, and only compiled if the "sse" feature flag is set.
335#[cfg(all(target_arch = "x86_64", feature = "sse"))]
336mod sse;
337
338// If we're not on x86_64, or if the "sse" feature was disabled, keep a stub implementation around that has the same API, but does nothing
339// That way, users can write code using the SSE planner and compile it on any platform
340#[cfg(not(all(target_arch = "x86_64", feature = "sse")))]
341mod sse {
342    pub mod sse_planner {
343        use crate::{Fft, FftDirection, FftNum};
344        use std::sync::Arc;
345
346        /// The SSE FFT planner creates new FFT algorithm instances using a mix of scalar and SSE accelerated algorithms.
347        /// It requires at least SSE4.1, which is available on all reasonably recent x86_64 cpus.
348        ///
349        /// RustFFT has several FFT algorithms available. For a given FFT size, the `FftPlannerSse` decides which of the
350        /// available FFT algorithms to use and then initializes them.
351        ///
352        /// ~~~
353        /// // Perform a forward Fft of size 1234
354        /// use std::sync::Arc;
355        /// use rustfft::{FftPlannerSse, num_complex::Complex};
356        ///
357        /// if let Ok(mut planner) = FftPlannerSse::new() {
358        ///   let fft = planner.plan_fft_forward(1234);
359        ///
360        ///   let mut buffer = vec![Complex{ re: 0.0f32, im: 0.0f32 }; 1234];
361        ///   fft.process(&mut buffer);
362        ///
363        ///   // The FFT instance returned by the planner has the type `Arc<dyn Fft<T>>`,
364        ///   // where T is the numeric type, ie f32 or f64, so it's cheap to clone
365        ///   let fft_clone = Arc::clone(&fft);
366        /// }
367        /// ~~~
368        ///
369        /// If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This
370        /// is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing
371        /// setup time. (FFT instances created with one planner will never re-use data and buffers with FFT instances created
372        /// by a different planner)
373        ///
374        /// Each FFT instance owns [`Arc`s](std::sync::Arc) to its internal data, rather than borrowing it from the planner, so it's perfectly
375        /// safe to drop the planner after creating Fft instances.
376        pub struct FftPlannerSse<T: FftNum> {
377            _phantom: std::marker::PhantomData<T>,
378        }
379        impl<T: FftNum> FftPlannerSse<T> {
380            /// Creates a new `FftPlannerSse` instance.
381            ///
382            /// Returns `Ok(planner_instance)` if this machine has the required instruction sets.
383            /// Returns `Err(())` if some instruction sets are missing.
384            pub fn new() -> Result<Self, ()> {
385                Err(())
386            }
387            /// Returns a `Fft` instance which uses SSE4.1 instructions to compute FFTs of size `len`.
388            ///
389            /// If the provided `direction` is `FftDirection::Forward`, the returned instance will compute forward FFTs. If it's `FftDirection::Inverse`, it will compute inverse FFTs.
390            ///
391            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
392            pub fn plan_fft(&mut self, _len: usize, _direction: FftDirection) -> Arc<dyn Fft<T>> {
393                unreachable!()
394            }
395            /// Returns a `Fft` instance which uses SSE4.1 instructions to compute forward FFTs of size `len`.
396            ///
397            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
398            pub fn plan_fft_forward(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
399                unreachable!()
400            }
401            /// Returns a `Fft` instance which uses SSE4.1 instructions to compute inverse FFTs of size `len.
402            ///
403            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
404            pub fn plan_fft_inverse(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
405                unreachable!()
406            }
407        }
408    }
409}
410
411pub use self::sse::sse_planner::FftPlannerSse;
412
413// Algorithms implemented to use Neon instructions. Only compiled on AArch64, and only compiled if the "neon" feature flag is set.
414#[cfg(all(target_arch = "aarch64", feature = "neon"))]
415mod neon;
416
417// If we're not on AArch64, or if the "neon" feature was disabled, keep a stub implementation around that has the same API, but does nothing
418// That way, users can write code using the Neon planner and compile it on any platform
419#[cfg(not(all(target_arch = "aarch64", feature = "neon")))]
420mod neon {
421    pub mod neon_planner {
422        use crate::{Fft, FftDirection, FftNum};
423        use std::sync::Arc;
424
425        /// The Neon FFT planner creates new FFT algorithm instances using a mix of scalar and Neon accelerated algorithms.
426        /// It is supported when using the 64-bit AArch64 instruction set.
427        ///
428        /// RustFFT has several FFT algorithms available. For a given FFT size, the `FftPlannerNeon` decides which of the
429        /// available FFT algorithms to use and then initializes them.
430        ///
431        /// ~~~
432        /// // Perform a forward Fft of size 1234
433        /// use std::sync::Arc;
434        /// use rustfft::{FftPlannerNeon, num_complex::Complex};
435        ///
436        /// if let Ok(mut planner) = FftPlannerNeon::new() {
437        ///   let fft = planner.plan_fft_forward(1234);
438        ///
439        ///   let mut buffer = vec![Complex{ re: 0.0f32, im: 0.0f32 }; 1234];
440        ///   fft.process(&mut buffer);
441        ///
442        ///   // The FFT instance returned by the planner has the type `Arc<dyn Fft<T>>`,
443        ///   // where T is the numeric type, ie f32 or f64, so it's cheap to clone
444        ///   let fft_clone = Arc::clone(&fft);
445        /// }
446        /// ~~~
447        ///
448        /// If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This
449        /// is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing
450        /// setup time. (FFT instances created with one planner will never re-use data and buffers with FFT instances created
451        /// by a different planner)
452        ///
453        /// Each FFT instance owns [`Arc`s](std::sync::Arc) to its internal data, rather than borrowing it from the planner, so it's perfectly
454        /// safe to drop the planner after creating Fft instances.
455        pub struct FftPlannerNeon<T: FftNum> {
456            _phantom: std::marker::PhantomData<T>,
457        }
458        impl<T: FftNum> FftPlannerNeon<T> {
459            /// Creates a new `FftPlannerNeon` instance.
460            ///
461            /// Returns `Ok(planner_instance)` if this machine has the required instruction sets.
462            /// Returns `Err(())` if some instruction sets are missing.
463            pub fn new() -> Result<Self, ()> {
464                Err(())
465            }
466            /// Returns a `Fft` instance which uses Neon instructions to compute FFTs of size `len`.
467            ///
468            /// If the provided `direction` is `FftDirection::Forward`, the returned instance will compute forward FFTs. If it's `FftDirection::Inverse`, it will compute inverse FFTs.
469            ///
470            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
471            pub fn plan_fft(&mut self, _len: usize, _direction: FftDirection) -> Arc<dyn Fft<T>> {
472                unreachable!()
473            }
474            /// Returns a `Fft` instance which uses Neon instructions to compute forward FFTs of size `len`.
475            ///
476            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
477            pub fn plan_fft_forward(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
478                unreachable!()
479            }
480            /// Returns a `Fft` instance which uses Neon instructions to compute inverse FFTs of size `len.
481            ///
482            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
483            pub fn plan_fft_inverse(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
484                unreachable!()
485            }
486        }
487    }
488}
489
490pub use self::neon::neon_planner::FftPlannerNeon;
491
492#[cfg(all(target_arch = "wasm32", feature = "wasm_simd"))]
493mod wasm_simd;
494
495// If we're not compiling to WebAssembly, or if the "wasm_simd" feature was disabled, keep a stub implementation around that has the same API, but does nothing
496// That way, users can write code using the WASM planner and compile it on any platform
497#[cfg(not(all(target_arch = "wasm32", feature = "wasm_simd")))]
498mod wasm_simd {
499    pub mod wasm_simd_planner {
500        use crate::{Fft, FftDirection, FftNum};
501        use std::sync::Arc;
502
503        /// The WASM FFT planner creates new FFT algorithm instances using a mix of scalar and WASM SIMD accelerated algorithms.
504        /// It is supported when using fairly recent browser versions as outlined in [the WebAssembly roadmap](https://webassembly.org/roadmap/).
505        ///
506        /// RustFFT has several FFT algorithms available. For a given FFT size, `FftPlannerWasmSimd` decides which of the
507        /// available FFT algorithms to use and then initializes them.
508        ///
509        /// ~~~
510        /// // Perform a forward Fft of size 1234
511        /// use std::sync::Arc;
512        /// use rustfft::{FftPlannerWasmSimd, num_complex::Complex};
513        ///
514        /// if let Ok(mut planner) = FftPlannerWasmSimd::new() {
515        ///   let fft = planner.plan_fft_forward(1234);
516        ///
517        ///   let mut buffer = vec![Complex{ re: 0.0f32, im: 0.0f32 }; 1234];
518        ///   fft.process(&mut buffer);
519        ///
520        ///   // The FFT instance returned by the planner has the type `Arc<dyn Fft<T>>`,
521        ///   // where T is the numeric type, ie f32 or f64, so it's cheap to clone
522        ///   let fft_clone = Arc::clone(&fft);
523        /// }
524        /// ~~~
525        ///
526        /// If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This
527        /// is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing
528        /// setup time. (FFT instances created with one planner will never re-use data and buffers with FFT instances created
529        /// by a different planner)
530        ///
531        /// Each FFT instance owns [`Arc`s](std::sync::Arc) to its internal data, rather than borrowing it from the planner, so it's perfectly
532        /// safe to drop the planner after creating Fft instances.
533        pub struct FftPlannerWasmSimd<T: FftNum> {
534            _phantom: std::marker::PhantomData<T>,
535        }
536        impl<T: FftNum> FftPlannerWasmSimd<T> {
537            /// Creates a new `FftPlannerWasmSimd` instance.
538            ///
539            /// Returns `Ok(planner_instance)` if this machine has the required instruction sets.
540            /// Returns `Err(())` if some instruction sets are missing.
541            pub fn new() -> Result<Self, ()> {
542                Err(())
543            }
544            /// Returns a `Fft` instance which uses WebAssembly SIMD instructions to compute FFTs of size `len`.
545            ///
546            /// If the provided `direction` is `FftDirection::Forward`, the returned instance will compute forward FFTs. If it's `FftDirection::Inverse`, it will compute inverse FFTs.
547            ///
548            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
549            pub fn plan_fft(&mut self, _len: usize, _direction: FftDirection) -> Arc<dyn Fft<T>> {
550                unreachable!()
551            }
552            /// Returns a `Fft` instance which uses WebAssembly SIMD instructions to compute forward FFTs of size `len`.
553            ///
554            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
555            pub fn plan_fft_forward(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
556                unreachable!()
557            }
558            /// Returns a `Fft` instance which uses WebAssembly SIMD instructions to compute inverse FFTs of size `len.
559            ///
560            /// If this is called multiple times, the planner will attempt to re-use internal data between calls, reducing memory usage and FFT initialization time.
561            pub fn plan_fft_inverse(&mut self, _len: usize) -> Arc<dyn Fft<T>> {
562                unreachable!()
563            }
564        }
565    }
566}
567
568pub use self::wasm_simd::wasm_simd_planner::FftPlannerWasmSimd;
569
570#[cfg(test)]
571mod test_utils;