Struct audio::buf::interleaved::Interleaved

pub struct Interleaved<T> { /* private fields */ }

A dynamically sized, multi-channel interleaved audio buffer.

An audio buffer can only be resized if it contains a type which is sample-apt. For more information of what this means, see Sample.

An interleaved audio buffer stores all audio data interleaved in memory, one sample from each channel in sequence until we’re out of samples. This naturally makes the buffer a bit harder to work with, and we have to rely on iterators to access logical channels.

Resized regions aren’t zeroed, so certain operations might cause stale data to be visible after a resize.

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 4);

for (c, s) in buf
    .get_mut(0)
    .unwrap()
    .iter_mut()
    .zip(&[1.0, 2.0, 3.0, 4.0])
{
    *c = *s;
}

for (c, s) in buf
    .get_mut(1)
    .unwrap()
    .iter_mut()
    .zip(&[5.0, 6.0, 7.0, 8.0])
{
    *c = *s;
}

assert_eq!(buf.as_slice(), &[1.0, 5.0, 2.0, 6.0, 3.0, 7.0, 4.0, 8.0]);

Implementations

impl<T> Interleaved<T>

pub fn new() -> Self

Construct a new empty audio buffer.

Examples

let buf = audio::buf::Interleaved::<f32>::new();

assert_eq!(buf.frames(), 0);

pub fn with_topology(channels: usize, frames: usize) -> Self

where T: Sample,

Allocate an audio buffer with the given topology. A “topology” is a given number of channels and the corresponding number of frames in their buffers.

Examples

let buf = audio::buf::Interleaved::<f32>::with_topology(4, 256);

assert_eq!(buf.frames(), 256);
assert_eq!(buf.channels(), 4);

pub fn from_vec(data: Vec<T>, channels: usize, frames: usize) -> Self

Allocate an audio buffer from a fixed-size array.

See dynamic!.

Examples

let buf = audio::interleaved![[2.0; 256]; 4];

assert_eq!(buf.frames(), 256);
assert_eq!(buf.channels(), 4);

for chan in &buf {
    assert!(chan.iter().eq([2.0; 256]));
}

pub fn from_frames<const N: usize>(frames: [T; N], channels: usize) -> Self

where T: Copy,

Allocate an interleaved audio buffer from a fixed-size array acting as a template for all the channels.

See sequential!.

Examples

let buf = audio::buf::Interleaved::from_frames([1.0, 2.0, 3.0, 4.0], 4);

assert_eq!(buf.frames(), 4);
assert_eq!(buf.channels(), 4);

pub fn from_array<const F: usize, const C: usize>(channels: [[T; F]; C]) -> Self

where T: Copy,

Allocate an interleaved audio buffer from a fixed-size array.

See interleaved!.

Examples

let buf = audio::buf::Interleaved::from_array([[1; 4]; 2]);

assert_eq!(buf.frames(), 4);
assert_eq!(buf.channels(), 2);

assert_eq! {
    buf.as_slice(),
    &[1, 1, 1, 1, 1, 1, 1, 1],
}

Using a specific array topology.

let buf = audio::buf::Interleaved::from_array([[1, 2, 3, 4], [5, 6, 7, 8]]);

assert_eq!(buf.frames(), 4);
assert_eq!(buf.channels(), 2);

assert_eq! {
    buf.as_slice(),
    &[1, 5, 2, 6, 3, 7, 4, 8],
}

pub fn into_vec(self) -> Vec<T>

Take ownership of the backing vector.

Examples

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 4);

for (c, s) in buf.get_mut(0).unwrap().iter_mut().zip(&[1.0, 2.0, 3.0, 4.0]) {
    *c = *s;
}

for (c, s) in buf.get_mut(1).unwrap().iter_mut().zip(&[1.0, 2.0, 3.0, 4.0]) {
    *c = *s;
}

buf.resize_frames(3);

assert_eq!(buf.into_vec(), vec![1.0, 1.0, 2.0, 2.0, 3.0, 3.0])

pub fn as_slice(&self) -> &[T]

Access the underlying vector as a slice.

Examples

