Trait dsp::Frame [−] [src]

pub trait Frame: Copy + PartialEq<Self> + Clone where Self::Channels::Item == Self::Sample, Self::Signed::Sample == Self::Sample::Signed, Self::Signed::NumChannels == Self::NumChannels, Self::Float::Sample == Self::Sample::Float, Self::Float::NumChannels == Self::NumChannels {
    type Sample: Sample;
    type NumChannels: NumChannels;
    type Channels: Iterator;
    type Signed: Frame;
    type Float: Frame;
    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 F: Frame<NumChannels=Self::NumChannels>, M: FnMut(Self::Sample, O::Sample) -> F::Sample, O: Frame<NumChannels=Self::NumChannels>;
    fn to_signed_frame(self) -> Self::Signed;
    fn to_float_frame(self) -> Self::Float;

    fn offset_amp(self, offset: Self::Sample::Signed) -> Self { ... }
    fn scale_amp(self, amp: Self::Sample::Float) -> Self { ... }
    fn add_amp<F>(self, other: F) -> Self where F: Frame<Sample=Self::Sample::Signed, NumChannels=Self::NumChannels> { ... }
    fn mul_amp<F>(self, other: F) -> Self where F: Frame<Sample=Self::Sample::Float, NumChannels=Self::NumChannels> { ... }
}

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.

Associated Types

type Sample: Sample

The type of PCM sample stored at each channel within the frame.

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.

type Channels: Iterator

An iterator yielding the sample in each channel, starting from left (channel 0) and ending at the right (channel NumChannels-1).

type Signed: Frame

A frame type with equilavent number of channels using the associated Sample::Signed format.

type Float: Frame

A frame type with equilavent number of channels using the associated Sample::Float format.

Required Methods

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]);
}

fn from_fn<F>(from: F) -> Self where F: FnMut(usize) -> Self::Sample

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.

fn from_samples<I>(samples: &mut I) -> Option<Self> where I: Iterator<Item=Self::Sample>

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.

fn n_channels() -> usize

The total number of channels (and in turn samples) stored within the frame.

fn channels(self) -> Self::Channels

Converts the frame into an iterator yielding the sample for each channel in the frame.

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.

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.

fn map<F, M>(self, map: M) -> F where F: Frame<NumChannels=Self::NumChannels>, M: FnMut(Self::Sample) -> F::Sample

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]);
}

fn zip_map<O, F, M>(self, other: O, zip_map: M) -> F where F: Frame<NumChannels=Self::NumChannels>, M: FnMut(Self::Sample, O::Sample) -> F::Sample, O: Frame<NumChannels=Self::NumChannels>

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.

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]);
}

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

fn offset_amp(self, offset: Self::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]);
}

fn scale_amp(self, amp: Self::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]);
}

fn add_amp<F>(self, other: F) -> Self where F: Frame<Sample=Self::Sample::Signed, NumChannels=Self::NumChannels>

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]);
}

fn mul_amp<F>(self, other: F) -> Self where F: Frame<Sample=Self::Sample::Float, NumChannels=Self::NumChannels>

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]);
}

Implementors