Trait sample::frame::Frame[−][src]

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>;
    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;

    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>,
    { ... }
}

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

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

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.

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

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

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

Required Methods

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

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.

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.

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

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

Yields a reference to the Sample of the channel at the given index if there is one.

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.

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

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.

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

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

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

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

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

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

Implementations on Foreign Types

impl<S> Frame for [S; 1] where
    S: Sample, 
[src]

impl<S> Frame for [S; 2] where
    S: Sample, 
[src]

impl<S> Frame for [S; 3] where
    S: Sample, 
[src]

impl<S> Frame for [S; 4] where
    S: Sample, 
[src]

impl<S> Frame for [S; 5] where
    S: Sample, 
[src]

impl<S> Frame for [S; 6] where
    S: Sample, 
[src]

impl<S> Frame for [S; 7] where
    S: Sample, 
[src]

impl<S> Frame for [S; 8] where
    S: Sample, 
[src]

impl<S> Frame for [S; 9] where
    S: Sample, 
[src]

impl<S> Frame for [S; 10] where
    S: Sample, 
[src]

impl<S> Frame for [S; 11] where
    S: Sample, 
[src]

impl<S> Frame for [S; 12] where
    S: Sample, 
[src]

impl<S> Frame for [S; 13] where
    S: Sample, 
[src]

impl<S> Frame for [S; 14] where
    S: Sample, 
[src]

impl<S> Frame for [S; 15] where
    S: Sample, 
[src]

impl<S> Frame for [S; 16] where
    S: Sample, 
[src]

impl<S> Frame for [S; 17] where
    S: Sample, 
[src]

impl<S> Frame for [S; 18] where
    S: Sample, 
[src]

impl<S> Frame for [S; 19] where
    S: Sample, 
[src]

impl<S> Frame for [S; 20] where
    S: Sample, 
[src]

impl<S> Frame for [S; 21] where
    S: Sample, 
[src]

impl<S> Frame for [S; 22] where
    S: Sample, 
[src]

impl<S> Frame for [S; 23] where
    S: Sample, 
[src]

impl<S> Frame for [S; 24] where
    S: Sample, 
[src]

impl<S> Frame for [S; 25] where
    S: Sample, 
[src]

impl<S> Frame for [S; 26] where
    S: Sample, 
[src]

impl<S> Frame for [S; 27] where
    S: Sample, 
[src]

impl<S> Frame for [S; 28] where
    S: Sample, 
[src]

impl<S> Frame for [S; 29] where
    S: Sample, 
[src]

impl<S> Frame for [S; 30] where
    S: Sample, 
[src]

impl<S> Frame for [S; 31] where
    S: Sample, 
[src]

impl<S> Frame for [S; 32] where
    S: Sample, 
[src]

Implementors