let buf = audio::buf::Interleaved::<i16>::with_topology(2, 4);
assert_eq!(buf.as_slice(), &[0, 0, 0, 0, 0, 0, 0, 0]);

pub fn as_slice_mut(&mut self) -> &mut [T]

Access the underlying vector as a mutable slice.

Examples

use audio::{Buf, Channel};

let mut buf = audio::buf::Interleaved::<u32>::with_topology(2, 4);
buf.as_slice_mut().copy_from_slice(&[1, 1, 2, 2, 3, 3, 4, 4]);

assert_eq! {
    buf.get_channel(0).unwrap(),
    [1u32, 2, 3, 4],
};

assert_eq! {
    buf.get_channel(1).unwrap(),
    [1u32, 2, 3, 4],
};

assert_eq!(buf.as_slice(), &[1, 1, 2, 2, 3, 3, 4, 4]);

pub fn capacity(&self) -> usize

Get the capacity of the interleaved buffer in number of frames.

The underlying buffer over-allocates a bit, so this will report the exact capacity available in the interleaved buffer.

Examples

let mut buf = audio::buf::Interleaved::<f32>::new();

assert_eq!(buf.capacity(), 0);

buf.resize_frames(11);
assert_eq!(buf.capacity(), 0);

buf.resize_channels(2);
assert_eq!(buf.capacity(), 22);

buf.resize_frames(12);
assert_eq!(buf.capacity(), 44);

buf.resize_frames(24);
assert_eq!(buf.capacity(), 44);

pub fn frames(&self) -> usize

Get the number of frames in the buffer.

Examples

let mut buf = audio::buf::Interleaved::<f32>::new();

assert_eq!(buf.frames(), 0);
buf.resize_frames(4);
assert_eq!(buf.frames(), 4);

pub fn channels(&self) -> usize

Get the number of channels in the buffer.

Examples

let mut buf = audio::buf::Interleaved::<f32>::new();

assert_eq!(buf.channels(), 0);
buf.resize_channels(2);
assert_eq!(buf.channels(), 2);

pub fn resize_channels(&mut self, channels: usize)

where T: Sample,

Resize to the given number of channels in use.

If the size of the buffer increases as a result, the new channels will be zeroed. If the size decreases, the channels that falls outside of the new size will be dropped.

Examples

let mut buf = audio::buf::Interleaved::<f32>::new();

assert_eq!(buf.channels(), 0);
assert_eq!(buf.frames(), 0);

buf.resize_channels(4);
buf.resize_frames(256);

assert_eq!(buf.channels(), 4);
assert_eq!(buf.frames(), 256);

pub fn resize_frames(&mut self, frames: usize)

where T: Sample,

Set the size of the buffer. The size is the size of each channel’s buffer.

If the size of the buffer increases as a result, the new regions in the frames will be zeroed. If the size decreases, the region will be left untouched. So if followed by another increase, the data will be “dirty”.

Examples

let mut buf = audio::buf::Interleaved::<f32>::new();

assert_eq!(buf.channels(), 0);
assert_eq!(buf.frames(), 0);

buf.resize_channels(4);
buf.resize_frames(256);

assert_eq!(buf.channels(), 4);
assert_eq!(buf.frames(), 256);

{
    let mut chan = buf.get_mut(1).unwrap();

    assert_eq!(chan.get(127), Some(0.0));
    *chan.get_mut(127).unwrap() = 42.0;
    assert_eq!(chan.get(127), Some(42.0));
}

buf.resize_frames(128);
assert_eq!(buf.sample(1, 127), Some(42.0));

buf.resize_frames(256);
assert_eq!(buf.sample(1, 127), Some(42.0));

buf.resize_channels(2);
assert_eq!(buf.sample(1, 127), Some(42.0));

buf.resize_frames(64);
assert_eq!(buf.sample(1, 127), None);

pub fn get_channel(&self, channel: usize) -> Option<InterleavedChannel<'_, T>>

Get a reference to a channel.

Examples

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 4);

for (c, s) in buf.get_mut(0).unwrap().iter_mut().zip(&[1.0, 2.0, 3.0, 4.0]) {
    *c = *s;
}

