Updated VolumeLevel to use Decibel and Amplitude Ratio Units

[bushrat011899]

Objective

• Fixes Expose both linear and logarithmic volume settings #9507

Solution

• Breaking changes in both the AudioSinkPlayback trait and VolumeLevel type.
• Replaced VolumeLevel with an enum representing either the amplitude ratio or decibel level. Names and types were chosen to be consistent with 3rd party crates like Kira, and the internally used types in the rest of bevy_audio

---

Changelog

• Moved VolumeLevel into its own file volume_level.rs to reduce clutter in audio.rs.
• Implemented total equality and ordering for VolumeLevel, as both variants Amplitude and Decibels are isomorphic and internally possess both properties.
• Implemented amplitude() and decibels() methods to get the desired unit type from VolumeLevel directly without a match statement.
• Added debug_assert! statements to ensure calculated values are within their appropriate bounds.
• Added a unit test for conversion between Amplitude and Decibels, with a truth table obtained from Wikipedia
• Updated internal functions to either accept the VolumeLevel type, or explicitly request an amplitude which is then wrapped in a VolumeLevel::Amplitude where appropriate.
• Removed VolumeLevel::get and VolumeLevel::new due to ambiguity in the unit to return.

Migration Guide

• VolumeLevel::new(volume) -> VolumeLevel::Amplitude(volume)
• VolumeLevel::get() -> VolumeLevel::amplitude()
• AudioSinkPlayback::volume() -> AudioSinkPlayback::volume().amplitude()
• AudioSinkPlayback::set_volume(volume) -> AudioSinkPlayback::set_volume(VolumeLevel::Amplitude(volume))

[bushrat011899]

This comment got me thinking, I can actually remove the bounds checks entirely. Both variants take a single f32 value:

• Decibels(a) is defined for all a, it's just that values larger in magnitude than 800 don't really exist in f32, so they're all clamped to f32::INFINITY in amplitude. Which is defined and sound behaviour.
• Amplitude(a) does actually exist for all a, if you consider the phase of the wave, not just its amplitude. A negative a indicates a 180° rotation of the phase, or a phase inversion. However, since nothing in the Bevy audio library works with phasing (at least that I can find), this information is largely meaningless and can just be ignored.

So I've adjusted the access and comparison methods to reflect the true statement that the amplitude of a Amplitude(a) is equal to a.abs() for all a. I've also added some unit tests to document this behaviour explicitly.

[hymm]

Do we really need 2 variants for volume? Unity, Unreal, and Godot all just use decibels. That might just be because they don't have sum types, but the current pr feels a little awkward when you want to do math on the volume.

[bushrat011899]

Do we really need 2 variants for volume? Unity, Unreal, and Godot all just use decibels. That might just be because they don't have sum types, but the current pr feels a little awkward when you want to do math on the volume.

I think using an enum is a good way to force understanding around what the volume type represents. The Amplitude variant is substantially more useful in engine code, since waveforms are just directly scaled by that amplitude value. Whereas, Decibels is more useful for user code as that unit matches real-world understanding of sound and relative "loudness".

An alternative could be to new-type f32, and just convert into either amplitude or decibels for all operations as required, but I don't know if that's substantially more ergonomic.

[SolarLiner]

At the risk of some bikeshedding (and probably pedantry), "amplitude" refers to the volume itself, not a specific "unit" -- Linear would be a better term, as it is the term that is most used for the unitless gain ratio (this applies to the method name line 26 too). I can imagine some users being confused when looking at this variant by itself and not knowing whether we are talking about the linear gain or the logarithmic one (in dB), and having to look up the enum definition to clear the confusion.

[SolarLiner]

It's been kept as-is to not introduce breaking changes, but I do think it would be better to have new_relative and new_absolute use the VolumeLevel. Or we can deprecate these ones and introduce new methods (meaning 4 methods total for the cartesian product of (relative,absolute)x(amplitude,decibel)?