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, 67 insertions, 51 deletions

diff --git a/include/z64audio.h b/include/z64audio.h
index 7e6f4e40b..1ec0f4a4d 100644
--- a/include/z64audio.h
+++ b/include/z64audio.h
@@ -1,11 +1,25 @@
 #ifndef Z64_AUDIO_H
 #define Z64_AUDIO_H
 
-#define MK_CMD(b0,b1,b2,b3) ((((b0) & 0xFF) << 0x18) | (((b1) & 0xFF) << 0x10) | (((b2) & 0xFF) << 0x8) | (((b3) & 0xFF) << 0))
+typedef void (*AudioCustomUpdateFunction)(void);
+
+
+#define REFRESH_RATE_PAL 50
+#define REFRESH_RATE_MPAL 60
+#define REFRESH_RATE_NTSC 60
+
+// Small deviation parameters used in estimating the max tempo
+// It is unclear why these vary by region, and aren't all just 1
+#define REFRESH_RATE_DEVIATION_PAL 1.001521f
+#define REFRESH_RATE_DEVIATION_MPAL 0.99276f
+#define REFRESH_RATE_DEVIATION_NTSC 1.00278f
+
+#define AUDIO_MK_CMD(b0,b1,b2,b3) ((((b0) & 0xFF) << 0x18) | (((b1) & 0xFF) << 0x10) | (((b2) & 0xFF) << 0x8) | (((b3) & 0xFF) << 0))
 
 #define NO_LAYER ((SequenceLayer*)(-1))
 
-#define TATUMS_PER_BEAT 48
+// Also known as "Pulses Per Quarter Note" or "Tatums Per Beat"
+#define SEQTICKS_PER_BEAT 48
 
 #define IS_SEQUENCE_CHANNEL_VALID(ptr) ((u32)(ptr) != (u32)&gAudioCtx.sequenceChannelNone)
 #define SEQ_NUM_CHANNELS 16