for (c, s) in buf.get_mut(1).unwrap().iter_mut().zip(&[5.0, 6.0, 7.0, 8.0]) {
    *c = *s;
}

assert_eq!(buf.get_channel(0).unwrap().iter().nth(2), Some(3.0));
assert_eq!(buf.get_channel(1).unwrap().iter().nth(2), Some(7.0));

pub fn sample(&self, channel: usize, frame: usize) -> Option<T>

where T: Copy,

Helper to access a single frame in a single channel.

Examples

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 256);

assert_eq!(buf.sample(1, 128), Some(0.0));
*buf.sample_mut(1, 128).unwrap() = 1.0;
assert_eq!(buf.sample(1, 128), Some(1.0));

pub fn get_mut( &mut self, channel: usize ) -> Option<InterleavedChannelMut<'_, T>>

Get a mutable reference to a channel.

Examples

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 4);

for (c, s) in buf.get_mut(0).unwrap().iter_mut().zip(&[1.0, 2.0, 3.0, 4.0]) {
    *c = *s;
}

for (c, s) in buf.get_mut(1).unwrap().iter_mut().zip(&[5.0, 6.0, 7.0, 8.0]) {
    *c = *s;
}

assert_eq!(buf.as_slice(), &[1.0, 5.0, 2.0, 6.0, 3.0, 7.0, 4.0, 8.0]);

pub fn sample_mut(&mut self, channel: usize, frame: usize) -> Option<&mut T>

Helper to access a single sample in a single channel mutably.

Examples

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 256);

assert_eq!(buf.sample(1, 128), Some(0.0));
*buf.sample_mut(1, 128).unwrap() = 1.0;
assert_eq!(buf.sample(1, 128), Some(1.0));

impl<T> Interleaved<T>

where T: Copy,

pub fn iter_channels(&self) -> IterChannels<'_, T>

Construct an iterator over all available channels.

Examples

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 4);

let mut it = buf.iter_channels_mut();

for (c, f) in it.next().unwrap().iter_mut().zip(&[1.0, 2.0, 3.0, 4.0]) {
    *c = *f;
}

for (c, f) in it.next().unwrap().iter_mut().zip(&[5.0, 6.0, 7.0, 8.0]) {
    *c = *f;
}

let channels = buf.iter_channels().collect::<Vec<_>>();
let left = channels[0].iter().collect::<Vec<_>>();
let right = channels[1].iter().collect::<Vec<_>>();

assert_eq!(left, &[1.0, 2.0, 3.0, 4.0]);
assert_eq!(right, &[5.0, 6.0, 7.0, 8.0]);

pub fn iter_channels_mut(&mut self) -> IterChannelsMut<'_, T>

Construct a mutable iterator over all available channels.

Examples

let mut buf = audio::buf::Interleaved::<f32>::with_topology(2, 4);

let mut it = buf.iter_channels_mut();

for (c, f) in it.next().unwrap().iter_mut().zip(&[1.0, 2.0, 3.0, 4.0]) {
    *c = *f;
}

for (c, f) in it.next().unwrap().iter_mut().zip(&[5.0, 6.0, 7.0, 8.0]) {
    *c = *f;
}

let channels = buf.iter_channels().collect::<Vec<_>>();
let left = channels[0].iter().collect::<Vec<_>>();
let right = channels[1].iter().collect::<Vec<_>>();

assert_eq!(left, &[1.0, 2.0, 3.0, 4.0]);
assert_eq!(right, &[5.0, 6.0, 7.0, 8.0]);

Trait Implementations

impl<T> Buf for Interleaved<T>

where T: Copy,

type Sample = T

The type of a single sample.

type Channel<'this> = InterleavedChannel<'this, <Interleaved<T> as Buf>::Sample> where Self::Sample: 'this

The type of the channel container.

type IterChannels<'this> = IterChannels<'this, <Interleaved<T> as Buf>::Sample> where Self::Sample: 'this

An iterator over available channels.

fn frames_hint(&self) -> Option<usize>

A typical number of frames for each channel in the buffer, if known.

fn channels(&self) -> usize

The number of channels in the buffer.

fn get_channel(&self, channel: usize) -> Option<Self::Channel<'_>>

