Objective

• Allow users to configure volume using decibels by changing the Volume type from newtyping an f32 to an enum with Linear and Decibels variants.
• Fixes Expose both linear and logarithmic volume settings #9507.
• Alternative reworked version of closed Updated VolumeLevel to use Decibel and Amplitude Ratio Units #9582.

Solution

Compared to #9582, this PR has the following main differences:

1. It uses the term "linear scale" instead of "amplitude" per https://github.com/bevyengine/bevy/pull/9582/files#r1513529491.
2. Supports ops for doing Volume arithmetic. Can add two volumes, e.g. to increase/decrease the current volume. Can multiply two volumes, e.g. to get the “effective” volume of an audio source considering global volume.

Testing

• Ran cargo run --example soundtrack.
• Ran cargo run --example audio_control.
• Ran cargo run --example spatial_audio_2d.
• Ran cargo run --example spatial_audio_3d.
• Ran cargo run --example pitch.
• Ran cargo run --example decodable.
• Ran cargo run --example audio.

Migration Guide

Audio volume can now be configured using decibel values, as well as using linear scale values. To enable this, some types and functions in bevy_audio have changed.

• Volume is now an enum with Linear and Decibels variants.

Before:

let v = Volume(1.0);

After:

let volume = Volume::Linear(1.0);
let volume = Volume::Decibels(0.0); // or now you can deal with decibels if you prefer

• Volume::ZERO has been renamed to the more semantically correct Volume::SILENT because Volume now supports decibels and "zero volume" in decibels actually means "normal volume".
• The AudioSinkPlayback trait's volume-related methods now deal with Volume types rather than f32s. AudioSinkPlayback::volume() now returns a Volume rather than an f32. AudioSinkPlayback::set_volume now receives a Volume rather than an f32. This affects the AudioSink and SpatialAudioSink implementations of the trait. The previous f32 values are equivalent to the volume converted to linear scale so the Volume:: Linear variant should be used to migrate between f32s and Volume.
• The GlobalVolume::new function now receives a Volume instead of an f32.