Audio in Karl2D: Software mixing, OS APIs and general design

audio_backend: Audio_Backend_Interface,
audio_backend_state: rawptr,

sound_data: hm.Dynamic_Handle_Map(Sound_Data, Sound_Data_Handle),
sound_instances: hm.Dynamic_Handle_Map(Sound_Instance, Sound),

// Sounds that have been started as because `play_sound` was called.
playing_sounds: [dynamic]Playing_Sound,

// 1 megabyte is arbitrarily chosen.
mix_buffer: [1*mem.Megabyte]Audio_Sample,

// Where the mixer currently is in the mix buffer.
mix_buffer_offset: int,

Audio_Backend_Interface :: struct #all_or_none {
	state_size: proc() -> int,
	init: proc(state: rawptr, allocator: runtime.Allocator),
	shutdown: proc(),
	set_internal_state: proc(state: rawptr),

	feed: proc(samples: []Audio_Sample),
	remaining_samples: proc() -> int,
}

Sound_Data :: struct {
	handle: Sound_Data_Handle,
	samples: []Audio_Sample,
	sample_rate: int,

	// When a Sound_Instance is destroyed, we check if this reaches zero. If it does, then the
	// Sound_Data and its samples slice are also destroyed/freed.
	instances: int,
}

Sound_Instance :: struct {
	handle: Sound,
	sound_data_handle: Sound_Data_Handle,
	volume: f32,
	target_volume: f32,
	pan: f32,
	target_pan: f32,
	pitch: f32,
	target_pitch: f32,
}

play_sound :: proc(snd: Sound, loop := false) {
	append(
		&s.playing_sounds,
		Playing_Sound {
			sound = snd,
			loop = loop,
		},
	)
}

update_audio_mixer :: proc() {
	if ab.remaining_samples() > (3 * AUDIO_MIX_CHUNK_SIZE)/2 {
		return
	}

	for &ps in s.playing_sounds {
		for samp_idx in 0..<AUDIO_MIX_CHUNK_SIZE {
			// add samples from `ps.samples` into `s.mix_buffer` and advance `ps.offset`
		}
	}

	ab.feed(s.mix_buffer[s.mix_buffer_offset:AUDIO_MIX_CHUNK_SIZE])

	// advance s.mix_buffer_offset
}

samples_per_mixer_sample := (pitch*f32(data.sample_rate))/f32(AUDIO_MIX_SAMPLE_RATE)

move_towards :: proc(current: f32, target: f32, delta: f32) -> f32 {
	if abs(target - current) < delta {
		return target
	}

	dir := math.sign(target - current)
	return current + dir * delta
}


volume_start := clamp(inst.volume, 0, 1)
volume_end := clamp(move_towards(inst.volume, inst.target_volume, adjust_parameter_delta), 0, 1)

add :: proc(
	dest: []Audio_Sample,
	source: []Audio_Sample,
	num: int,
	volume_start: f32,
	volume_end: f32,
	pan_start: [2]f32,
	pan_end: [2]f32,
) -> int {
	to_write := num

	if to_write > len(source) {
		to_write = len(source)
	}
	
	for samp_idx in 0..<to_write {
		t := f32(samp_idx) / f32(to_write)
		volume := math.lerp(volume_start, volume_end, t)
		pan := linalg.lerp(pan_start, pan_end, t)
		dest[samp_idx] += pan * source[samp_idx] * volume
	}

	return to_write
}

add(
	s.mix_buffer[s.mix_buffer_offset:],
	data.samples[ps.offset:],
	AUDIO_MIX_CHUNK_SIZE,
	volume_start,
	volume_end,
	pan_stereo_start,
	pan_stereo_end,
)

#+build windows
#+vet explicit-allocators
#+private file
package karl2d

