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

pub trait Frame: Clone + PartialEq<Self> + Copy where
    <Self::Channels as Iterator>::Item == Self::Sample,
    <Self::Signed as Frame>::Sample == <Self::Sample as Sample>::Signed,
    <Self::Signed as Frame>::NumChannels == Self::NumChannels,
    <Self::Float as Frame>::Sample == <Self::Sample as Sample>::Float,
    <Self::Float as Frame>::NumChannels == Self::NumChannels, {
    type Sample: Sample;
    type NumChannels: NumChannels;
    type Channels: Iterator;
    type Signed: Frame;
    type Float: Frame;

    const EQUILIBRIUM: Self;
    const CHANNELS: usize;

    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 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 as Frame>::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 as Frame>::Sample) -> <F as Frame>::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 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.

Implementations are provided for:

  • All fixed-size arrays up to a length of 32 elements.
  • All primitive types that implement Sample. These implementations assume CHANNELS = 1.

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.

Loading content...

Associated Constants

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

Examples

use dasp_frame::{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]);
}

const CHANNELS: usize

The total number of channels within the frame.

Examples

use dasp_frame::{Frame, Mono, Stereo};

fn main() {
    assert_eq!(Mono::<f32>::CHANNELS, 1);
    assert_eq!(Stereo::<f32>::CHANNELS, 2);
    assert_eq!(<[f32; 3]>::CHANNELS, 3);
    assert_eq!(<[u8; 2]>::CHANNELS, 2);
}
Loading content...

Required methods

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 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 as Frame>::Sample, 

Applies the given function to each sample in the Frame in channel order and returns the result as a new Frame.

Example

use dasp_frame::Frame;
use dasp_sample::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 as Frame>::Sample) -> <F as Frame>::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

use dasp_frame::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

use dasp_frame::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

use dasp_frame::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

use dasp_frame::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

use dasp_frame::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

use dasp_frame::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, -1.0]);
    assert_eq!(bar, [128, 192]);
}
Loading content...

Implementations on Foreign Types

impl Frame for i8[src]

type Sample = i8

type NumChannels = N1

type Channels = Channels<i8>

type Float = <i8 as Sample>::Float

type Signed = <i8 as Sample>::Signed

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

type Sample = S

type NumChannels = N6

type Channels = Channels<[S; 6]>

type Float = [<S as Sample>::Float; 6]

type Signed = [<S as Sample>::Signed; 6]

impl Frame for u64[src]

type Sample = u64

type NumChannels = N1

type Channels = Channels<u64>

type Float = <u64 as Sample>::Float

type Signed = <u64 as Sample>::Signed

impl Frame for u16[src]

type Sample = u16

type NumChannels = N1

type Channels = Channels<u16>

type Float = <u16 as Sample>::Float

type Signed = <u16 as Sample>::Signed

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

type Sample = S

type NumChannels = N2

type Channels = Channels<[S; 2]>

type Float = [<S as Sample>::Float; 2]

type Signed = [<S as Sample>::Signed; 2]

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

type Sample = S

type NumChannels = N32

type Channels = Channels<[S; 32]>

type Float = [<S as Sample>::Float; 32]

type Signed = [<S as Sample>::Signed; 32]

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

type Sample = S

type NumChannels = N5

type Channels = Channels<[S; 5]>

type Float = [<S as Sample>::Float; 5]

type Signed = [<S as Sample>::Signed; 5]

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

type Sample = S

type NumChannels = N4

type Channels = Channels<[S; 4]>

type Float = [<S as Sample>::Float; 4]

type Signed = [<S as Sample>::Signed; 4]

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

type Sample = S

type NumChannels = N17

type Channels = Channels<[S; 17]>

type Float = [<S as Sample>::Float; 17]

type Signed = [<S as Sample>::Signed; 17]

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

type Sample = S

type NumChannels = N27

type Channels = Channels<[S; 27]>

type Float = [<S as Sample>::Float; 27]

type Signed = [<S as Sample>::Signed; 27]

impl Frame for i64[src]

type Sample = i64

type NumChannels = N1

type Channels = Channels<i64>

type Float = <i64 as Sample>::Float

type Signed = <i64 as Sample>::Signed

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

type Sample = S

type NumChannels = N8

type Channels = Channels<[S; 8]>

type Float = [<S as Sample>::Float; 8]

type Signed = [<S as Sample>::Signed; 8]

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

type Sample = S

type NumChannels = N19

type Channels = Channels<[S; 19]>

type Float = [<S as Sample>::Float; 19]

type Signed = [<S as Sample>::Signed; 19]

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

type Sample = S

type NumChannels = N26

type Channels = Channels<[S; 26]>

type Float = [<S as Sample>::Float; 26]

type Signed = [<S as Sample>::Signed; 26]

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

type Sample = S

type NumChannels = N7

type Channels = Channels<[S; 7]>

type Float = [<S as Sample>::Float; 7]

type Signed = [<S as Sample>::Signed; 7]

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

type Sample = S

type NumChannels = N20

type Channels = Channels<[S; 20]>

type Float = [<S as Sample>::Float; 20]

type Signed = [<S as Sample>::Signed; 20]

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

type Sample = S

type NumChannels = N1

type Channels = Channels<[S; 1]>

type Float = [<S as Sample>::Float; 1]

type Signed = [<S as Sample>::Signed; 1]

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

type Sample = S

type NumChannels = N12

type Channels = Channels<[S; 12]>

type Float = [<S as Sample>::Float; 12]

type Signed = [<S as Sample>::Signed; 12]

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

