audio: stereo downmix, volume boost options (#722)

## Link to GitHub Issue or related Pull Request, if one exists
Fixes #717, fixes #647

## Description of change
Adds an option to downmix surround sound (5.1, 7.1, etc) down to stereo
(2 speakers). This can be used in most WASAPI games, including Gitadora
and FTT.

How it works: when the game tries to open surround format (say, 7.1) we
create a fake buffer and tell the game that it is supported. In reality
we open a 2-channel stream with the real sound card. When the stream
begins, we downmix the channels down to two (using one of many
algorithms) and output to the sound card.

While we're here, implement an option to boost the game volume by some
decibel value, which is a feature often requested by SDVX players. This
was needed since downmixing can sometimes result in quieter audio.

## Testing
Tested GW Delta and FTT.

Downmix doesn't work on IIDX (32 bits) but volume boost works.

src/spice2x/hooks/audio/backends/wasapi/audio_client.cpp

@@ -4,6 +4,7 @@
 #include <ksmedia.h>
 
 #include "avs/game.h"
+#include "games/gitadora/gitadora.h"
 #include "hooks/audio/audio.h"
 #include "hooks/audio/util.h"
 #include "hooks/audio/backends/wasapi/util.h"
@@ -41,6 +42,27 @@ static void fix_rec_format(WAVEFORMATEX *pFormat) {
     pFormat->nAvgBytesPerSec = pFormat->nSamplesPerSec * pFormat->nBlockAlign;
 }
 
+// decide whether the given multi-channel format should be downmixed to stereo and which algorithm
+// to use. an explicit user selection (-downmix) takes precedence; otherwise gitadora arena
+// two-channel mode defaults to the AC-4 algorithm.
+static std::optional<hooks::audio::DownmixAlgorithm> resolve_downmix(const WAVEFORMATEX *format) {
+    if (format == nullptr
+            || format->nChannels <= 2
+            || format->wFormatTag != WAVE_FORMAT_EXTENSIBLE) {
+        return std::nullopt;
+    }
+
+    if (hooks::audio::DOWNMIX_ALGORITHM.has_value()) {
+        return hooks::audio::DOWNMIX_ALGORITHM;
+    }
+
+    if (games::gitadora::is_arena_model() && games::gitadora::TWOCHANNEL) {
+        return hooks::audio::DownmixAlgorithm::AC4;
+    }
+
+    return std::nullopt;
+}
+
 IAudioClient *wrap_audio_client(IAudioClient *audio_client) {
     log_misc("audio::wasapi", "wrapping IAudioClient");
 
@@ -145,13 +167,27 @@ HRESULT STDMETHODCALLTYPE WrappedIAudioClient::Initialize(
         fix_rec_format(const_cast<WAVEFORMATEX *>(pFormat));
     }
 
+    // when downmixing, open the real device as stereo while the game keeps writing its native
+    // multi-channel format into the scratch buffer.
+    WAVEFORMATEXTENSIBLE stereo_storage = {};
+    const WAVEFORMATEX *device_format = pFormat;
+
+    if (auto algorithm = resolve_downmix(pFormat)) {
+        this->downmix.setup(pFormat, &stereo_storage, *algorithm);
+        device_format = reinterpret_cast<const WAVEFORMATEX *>(&stereo_storage);
+        log_info("audio::wasapi", "downmix enabled: {} channels -> 2 channels ({})",
+                pFormat->nChannels, hooks::audio::Downmix::algorithm_name(*algorithm));
+    } else if (games::gitadora::is_arena_model()) {
+        games::gitadora::fix_audio_channel_mask(const_cast<WAVEFORMATEX *>(pFormat));
+    }
+
     // verbose output
     log_info("audio::wasapi", "IAudioClient::Initialize hook hit");
     log_info("audio::wasapi", "... ShareMode         : {}", share_mode_str(ShareMode));
     log_info("audio::wasapi", "... StreamFlags       : {}", stream_flags_str(StreamFlags));
     log_info("audio::wasapi", "... hnsBufferDuration : {}", hnsBufferDuration);
     log_info("audio::wasapi", "... hnsPeriodicity    : {}", hnsPeriodicity);
-    print_format(pFormat);
+    print_format(device_format);
 
     if (this->backend) {
         SAFE_CALL("AudioBackend", "on_initialize", this->backend->on_initialize(
@@ -173,17 +209,29 @@ HRESULT STDMETHODCALLTYPE WrappedIAudioClient::Initialize(
     // check for exclusive mode
     if (ShareMode == AUDCLNT_SHAREMODE_EXCLUSIVE) {
         this->exclusive_mode = true;
-        this->frame_size = pFormat->nChannels * (pFormat->wBitsPerSample / 8);
+        this->frame_size = device_format->nChannels * (device_format->wBitsPerSample / 8);
     }
 
     // call next
-    HRESULT ret = pReal->Initialize(
-            ShareMode,
-            StreamFlags,
-            hnsBufferDuration,
-            hnsPeriodicity,
-            pFormat,
-            AudioSessionGuid);
+    HRESULT ret;
+    if (this->downmix.enabled) {
+        ret = this->downmix.initialize(
+                pReal,
+                ShareMode,
+                StreamFlags,
+                hnsBufferDuration,
+                hnsPeriodicity,
+                device_format,
+                AudioSessionGuid);
+    } else {
+        ret = pReal->Initialize(
+                ShareMode,
+                StreamFlags,
+                hnsBufferDuration,
+                hnsPeriodicity,
+                device_format,
+                AudioSessionGuid);
+    }
 
     // check for failure
     if (FAILED(ret)) {
@@ -192,7 +240,8 @@ HRESULT STDMETHODCALLTYPE WrappedIAudioClient::Initialize(
     }
 
     log_info("audio::wasapi", "IAudioClient::Initialize success, hr={}", FMT_HRESULT(ret));
-    copy_wave_format(&hooks::audio::FORMAT, pFormat);
+    copy_wave_format(&hooks::audio::FORMAT, device_format);
+    copy_wave_format(&this->device_format, device_format);
 
     return ret;
 }
@@ -274,6 +323,18 @@ HRESULT STDMETHODCALLTYPE WrappedIAudioClient::IsFormatSupported(
         fix_rec_format(const_cast<WAVEFORMATEX *>(pFormat));
     }
 
+    // when downmixing, the real device is opened as stereo, so check whether the equivalent
+    // stereo format is supported instead of the multi-channel one.
+    if (resolve_downmix(pFormat)) {
+        WAVEFORMATEXTENSIBLE stereo_storage = {};
+        hooks::audio::Downmix::make_stereo_format(pFormat, &stereo_storage);
+        const auto stereo_format = reinterpret_cast<const WAVEFORMATEX *>(&stereo_storage);
+
+        CHECK_RESULT(pReal->IsFormatSupported(ShareMode, stereo_format, ppClosestMatch));
+    } else if (games::gitadora::is_arena_model()) {
+        games::gitadora::fix_audio_channel_mask(const_cast<WAVEFORMATEX *>(pFormat));
+    }
+
     if (this->backend) {
         HRESULT ret = this->backend->on_is_format_supported(&ShareMode, pFormat, ppClosestMatch);
 
@@ -466,5 +527,6 @@ HRESULT STDMETHODCALLTYPE WrappedIAudioClient::InitializeSharedAudioStream(
 
     log_info("audio::wasapi", "IAudioClient3::InitializeSharedAudioStream success, hr={}", FMT_HRESULT(ret));
     copy_wave_format(&hooks::audio::FORMAT, pFormat);
+    copy_wave_format(&this->device_format, pFormat);
     return ret;
 }