Struct ChannelLayout

Source

pub struct ChannelLayout<'a>(/* private fields */);

Implementations§

Source §

impl<'a> ChannelLayout<'a>

Source

pub fn unspecified(channels: u32) -> Self

Get a new channel layout with an unspecified channel ordering.

Source

pub fn custom(channels: Vec<ChannelCustom>) -> Self

Source

pub fn default_for_channels(channels: u32) -> Self

Get the default channel layout for a given number of channels.

If no default layout exists for the given number of channels, an unspecified layout will be returned.

Source

pub fn standard_layouts() -> ChannelLayoutIter ⓘ

Get an iterator over all standard channel layouts.

Source

pub fn from_mask(layout_mask: ChannelLayoutMask) -> Option<Self>

Initialize a native channel layout from a bitmask indicating which channels are present.

This will return None for invalid bitmask values.

Source

pub fn from_string<S: AsRef<str>>(description: S) -> Option<Self>

Initialize a channel layout from a given string description.

This can be

the formal channel layout name (as returned by description),
one or more channel names concatenated with “+”, each optionally containing a custom name after an “@”, e.g. “FL@Left+FR@Right+LFE”,
a decimal or hexadecimal value of a native channel layout (e.g. “4” or “0x4”),
the number of channels with the default layout (e.g. “4c”),
the number of unordered channels (e.g. “4C” or “4 channels”) or
the ambisonic order followed by optional non-diegetic channels (e.g. “ambisonic 2+stereo”)

Source

pub fn order(&self) -> ChannelOrder

The ChannelOrder used in this layout.

Source

pub fn channels(&self) -> u32

The number of channels in this layout.

Source

pub fn mask(&self) -> Option<ChannelLayoutMask>

If order is Native: A ChannelLayoutMask containing the channels of this layout.

If order is Ambisonic: A ChannelLayoutMask containing the non-diegetic channels of this layout.

Otherwise: None.

Source

pub fn map(&self) -> Option<&[ChannelCustom]>

Returns the custom channel map for this layout.

None if order is not Custom.

Source

pub fn into_owned(self) -> AVChannelLayout

Extracts the owned AVChannelLayout.

Clones it if not already owned.

Source

pub fn as_ptr(&self) -> *const AVChannelLayout

Exposes a pointer to the contained AVChannelLayout for FFI purposes.

This is guaranteed to be a non-null pointer.

Source

pub fn description(&self) -> String

Get a human-readable String describing the channel layout properties.

The returned string will be in the same format that is accepted by from_string, allowing to rebuild the same channel layout (excluding opaque pointers).

Source

pub fn channel_from_index(&self, idx: u32) -> Channel

Get the channel with the given index in a channel layout.

Returns Channel::None when the index is invalid or the channel order is unspecified.

Source

pub fn index_from_channel(&self, channel: Channel) -> Option<u32>

Get the index of a given channel in a channel layout.

Source

pub fn index_from_string<S: AsRef<str>>(&self, name: S) -> Option<u32>

Get the index in a channel layout of a channel described by the given string.

Returns the first match. Accepts channel names in the same format as from_string.

Source

pub fn channel_from_string<S: AsRef<str>>(&self, name: S) -> Channel

Get a channel described by the given string.

Accepts channel names in the same format as from_string.

Returns Channel::None when the string is invalid or the channel order is unspecified.

Source

pub fn subset(&self, mask: ChannelLayoutMask) -> ChannelLayoutMask

Find out what channels from a given set are present in this layout, without regard for their positions.

Source

pub fn is_valid(&self) -> bool

Check whether this layout is valid (i.e. can describe audio data).

Source

pub fn retype( &mut self, target: ChannelRetypeTarget, ) -> Result<ChannelRetypeKind, Error>

Change the ChannelOrder of this channel layout. If the current layout is borrowed, calling this function will clone the contained AVChannelLayout.

This change can be lossless or lossy:

A lossless conversion keeps all Channel designations and names intact.
A lossy conversion might lose Channel designations and names depending on the targeted channel order.

§Supported conversions

Any -> Custom: Always possible, always lossless.
Any -> Unspecified: Always possible, only lossless if every channel is designated Unknown and no channel names are used.
Custom -> Ambisonic: Possible if it contains ambisonic channels with optional non-diegetic channels in the end. Lossless only if no channels have custom names.
Custom -> Native: Possible if it contains native channels in native order. Lossless only if no channels have custom names.

§Returns

Ok if the conversion succeeded. The contained ChannelRetypeKind indicates whether the conversion was lossless or not.
Err if the conversion failed. The original layout is untouched in this case.

Source §