type Sample = S

type NumChannels = N24

type Channels = Channels<[S; 24]>

type Float = [<S as Sample>::Float; 24]

type Signed = [<S as Sample>::Signed; 24]

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

type Sample = S

type NumChannels = N31

type Channels = Channels<[S; 31]>

type Float = [<S as Sample>::Float; 31]

type Signed = [<S as Sample>::Signed; 31]

impl Frame for f64[src]

type Sample = f64

type NumChannels = N1

type Channels = Channels<f64>

type Float = <f64 as Sample>::Float

type Signed = <f64 as Sample>::Signed

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

type Sample = S

type NumChannels = N23

type Channels = Channels<[S; 23]>

type Float = [<S as Sample>::Float; 23]

type Signed = [<S as Sample>::Signed; 23]

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

type Sample = S

type NumChannels = N13

type Channels = Channels<[S; 13]>

type Float = [<S as Sample>::Float; 13]

type Signed = [<S as Sample>::Signed; 13]

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

type Sample = S

type NumChannels = N22

type Channels = Channels<[S; 22]>

type Float = [<S as Sample>::Float; 22]

type Signed = [<S as Sample>::Signed; 22]

impl Frame for f32[src]

type Sample = f32

type NumChannels = N1

type Channels = Channels<f32>

type Float = <f32 as Sample>::Float

type Signed = <f32 as Sample>::Signed

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

type Sample = S

type NumChannels = N3

type Channels = Channels<[S; 3]>

type Float = [<S as Sample>::Float; 3]

type Signed = [<S as Sample>::Signed; 3]

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

type Sample = S

type NumChannels = N11

type Channels = Channels<[S; 11]>

type Float = [<S as Sample>::Float; 11]

type Signed = [<S as Sample>::Signed; 11]

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

type Sample = S

type NumChannels = N10

type Channels = Channels<[S; 10]>

type Float = [<S as Sample>::Float; 10]

type Signed = [<S as Sample>::Signed; 10]

impl Frame for u32[src]

type Sample = u32

type NumChannels = N1

type Channels = Channels<u32>

type Float = <u32 as Sample>::Float

type Signed = <u32 as Sample>::Signed

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

type Sample = S

type NumChannels = N30

type Channels = Channels<[S; 30]>

type Float = [<S as Sample>::Float; 30]

type Signed = [<S as Sample>::Signed; 30]

impl Frame for i32[src]

type Sample = i32

type NumChannels = N1

type Channels = Channels<i32>

type Float = <i32 as Sample>::Float

type Signed = <i32 as Sample>::Signed

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

type Sample = S

type NumChannels = N15

type Channels = Channels<[S; 15]>

type Float = [<S as Sample>::Float; 15]

type Signed = [<S as Sample>::Signed; 15]

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

type Sample = S

type NumChannels = N21

type Channels = Channels<[S; 21]>

type Float = [<S as Sample>::Float; 21]

type Signed = [<S as Sample>::Signed; 21]

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

type Sample = S

type NumChannels = N18

type Channels = Channels<[S; 18]>

type Float = [<S as Sample>::Float; 18]

type Signed = [<S as Sample>::Signed; 18]

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

type Sample = S

type NumChannels = N28

type Channels = Channels<[S; 28]>

type Float = [<S as Sample>::Float; 28]

type Signed = [<S as Sample>::Signed; 28]

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

type Sample = S

type NumChannels = N14

type Channels = Channels<[S; 14]>

type Float = [<S as Sample>::Float; 14]

type Signed = [<S as Sample>::Signed; 14]

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

type Sample = S

type NumChannels = N29

type Channels = Channels<[S; 29]>

type Float = [<S as Sample>::Float; 29]

type Signed = [<S as Sample>::Signed; 29]

impl Frame for u8[src]

type Sample = u8

type NumChannels = N1

type Channels = Channels<u8>

type Float = <u8 as Sample>::Float

type Signed = <u8 as Sample>::Signed

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

type Sample = S

type NumChannels = N25

type Channels = Channels<[S; 25]>

type Float = [<S as Sample>::Float; 25]

type Signed = [<S as Sample>::Signed; 25]

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

type Sample = S

type NumChannels = N9

type Channels = Channels<[S; 9]>

type Float = [<S as Sample>::Float; 9]

type Signed = [<S as Sample>::Signed; 9]

impl Frame for i16[src]

type Sample = i16

type NumChannels = N1

type Channels = Channels<i16>

type Float = <i16 as Sample>::Float

type Signed = <i16 as Sample>::Signed

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

type Sample = S

type NumChannels = N16

type Channels = Channels<[S; 16]>

type Float = [<S as Sample>::Float; 16]

type Signed = [<S as Sample>::Signed; 16]

Loading content...

Implementors

impl Frame for I24[src]

type Sample = I24

type NumChannels = N1

type Channels = Channels<I24>

type Float = <I24 as Sample>::Float

type Signed = <I24 as Sample>::Signed

impl Frame for I48[src]

type Sample = I48

type NumChannels = N1

type Channels = Channels<I48>

type Float = <I48 as Sample>::Float

type Signed = <I48 as Sample>::Signed

impl Frame for U24[src]

type Sample = U24

type NumChannels = N1

type Channels = Channels<U24>

type Float = <U24 as Sample>::Float

type Signed = <U24 as Sample>::Signed

impl Frame for U48[src]

type Sample = U48

type NumChannels = N1

type Channels = Channels<U48>

type Float = <U48 as Sample>::Float

type Signed = <U48 as Sample>::Signed

Loading content...