From 8615160344bbee59d08d23bd7c88895a9c526a2a Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Sun, 12 May 2024 17:28:53 +0200 Subject: [PATCH] doc: improvements for SampleFormat (#885) * doc: fix SampleFormat inconsistencies * doc: add more documentation for SampleFormat --- src/samples_formats.rs | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/src/samples_formats.rs b/src/samples_formats.rs index 3973b18de..bf2197f91 100644 --- a/src/samples_formats.rs +++ b/src/samples_formats.rs @@ -4,47 +4,61 @@ use wasm_bindgen::prelude::*; pub use dasp_sample::{FromSample, Sample, I24, I48, U24, U48}; -/// Format that each sample has. +/// Format that each sample has. Usually, this corresponds to the sampling +/// depth of the audio source. For example, 16 bit quantized samples can be +/// encoded in `i16` or `u16`. Note that the sampling depth is not directly +/// visible for formats where [`is_float`] is true. +/// +/// Also note that the backend must support the encoding of the quantized +/// samples in the given format, as there is no generic transformation from one +/// format into the other done inside the frontend-library code. You can query +/// the supported formats by using [`supported_input_configs`]. +/// +/// A good rule of thumb is to use [`SampleFormat::I16`] as this covers typical +/// music (WAV, MP3) as well as typical audio input devices on most platforms, +/// +/// [`is_float`]: SampleFormat::is_float +/// [`supported_input_configs`]: crate::Device::supported_input_configs #[cfg_attr(target_os = "emscripten", wasm_bindgen)] #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] #[non_exhaustive] pub enum SampleFormat { - /// `i8` with a valid range of 'u8::MIN..=u8::MAX' with `0` being the origin + /// `i8` with a valid range of `i8::MIN..=i8::MAX` with `0` being the origin. I8, - /// `i16` with a valid range of 'u16::MIN..=u16::MAX' with `0` being the origin + /// `i16` with a valid range of `i16::MIN..=i16::MAX` with `0` being the origin. I16, // /// `I24` with a valid range of '-(1 << 23)..(1 << 23)' with `0` being the origin // I24, - /// `i32` with a valid range of 'u32::MIN..=u32::MAX' with `0` being the origin + /// `i32` with a valid range of `i32::MIN..=i32::MAX` with `0` being the origin. I32, // /// `I24` with a valid range of '-(1 << 47)..(1 << 47)' with `0` being the origin // I48, - /// `i64` with a valid range of 'u64::MIN..=u64::MAX' with `0` being the origin + /// `i64` with a valid range of `i64::MIN..=i64::MAX` with `0` being the origin. I64, - /// `u8` with a valid range of 'u8::MIN..=u8::MAX' with `1 << 7 == 128` being the origin + /// `u8` with a valid range of `u8::MIN..=u8::MAX` with `1 << 7 == 128` being the origin. U8, - /// `u16` with a valid range of 'u16::MIN..=u16::MAX' with `1 << 15 == 32768` being the origin + /// `u16` with a valid range of `u16::MIN..=u16::MAX` with `1 << 15 == 32768` being the origin. U16, // /// `U24` with a valid range of '0..16777216' with `1 << 23 == 8388608` being the origin // U24, - /// `u32` with a valid range of 'u32::MIN..=u32::MAX' with `1 << 31` being the origin + /// `u32` with a valid range of `u32::MIN..=u32::MAX` with `1 << 31` being the origin. U32, // /// `U48` with a valid range of '0..(1 << 48)' with `1 << 47` being the origin // U48, - /// `u64` with a valid range of 'u64::MIN..=u64::MAX' with `1 << 63` being the origin + /// `u64` with a valid range of `u64::MIN..=u64::MAX` with `1 << 63` being the origin. U64, - /// `f32` with a valid range of `-1.0..1.0` with `0.0` being the origin + /// `f32` with a valid range of `-1.0..1.0` with `0.0` being the origin. F32, - /// `f64` with a valid range of -1.0..1.0 with 0.0 being the origin + /// `f64` with a valid range of `-1.0..1.0` with `0.0` being the origin. F64, }