@(private="package")
AUDIO_BACKEND_WAVEOUT :: Audio_Backend_Interface {
	state_size = waveout_state_size,
	init = waveout_init,
	shutdown = waveout_shutdown,
	set_internal_state = waveout_set_internal_state,

	feed = waveout_feed,
	remaining_samples = waveout_remaining_samples,
}

import "base:runtime"
import "log"
import win32 "core:sys/windows"
import "core:time"
import "core:slice"

Waveout_State :: struct {
	device: win32.HWAVEOUT,
	allocator: runtime.Allocator,
	headers: [32]win32.WAVEHDR,
	cur_header: int,
	submitted_samples: int,
}

waveout_state_size :: proc() -> int {
	return size_of(Waveout_State)
}

s: ^Waveout_State

waveout_init :: proc(state: rawptr, allocator: runtime.Allocator) {
	assert(state != nil)
	s = (^Waveout_State)(state)
	s.allocator = allocator
	log.debug("Init audio backend waveout")

	// Added constant missing in bindings:
	// KSDATAFORMAT_SUBTYPE_IEEE_FLOAT GUID: 00000003-0000-0010-8000-00aa00389b71
	KSDATAFORMAT_SUBTYPE_IEEE_FLOAT :: win32.GUID{0x00000003, 0x0000, 0x0010, {0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}}

	format := win32.WAVEFORMATEXTENSIBLE {
		Format = {
			nSamplesPerSec = 44100,
			wBitsPerSample = 32,
			nChannels = 2,
			wFormatTag = win32.WAVE_FORMAT_EXTENSIBLE,
			cbSize = size_of(win32.WAVEFORMATEXTENSIBLE) - size_of(win32.WAVEFORMATEX),
		},
		Samples = {
			wValidBitsPerSample = 32,
		},
		dwChannelMask = { .FRONT_LEFT, .FRONT_RIGHT },
		SubFormat = KSDATAFORMAT_SUBTYPE_IEEE_FLOAT,
	}

	format.nBlockAlign = (format.wBitsPerSample * format.nChannels) / 8 // see nBlockAlign docs
	format.nAvgBytesPerSec = (u32(format.wBitsPerSample * format.nChannels) * format.nSamplesPerSec) / 8

	ch(win32.waveOutOpen(
		&s.device,
		win32.WAVE_MAPPER,
		&format,
		0,
		0,
		win32.CALLBACK_NULL,
	))
}

ch :: proc(mr: win32.MMRESULT, loc := #caller_location) -> win32.MMRESULT {
	if mr == 0 {
		return mr
	}

	log.errorf("waveout error. Error code: %v", u32(mr), location = loc)
	return mr
}

waveout_shutdown :: proc() {
	log.debug("Shutdown audio backend waveout")
	win32.waveOutClose(s.device)
}

waveout_set_internal_state :: proc(state: rawptr) {
	assert(state != nil)
	s = (^Waveout_State)(state)
}

waveout_feed :: proc(samples: []Audio_Sample) {
	h := &s.headers[s.cur_header]

	for win32.waveOutUnprepareHeader(s.device, h, size_of(win32.WAVEHDR)) == win32.WAVERR_STILLPLAYING {
		time.sleep(1 * time.Millisecond)
	}

	byte_samples := slice.reinterpret([]u8, samples)

	h^ = {
		dwBufferLength = u32(len(byte_samples)),
		lpData = raw_data(byte_samples),
	}

	win32.waveOutPrepareHeader(s.device, h, size_of(win32.WAVEHDR))
	win32.waveOutWrite(s.device, h, size_of(win32.WAVEHDR))

	s.submitted_samples += len(samples)
	s.cur_header += 1

	if s.cur_header >= len(s.headers) {
		s.cur_header = 0
	}
}

waveout_remaining_samples :: proc() -> int {
	t := win32.MMTIME {
		wType = .TIME_SAMPLES,
	}
	win32.waveOutGetPosition(s.device, &t, size_of(win32.MMTIME))
	return s.submitted_samples - int(t.u.sample)
}

