Struct ChannelLayout

pub struct ChannelLayout {
    pub name: String,
    pub channels: Vec<ChannelId>,
}

A ChannelLayout specifies a number of channels, and the ChannelId of each channel. A ChannelLayout also has a name, though it is really only for display purposes and does not affect execution at any point.

For example, the built-in stereo layout that is returned by ChannelLayout::get_builtin(ChannelLayoutId::Stereo)` is equal to:

soundio::ChannelLayout {
	name: "Stereo".to_string(),
	channels: vec![soundio::ChannelId::FrontLeft, soundio::ChannelId::FrontRight],
};

Fields

name: String

The name of the layout. This is mostly useful when enumerating built-in layouts.

channels: Vec<ChannelId>

A list of channels. Order is significant.

Implementations

impl ChannelLayout

pub fn get_all_builtin() -> Vec<ChannelLayout>

Get all of the built-in layouts.

Examples

let builtins = soundio::ChannelLayout::get_all_builtin();
println!("{:?}", builtins);

pub fn get_builtin(id: ChannelLayoutId) -> ChannelLayout

Get a specific built-in layout. See ChannelLayoutId for a list of built-in layouts.

Examples

let stereo_layout = soundio::ChannelLayout::get_builtin(soundio::ChannelLayoutId::Stereo);
assert_eq!(stereo_layout.channels.len(), 2);

pub fn get_default(channel_count: i32) -> ChannelLayout

Get the default layout for the given number of channels.

Examples

let default_stereo = soundio::ChannelLayout::get_default(2);
assert_eq!(default_stereo.name, "Stereo".to_string());

pub fn best_matching_channel_layout( preferred_layouts: &[ChannelLayout], available_layouts: &[ChannelLayout], ) -> Option<ChannelLayout>

Iterates over preferred_layouts. Returns the first channel layout in preferred_layouts which matches (using ==) one of the channel layouts in available_layouts. Returns None if none matches.

Examples

let my_device: Device = ...;
let preferred_layouts = vec![ChannelLayout::get_builtin(ChannelLayoutId::Stereo),
                             ChannelLayout::get_builtin(ChannelLayoutId::Mono)];

let available_layouts = my_device.layouts();

let best_layout = ChannelLayout::best_matching_channel_layout(preferred_layouts, available_layouts);

if best_layout == None {
    panic!("Stereo and mono not available! What *is* this device??");
}
let Some(best_layout) = best_layout;

pub fn find_channel(&self, channel: ChannelId) -> Option<usize>

Find the given channel in a layout and return its index, or None if it wasn’t found.

Examples

let layout = soundio::ChannelLayout::get_builtin(soundio::ChannelLayoutId::Stereo);
let left_idx = layout.find_channel(soundio::ChannelId::FrontLeft);
let center_idx = layout.find_channel(soundio::ChannelId::FrontCenter);

assert_eq!(left_idx, Some(0));
assert_eq!(center_idx, None);

pub fn detect_builtin(&mut self) -> bool

Populate the name field with the built-in name if this layout matches one of the built-in layouts. Returns true if it did.

Examples

let mut layout = soundio::ChannelLayout {
    name: "".to_string(),
    channels: vec![soundio::ChannelId::FrontLeft, soundio::ChannelId::FrontRight],
};

assert_eq!(layout.detect_builtin(), true);
assert_eq!(layout.name, "Stereo".to_string());

pub fn sort(layouts: &mut [ChannelLayout])

Sort a set of ChannelLayouts by channel count, descending. The content of the channels and the layout name are ignored; only the number of channels is significant.

Examples

let mut layouts = soundio::ChannelLayout::get_all_builtin();

soundio::ChannelLayout::sort(&mut layouts);

for i in 0..layouts.len()-1 {
    assert!(layouts[i+1].channels.len() >= layouts[i].channels.len());
}

Trait Implementations

impl Clone for ChannelLayout

fn clone(&self) -> ChannelLayout

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ChannelLayout

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

Formats the value using the given formatter.

impl From<ChannelLayout> for SoundIoChannelLayout

fn from(layout: ChannelLayout) -> SoundIoChannelLayout

Converts to this type from the input type.

impl From<SoundIoChannelLayout> for ChannelLayout

fn from(layout: SoundIoChannelLayout) -> ChannelLayout

Converts to this type from the input type.

impl PartialEq for ChannelLayout

Equality testing for layouts. The channels must be the same IDs and in the same order. The layout name is ignored.

Examples

let layout_a = soundio::ChannelLayout {
    name: "unimportant".to_string(),
    channels: vec![soundio::ChannelId::FrontLeft, soundio::ChannelId::FrontRight],
};
let layout_b = soundio::ChannelLayout {
    name: "doesn't matter".to_string(),
    channels: vec![soundio::ChannelId::FrontLeft, soundio::ChannelId::FrontRight],
};

assert_eq!(layout_a, layout_b);

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl Eq for ChannelLayout