mirror/oot
1
0
Fork 0
mirror of https://github.com/zeldaret/oot synced 2026-06-03 18:36:34 -04:00
Code Issues Packages Projects Releases Wiki Activity

Document Audio Thread Commands (#1399)

Browse Source 
* 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>
This commit is contained in:
engineer124
2024-02-01 10:25:23 +11:00
committed by GitHub
parent d65fb6ed28
commit a0d31dba68
25 changed files with 1393 additions and 842 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/z64audio.h
+67 -51
View File
@@ -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,10 +977,15 @@ 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.