pub trait Frame:
Copy
+ Clone
+ PartialEq {
type Sample: Sample;
type NumChannels: NumChannels;
type Channels: Iterator<Item = Self::Sample>;
type Signed: Frame<Sample = <Self::Sample as Sample>::Signed, NumChannels = Self::NumChannels>;
type Float: Frame<Sample = <Self::Sample as Sample>::Float, NumChannels = Self::NumChannels>;
Show 15 methods
// Required methods
fn equilibrium() -> Self;
fn from_fn<F>(from: F) -> Self
where F: FnMut(usize) -> Self::Sample;
fn from_samples<I>(samples: &mut I) -> Option<Self>
where I: Iterator<Item = Self::Sample>;
fn n_channels() -> usize;
fn channels(self) -> Self::Channels;
fn channel(&self, idx: usize) -> Option<&Self::Sample>;
unsafe fn channel_unchecked(&self, idx: usize) -> &Self::Sample;
fn map<F, M>(self, map: M) -> F
where F: Frame<NumChannels = Self::NumChannels>,
M: FnMut(Self::Sample) -> F::Sample;
fn zip_map<O, F, M>(self, other: O, zip_map: M) -> F
where O: Frame<NumChannels = Self::NumChannels>,
F: Frame<NumChannels = Self::NumChannels>,
M: FnMut(Self::Sample, O::Sample) -> F::Sample;
fn to_signed_frame(self) -> Self::Signed;
fn to_float_frame(self) -> Self::Float;
// Provided methods
fn offset_amp(self, offset: <Self::Sample as Sample>::Signed) -> Self { ... }
fn scale_amp(self, amp: <Self::Sample as Sample>::Float) -> Self { ... }
fn add_amp<F>(self, other: F) -> Self
where F: Frame<Sample = <Self::Sample as Sample>::Signed, NumChannels = Self::NumChannels> { ... }
fn mul_amp<F>(self, other: F) -> Self
where F: Frame<Sample = <Self::Sample as Sample>::Float, NumChannels = Self::NumChannels> { ... }
}Expand description
Represents one sample from each channel at a single discrete instance in time within a PCM signal.
We provide implementations for Frame for all fixed-size arrays up to a length of 32 elements.
Required Associated Types§
Sourcetype NumChannels: NumChannels
type NumChannels: NumChannels
A typified version of a number of channels in the Frame, used for safely mapping frames
of the same length to other Frames, perhaps with a different Sample associated type.
Sourcetype Channels: Iterator<Item = Self::Sample>
type Channels: Iterator<Item = Self::Sample>
An iterator yielding the sample in each channel, starting from left (channel 0) and ending at the right (channel NumChannels-1).
Required Methods§
Sourcefn equilibrium() -> Self
fn equilibrium() -> Self
The equilibrium value for the wave that this Sample type represents. This is normally the
value that is equal distance from both the min and max ranges of the sample.
NOTE: This will likely be changed to an “associated const” if the feature lands.
§Examples
extern crate sample;
use sample::Frame;
use sample::frame::{Mono, Stereo};
fn main() {
assert_eq!(Mono::<f32>::equilibrium(), [0.0]);
assert_eq!(Stereo::<f32>::equilibrium(), [0.0, 0.0]);
assert_eq!(<[f32; 3]>::equilibrium(), [0.0, 0.0, 0.0]);
assert_eq!(<[u8; 2]>::equilibrium(), [128u8, 128]);
}Sourcefn from_fn<F>(from: F) -> Self
fn from_fn<F>(from: F) -> Self
Create a new Frame where the Sample for each channel is produced by the given function.
The given function should map each channel index to its respective sample.
Sourcefn from_samples<I>(samples: &mut I) -> Option<Self>
fn from_samples<I>(samples: &mut I) -> Option<Self>
Create a new Frame from a borrowed Iterator yielding samples for each channel.
Returns None if the given Iterator does not yield enough Samples.
This is necessary for the signal::FromSamples Iterator, that converts some Iterator
yielding Samples to an Iterator yielding Frames.
Sourcefn n_channels() -> usize
fn n_channels() -> usize
The total number of channels (and in turn samples) stored within the frame.
Sourcefn channels(self) -> Self::Channels
fn channels(self) -> Self::Channels
Converts the frame into an iterator yielding the sample for each channel in the frame.
Sourcefn channel(&self, idx: usize) -> Option<&Self::Sample>
fn channel(&self, idx: usize) -> Option<&Self::Sample>
Yields a reference to the Sample of the channel at the given index if there is one.
Sourceunsafe fn channel_unchecked(&self, idx: usize) -> &Self::Sample
unsafe fn channel_unchecked(&self, idx: usize) -> &Self::Sample
Returns a pointer to the sample of the channel at the given index, without doing bounds checking.
Note: This is primarily a necessity for efficient Frame::map and Frame::zip_map
methods, as for those methods we can guarantee lengths of different Frames to be the same
at compile-time.
Sourcefn map<F, M>(self, map: M) -> F
fn map<F, M>(self, map: M) -> F
Applies the given function to each sample in the Frame in channel order and returns the
result as a new Frame.
§Example
extern crate sample;
use sample::{Frame, Sample};
fn main() {
let foo = [0i16, 0];
let bar: [u8; 2] = foo.map(Sample::to_sample);
assert_eq!(bar, [128u8, 128]);
}Sourcefn zip_map<O, F, M>(self, other: O, zip_map: M) -> Fwhere
O: Frame<NumChannels = Self::NumChannels>,
F: Frame<NumChannels = Self::NumChannels>,
M: FnMut(Self::Sample, O::Sample) -> F::Sample,
fn zip_map<O, F, M>(self, other: O, zip_map: M) -> Fwhere
O: Frame<NumChannels = Self::NumChannels>,
F: Frame<NumChannels = Self::NumChannels>,
M: FnMut(Self::Sample, O::Sample) -> F::Sample,
Calls the given function with the pair of elements at every index and returns the resulting Frame.
On a Vec this would be akin to .into_iter().zip(other).map(|(a, b)| ...).collect(), though
much quicker and tailored to fixed-size arrays of samples.
Sourcefn to_signed_frame(self) -> Self::Signed
fn to_signed_frame(self) -> Self::Signed
Converts the frame type to the equivalent signal in its associated Floating point format.
§Example
extern crate sample;
use sample::Frame;
fn main() {
let foo = [128u8; 2];
let signed = foo.to_signed_frame();
assert_eq!(signed, [0i8; 2]);
}Sourcefn to_float_frame(self) -> Self::Float
fn to_float_frame(self) -> Self::Float
Converts the frame type to the equivalent signal in its associated Signed format.
§Example
extern crate sample;
use sample::Frame;
fn main() {
let foo = [128u8; 2];
let float = foo.to_float_frame();
assert_eq!(float, [0.0; 2]);
}Provided Methods§
Sourcefn offset_amp(self, offset: <Self::Sample as Sample>::Signed) -> Self
fn offset_amp(self, offset: <Self::Sample as Sample>::Signed) -> Self
Offsets the amplitude of every channel in the frame by the given offset and yields the
resulting frame.
§Example
extern crate sample;
use sample::Frame;
fn main() {
assert_eq!([0.25, -0.5].offset_amp(0.5), [0.75, 0.0]);
assert_eq!([0.5, -0.25].offset_amp(-0.25), [0.25, -0.5]);
assert_eq!([128u8, 192].offset_amp(-64), [64, 128]);
}Sourcefn scale_amp(self, amp: <Self::Sample as Sample>::Float) -> Self
fn scale_amp(self, amp: <Self::Sample as Sample>::Float) -> Self
Multiplies each Sample in the Frame by the given amplitude and returns the resulting
Frame.
- A > 1.0 amplifies the sample.
- A < 1.0 attenuates the sample.
- A == 1.0 yields the same sample.
- A == 0.0 yields the
Sample::equilibrium.
§Example
extern crate sample;
use sample::Frame;
fn main() {
assert_eq!([0.1, 0.2, -0.1, -0.2].scale_amp(2.0), [0.2, 0.4, -0.2, -0.4]);
}Sourcefn add_amp<F>(self, other: F) -> Self
fn add_amp<F>(self, other: F) -> Self
Sums each channel in other with each channel in self and returns the resulting Frame.
§Example
extern crate sample;
use sample::Frame;
fn main() {
let foo = [0.25, 0.5].add_amp([-0.75, 0.25]);
assert_eq!(foo, [-0.5, 0.75]);
}Sourcefn mul_amp<F>(self, other: F) -> Self
fn mul_amp<F>(self, other: F) -> Self
Multiplies other with self and returns the resulting Frame.
§Example
extern crate sample;
use sample::Frame;
fn main() {
let foo = [0.25, 0.4].mul_amp([0.2, 0.5]);
assert_eq!(foo, [0.05, 0.2]);
let bar = [192u8, 64].mul_amp([0.0, -2.0]);
assert_eq!(bar, [128, 0]);
}Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.