logarithmic volume control for global soundtray / volume (#3248)

* logarithmic volume control for global soundtray / volume

* use logarithmic sound volume at the transform

* clamp volume again

* small fixes

* add dynamic FlxG.applySoundCurve

* fix coverage

---------

Co-authored-by: GeoKureli-BlackbookPro <[email protected]>

Author: ninjamuffin99

flixel/sound/FlxSound.hx

@@ -594,13 +594,26 @@ class FlxSound extends FlxBasic
 	@:allow(flixel.sound.FlxSoundGroup)
 	function updateTransform():Void
 	{
-		_transform.volume = #if FLX_SOUND_SYSTEM (FlxG.sound.muted ? 0 : 1) * FlxG.sound.volume * #end
-			(group != null ? group.volume : 1) * _volume * _volumeAdjust;
-			
+		_transform.volume = calcTransformVolume();
+		
 		if (_channel != null)
 			_channel.soundTransform = _transform;
 	}
 
+	function calcTransformVolume():Float
+	{
+		final volume = (group != null ? group.volume : 1.0) * _volume * _volumeAdjust;
+		
+		#if FLX_SOUND_SYSTEM
+		if (FlxG.sound.muted)
+			return 0.0;
+		
+		return FlxG.sound.applySoundCurve(FlxG.sound.volume * volume);
+		#else
+		return volume;
+		#end
+	}
+	
 	/**
 	 * An internal helper function used to attempt to start playing
 	 * the sound and populate the _channel variable.

flixel/system/frontEnds/SoundFrontEnd.hx

@@ -379,7 +379,35 @@ class SoundFrontEnd
 		}
 		#end
 	}
-
+	
+	/**
+	 * Takes the volume scale used by Flixel fields and gives the final transformed volume that is
+	 * actually used to play the sound. To reverse this operation, use `reverseSoundCurve`. This
+	 * field is `dynamic` and can be overwritten. 
+	 */
+	public dynamic function applySoundCurve(volume:Float)
+	{
+		return volume;
+		
+		// Example of linear to logarithmic sound curve:
+		// final clampedVolume = Math.max(0, Math.min(1, volume));
+		// return Math.exp(Math.log(0.001) * (1 - clampedVolume));
+	}
+	
+	/**
+	 * Takes a transformed volume and returns the corresponding volume scale used by Flixel fields.
+	 * Used to reverse the operation of `applySoundCurve`. This field is `dynamic` and can be
+	 * set to a custom function.
+	 */
+	public dynamic function reverseSoundCurve(curvedVolume:Float)
+	{
+		return curvedVolume;
+		
+		// Example of logarithmic to linear sound curve:
+		// final clampedVolume = Math.max(minValue, Math.min(1, x));
+		// return 1 - (Math.log(clampedVolume) / Math.log(0.001));
+	}
+	
 	function new()
 	{
 		#if FLX_SAVE

tests/unit/src/flixel/system/frontEnds/SoundFrontEndTest.hx

@@ -1,6 +1,7 @@
 package flixel.system.frontEnds;
 
 import flixel.FlxG;
+import massive.munit.Assert;
 
 class SoundFrontEndTest
 {
@@ -22,5 +23,32 @@ class SoundFrontEndTest
 	{
 		FlxG.sound.load("assets/invalid").play();
 	}
+
+	@Test // #1511
+	function testSoundCurve()
+	{
+		Assert.areEqual(1.0, FlxG.sound.applySoundCurve(1));
+		Assert.areEqual(1.0, FlxG.sound.reverseSoundCurve(1));
+		
+		FlxG.sound.applySoundCurve = function (volume)
+		{
+			final clampedVolume = Math.max(0, Math.min(1, volume));
+			return Math.exp(Math.log(0.001) * (1 - volume));
+		};
+		
+		FlxG.sound.reverseSoundCurve = function (volume)
+		{
+			final clampedVolume = Math.max(0.001, Math.min(1, volume));
+			return 1 - (Math.log(clampedVolume) / Math.log(0.001));
+		};
+		
+		FlxAssert.areNear(1.0, FlxG.sound.applySoundCurve(1));
+		FlxAssert.areNear(1.0, FlxG.sound.reverseSoundCurve(1));
+		FlxAssert.areNear(0.001, FlxG.sound.applySoundCurve(0));
+		FlxAssert.areNear(0.0, FlxG.sound.reverseSoundCurve(0));
+		FlxAssert.areNear(0.031, FlxG.sound.applySoundCurve(0.5));
+		FlxAssert.areNear(0.899, FlxG.sound.reverseSoundCurve(0.5));
+		FlxAssert.areNear(0.5, FlxG.sound.reverseSoundCurve(FlxG.sound.applySoundCurve(0.5)));
+	}
 	#end
 }