pub struct Format { /* private fields */ }Expand description
PCM audio stream format.
Holds the parameters that the audio engine negotiates with an
APO: format tag, channel count, sample rate, bit depth, and (for
the extensible variant) channel mask plus sub-format GUID. The
derived fields (block_align, avg_bytes_per_sec) are computed
at construction from the inputs.
Implementations§
Source§impl Format
impl Format
Sourcepub const fn from_raw(
format_tag: u16,
channels: u16,
samples_per_sec: u32,
bits_per_sample: u16,
) -> Self
pub const fn from_raw( format_tag: u16, channels: u16, samples_per_sec: u32, bits_per_sample: u16, ) -> Self
Construct a format directly from its fields.
Prefer the typed constructors (pcm_int16, pcm_float32,
…) when modelling a standard PCM stream. This raw
constructor is intended for round-tripping through
WAVEFORMATEX and for tests. Initialises the extension
fields (valid_bits_per_sample, channel_mask) to zero.
Sourcepub const fn pcm_int16(sample_rate: u32, channels: u16) -> Self
pub const fn pcm_int16(sample_rate: u32, channels: u16) -> Self
16-bit signed integer PCM (WAVE_FORMAT_PCM).
Sourcepub const fn pcm_int24(sample_rate: u32, channels: u16) -> Self
pub const fn pcm_int24(sample_rate: u32, channels: u16) -> Self
24-bit signed integer PCM packed into 3-byte containers
(WAVE_FORMAT_PCM).
Sourcepub const fn pcm_int32(sample_rate: u32, channels: u16) -> Self
pub const fn pcm_int32(sample_rate: u32, channels: u16) -> Self
32-bit signed integer PCM (WAVE_FORMAT_PCM).
Sourcepub const fn pcm_float32(sample_rate: u32, channels: u16) -> Self
pub const fn pcm_float32(sample_rate: u32, channels: u16) -> Self
32-bit IEEE float PCM (WAVE_FORMAT_IEEE_FLOAT). This is the
canonical format negotiated between the Windows audio engine
and most APOs.
Sourcepub const fn pcm_float64(sample_rate: u32, channels: u16) -> Self
pub const fn pcm_float64(sample_rate: u32, channels: u16) -> Self
64-bit IEEE float PCM (WAVE_FORMAT_IEEE_FLOAT).
Sourcepub const fn format_tag(&self) -> u16
pub const fn format_tag(&self) -> u16
wFormatTag field — one of WAVE_FORMAT_PCM,
WAVE_FORMAT_IEEE_FLOAT, or WAVE_FORMAT_EXTENSIBLE.
Sourcepub const fn sample_rate(&self) -> u32
pub const fn sample_rate(&self) -> u32
nSamplesPerSec field, in hertz.
Sourcepub const fn bits_per_sample(&self) -> u16
pub const fn bits_per_sample(&self) -> u16
wBitsPerSample field.
Sourcepub const fn block_align(&self) -> u16
pub const fn block_align(&self) -> u16
nBlockAlign field — bytes per audio frame (one sample
across all channels).
Sourcepub const fn avg_bytes_per_sec(&self) -> u32
pub const fn avg_bytes_per_sec(&self) -> u32
nAvgBytesPerSec field — sample_rate * block_align.
Sourcepub const fn is_int_pcm(&self) -> bool
pub const fn is_int_pcm(&self) -> bool
true if this is an integer PCM stream.
Sourcepub const fn is_extensible(&self) -> bool
pub const fn is_extensible(&self) -> bool
true if this is the extensible variant — the wire format
uses WAVE_FORMAT_EXTENSIBLE and cbSize == 22 to surface
channel_mask and valid_bits_per_sample over the wire.
The logical PCM / float distinction stays in format_tag
and resolves to the sub-format GUID at conversion time.
Sourcepub const fn channel_mask(&self) -> u32
pub const fn channel_mask(&self) -> u32
WAVEFORMATEXTENSIBLE::dwChannelMask value (zero if
unspecified — the audio engine picks a default for the
channel count).
Sourcepub const fn valid_bits_per_sample(&self) -> u16
pub const fn valid_bits_per_sample(&self) -> u16
WAVEFORMATEXTENSIBLE::Samples::wValidBitsPerSample —
effective precision when the container is wider than the
sample (e.g. 24-bit-in-32-bit). Zero means “same as
bits_per_sample”.
Sourcepub const fn with_extensible(self) -> Self
pub const fn with_extensible(self) -> Self
Promote a base WAVEFORMATEX-style format to the extensible
wire variant.
Flips the extensible flag to true and fills in the
channel-position mask via default_channel_mask when
channel_mask is currently zero. The format_tag field
stays as WAVE_FORMAT_PCM / WAVE_FORMAT_IEEE_FLOAT so
the sub-format GUID can still be resolved; only the
over-the-wire wFormatTag changes (to
WAVE_FORMAT_EXTENSIBLE).
Sourcepub const fn with_channel_mask(self, mask: u32) -> Self
pub const fn with_channel_mask(self, mask: u32) -> Self
Override channel_mask. Useful for declaring custom
channel layouts; pass zero to clear back to the default.
Sourcepub const fn with_valid_bits_per_sample(self, bits: u16) -> Self
pub const fn with_valid_bits_per_sample(self, bits: u16) -> Self
Override valid_bits_per_sample. Pass zero to clear back
to “same as bits_per_sample”.