Struct soundio::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.

Methods

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 copy 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 Eq for ChannelLayout

impl From<ChannelLayout> for SoundIoChannelLayout

fn from(layout: ChannelLayout) -> SoundIoChannelLayout

Performs the conversion.

impl From<SoundIoChannelLayout> for ChannelLayout

fn from(layout: SoundIoChannelLayout) -> ChannelLayout

Performs the conversion.

impl PartialEq<ChannelLayout> 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

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

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

This method tests for !=.