@@ -297,12 +311,12 @@ typedef struct {
     /* 0x005 */ u8 defaultFont;
     /* 0x006 */ u8 unk_06[1];
     /* 0x007 */ s8 playerIdx;
-    /* 0x008 */ u16 tempo; // tatums per minute
-    /* 0x00A */ u16 tempoAcc;
-    /* 0x00C */ u16 unk_0C;
+    /* 0x008 */ u16 tempo; // seqTicks per minute
+    /* 0x00A */ u16 tempoAcc; // tempo accumulation, used in a discretized algorithm to apply tempo.
+    /* 0x00C */ u16 tempoChange; // Used to adjust the tempo without altering the base tempo.
     /* 0x00E */ s16 transposition;
     /* 0x010 */ u16 delay;
-    /* 0x012 */ u16 fadeTimer;
+    /* 0x012 */ u16 fadeTimer; // in ticks
     /* 0x014 */ u16 fadeTimerUnkEu;
     /* 0x018 */ u8* seqData;
     /* 0x01C */ f32 fadeVolume;
@@ -320,7 +334,7 @@ typedef struct {
     /* 0x0DC */ s32 skipTicks;
     /* 0x0E0 */ u32 scriptCounter;
     /* 0x0E4 */ char unk_E4[0x74]; // unused struct members for sequence/sound font dma management, according to sm64 decomp
-    /* 0x158 */ s8 soundScriptIO[8];
+    /* 0x158 */ s8 seqScriptIO[8];
 } SequencePlayer; // size = 0x160
 
 typedef struct {
@@ -332,7 +346,7 @@ typedef struct {
 typedef struct {
     /* 0x00 */ union {
         struct A {
-            /* 0x00 */ u8 unk_0b80 : 1;
+            /* 0x00 */ u8 unused : 1;
             /* 0x00 */ u8 hang : 1;
             /* 0x00 */ u8 decay : 1;
             /* 0x00 */ u8 release : 1;
@@ -370,8 +384,8 @@ typedef struct {
     /* 0x01 */ u8 gain; // Increases volume by a multiplicative scaling factor. Represented as a UQ4.4 number
     /* 0x02 */ u8 pan;
     /* 0x03 */ Stereo stereo;
-    /* 0x04 */ u8 unk_4;
-    /* 0x06 */ u16 unk_6;
+    /* 0x04 */ u8 combFilterSize;
+    /* 0x06 */ u16 combFilterGain;
     /* 0x08 */ f32 freqScale;
     /* 0x0C */ f32 velocity;
     /* 0x10 */ s16* filter;
@@ -383,7 +397,7 @@ typedef struct SequenceChannel {
     /* 0x00 */ u8 enabled : 1;
     /* 0x00 */ u8 finished : 1;
     /* 0x00 */ u8 stopScript : 1;
-    /* 0x00 */ u8 stopSomething2 : 1; // sets SequenceLayer.stopSomething
+    /* 0x00 */ u8 muted : 1; // sets SequenceLayer.muted
     /* 0x00 */ u8 hasInstrument : 1;
     /* 0x00 */ u8 stereoHeadsetEffects : 1;
     /* 0x00 */ u8 largeNotes : 1; // notes specify duration and velocity
@@ -398,7 +412,7 @@ typedef struct SequenceChannel {
     } changes;
     /* 0x02 */ u8 noteAllocPolicy;
     /* 0x03 */ u8 muteBehavior;
-    /* 0x04 */ u8 reverb;       // or dry/wet mix
+    /* 0x04 */ u8 targetReverbVol;
     /* 0x05 */ u8 notePriority; // 0-3
     /* 0x06 */ u8 someOtherPriority;
     /* 0x07 */ u8 fontId;
@@ -409,16 +423,16 @@ typedef struct SequenceChannel {
     /* 0x0C */ u8 gain; // Increases volume by a multiplicative scaling factor. Represented as a UQ4.4 number
     /* 0x0D */ u8 velocityRandomVariance;
     /* 0x0E */ u8 gateTimeRandomVariance;
-    /* 0x0F */ u8 unk_0F;
+    /* 0x0F */ u8 combFilterSize;
     /* 0x10 */ u16 vibratoRateStart;
-    /* 0x12 */ u16 vibratoExtentStart;
+    /* 0x12 */ u16 vibratoDepthStart;
     /* 0x14 */ u16 vibratoRateTarget;
-    /* 0x16 */ u16 vibratoExtentTarget;
+    /* 0x16 */ u16 vibratoDepthTarget;
     /* 0x18 */ u16 vibratoRateChangeDelay;
-    /* 0x1A */ u16 vibratoExtentChangeDelay;
+    /* 0x1A */ u16 vibratoDepthChangeDelay;
     /* 0x1C */ u16 vibratoDelay;
     /* 0x1E */ u16 delay;
-    /* 0x20 */ u16 unk_20;
+    /* 0x20 */ u16 combFilterGain;
     /* 0x22 */ u16 unk_22;
     /* 0x24 */ s16 instOrWave; // either 0 (none), instrument index + 1, or
                              // 0x80..0x83 for sawtooth/triangle/sine/square waves.
@@ -437,7 +451,7 @@ typedef struct SequenceChannel {
     /* 0x60 */ SeqScriptState scriptState;
     /* 0x7C */ AdsrSettings adsr;
     /* 0x84 */ NotePool notePool;
-    /* 0xC4 */ s8 soundScriptIO[8]; // bridge between sound script and audio lib, "io ports"
+    /* 0xC4 */ s8 seqScriptIO[8]; // bridge between .seq script and audio lib, "io ports"
     /* 0xCC */ s16* filter;
     /* 0xD0 */ Stereo stereo;
 } SequenceChannel; // size = 0xD4
@@ -446,7 +460,7 @@ typedef struct SequenceChannel {
 typedef struct SequenceLayer {
     /* 0x00 */ u8 enabled : 1;
     /* 0x00 */ u8 finished : 1;
-    /* 0x00 */ u8 stopSomething : 1;
+    /* 0x00 */ u8 muted : 1;
     /* 0x00 */ u8 continuousNotes : 1; // keep the same note for consecutive notes with the same sound
     /* 0x00 */ u8 bit3 : 1; // "loaded"?
     /* 0x00 */ u8 ignoreDrumPan : 1;
@@ -490,7 +504,7 @@ typedef struct {
     /* 0x040 */ s16 mixEnvelopeState[32];
     /* 0x080 */ s16 unusedState[16];
     /* 0x0A0 */ s16 haasEffectDelayState[32];
-    /* 0x0E0 */ s16 unkState[128];
+    /* 0x0E0 */ s16 combFilterState[128];
 } NoteSynthesisBuffers; // size = 0x1E0
 
 typedef struct {
@@ -505,23 +519,20 @@ typedef struct {
     /* 0x0C */ NoteSynthesisBuffers* synthesisBuffers;
     /* 0x10 */ s16 curVolLeft;
     /* 0x12 */ s16 curVolRight;
-    /* 0x14 */ u16 unk_14;
-    /* 0x16 */ u16 unk_16;
-    /* 0x18 */ u16 unk_18;
-    /* 0x1A */ u8 unk_1A;
-    /* 0x1C */ u16 unk_1C;
-    /* 0x1E */ u16 unk_1E;
+    /* 0x14 */ char unk_14[0x6];
+    /* 0x1A */ u8 combFilterNeedsInit;
+    /* 0x1C */ char unk_1C[0x4];
 } NoteSynthesisState; // size = 0x20
 
 typedef struct {
     /* 0x00 */ struct SequenceChannel* channel;
     /* 0x04 */ u32 time;
-    /* 0x08 */ s16* curve;
-    /* 0x0C */ f32 extent;
+    /* 0x08 */ s16* curve; // sineWave
+    /* 0x0C */ f32 depth;
     /* 0x10 */ f32 rate;
     /* 0x14 */ u8 active;
     /* 0x16 */ u16 rateChangeTimer;
-    /* 0x18 */ u16 extentChangeTimer;
+    /* 0x18 */ u16 depthChangeTimer;
     /* 0x1A */ u16 delay;
 } VibratoState; // size = 0x1C
 
@@ -567,11 +578,11 @@ typedef struct {
     /* 0x04 */ u8 haasEffectRightDelaySize;
     /* 0x05 */ u8 reverbVol;
     /* 0x06 */ u8 harmonicIndexCurAndPrev; // bits 3..2 store curHarmonicIndex, bits 1..0 store prevHarmonicIndex
-    /* 0x07 */ u8 unk_07;
+    /* 0x07 */ u8 combFilterSize;
     /* 0x08 */ u16 targetVolLeft;
     /* 0x0A */ u16 targetVolRight;
     /* 0x0C */ u16 resamplingRateFixedPoint;
-    /* 0x0E */ u16 unk_0E;
+    /* 0x0E */ u16 combFilterGain;
     /* 0x10 */ union {
                  TunedSample* tunedSample;
                  s16* waveSampleAddr; // used for synthetic waves
@@ -642,15 +653,15 @@ typedef struct {
     /* 0x06 */ s16 samplesPerFrameTarget;
     /* 0x08 */ s16 maxAiBufferLength;
     /* 0x0A */ s16 minAiBufferLength;
-    /* 0x0C */ s16 updatesPerFrame; // for each frame of the audio thread (default 60 fps), number of updates to process audio
-    /* 0x0E */ s16 samplesPerUpdate;
-    /* 0x10 */ s16 samplesPerUpdateMax;
-    /* 0x12 */ s16 samplesPerUpdateMin;
+    /* 0x0C */ s16 ticksPerUpdate; // for each audio thread update, number of ticks to process audio
+    /* 0x0E */ s16 samplesPerTick;
+    /* 0x10 */ s16 samplesPerTickMax;
+    /* 0x12 */ s16 samplesPerTickMin;
     /* 0x14 */ s16 numSequencePlayers;
     /* 0x18 */ f32 resampleRate;
-    /* 0x1C */ f32 updatesPerFrameInv; // inverse (reciprocal) of updatesPerFrame
-    /* 0x20 */ f32 updatesPerFrameInvScaled; // updatesPerFrameInv scaled down by a factor of 256
-    /* 0x24 */ f32 updatesPerFrameScaled; // updatesPerFrame scaled down by a factor of 4
+    /* 0x1C */ f32 ticksPerUpdateInv; // inverse (reciprocal) of ticksPerUpdate
+    /* 0x20 */ f32 ticksPerUpdateInvScaled; // ticksPerUpdateInv scaled down by a factor of 256
+    /* 0x24 */ f32 ticksPerUpdateScaled; // ticksPerUpdate scaled down by a factor of 4
 } AudioBufferParameters; // size = 0x28
 
 /**
@@ -887,7 +898,7 @@ typedef struct {
     /* 0x288C */ s32 sampleDmaBufSize;
     /* 0x2890 */ s32 maxAudioCmds;
     /* 0x2894 */ s32 numNotes;
-    /* 0x2898 */ s16 tempoInternalToExternal;
+    /* 0x2898 */ s16 maxTempo; // Maximum possible tempo (seqTicks per minute), using every tick as a seqTick to process a .seq file
     /* 0x289A */ s8 soundMode;
     /* 0x289C */ s32 totalTaskCount; // The total number of times the top-level function on the audio thread has run since audio was initialized
     /* 0x28A0 */ s32 curAudioFrameDmaCount;
@@ -898,7 +909,7 @@ typedef struct {
     /* 0x28B8 */ AudioTask* curTask;
     /* 0x28BC */ char unk_28BC[0x4];
     /* 0x28C0 */ AudioTask rspTask[2];
-    /* 0x2960 */ f32 unk_2960;
+    /* 0x2960 */ f32 maxTempoTvTypeFactors; // tvType factors that impact maxTempo, in units of milliseconds/frame
     /* 0x2964 */ s32 refreshRate;
     /* 0x2968 */ s16* aiBuffers[3];
     /* 0x2974 */ s16 aiBufLengths[3];
@@ -929,7 +940,7 @@ typedef struct {
     /* 0x3468 */ u8 fontLoadStatus[0x30];
     /* 0x3498 */ u8 seqLoadStatus[0x80];
     /* 0x3518 */ volatile u8 resetStatus;
-    /* 0x3519 */ u8 audioResetSpecIdToLoad;
+    /* 0x3519 */ u8 specId;
     /* 0x351C */ s32 audioResetFadeOutFramesLeft;
     /* 0x3520 */ f32* adsrDecayTable; // A table on the audio heap that stores decay rates used for adsr
     /* 0x3524 */ u8* audioHeap;
@@ -941,20 +952,20 @@ typedef struct {
     /* 0x5B84 */ s32 noteSubEuOffset;
     /* 0x5B88 */ AudioListItem layerFreeList;
     /* 0x5B98 */ NotePool noteFreeLists;
-    /* 0x5BD8 */ u8 cmdWrPos;
-    /* 0x5BD9 */ u8 cmdRdPos;
-    /* 0x5BDA */ u8 cmdQueueFinished;
-    /* 0x5BDC */ u16 unk_5BDC[4];
+    /* 0x5BD8 */ u8 threadCmdWritePos;
+    /* 0x5BD9 */ u8 threadCmdReadPos;
+    /* 0x5BDA */ u8 threadCmdQueueFinished;
+    /* 0x5BDC */ u16 threadCmdChannelMask[4]; // bitfield for 16 channels. When processing an audio thread channel command on all channels, only process channels with their bit set.
     /* 0x5BE4 */ OSMesgQueue* audioResetQueueP;
     /* 0x5BE8 */ OSMesgQueue* taskStartQueueP;
-    /* 0x5BEC */ OSMesgQueue* cmdProcQueueP;
+    /* 0x5BEC */ OSMesgQueue* threadCmdProcQueueP;
     /* 0x5BF0 */ OSMesgQueue taskStartQueue;
-    /* 0x5C08 */ OSMesgQueue cmdProcQueue;
+    /* 0x5C08 */ OSMesgQueue threadCmdProcQueue;
     /* 0x5C20 */ OSMesgQueue audioResetQueue;
     /* 0x5C38 */ OSMesg taskStartMsgBuf[1];
     /* 0x5C3C */ OSMesg audioResetMsgBuf[1];
-    /* 0x5C40 */ OSMesg cmdProcMsgBuf[4];
-    /* 0x5C50 */ AudioCmd cmdBuf[0x100]; // Audio commands used to transfer audio requests from the graph thread to the audio thread
+    /* 0x5C40 */ OSMesg threadCmdProcMsgBuf[4];
+    /* 0x5C50 */ AudioCmd threadCmdBuf[0x100]; // Audio thread commands used to transfer audio requests from the graph thread to the audio thread
 } AudioContext; // size = 0x6450
 
 typedef struct {
@@ -966,11 +977,16 @@ typedef struct {
     /* 0x08 */ f32 velocity;
     /* 0x0C */ char unk_0C[0x4];
     /* 0x10 */ s16* filter;
-    /* 0x14 */ u8 unk_14;
-    /* 0x16 */ u16 unk_16;
+    /* 0x14 */ u8 combFilterSize;
+    /* 0x16 */ u16 combFilterGain;
 } NoteSubAttributes; // size = 0x18
 
 typedef struct {
+    /* 0x0 */ s16 unk_00; // set to 0x1C00, unused
+    /* 0x2 */ s16 seqTicksPerBeat;
+} TempoData; // size = 0x4
+
+typedef struct {
     /* 0x00 */ u32 heapSize; // total number of bytes allocated to the audio heap. Must be <= the size of `gAudioHeap` (ideally about the same size)
     /* 0x04 */ u32 initPoolSize; // The entire audio heap is split into two pools.
     /* 0x08 */ u32 permanentPoolSize;