Struct audio::buf::dynamic::Dynamic

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

A dynamically sized, multi-channel 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.

This kind of buffer stores each channel in its own heap-allocated slice of memory, meaning they can be manipulated more cheaply independently of each other than say Interleaved or Sequential. These would have to re-organize every constituent channel when resizing, while Dynamic generally only requires growing and shrinking of a memory region.

This kind of buffer is a good choice if you need to resize_frames frequently.

Implementations

impl<T> Dynamic<T>

pub fn new() -> Self

Construct a new empty audio buffer.

Examples

let buf = audio::buf::Dynamic::<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::Dynamic::<f32>::with_topology(4, 256);

assert_eq!(buf.frames(), 256);
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 audio buffer from a fixed-size array.

See dynamic!.

Examples

let buf = audio::buf::Dynamic::<f32>::from_array([[2.0; 256]; 4]);

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

for chan in &buf {
    assert_eq!(chan.as_ref(), [2.0; 256]);
}

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

where T: Copy,

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

See dynamic!.

Examples

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

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

pub fn frames(&self) -> usize

Get how many frames there are in the buffer.

Examples

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

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

pub fn channels(&self) -> usize

Get how many channels there are in the buffer.

Examples

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

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

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

Construct a mutable iterator over all available channels.

Examples

use rand::Rng;

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

let all_zeros = vec![0.0; 256];

for chan in buf.iter_channels() {
    assert_eq!(chan.as_ref(), &all_zeros[..]);
}

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

Construct a mutable iterator over all available channels.

Examples

use rand::Rng;

let mut buf = audio::buf::Dynamic::<f32>::with_topology(4, 256);
let mut rng = rand::thread_rng();

for mut chan in buf.iter_channels_mut() {
    rng.fill(chan.as_mut());
}

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::Dynamic::<f32>::new();

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

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

assert_eq!(buf[1][128], 0.0);
buf[1][128] = 42.0;

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

Decreasing and increasing the size will not touch a buffer that has already been allocated.

assert_eq!(buf[1][128], 0.0);
buf[1][128] = 42.0;

buf.resize_frames(64);
assert!(buf[1].get(128).is_none());

buf.resize_frames(256);
assert_eq!(buf[1][128], 42.0);

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

where T: Sample,

Set the 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::Dynamic::<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 get_channel(&self, channel: usize) -> Option<LinearChannel<'_, T>>

Get a reference to the buffer of the given channel.

Examples

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

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

let expected = vec![0.0; 256];

assert_eq!(buf.get_channel(0).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(1).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(2).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(3).unwrap(), &expected[..]);
assert!(buf.get_channel(4).is_none());

pub fn get_or_default(&mut self, channel: usize) -> &[T]

where T: Sample,

Get the given channel or initialize the buffer with the default value.

Examples

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

buf.resize_frames(256);

let expected = vec![0f32; 256];

assert_eq!(buf.get_or_default(0), &expected[..]);
assert_eq!(buf.get_or_default(1), &expected[..]);

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

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

Get a mutable reference to the buffer of the given channel.

Examples

use rand::Rng;

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

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

let mut rng = rand::thread_rng();

if let Some(mut left) = buf.get_mut(0) {
    rng.fill(left.as_mut());
}

if let Some(mut right) = buf.get_mut(1) {
    rng.fill(right.as_mut());
}

pub fn get_or_default_mut(&mut self, channel: usize) -> &mut [T]

where T: Sample,

Get the given channel or initialize the buffer with the default value.

If a channel that is out of bound is queried, the buffer will be empty.

Examples

use rand::Rng;

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

buf.resize_frames(256);

let mut rng = rand::thread_rng();

rng.fill(buf.get_or_default_mut(0));
rng.fill(buf.get_or_default_mut(1));

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

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

Convert into a vector of vectors.

This is provided for the Dynamic type because it’s a very cheap oepration due to its memory topology. No copying of the underlying buffers is necessary.

Examples

let mut buf = audio::buf::Dynamic::<f32>::new();
buf.resize_channels(4);
buf.resize_frames(512);

let expected = vec![0.0; 512];

let buffers = buf.into_vectors();
assert_eq!(buffers.len(), 4);
assert_eq!(buffers[0], &expected[..]);
assert_eq!(buffers[1], &expected[..]);
assert_eq!(buffers[2], &expected[..]);
assert_eq!(buffers[3], &expected[..]);

pub fn into_vectors_if( self, condition: impl FnMut(usize) -> bool ) -> Vec<Vec<T>>

Convert into a vector of vectors using a condition.

This is provided for the Dynamic type because it’s a very cheap oepration due to its memory topology. No copying of the underlying buffers is necessary.

Channels which does not match the condition will be filled with an empty vector.

Examples

let mut buf = audio::buf::Dynamic::<f32>::new();
buf.resize_channels(4);
buf.resize_frames(512);

let expected = vec![0.0; 512];

let buffers = buf.into_vectors_if(|n| n != 1);
assert_eq!(buffers.len(), 4);
assert_eq!(buffers[0], &expected[..]);
assert_eq!(buffers[1], &[][..]);
assert_eq!(buffers[2], &expected[..]);
assert_eq!(buffers[3], &expected[..]);

Trait Implementations

impl<T> Buf for Dynamic<T>

where T: Copy,

type Sample = T

The type of a single sample.

type Channel<'this> = LinearChannel<'this, <Dynamic<T> as Buf>::Sample> where Self::Sample: 'this

The type of the channel container.

type IterChannels<'this> = IterChannels<'this, T> 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 Dynamic<T>

where T: Copy,

type ChannelMut<'this> = LinearChannelMut<'this, <Dynamic<T> as Buf>::Sample> where Self: 'this

The type of the mutable channel container.

type IterChannelsMut<'this> = IterChannelsMut<'this, T> where Self: '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.

impl<T> Debug for Dynamic<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> Default for Dynamic<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for Dynamic<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> ExactSizeBuf for Dynamic<T>

where T: Copy,

fn frames(&self) -> usize

The number of frames in a buffer.

impl<T, const F: usize, const C: usize> From<[[T; F]; C]> for Dynamic<T>

where T: Copy,

Allocate an audio buffer from a fixed-size array.

See dynamic!.

fn from(channels: [[T; F]; C]) -> Self

Converts to this type from the input type.

impl<T> Hash for Dynamic<T>

where T: 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> Index<usize> for Dynamic<T>

type Output = [T]

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<usize> for Dynamic<T>

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

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

type IntoIter = IterChannels<'a, T>

Which kind of iterator are we turning this into?

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

type IntoIter = IterChannelsMut<'a, T>

Which kind of iterator are we turning this into?

type Item = <<&'a mut Dynamic<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 Dynamic<T>

where T: 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 Dynamic<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 ==.

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

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 Dynamic<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> Eq for Dynamic<T>

where T: Eq,

impl<T> Send for Dynamic<T>

where T: Send,

impl<T> Sync for Dynamic<T>

where T: Sync,