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

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

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<Item = Self::Sample>

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

type Signed: Frame<Sample = <Self::Sample as Sample>::Signed, NumChannels = Self::NumChannels>

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

type Float: Frame<Sample = <Self::Sample as Sample>::Float, NumChannels = Self::NumChannels>

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

Loading content...

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

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

Provided methods

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

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

fn add_amp<F>(self, other: F) -> Self where
    F: Frame<Sample = <Self::Sample as 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 as 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]);
}
Loading content...

Implementations on Foreign Types

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

type Sample = S

type NumChannels = N1

type Channels = Channels<Self>

type Float = [S::Float; 1]

type Signed = [S::Signed; 1]

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

type Sample = S

type NumChannels = N2

type Channels = Channels<Self>

type Float = [S::Float; 2]

type Signed = [S::Signed; 2]

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

type Sample = S

type NumChannels = N3

type Channels = Channels<Self>

type Float = [S::Float; 3]

type Signed = [S::Signed; 3]

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

type Sample = S

type NumChannels = N4

type Channels = Channels<Self>

type Float = [S::Float; 4]

type Signed = [S::Signed; 4]

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

type Sample = S

type NumChannels = N5

type Channels = Channels<Self>

type Float = [S::Float; 5]

type Signed = [S::Signed; 5]

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

type Sample = S

type NumChannels = N6

type Channels = Channels<Self>

type Float = [S::Float; 6]

type Signed = [S::Signed; 6]

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

type Sample = S

type NumChannels = N7

type Channels = Channels<Self>

type Float = [S::Float; 7]

type Signed = [S::Signed; 7]

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

type Sample = S

type NumChannels = N8

type Channels = Channels<Self>

type Float = [S::Float; 8]

type Signed = [S::Signed; 8]

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

type Sample = S

type NumChannels = N9

type Channels = Channels<Self>

type Float = [S::Float; 9]

type Signed = [S::Signed; 9]

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

type Sample = S

type NumChannels = N10

type Channels = Channels<Self>

type Float = [S::Float; 10]

type Signed = [S::Signed; 10]

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

type Sample = S

type NumChannels = N11

type Channels = Channels<Self>

type Float = [S::Float; 11]

type Signed = [S::Signed; 11]

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

type Sample = S

type NumChannels = N12

type Channels = Channels<Self>

type Float = [S::Float; 12]

type Signed = [S::Signed; 12]

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

type Sample = S

type NumChannels = N13

type Channels = Channels<Self>

type Float = [S::Float; 13]

type Signed = [S::Signed; 13]

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

type Sample = S

type NumChannels = N14

type Channels = Channels<Self>

type Float = [S::Float; 14]

type Signed = [S::Signed; 14]

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

type Sample = S

type NumChannels = N15

type Channels = Channels<Self>

type Float = [S::Float; 15]

type Signed = [S::Signed; 15]

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

type Sample = S

type NumChannels = N16

type Channels = Channels<Self>

type Float = [S::Float; 16]

type Signed = [S::Signed; 16]

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

type Sample = S

type NumChannels = N17

type Channels = Channels<Self>

type Float = [S::Float; 17]

type Signed = [S::Signed; 17]

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

type Sample = S

type NumChannels = N18

type Channels = Channels<Self>

type Float = [S::Float; 18]

type Signed = [S::Signed; 18]

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

type Sample = S

type NumChannels = N19

type Channels = Channels<Self>

type Float = [S::Float; 19]

type Signed = [S::Signed; 19]

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

type Sample = S

type NumChannels = N20

type Channels = Channels<Self>

type Float = [S::Float; 20]

type Signed = [S::Signed; 20]

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

type Sample = S

type NumChannels = N21

type Channels = Channels<Self>

type Float = [S::Float; 21]

type Signed = [S::Signed; 21]

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

type Sample = S

type NumChannels = N22

type Channels = Channels<Self>

type Float = [S::Float; 22]

type Signed = [S::Signed; 22]

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

type Sample = S

type NumChannels = N23

type Channels = Channels<Self>

type Float = [S::Float; 23]

type Signed = [S::Signed; 23]

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

type Sample = S

type NumChannels = N24

type Channels = Channels<Self>

type Float = [S::Float; 24]

type Signed = [S::Signed; 24]

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

type Sample = S

type NumChannels = N25

type Channels = Channels<Self>

type Float = [S::Float; 25]

type Signed = [S::Signed; 25]

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

type Sample = S

type NumChannels = N26

type Channels = Channels<Self>

type Float = [S::Float; 26]

type Signed = [S::Signed; 26]

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

type Sample = S

type NumChannels = N27

type Channels = Channels<Self>

type Float = [S::Float; 27]

type Signed = [S::Signed; 27]

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

type Sample = S

type NumChannels = N28

type Channels = Channels<Self>

type Float = [S::Float; 28]

type Signed = [S::Signed; 28]

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

type Sample = S

type NumChannels = N29

type Channels = Channels<Self>

type Float = [S::Float; 29]

type Signed = [S::Signed; 29]

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

type Sample = S

type NumChannels = N30

type Channels = Channels<Self>

type Float = [S::Float; 30]

type Signed = [S::Signed; 30]

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

type Sample = S

type NumChannels = N31

type Channels = Channels<Self>

type Float = [S::Float; 31]

type Signed = [S::Signed; 31]

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

type Sample = S

type NumChannels = N32

type Channels = Channels<Self>

type Float = [S::Float; 32]

type Signed = [S::Signed; 32]

Loading content...

Implementors

Loading content...