Struct Planar 

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

A planar / separate-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 = Planar::new(2, 3);
let mut block = Planar::from_block(&block);

block.channel_mut(0).fill(0.0);
block.channel_mut(1).fill(1.0);

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

Implementations

impl<S: Sample + Default> Planar<S>

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

Creates a new audio block with the specified dimensions.

Allocates memory for a new planar 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.

impl<S: Sample> Planar<S>

pub fn from_slice<V: AsRef<[S]>>(data: &[V]) -> Self

Creates a new audio block from a slice of planar audio data.

Parameters

• data - The slice containing planar audio samples (one slice per channel)

Panics

Panics if the channel slices have different lengths.

pub fn from_slice_limited<V: AsRef<[S]>>( data: &[V], num_channels_visible: u16, num_frames_visible: usize, ) -> Self

Creates a new audio block from a slice with limited visibility.

This function allows creating a view that exposes only a subset of the allocated channels and frames, which is useful for working with a logical section of a larger buffer.

Parameters

• data - The slice containing planar audio samples (one slice per channel)
• num_channels_visible - Number of audio channels to expose in the view
• num_frames_visible - Number of audio frames to expose in the view

Panics

• Panics if num_channels_visible exceeds the number of channels in data
• Panics if num_frames_visible exceeds the length of any channel buffer
• Panics if channel slices have different lengths

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

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

Converts any AudioBlock implementation to a planar 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

pub fn channel(&self, channel: u16) -> &[S]

Returns a slice for a single channel.

Panics

Panics if channel index is out of bounds.

pub fn channel_mut(&mut self, channel: u16) -> &mut [S]

Returns a mutable slice for a single channel.

Panics

Panics if channel index is out of bounds.

pub fn channels(&self) -> impl ExactSizeIterator<Item = &[S]>

Returns an iterator over all channels in the block.

Each channel is represented as a slice of samples.

pub fn channels_mut(&mut self) -> impl ExactSizeIterator<Item = &mut [S]>

Returns a mutable iterator over all channels in the block.

Each channel is represented as a mutable slice of samples.

pub fn raw_data(&self) -> &[Box<[S]>]

Provides direct access to the underlying memory.

This function gives access to all allocated data, including any reserved capacity beyond the visible range.

pub fn raw_data_mut(&mut self) -> &mut [Box<[S]>]

Provides direct access to the underlying memory.

This function gives access to all allocated data, including any reserved capacity beyond the visible range.

pub fn view(&self) -> PlanarView<'_, S, Box<[S]>>

pub fn view_mut(&mut self) -> PlanarViewMut<'_, S, Box<[S]>>

Trait Implementations

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

type PlanarView = Box<[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 layout(&self) -> BlockLayout

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

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

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

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

Returns an iterator over all samples in the specified channel.

fn channels_iter( &self, ) -> impl ExactSizeIterator<Item = impl ExactSizeIterator<Item = &S>>

Returns an iterator that yields an iterator for each channel.

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

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

fn frames_iter( &self, ) -> impl ExactSizeIterator<Item = impl ExactSizeIterator<Item = &S>>

Returns an iterator that yields an iterator for each frame.

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

Creates a non-owning view of this audio block.

fn as_planar_view(&self) -> Option<PlanarView<'_, S, Self::PlanarView>>

Attempts to downcast this generic audio block to a concrete planar view. This enables access to frame slices and the underlying raw data.

fn as_interleaved_view(&self) -> Option<InterleavedView<'_, S>>

Attempts to downcast this generic audio block to a concrete interleaved view. This enables access to frame slices and the underlying raw data.

fn as_sequential_view(&self) -> Option<SequentialView<'_, S>>

Attempts to downcast this generic audio block to a concrete sequential view. This enables access to frame slices and the underlying raw data.

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

type PlanarViewMut = Box<[S]>

fn set_num_channels_visible(&mut self, num_channels: u16)

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

fn set_num_frames_visible(&mut self, num_frames: usize)

Sets the visible 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_iter_mut( &mut self, channel: u16, ) -> impl ExactSizeIterator<Item = &mut S>

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

fn channels_iter_mut( &mut self, ) -> impl ExactSizeIterator<Item = impl ExactSizeIterator<Item = &mut S>>

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

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

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

fn frames_iter_mut( &mut self, ) -> impl ExactSizeIterator<Item = impl ExactSizeIterator<Item = &mut S>>

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

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

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

fn as_planar_view_mut( &mut self, ) -> Option<PlanarViewMut<'_, S, Self::PlanarViewMut>>

Attempts to downcast this generic audio block to a concrete planar view. This enables access to frame slices and the underlying raw data.

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

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

fn as_interleaved_view_mut(&mut self) -> Option<InterleavedViewMut<'_, S>>

Attempts to downcast this generic audio block to a concrete interleaved view. This enables access to frame slices and the underlying raw data.

fn as_sequential_view_mut(&mut self) -> Option<SequentialViewMut<'_, S>>

Attempts to downcast this generic audio block to a concrete sequential view. This enables access to frame slices and the underlying raw data.

impl<S: Clone + Sample> Clone for Planar<S>

fn clone(&self) -> Planar<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Sample + Debug> Debug for Planar<S>

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

Formats the value using the given formatter.

impl<S: Default + Sample> Default for Planar<S>

fn default() -> Planar<S>

Returns the “default value” for a type.