#+build js
#+vet explicit-allocators
#+private file
package karl2d

@(private="package")
AUDIO_BACKEND_WEB_AUDIO :: Audio_Backend_Interface {
	state_size = web_audio_state_size,
	init = web_audio_init,
	shutdown = web_audio_shutdown,
	set_internal_state = web_audio_set_internal_state,
	feed = web_audio_feed,
	remaining_samples = web_audio_remaining_samples,
}

import "base:runtime"
import "core:slice"

foreign import karl2d_web_audio "karl2d_web_audio"

// The `js_` prefix is there to just avoid clashes with the procs in this file.
@(default_calling_convention="contextless")
foreign karl2d_web_audio {
	@(link_name="web_audio_init")
	js_web_audio_init :: proc() ---
	@(link_name="web_audio_shutdown")
	js_web_audio_shutdown :: proc() ---
	@(link_name="web_audio_feed")
	js_web_audio_feed :: proc(samples: []f32) ---
	@(link_name="web_audio_remaining_samples")
	js_web_audio_remaining_samples :: proc() -> int ---
}

web_audio_state_size :: proc() -> int {
	return 0
}

web_audio_init :: proc(state: rawptr, allocator: runtime.Allocator) {
	js_web_audio_init()
}

web_audio_shutdown :: proc() {
	js_web_audio_shutdown()
}

web_audio_set_internal_state :: proc(state: rawptr) {
	// No hot reload on web.
}

web_audio_feed :: proc(samples: []Audio_Sample) {
	// The JS backend just sees an array of f32. But it knows that they are interleaved Left & Right
	js_web_audio_feed(slice.reinterpret([]f32, samples))
}

web_audio_remaining_samples :: proc() -> int {
	return js_web_audio_remaining_samples()
}

