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;