Struct Stacked

pub struct Stacked<S: Sample> { /* private fields */ }

A stacked / seperate-channel audio block that owns its data.

• Layout: [[ch0, ch0, ch0], [ch1, ch1, ch1]]
• Interpretation: Each channel has its own separate buffer or array.
• Terminology: Also described as “planar” or “channels first” though more specifically it’s channel-isolated buffers.
• Usage: Very common in real-time DSP, as it simplifies memory access and can improve SIMD/vectorization efficiency.

Example

use audio_blocks::*;

let block = Stacked::new(2, 3);
let mut block = Stacked::from_block(&block);

block.channel_mut(0).for_each(|v| *v = 0.0);
block.channel_mut(1).for_each(|v| *v = 1.0);

assert_eq!(block.raw_data(Some(0)), &[0.0, 0.0, 0.0]);
assert_eq!(block.raw_data(Some(1)), &[1.0, 1.0, 1.0]);

Implementations

impl<S: Sample> Stacked<S>

pub fn new(num_channels: u16, num_frames: usize) -> Self

Creates a new Stacked audio block with the specified dimensions.

Allocates memory for a new stacked audio block with exactly the specified number of channels and frames. The block is initialized with the default value for the sample type.

Do not use in real-time processes!

Arguments

• num_channels - The number of audio channels
• num_frames - The number of frames per channel

Panics

Panics if the multiplication of num_channels and num_frames would overflow a usize.

pub fn from_block(block: &impl AudioBlock<S>) -> Self

Creates a new Stacked audio block by copying data from another AudioBlock.

Converts any AudioBlock implementation to a stacked format by iterating through each channel of the source block and copying its samples. The new block will have the same dimensions as the source block.

Warning

This function allocates memory and should not be used in real-time audio processing contexts.

Arguments

• block - The source audio block to copy data from

Trait Implementations

impl<S: Sample> AudioBlock<S> for Stacked<S>

fn num_channels(&self) -> u16

Returns the number of active audio channels.

fn num_frames(&self) -> usize

Returns the number of audio frames (samples per channel).

fn num_channels_allocated(&self) -> u16

Returns the total number of channels allocated in memory.

fn num_frames_allocated(&self) -> usize

Returns the total number of frames allocated in memory.

fn sample(&self, channel: u16, frame: usize) -> S

Returns the sample value at the specified channel and frame position.

fn channel(&self, channel: u16) -> impl Iterator<Item = &S>

Returns an iterator over all samples in the specified channel.

fn channels(&self) -> impl Iterator<Item = impl Iterator<Item = &S> + '_> + '_

Returns an iterator that yields iterators for each channel.

fn channel_slice(&self, channel: u16) -> Option<&[S]>

Returns a slice of the data in case of sequential or stacked layout.

fn frame(&self, frame: usize) -> impl Iterator<Item = &S>

Returns an iterator over all samples in the specified frame (across all channels).

fn frames(&self) -> impl Iterator<Item = impl Iterator<Item = &S> + '_> + '_

Returns an iterator that yields iterators for each frame.

fn view(&self) -> impl AudioBlock<S>

Creates a non-owning view of this audio block.

fn layout(&self) -> BlockLayout

Returns the memory layout of this audio block (interleaved, sequential, or stacked).

fn raw_data(&self, stacked_ch: Option<u16>) -> &[S]

Provides direct access to the underlying memory as a slice.

fn frame_slice(&self, frame: usize) -> Option<&[S]>

Returns a slice of the data in case of interleaved memory layout.

impl<S: Sample> AudioBlockMut<S> for Stacked<S>

fn set_active_num_channels(&mut self, num_channels: u16)

Sets the active size of the audio block to the specified number of channels.

fn set_active_num_frames(&mut self, num_frames: usize)

Sets the active size of the audio block to the specified number of frames.

fn sample_mut(&mut self, channel: u16, frame: usize) -> &mut S

Returns a mutable reference to the sample at the specified channel and frame position.

fn channel_mut(&mut self, channel: u16) -> impl Iterator<Item = &mut S>

Returns a mutable iterator over all samples in the specified channel.

fn channels_mut( &mut self, ) -> impl Iterator<Item = impl Iterator<Item = &mut S> + '_> + '_

Returns a mutable iterator that yields mutable iterators for each channel.

fn channel_slice_mut(&mut self, channel: u16) -> Option<&mut [S]>

Returns a slice of the data in case of sequential or stacked layout.

fn frame_mut(&mut self, frame: usize) -> impl Iterator<Item = &mut S>

Returns a mutable iterator over all samples in the specified frame (across all channels).

fn frames_mut( &mut self, ) -> impl Iterator<Item = impl Iterator<Item = &mut S> + '_> + '_

Returns a mutable iterator that yields mutable iterators for each frame.

fn view_mut(&mut self) -> impl AudioBlockMut<S>

Creates a non-owning mutable view of this audio block.

fn raw_data_mut(&mut self, stacked_ch: Option<u16>) -> &mut [S]

Provides direct mutable access to the underlying memory as a slice.

fn set_active_size(&mut self, num_channels: u16, num_frames: usize)

Sets the active size of the audio block to the specified number of channels and frames.

fn frame_slice_mut(&mut self, frame: usize) -> Option<&mut [S]>

Returns a slice of the data in case of interleaved memory layout.