Add support for audio channel remapping.

The AudioServer processes audio samples as a number of stereo channels,
which are copied to the audio driver buffers. This commit adds
the ability to remap AudioServer channels to different driver
channels, primarily for debugging purposes. The way it is configured
is with get/set methods on AudioServer, exposed in GDScript/C#.

This depends on the speaker_mode override PR godotengine#105934.

It only allows for remapping the stereo channels Godot works with, and
not for mixing left/right samples between channels.

Author: BuzzLord

doc/classes/AudioServer.xml

@@ -118,6 +118,19 @@
 				[b]Note:[/b] The returned value is equivalent to the result of [method @GlobalScope.db_to_linear] on the result of [method get_bus_volume_db].
 			</description>
 		</method>
+		<method name="get_channel_remap" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="output_channel" type="int" />
+			<description>
+				Returns the mapping for the stereo channel index at [param output_channel]. Channel index values correspond to the following stereo channels:
+				- [code]0[/code]: Front left and right
+				- [code]1[/code]: Center and LFE (bass)
+				- [code]2[/code]: Back left and right
+				- [code]3[/code]: Side left and right
+				- [code]-1[/code]: Muted
+				The default is for the [param output_channel] to map to the same corresponding internal stereo channel.
+			</description>
+		</method>
 		<method name="get_driver_name" qualifiers="const">
 			<return type="String" />
 			<description>
@@ -322,6 +335,19 @@
 				[b]Note:[/b] Using this method is equivalent to calling [method set_bus_volume_db] with the result of [method @GlobalScope.linear_to_db] on a value.
 			</description>
 		</method>
+		<method name="set_channel_remap">
+			<return type="void" />
+			<param index="0" name="output_channel" type="int" />
+			<param index="1" name="source_channel" type="int" />
+			<description>
+				Given a stereo channel index [param output_channel], configures the [AudioServer] to map it to the internal channel [param source_channel]. Channel index values correspond to the following stereo channels:
+				- [code]0[/code]: Front left and right
+				- [code]1[/code]: Center and LFE (bass)
+				- [code]2[/code]: Back left and right
+				- [code]3[/code]: Side left and right
+				Setting an output channel to an invalid source channel (e.g. [code]-1[/code]) will mute output from that channel. If the current [method get_speaker_mode] does not use a particular channel, mapping that source channel to an output channel will mute the output channel.
+			</description>
+		</method>
 		<method name="set_enable_tagging_used_audio_streams">
 			<return type="void" />
 			<param index="0" name="enable" type="bool" />

servers/audio_server.cpp

