# r8brain-sys
Raw Rust bindings to the public C++ API of
[r8brain-free-src](https://github.com/avaneev/r8brain-free-src), Aleksey
Vaneev's high-quality sample-rate converter.
The default `build` feature compiles r8brain's 7.3 source.
```rust
use std::ptr;
use r8brain_sys::*;
unsafe {
let resampler = resampler24_create(44_100.0, 48_000.0, 1024, 2.0);
assert!(!resampler.is_null());
let mut input = vec![0.0; 1024];
let mut output = ptr::null_mut();
let output_len = resampler24_process(
resampler,
input.as_mut_ptr(),
input.len() as i32,
&mut output,
);
let output = std::slice::from_raw_parts(output, output_len as usize);
// Consume `output` before calling a mutating function on `resampler`.
resampler24_destroy(resampler);
}
```
## Exposed C++ surface
- `CDSPResampler`, `CDSPResampler16`, `CDSPResampler16IR`, and
`CDSPResampler24`, including every public query, streaming processing, and
the `f64` specialization of the templated one-shot method.
- Every concrete `CDSPProcessor`: `CDSPBlockConvolver`,
`CDSPHBDownsampler`, `CDSPHBUpsampler`, and `CDSPFracInterpolator`.
- `CDSPFIRFilter`, `CDSPFIRFilterCache`, `CDSPFracDelayFilterBank`, and its
cache, including explicit reference-management functions.
- `CDSPRealFFTKeeper` and all operations on its acquired `CDSPRealFFT`.
- `CDSPSincFilterGen`, its public state, initialization modes, window
calculators, and generation methods.
- `CSineGen` and r8brain's documented FIR, spline, minimum-phase, stepping,
response-scanning, and mathematical utility functions.
Allocator, synchronization, and ownership-helper templates remain internal
implementation details. C++ overloads have distinct C names, and APIs that
take C++ `bool` use `c_int` (`0` is false, nonzero is true). The sinc
generator's member-function pointer parameters use the `wc*` selector
constants. Direct FFT buffers must satisfy the active backend's alignment
requirements (at least 16-byte alignment for the bundled PFFFT backends).
## Safety and ownership
As a `-sys` crate, all functions are raw and unsafe. Constructor preconditions and buffer sizes
documented by r8brain must be upheld. In particular, an input block passed to
a resampler must not exceed the `MaxInLen` supplied at construction.
The one-shot resampler functions require writable input in r8brain 7.3 because
the implementation may use the input buffer as temporary storage.
Streaming resamplers return a borrowed pointer that may alias the input or
resampler-owned storage. It must not be freed and must be consumed before the
same object is mutated again. Other `CDSPProcessor` implementations expect
the caller to initialize the output pointer to storage sized using that
processor's `getMaxOutLen` function.
Objects acquired from `firFilterCache_getLPFilter` must be released with
`firFilter_unref`, unless their reference is transferred to
`blockConvolver_create`, which inherits and releases it. Non-static filter
banks acquired from the cache must be released with
`fracDelayFilterBank_unref`; directly constructed banks use
`fracDelayFilterBank_destroy`.
Optional `r8b_pffft` and `r8b_pffft_double` features select the bundled PFFFT
FFT backends. If both are enabled, the double-precision backend takes
precedence.
The `r8b_fasttiming` and `r8b_extfft` Cargo features enable r8brain's corresponding `R8B_FASTTIMING` and `R8B_EXTFFT` compile-time options, respectively.
Disabling default features skips
compilation of the bundled C++ source; the final application must then provide
every referenced shim symbol.