Struct rotary::interleaved::Interleaved

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

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 buffer = rotary::Interleaved::<f32>::with_topology(2, 4);

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

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

assert_eq!(buffer.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 mut buffer = rotary::Interleaved::<f32>::new();

assert_eq!(buffer.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 mut buffer = rotary::Interleaved::<f32>::with_topology(4, 256);

assert_eq!(buffer.frames(), 256);
assert_eq!(buffer.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 mut buffer = rotary::interleaved![[2.0; 256]; 4];

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

for chan in &buffer {
    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 mut buffer = rotary::Interleaved::from_frames([1.0, 2.0, 3.0, 4.0], 4);

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

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

Take ownership of the backing vector.

Examples

let mut buffer = rotary::Interleaved::<f32>::with_topology(2, 4);

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

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

buffer.resize(3);

assert_eq!(buffer.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 mut buffer = rotary::Interleaved::<f32>::with_topology(2, 4);

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

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

buffer.resize(3);

assert_eq!(buffer.as_slice(), &[1.0, 1.0, 2.0, 2.0, 3.0, 3.0])

pub fn frames(&self) -> usize

Get the number of frames in the channels of an audio buffer.

Examples

let mut buffer = rotary::Interleaved::<f32>::new();

assert_eq!(buffer.frames(), 0);
buffer.resize(256);
assert_eq!(buffer.frames(), 256);

pub fn channels(&self) -> usize

Get the number of channels in the buffer.

Examples

let mut buffer = rotary::Interleaved::<f32>::new();

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

pub fn interleaved_skip(&self, skip: usize) -> Interleaved<&[T]>

Offset the interleaved buffer and return a wrapped buffer.

This is provided as a special operation for this buffer kind, because it can be done more efficiently than what is available through Buf::skip.

pub fn interleaved_skip_mut(&mut self, skip: usize) -> Interleaved<&mut [T]>

Offset the interleaved buffer and return a mutable wrapped buffer.

This is provided as a special operation for this buffer kind, because it can be done more efficiently than what is available through Buf::skip.

Examples

use rotary::{Buf as _, BufMut as _};

let mut buffer = rotary::Interleaved::with_topology(2, 4);

buffer.interleaved_skip_mut(2).channel_mut(0).copy_from_slice(&[1.0, 1.0]);

assert_eq!(buffer.as_slice(), &[0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0])

pub fn interleaved_limit(&self, limit: usize) -> Interleaved<&[T]>

Limit the interleaved buffer and return a wrapped buffer.

This is provided as a special operation for this buffer kind, because it can be done more efficiently than what is available through Buf::limit.

Examples

use rotary::{Buf as _, BufMut as _};

let from = rotary::interleaved![[1.0f32; 4]; 2];
let mut to = rotary::Interleaved::<f32>::with_topology(2, 4);

to.channel_mut(0).copy_from(from.interleaved_limit(2).channel(0));
assert_eq!(to.as_slice(), &[1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);

pub fn interleaved_limit_mut(&mut self, limit: usize) -> Interleaved<&mut [T]>

Limit the interleaved buffer and return a mutable wrapped buffer.

This is provided as a special operation for this buffer kind, because it can be done more efficiently than what is available through Buf::limit.

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 buffer = rotary::Interleaved::<f32>::new();

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

buffer.resize_channels(4);
buffer.resize(256);

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

pub fn resize(&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 buffer = rotary::Interleaved::<f32>::new();

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

buffer.resize_channels(4);
buffer.resize(256);

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

{
    let mut chan = buffer.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));
}

buffer.resize(128);
assert_eq!(buffer.frame(1, 127), Some(42.0));

buffer.resize(256);
assert_eq!(buffer.frame(1, 127), Some(42.0));

buffer.resize_channels(2);
assert_eq!(buffer.frame(1, 127), Some(42.0));

buffer.resize(64);
assert_eq!(buffer.frame(1, 127), None);

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

Get a reference to a channel.

Examples

let mut buffer = rotary::Interleaved::<f32>::with_topology(2, 4);

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

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

assert_eq!(buffer.get(0).unwrap().iter().nth(2), Some(&3.0));
assert_eq!(buffer.get(1).unwrap().iter().nth(2), Some(&7.0));

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

Helper to access a single frame in a single channel.

Examples

let mut buffer = rotary::Interleaved::<f32>::with_topology(2, 256);

assert_eq!(buffer.frame(1, 128), Some(0.0));
*buffer.frame_mut(1, 128).unwrap() = 1.0;
assert_eq!(buffer.frame(1, 128), Some(1.0));

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

Get a mutable reference to a channel.

Examples

let mut buffer = rotary::Interleaved::<f32>::with_topology(2, 4);

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

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

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

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

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

Examples

let mut buffer = rotary::Interleaved::<f32>::with_topology(2, 256);

assert_eq!(buffer.frame(1, 128), Some(0.0));
*buffer.frame_mut(1, 128).unwrap() = 1.0;
assert_eq!(buffer.frame(1, 128), Some(1.0));

pub fn iter(&self) -> Iter<'_, T>

Construct an iterator over all available channels.

Examples

let mut buffer = rotary::Interleaved::<f32>::with_topology(2, 4);

let mut it = buffer.iter_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 = buffer.iter().collect::<Vec<_>>();
let left = channels[0].iter().copied().collect::<Vec<_>>();
let right = channels[1].iter().copied().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_mut(&mut self) -> IterMut<'_, T>

Construct a mutable iterator over all available channels.

Examples

let mut buffer = rotary::Interleaved::<f32>::with_topology(2, 4);

let mut it = buffer.iter_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;
}

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

Trait Implementations

impl<T> Buf<T> for Interleaved<T>

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

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

fn channels(&self) -> usize

The number of channels in the buffer.

fn channel(&self, channel: usize) -> Channel<'_, T>

Return a handler to the buffer associated with the channel.

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

Construct a new buffer where n frames are skipped.

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

Construct a new buffer where n frames are skipped.

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

Limit the channel buffer to limit number of frames.

pub fn chunk(self, n: usize, len: usize) -> Chunk<Self>

Construct a range of frames corresponds to the chunk with len and position n.

impl<T> BufMut<T> for Interleaved<T>

fn channel_mut(&mut self, channel: usize) -> ChannelMut<'_, T>

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

impl<T> Debug for Interleaved<T> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<T> Eq for Interleaved<T> where
    T: Eq, 

impl<T> ExactSizeBuf for Interleaved<T>

fn frames(&self) -> usize

The number of frames in a buffer.

impl<T> Hash for Interleaved<T> where
    T: Hash, 

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

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

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

type Item = <Self::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<'a, T> IntoIterator for &'a mut Interleaved<T>

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

type Item = <Self::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: Ord, 

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T> PartialEq<Interleaved<T>> for Interleaved<T> where
    T: PartialEq, 

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

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<Interleaved<T>> for Interleaved<T> where
    T: PartialOrd, 

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub 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 resize(&mut self, frames: usize)

Resize the number of frames in the buffer.

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

Resize the buffer to match the given topology.