@@ -293,12 +293,14 @@ void AudioServer::_driver_process(int p_frames, int32_t *p_buffer) {
 			// The destination start for data will be the same in all cases.
 			int32_t *dest = &p_buffer[from_buf * (cs * 2) + (k * 2)];
 
+			int rk = channel_remap[k];
+
 #ifdef DEBUG_ENABLED
-			if (!debug_mute && k < mcs && master->channels[k].active) {
+			if (!debug_mute && rk < mcs && master->channels[rk].active) {
 #else
-			if (k < mcs && master->channels[k].active) {
+			if (rk < mcs && master->channels[rk].active) {
 #endif // DEBUG_ENABLED
-				const AudioFrame *buf = master->channels[k].buffer.ptr();
+				const AudioFrame *buf = master->channels[rk].buffer.ptr();
 
 				for (int j = 0; j < to_copy; j++) {
 					float l = CLAMP(buf[from + j].left, -1.0, 1.0);
@@ -1504,6 +1506,38 @@ int AudioServer::get_driver_channel_count() const {
 	ERR_FAIL_V(1);
 }
 
+void AudioServer::set_channel_remap(int p_output_channel, int p_source_channel) {
+	ERR_FAIL_INDEX_MSG(p_output_channel, MAX_CHANNELS_PER_BUS, "Invalid output channel, out of range");
+	bool remap_changed;
+
+	lock();
+	if (p_source_channel < 0 || p_source_channel > MAX_CHANNELS_PER_BUS) {
+		remap_changed = channel_remap[p_output_channel] != MAX_CHANNELS_PER_BUS;
+
+		// Source channels outside valid range will get muted.
+		channel_remap[p_output_channel] = MAX_CHANNELS_PER_BUS;
+	} else {
+		remap_changed = channel_remap[p_output_channel] != p_source_channel;
+		channel_remap[p_output_channel] = p_source_channel;
+	}
+	unlock();
+
+	if (remap_changed) {
+		print_verbose(vformat("AudioServer: channel remap changed: output channel [%d] -> source channel [%d]", p_output_channel, channel_remap[p_output_channel]))
+	}
+}
+
+int AudioServer::get_channel_remap(int p_output_channel) const {
+	ERR_FAIL_INDEX_V_MSG(p_output_channel, MAX_CHANNELS_PER_BUS, -1, "Invalid output channel, out of range");
+	return channel_remap[p_output_channel] == MAX_CHANNELS_PER_BUS ? -1 : channel_remap[p_output_channel];
+}
+
+void AudioServer::init_channel_remap() {
+	for (int i = 0; i < MAX_CHANNELS_PER_BUS; i++) {
+		channel_remap[i] = i;
+	}
+}
+
 void AudioServer::notify_listener_changed() {
 	for (CallbackItem *ci : listener_changed_callback_list) {
 		ci->callback(ci->userdata);
@@ -1536,6 +1570,7 @@ void AudioServer::init() {
 	channel_disable_frames = float(GLOBAL_DEF_RST(PropertyInfo(Variant::FLOAT, "audio/buses/channel_disable_time", PROPERTY_HINT_RANGE, "0,5,0.01,or_greater"), 2.0)) * get_mix_rate();
 
 	speaker_mode_config = GLOBAL_DEF(PropertyInfo(Variant::INT, "audio/general/speaker_mode", PROPERTY_HINT_ENUM, "Default:-1,Stereo:0,Surround 3.1:1,Surround 5.1:2,Surround 7.1:3"), -1);
+	init_channel_remap();
 
 	// TODO: Buffer size is hardcoded for now. This would be really nice to have as a project setting because currently it limits audio latency to an absolute minimum of 11ms with default mix rate, but there's some additional work required to make that happen. See TODOs in `_mix_step_for_channel`.
 	// When this becomes a project setting, it should be specified in milliseconds rather than raw sample count, because 512 samples at 192khz is shorter than it is at 48khz, for example.
@@ -2048,6 +2083,9 @@ void AudioServer::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_bus_effect_enabled", "bus_idx", "effect_idx", "enabled"), &AudioServer::set_bus_effect_enabled);
 	ClassDB::bind_method(D_METHOD("is_bus_effect_enabled", "bus_idx", "effect_idx"), &AudioServer::is_bus_effect_enabled);
 
+	ClassDB::bind_method(D_METHOD("set_channel_remap", "output_channel", "source_channel"), &AudioServer::set_channel_remap);
+	ClassDB::bind_method(D_METHOD("get_channel_remap", "output_channel"), &AudioServer::get_channel_remap);
+
 	ClassDB::bind_method(D_METHOD("get_bus_peak_volume_left_db", "bus_idx", "channel"), &AudioServer::get_bus_peak_volume_left_db);
 	ClassDB::bind_method(D_METHOD("get_bus_peak_volume_right_db", "bus_idx", "channel"), &AudioServer::get_bus_peak_volume_right_db);
 

servers/audio_server.h

@@ -225,6 +225,7 @@ class AudioServer : public Object {
 	int to_mix = 0;
 
 	int speaker_mode_config = -1;
+	int channel_remap[MAX_CHANNELS_PER_BUS];
 
 	float playback_speed_scale = 1.0f;
 
@@ -329,6 +330,7 @@ class AudioServer : public Object {
 	static AudioServer *singleton;
 
 	void init_channels_and_buffers();
+	void init_channel_remap();
 
 	void _mix_step();
 	void _mix_step_for_channel(AudioFrame *p_out_buf, AudioFrame *p_source_buf, AudioFrame p_vol_start, AudioFrame p_vol_final, float p_attenuation_filter_cutoff_hz, float p_highshelf_gain, AudioFilterSW::Processor *p_processor_l, AudioFilterSW::Processor *p_processor_r);
@@ -430,6 +432,9 @@ class AudioServer : public Object {
 
 	bool is_bus_channel_active(int p_bus, int p_channel) const;
 
+	void set_channel_remap(int p_output_channel, int p_source_channel);
+	int get_channel_remap(int p_output_channel) const;
+
 	void set_playback_speed_scale(float p_scale);
 	float get_playback_speed_scale() const;