// Update the audio mixer and feed more audio data into the audio backend. This is done
// automatically when `update` runs, so you normally don't need to call this manually.
//
// This procedure implements a custom software audio mixer. The backend is just fed the resulting
// mix. Therefore, you can see everything regarding how audio is processed in this procedure.
//
// Will only run if the audio backend is running low on audio data.
update_audio_mixer :: proc() {
	// If the sample rate of the backend is 44100 samples/second and AUDIO_MIX_CHUNK_SIZE is 1400
	// samples, then this procedure will only run roughly 44100/1400 = 31 times per second. This
	// gives a latency of up to (1.5 * (44100/1400)) = 47 milliseconds. Is it too big, or too small?
	// Perhaps we can use more low latency backends to push it down. Perhaps the backend should
	// control AUDIO_MIX_CHUNK_SIZE based on how low latency it can give us without stalling?
	if ab.remaining_samples() > (3 * AUDIO_MIX_CHUNK_SIZE)/2 {
		return
	}
	
	// We are going to go past the end of the mix_buffer, so just hop to the start instead. It's
	// 1 megabyte big, so hopping over a few bytes at the end is OK.
	if (s.mix_buffer_offset + AUDIO_MIX_CHUNK_SIZE) > len(s.mix_buffer) {
		s.mix_buffer_offset = 0
	}

	// A slice of the mixed samples we are going to output.
	out := s.mix_buffer[s.mix_buffer_offset:s.mix_buffer_offset + AUDIO_MIX_CHUNK_SIZE]
	
	// Zero out old mixed data from buffer (the buffer is "circular", there may be old stuff in
	// the `out` slice).
	slice.zero(out)

	// For usage when the sample rates of the playing sound and the mixer match.
	add :: proc(
		dest: []Audio_Sample,
		source: []Audio_Sample,
		num: int,
		volume_start: f32,
		volume_end: f32,
		pan_start: [2]f32,
		pan_end: [2]f32,
	) -> int {
		to_write := num

		if to_write > len(source) {
			to_write = len(source)
		}
		
		for samp_idx in 0..<to_write {
			t := f32(samp_idx) / f32(to_write)
			volume := math.lerp(volume_start, volume_end, t)
			pan := linalg.lerp(pan_start, pan_end, t)
			dest[samp_idx] += pan * source[samp_idx] * volume
		}

		return to_write
	}

	// For usage when the sample rates don't match. Needs a `dest_source_ratio` parameter that tells
	// us how the sample ratios relate. It's used for getting from indices from dest sample space
	// to source sample space.
	add_interpolate :: proc(
		dest: []Audio_Sample,
		source: []Audio_Sample,
		source_offset: f32,
		num_dest: int,
		dest_source_ratio: f32,
		volume_start: f32,
		volume_end: f32,
		pan_start: [2]f32,
		pan_end: [2]f32,
	) -> int {
		
		dest_idx: int
		for ; dest_idx < num_dest; dest_idx += 1 {
			src_pos := source_offset + f32(dest_idx) * dest_source_ratio
			src_idx := int(src_pos)
			
			if src_idx >= len(source) {
				break
			}

			src_next := min(src_idx + 1, len(source) - 1)
			frac := src_pos - f32(src_idx)

			prev_val := source[src_idx]
			cur_val := source[src_next]

			t := f32(dest_idx) / f32(num_dest)
			volume := math.lerp(volume_start, volume_end, t)
			pan := linalg.lerp(pan_start, pan_end, t)

			dest[dest_idx] += pan * linalg.lerp(prev_val, cur_val, frac) * volume
		}

		return dest_idx
	}

	for idx := 0; idx < len(s.playing_sounds); idx += 1 {
		ps := &s.playing_sounds[idx]
		inst := hm.get(&s.sound_instances, ps.sound)

		if inst == nil {
			log.error("Trying to play destroyed sound")
			unordered_remove(&s.playing_sounds, idx)
			idx -= 1
			continue
		}

		data := hm.get(&s.sound_data, inst.sound_data_handle)

		if data == nil {
			log.error("Trying to play sound with destroyed data")
			unordered_remove(&s.playing_sounds, idx)
			idx -= 1
			continue
		}

		// Before we get to the mixing we smoothly adjust pitch, volume and pan. We do this to avoid
		// clicks in the audio. The clicks happen because abrupt changes cause discontinuities in
		// the audio waveform. Understand: Sound does not happen because the waveform has a high
		// value, it happens because there is a sudden change in the waveform. Bigger change, bigger
		// sound.

		calc_adjust_parameter_delta :: proc(sample_rate: int, pitch: f32) -> f32 {
			RAMP_TIME :: 0.03
			ramp_samples := RAMP_TIME * f32(sample_rate) * pitch
			return AUDIO_MIX_CHUNK_SIZE / ramp_samples
		}

		move_towards :: proc(current: f32, target: f32, delta: f32) -> f32 {
			if abs(target - current) < delta {
				return target
			}

			dir := math.sign(target - current)
			return current + dir * delta
		}

		// We get the delta twice because we first need to move the pitch towards its target.
		adjust_parameter_delta := calc_adjust_parameter_delta(data.sample_rate, max(inst.pitch, 0.01))
		inst.pitch = max(move_towards(inst.pitch, inst.target_pitch, adjust_parameter_delta), 0.01)
		pitch := inst.pitch
		adjust_parameter_delta = calc_adjust_parameter_delta(data.sample_rate, pitch)

		// We can't just use the `volume_end` value for the volume. We are going to mix in
		// `AUDIO_MIX_CHUNK_SIZE` number of samples. We'd still get clicks in the sound if we hopped
		// to the ending volume. Instead, we calculate what the first sample should use and what
		// the last one should use. Then we feed those into the `add`/`add_interpolate` procedures.
		// It will lerp across the range as it is mixing in the samples.

		volume_start := clamp(inst.volume, 0, 1)
		volume_end := clamp(move_towards(inst.volume, inst.target_volume, adjust_parameter_delta), 0, 1)
		inst.volume = volume_end

		if volume_start == volume_end && volume_end == 0 {
			continue
		}
		
		pan_start := clamp(inst.pan, -1, 1)
		pan_end := clamp(move_towards(inst.pan, inst.target_pan, adjust_parameter_delta), -1, 1)
		inst.pan = pan_end
		
		// Use cos/sine to get a constant-power audio curve. This means that the sound won't get
		// quieter in the middle, but will instead just pan.
		pan_stereo_start := [2]f32 {
			math.cos((pan_start + 1) * math.PI / 4),
			math.sin((pan_start + 1) * math.PI / 4),
		}

		pan_stereo_end := [2]f32 {
			math.cos((pan_end + 1) * math.PI / 4),
			math.sin((pan_end + 1) * math.PI / 4),
		}

		interpolate := data.sample_rate != AUDIO_MIX_SAMPLE_RATE || pitch != 1
		num_mixed: int
		
		if interpolate {
			samples_per_mixer_sample := (pitch*f32(data.sample_rate))/f32(AUDIO_MIX_SAMPLE_RATE)

			num_mixed = add_interpolate(
				s.mix_buffer[s.mix_buffer_offset:],
				data.samples[ps.offset:],
				ps.offset_fraction,
				AUDIO_MIX_CHUNK_SIZE,
				samples_per_mixer_sample,
				volume_start,
				volume_end,
				pan_stereo_start,
				pan_stereo_end,
			)
			
			num_mixed_f32 := f32(num_mixed) * samples_per_mixer_sample
			fraction_advance := ps.offset_fraction + num_mixed_f32

			// The fraction advance may become larger than 1, in which case the offset needs to eat
			// the integer part.
			ps.offset += int(fraction_advance)
			
			ps.offset_fraction = linalg.fract(fraction_advance)
		} else {
			num_mixed = add(
				s.mix_buffer[s.mix_buffer_offset:],
				data.samples[ps.offset:],
				AUDIO_MIX_CHUNK_SIZE,
				volume_start,
				volume_end,
				pan_stereo_start,
				pan_stereo_end,
			)
			
			ps.offset += num_mixed
			ps.offset_fraction = 0
		}

		// We didn't mix all the samples! This means that we reached the end of the sound.
		if num_mixed < AUDIO_MIX_CHUNK_SIZE {
			if ps.loop {
				ps.offset = 0
				ps.offset_fraction = 0

				// The sound looped. Make sure to mix in the remaining samples from the start of the
				// sound!
				overflow := AUDIO_MIX_CHUNK_SIZE - num_mixed

				if interpolate {
					samples_per_mixer_sample := (pitch*f32(data.sample_rate))/f32(AUDIO_MIX_SAMPLE_RATE)

					num_mixed = add_interpolate(
						s.mix_buffer[s.mix_buffer_offset + num_mixed:],
						data.samples[ps.offset:],
						ps.offset_fraction,
						overflow,
						samples_per_mixer_sample,
						volume_start,
						volume_end,
						pan_stereo_start,
						pan_stereo_end,
					)

					num_mixed_f32 := f32(num_mixed) * samples_per_mixer_sample
					fraction_advance := ps.offset_fraction + num_mixed_f32
					ps.offset += int(fraction_advance)
					ps.offset_fraction = linalg.fract(fraction_advance)
				} else {
					num_mixed = add(
						s.mix_buffer[s.mix_buffer_offset + num_mixed:],
						data.samples[ps.offset:],
						overflow,
						volume_start,
						volume_end,
						pan_stereo_start,
						pan_stereo_end,
					)

					ps.offset += num_mixed
					ps.offset_fraction = 0
				}
			} else {
				unordered_remove(&s.playing_sounds, idx)
				idx -= 1
			}
		}
	}

	ab.feed(out)
	s.mix_buffer_offset += AUDIO_MIX_CHUNK_SIZE
}