Return a handler to the buffer associated with the channel.

fn iter_channels(&self) -> Self::IterChannels<'_>

Construct an iterator over all the channels in the audio buffer.

fn skip(self, n: usize) -> Skip<Self>

where Self: Sized,

Construct a wrapper around this buffer that skips the first n frames.

fn tail(self, n: usize) -> Tail<Self>

where Self: Sized,

Construct a wrapper around this buffer that skips to the last n frames.

fn limit(self, limit: usize) -> Limit<Self>

where Self: Sized,

Construct a wrapper around this buffer which stops after limit frames.

impl<T> BufMut for Interleaved<T>

where T: Copy,

type ChannelMut<'this> = InterleavedChannelMut<'this, <Interleaved<T> as Buf>::Sample> where Self::Sample: 'this

The type of the mutable channel container.

type IterChannelsMut<'this> = IterChannelsMut<'this, <Interleaved<T> as Buf>::Sample> where Self::Sample: 'this

A mutable iterator over available channels.

fn get_channel_mut(&mut self, channel: usize) -> Option<Self::ChannelMut<'_>>

Return a mutable handler to the buffer associated with the channel.

fn copy_channel(&mut self, from: usize, to: usize)

Copy one channel into another.

fn iter_channels_mut(&mut self) -> Self::IterChannelsMut<'_>

Construct a mutable iterator over available channels.

fn fill(&mut self, value: T)

where T: Copy,

Fill the entire buffer with the specified value

impl<T> Debug for Interleaved<T>

where T: Copy + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Interleaved<T>

fn default() -> Interleaved<T>

Returns the “default value” for a type.

impl<T> ExactSizeBuf for Interleaved<T>

where T: Copy,

fn frames(&self) -> usize

The number of frames in a buffer.

impl<T> Hash for Interleaved<T>

where T: Copy + Hash,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> InterleavedBuf for Interleaved<T>

where T: Copy,

type Sample = T

The type of a single sample.

fn as_interleaved(&self) -> &[Self::Sample]

Access the underlying raw interleaved buffer.

impl<T> InterleavedBufMut for Interleaved<T>

where T: Copy,

fn as_interleaved_mut(&mut self) -> &mut [Self::Sample]

Access the underlying interleaved mutable buffer.

fn as_interleaved_mut_ptr(&mut self) -> NonNull<Self::Sample>

Access a pointer to the underlying interleaved mutable buffer.

unsafe fn set_interleaved_topology(&mut self, channels: usize, frames: usize)

Specify the topology of the underlying interleaved buffer.

impl<'a, T> IntoIterator for &'a Interleaved<T>

where T: Copy,

type IntoIter = IterChannels<'a, T>

Which kind of iterator are we turning this into?

type Item = <<&'a Interleaved<T> as IntoIterator>::IntoIter as Iterator>::Item

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> Ord for Interleaved<T>

where T: Copy + Ord,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T> PartialEq for Interleaved<T>

where T: Copy + PartialEq,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Interleaved<T>

where T: Copy + PartialOrd,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> ResizableBuf for Interleaved<T>

where T: Sample,

fn try_reserve(&mut self, capacity: usize) -> bool

Ensure that the audio buffer has space for at least the given capacity of contiguous memory. The capacity is specified in number of Samples.

fn resize_frames(&mut self, frames: usize)

Resize the number of per-channel frames in the buffer.

fn resize_topology(&mut self, channels: usize, frames: usize)

Resize the buffer to match the given topology.

impl<T> UniformBuf for Interleaved<T>

where T: Copy,

type Frame<'this> = InterleavedFrame<'this, T> where Self: 'this

The type the channel assumes when coerced into a reference.

type IterFrames<'this> = InterleavedFramesIter<'this, T> where Self: 'this

A borrowing iterator over the channel.

fn get_frame(&self, frame: usize) -> Option<Self::Frame<'_>>

Get a single frame at the given offset.

fn iter_frames(&self) -> Self::IterFrames<'_>

Construct an iterator over all the frames in the audio buffer.

impl<T> Eq for Interleaved<T>

where T: Copy + Eq,