Document Audio Thread Commands (#1399)

* begin docs

* cleanup

* copy over progress

* cleanup

* small cleanup

* more docs, fill out cmds

* small touchup

* pan weight ganon comment

* fix specId

* seqcmd cleanup

* format

* small cleanup

* one more thing

* small feedback from MM

* partial PR

* some PR Suggestions

* small adjustments

* ticks, seqticks, frames, updates: term cleanup

* small fix

* PR Review

* PR Review

* PR Review

* rm param

* adjust comment

* update renamed functions

* format

---------

Co-authored-by: Dragorn421 <Dragorn421@users.noreply.github.com>

1 files changed, 37 insertions, 34 deletions

diff --git a/src/audio/lib/synthesis.c b/src/audio/lib/synthesis.c
index 51b2c2e5a..321bd79a5 100644
--- a/src/audio/lib/synthesis.c
+++ b/src/audio/lib/synthesis.c
@@ -5,7 +5,7 @@
 #define DMEM_TEMP 0x3C0
 #define DMEM_UNCOMPRESSED_NOTE 0x580
 #define DMEM_HAAS_TEMP 0x5C0
-#define DMEM_SCRATCH2 0x760              // = DMEM_TEMP + DMEM_2CH_SIZE + a bit more
+#define DMEM_COMB_TEMP 0x760             // = DMEM_TEMP + DMEM_2CH_SIZE + a bit more
 #define DMEM_COMPRESSED_ADPCM_DATA 0x940 // = DMEM_LEFT_CH
 #define DMEM_LEFT_CH 0x940
 #define DMEM_RIGHT_CH 0xAE0
@@ -38,14 +38,14 @@ u32 sEnvMixerOp = _SHIFTL(A_ENVMIXER, 24, 8);
 
 // Store the left dry channel in a temp space to be delayed to produce the haas effect
 u32 sEnvMixerLeftHaasDmemDests =
-    MK_CMD(DMEM_HAAS_TEMP >> 4, DMEM_RIGHT_CH >> 4, DMEM_WET_LEFT_CH >> 4, DMEM_WET_RIGHT_CH >> 4);
+    AUDIO_MK_CMD(DMEM_HAAS_TEMP >> 4, DMEM_RIGHT_CH >> 4, DMEM_WET_LEFT_CH >> 4, DMEM_WET_RIGHT_CH >> 4);
 
 // Store the right dry channel in a temp space to be delayed to produce the haas effect
 u32 sEnvMixerRightHaasDmemDests =
-    MK_CMD(DMEM_LEFT_CH >> 4, DMEM_HAAS_TEMP >> 4, DMEM_WET_LEFT_CH >> 4, DMEM_WET_RIGHT_CH >> 4);
+    AUDIO_MK_CMD(DMEM_LEFT_CH >> 4, DMEM_HAAS_TEMP >> 4, DMEM_WET_LEFT_CH >> 4, DMEM_WET_RIGHT_CH >> 4);
 
 u32 sEnvMixerDefaultDmemDests =
-    MK_CMD(DMEM_LEFT_CH >> 4, DMEM_RIGHT_CH >> 4, DMEM_WET_LEFT_CH >> 4, DMEM_WET_RIGHT_CH >> 4);
+    AUDIO_MK_CMD(DMEM_LEFT_CH >> 4, DMEM_RIGHT_CH >> 4, DMEM_WET_LEFT_CH >> 4, DMEM_WET_RIGHT_CH >> 4);
 
 u16 D_801304B0[] = {
     0x7FFF, 0xD001, 0x3FFF, 0xF001, 0x5FFF, 0x9001, 0x7FFF, 0x8001,
@@ -158,32 +158,32 @@ Acmd* AudioSynth_Update(Acmd* cmdStart, s32* cmdCnt, s16* aiStart, s32 aiBufLen)
     SynthesisReverb* reverb;
 
     cmdP = cmdStart;
-    for (i = gAudioCtx.audioBufferParameters.updatesPerFrame; i > 0; i--) {
+    for (i = gAudioCtx.audioBufferParameters.ticksPerUpdate; i > 0; i--) {
         AudioSeq_ProcessSequences(i - 1);
-        func_800DB03C(gAudioCtx.audioBufferParameters.updatesPerFrame - i);
+        func_800DB03C(gAudioCtx.audioBufferParameters.ticksPerUpdate - i);
     }
 
     aiBufP = aiStart;
     gAudioCtx.curLoadedBook = NULL;
 
-    for (i = gAudioCtx.audioBufferParameters.updatesPerFrame; i > 0; i--) {
+    for (i = gAudioCtx.audioBufferParameters.ticksPerUpdate; i > 0; i--) {
         if (i == 1) {
             chunkLen = aiBufLen;
-        } else if ((aiBufLen / i) >= gAudioCtx.audioBufferParameters.samplesPerUpdateMax) {
-            chunkLen = gAudioCtx.audioBufferParameters.samplesPerUpdateMax;
-        } else if (gAudioCtx.audioBufferParameters.samplesPerUpdateMin >= (aiBufLen / i)) {
-            chunkLen = gAudioCtx.audioBufferParameters.samplesPerUpdateMin;
+        } else if ((aiBufLen / i) >= gAudioCtx.audioBufferParameters.samplesPerTickMax) {
+            chunkLen = gAudioCtx.audioBufferParameters.samplesPerTickMax;
+        } else if (gAudioCtx.audioBufferParameters.samplesPerTickMin >= (aiBufLen / i)) {
+            chunkLen = gAudioCtx.audioBufferParameters.samplesPerTickMin;
         } else {
-            chunkLen = gAudioCtx.audioBufferParameters.samplesPerUpdate;
+            chunkLen = gAudioCtx.audioBufferParameters.samplesPerTick;
         }
 
         for (j = 0; j < gAudioCtx.numSynthesisReverbs; j++) {
             if (gAudioCtx.synthesisReverbs[j].useReverb) {
-                AudioSynth_InitNextRingBuf(chunkLen, gAudioCtx.audioBufferParameters.updatesPerFrame - i, j);
+                AudioSynth_InitNextRingBuf(chunkLen, gAudioCtx.audioBufferParameters.ticksPerUpdate - i, j);
             }
         }
 
-        cmdP = AudioSynth_DoOneAudioUpdate(aiBufP, chunkLen, cmdP, gAudioCtx.audioBufferParameters.updatesPerFrame - i);
+        cmdP = AudioSynth_DoOneAudioUpdate(aiBufP, chunkLen, cmdP, gAudioCtx.audioBufferParameters.ticksPerUpdate - i);
         aiBufLen -= chunkLen;
         aiBufP += 2 * chunkLen;
     }
@@ -203,7 +203,7 @@ void func_800DB2C0(s32 updateIndex, s32 noteIndex) {
     NoteSubEu* noteSubEu;
     s32 i;
 
-    for (i = updateIndex + 1; i < gAudioCtx.audioBufferParameters.updatesPerFrame; i++) {
+    for (i = updateIndex + 1; i < gAudioCtx.audioBufferParameters.ticksPerUpdate; i++) {
         noteSubEu = &gAudioCtx.noteSubsEu[(gAudioCtx.numNotes * i) + noteIndex];
         if (!noteSubEu->bitField0.needsInit) {
             noteSubEu->bitField0.enabled = false;
@@ -717,7 +717,7 @@ Acmd* AudioSynth_ProcessNote(s32 noteIndex, NoteSubEu* noteSubEu, NoteSynthesisS
     s32 frameIndex;
     s32 skipBytes;
     s32 temp_v1_6;
-    void* buf;
+    s16* combFilterState;
     s32 nSamplesToDecode;
     u32 sampleAddr;
     u32 samplesLenFixedPoint;
@@ -740,12 +740,12 @@ Acmd* AudioSynth_ProcessNote(s32 noteIndex, NoteSubEu* noteSubEu, NoteSynthesisS
     s32 resampledTempLen;
     u16 sampleDmemBeforeResampling;
     s32 sampleDataOffset;
-    s32 thing;
+    s32 combFilterDmem;
     s32 s5;
     Note* note;
     u32 numSamplesToLoad;
-    u16 unk7;
-    u16 unkE;
+    u16 combFilterSize;
+    u16 combFilterGain;
     s16* filter;
     s32 bookOffset;
     s32 finished;
@@ -769,7 +769,7 @@ Acmd* AudioSynth_ProcessNote(s32 noteIndex, NoteSubEu* noteSubEu, NoteSynthesisS
         synthState->prevHaasEffectRightDelaySize = 0;
         synthState->reverbVol = noteSubEu->reverbVol;
         synthState->numParts = 0;
-        synthState->unk_1A = 1;
+        synthState->combFilterNeedsInit = true;
         note->noteSubEu.bitField0.finished = false;
         finished = false;
     }
@@ -1089,23 +1089,26 @@ Acmd* AudioSynth_ProcessNote(s32 noteIndex, NoteSubEu* noteSubEu, NoteSynthesisS
         AudioSynth_LoadFilterBuffer(cmd++, flags, DMEM_TEMP, synthState->synthesisBuffers->mixEnvelopeState);
     }
 
-    unk7 = noteSubEu->unk_07;
-    unkE = noteSubEu->unk_0E;
-    buf = synthState->synthesisBuffers->unkState;
-    if (unk7 != 0 && noteSubEu->unk_0E != 0) {
-        AudioSynth_DMemMove(cmd++, DMEM_TEMP, DMEM_SCRATCH2, aiBufLen * SAMPLE_SIZE);
-        thing = DMEM_SCRATCH2 - unk7;
-        if (synthState->unk_1A != 0) {
-            AudioSynth_ClearBuffer(cmd++, thing, unk7);
-            synthState->unk_1A = 0;
+    // Apply the comb filter to the mono-signal by taking the signal with a small temporal offset,
+    // and adding it back to itself
+    combFilterSize = noteSubEu->combFilterSize;
+    combFilterGain = noteSubEu->combFilterGain;
+    combFilterState = synthState->synthesisBuffers->combFilterState;
+    if ((combFilterSize != 0) && (noteSubEu->combFilterGain != 0)) {
+        AudioSynth_DMemMove(cmd++, DMEM_TEMP, DMEM_COMB_TEMP, aiBufLen * SAMPLE_SIZE);
+        combFilterDmem = DMEM_COMB_TEMP - combFilterSize;
+        if (synthState->combFilterNeedsInit) {
+            AudioSynth_ClearBuffer(cmd++, combFilterDmem, combFilterSize);
+            synthState->combFilterNeedsInit = false;
         } else {
-            AudioSynth_LoadBuffer(cmd++, thing, unk7, buf);
+            AudioSynth_LoadBuffer(cmd++, combFilterDmem, combFilterSize, combFilterState);
         }
-        AudioSynth_SaveBuffer(cmd++, DMEM_TEMP + (aiBufLen * SAMPLE_SIZE) - unk7, unk7, buf);
-        AudioSynth_Mix(cmd++, (aiBufLen * (s32)SAMPLE_SIZE) >> 4, unkE, DMEM_SCRATCH2, thing);
-        AudioSynth_DMemMove(cmd++, thing, DMEM_TEMP, aiBufLen * SAMPLE_SIZE);
+        AudioSynth_SaveBuffer(cmd++, DMEM_TEMP + (aiBufLen * SAMPLE_SIZE) - combFilterSize, combFilterSize,
+                              combFilterState);
+        AudioSynth_Mix(cmd++, (aiBufLen * (s32)SAMPLE_SIZE) >> 4, combFilterGain, DMEM_COMB_TEMP, combFilterDmem);
+        AudioSynth_DMemMove(cmd++, combFilterDmem, DMEM_TEMP, aiBufLen * SAMPLE_SIZE);
     } else {
-        synthState->unk_1A = 1;
+        synthState->combFilterNeedsInit = true;
     }
 
     if ((noteSubEu->haasEffectLeftDelaySize != 0) || (synthState->prevHaasEffectLeftDelaySize != 0)) {