sound
The Sound guide explains this folder.
audio.c
Functions
Pcm_KeyToFrequency
s32 Pcm_KeyToFrequency(void *wave, u8 key, u8 pitch)
Interpolates adjacent key frequencies and scales them by the wave sample frequency. Called by the song player for each PCM note.
Audio_NoopStub
void Audio_NoopStub(void)
Provides the empty callback retained by the sound driver.
Audio_ResumePlayer
void Audio_ResumePlayer(struct SoundPlayer *player)
Clears the player's paused flag while holding the player lock. Called by the resume and play-or-resume commands.
Used by Audio_PlayOrResumeSound, Audio_ResumeAllPlayers, Audio_ResumeSound, MusicPlayer_Resume.
MusicPlayer_SetFadeParameters
static __inline__ void MusicPlayer_SetFadeParameters(struct SoundPlayer *player, u16 period, u16 volume)
Starts a fade under the player lock, resuming the player for fade-ins.
Used by MusicPlayer_BeginFadeOut, MusicPlayer_FadeIn, MusicPlayer_FadeOutPause.
MusicPlayer_BeginFadeOut
void MusicPlayer_BeginFadeOut(struct SoundPlayer *player, u16 speed)
Begins a fade that stops and clears tracks when its volume reaches zero. Called by MusicPlayer_FadeOut.
Used by MusicPlayer_FadeOut.
Audio_Initialize
void Audio_Initialize(void)
Copies the RAM mixer to IWRAM, initializes the PCM and CGB paths and configures every player from gSound_PlayerSlots. Called by Audio_InitializeRuntimeDefaults at power-on.
Used by Audio_InitializeRuntimeDefaults.
Audio_PlaySound
void Audio_PlaySound(u16 songId)
Starts the song on the player selected by its song-table entry. Called by AudioCommand_Play.
Used by AudioCommand_Play.
Audio_PlaySoundIfInactive
UNUSED void Audio_PlaySoundIfInactive(u16 songId)
Starts the song unless its selected player is already playing it. Nothing in ☀️ calls it.
Audio_PlayOrResumeSound
UNUSED void Audio_PlayOrResumeSound(u16 songId)
Starts a different or finished song, or resumes the same paused song. Nothing in ☀️ calls it.
Audio_StopSound
UNUSED void Audio_StopSound(u16 songId)
Stops the selected player only when it holds this song. Nothing in ☀️ calls it.
Audio_ResumeSound
UNUSED void Audio_ResumeSound(u16 songId)
Resumes the selected player only when it holds this song. Nothing in ☀️ calls it.
Audio_StopAllPlayers
UNUSED void Audio_StopAllPlayers(void)
Stops every player. Nothing in ☀️ calls it.
Used by AudioCommand_StopAllPlayers.
MusicPlayer_Resume
UNUSED void MusicPlayer_Resume(struct SoundPlayer *player)
Resumes player. Nothing in ☀️ calls it.
Audio_ResumeAllPlayers
UNUSED void Audio_ResumeAllPlayers(void)
Resumes every player. Nothing in ☀️ calls it.
Used by AudioCommand_ResumeAllPlayers.
MusicPlayer_FadeOut
void MusicPlayer_FadeOut(struct SoundPlayer *player, u16 speed)
Begins the standard stop-and-clear fade. Called by AudioCommand_Play's fade cues.
Used by AudioCommand_Play.
MusicPlayer_FadeOutPause
UNUSED void MusicPlayer_FadeOutPause(struct SoundPlayer *player, u16 speed)
Begins a fade that pauses the player at zero volume, keeping its tracks' state for a later resume. Nothing in ☀️ calls it.
MusicPlayer_FadeIn
UNUSED void MusicPlayer_FadeIn(struct SoundPlayer *player, u16 speed)
Starts a fade from zero volume and resumes the player. Nothing in ☀️ calls it.
MusicPlayer_ResetActiveTracks
UNUSED void MusicPlayer_ResetActiveTracks(struct SoundPlayer *player)
Initializes active tracks still carrying their reset flag: clears their settings and gives them the default bend range, volume and LFO speed. Nothing in ☀️ calls it.
CgbAudio_Initialize
void CgbAudio_Initialize(struct CgbNote *notes)
Resets the CGB sound hardware, installs the CGB-aware command handlers and
callbacks in the sound work, and clears the four channel records notes.
Called by Audio_Initialize.
Used by Audio_Initialize.
Also, functions without a comment: AudioEngine_RunMixer.
Macros
SOUND_MIXER_CODE_SIZE
#define SOUND_MIXER_CODE_SIZE 0x400
The bytes of mixer code Audio_Initialize copies to IWRAM.
Used by Audio_Initialize.
Also, macros without a comment: SOUND_PLAYER_COUNT, SOUND_MAX_LINES.
Globals, without a comment: gSound_PcmPitchCodes, gSound_PcmFrequencySteps, Sound_PlayerCount, Sound_MaxLines, gSound_Work, gSound_CgbNotes, gSound_WorkBytes, gSound_PlayerSlots, gSound_SongTable, gSound_CommandTable.
Declarations, without a comment: Audio_UmulHigh32, Sound_Mixer, AudioEngine_RunMixerTick, MusicTrack_SetLfoSpeedFromCommand, MusicTrack_SetModulationFromCommand, MusicTrack_ReleaseKey, MusicTrack_Stop.
empty_callback.c
games/tbs/src/sound/empty_callback.c
Functions
Audio_EmptyCallback
void Audio_EmptyCallback(void)
Provides the default empty callback before the sound driver installs its handlers.
Used by AudioEngine_Initialize.
engine.c
Functions
AudioCommand_InvokeSlot34
void AudioCommand_InvokeSlot34(struct SoundNote *note)
Detaches a note through the command table entry installed by the driver. Called by the song player (MusicPlayer_Tick, MusicTrack_HandleNote).
AudioCommand_InvokeSlot35
void AudioCommand_InvokeSlot35(void *block)
Clears a 64-byte player or track prefix through the driver command table. Called by the song player and MusicPlayer_ResetActiveTracks.
Used by MusicPlayer_Initialize, MusicPlayer_ResetActiveTracks.
AudioEngine_Initialize
void AudioEngine_Initialize(struct SoundWork *work)
Resets the sound hardware, clears the whole sound work block and installs
the default PCM driver: stores work in SOUND_WORK, points the FIFO DMAs at
its two buffers, fills in the driver callbacks and command table, sets the
default rate and finally sets the work's lock. Called by Audio_Initialize.
Used by Audio_Initialize.
AudioEngine_SetPcmRate
void AudioEngine_SetPcmRate(u32 mode)
Sets the PCM frame length (mode bits 16 to 19 pick a gSound_FrameLengths
entry) and the rates derived from it, and Timer 0's reload, starting
playback at scanline 159. Called by AudioEngine_Initialize and
AudioEngine_SetMode, and by songs through the command table.
Used by AudioEngine_Initialize, AudioEngine_SetMode, CgbAudio_Initialize, gSound_CommandTableTemplate.
AudioEngine_SetMode
void AudioEngine_SetMode(u32 mode)
Applies the reverb, channel-count, volume, bias and sample-rate fields of
mode to the sound work, under its lock. Called by Audio_Initialize.
Used by Audio_Initialize, MusicPlayer_StartSong.
AudioEngine_StopAllChannels
UNUSED void AudioEngine_StopAllChannels(void)
Silences every PCM and CGB note while holding the sound work lock. Nothing in ☀️ calls it.
AudioEngine_SuspendDirectSound
void AudioEngine_SuspendDirectSound(void)
Stops both FIFO transfers and clears their sample buffers, raising the work's lock until AudioEngine_ResumeDirectSound. Called by AudioEngine_SetMode around a rate change.
Used by AudioEngine_SetMode.
AudioEngine_ResumeDirectSound
void AudioEngine_ResumeDirectSound(void)
Restarts both FIFO transfers and releases the suspended-work lock. Called by AudioEngine_SetPcmRate.
Used by AudioEngine_SetPcmRate.
MusicPlayer_Initialize
void MusicPlayer_Initialize(struct SoundPlayer *player, struct SoundTrack *tracks, u8 trackCount)
Deactivates up to sixteen tracks and links the player into the mixer tick chain.
Used by Audio_Initialize.
MusicPlayer_StartSong
void MusicPlayer_StartSong(struct SoundPlayer *player, const struct SequenceHeader *header)
Starts a song when its priority permits, resetting its tracks and tempo.
Used by AudioCommand_Play, Audio_PlayOrResumeSound, Audio_PlaySound, Audio_PlaySoundIfInactive.
MusicPlayer_Stop
void MusicPlayer_Stop(struct SoundPlayer *player)
Pauses this player and stops all of its tracks, under the player's lock. Called by Audio_StopSound and Audio_StopAllPlayers.
Used by Audio_StopAllPlayers, Audio_StopSound.
MusicPlayer_StepFade
void MusicPlayer_StepFade(struct SoundPlayer *player)
Advances a due fade step, updating active track volumes, or at the end of a fade out stops (or pauses) the player. Called by the song player each tick through the command table.
Used by CgbAudio_Initialize, gSound_CommandTableTemplate.
MusicTrack_CalcOutput
void MusicTrack_CalcOutput(struct SoundPlayer *player, struct SoundTrack *track)
Recalculates dirty stereo volumes and pitch from track settings and modulation.
Used by CgbAudio_Initialize, gSound_CommandTableTemplate.
Cgb_KeyToFrequency
s32 Cgb_KeyToFrequency(u8 kind, u8 key, u8 fine)
Converts a key and fractional pitch to a CGB tone or noise-register value. Installed as the work's cgbFrequency callback by CgbAudio_Initialize.
Used by CgbAudio_Initialize.
CgbChannel_Mute
void CgbChannel_Mute(u8 channel)
Disables one CGB channel using its envelope or wave-control register. Called by Cgb_UpdateChannels, and installed as the work's cgbMute callback.
Used by CgbAudio_Initialize, Cgb_UpdateChannels.
CgbNote_UpdatePanEnvelope
void CgbNote_UpdatePanEnvelope(struct CgbNote *note)
Chooses stereo routing and derives peak and sustain levels for a CGB note,
writing them into note. Called by Cgb_UpdateChannels. Its separate peak
calculations and jumps are the form the bytes show: shared, tbs-en is four
bytes shorter.
Used by Cgb_UpdateChannels.
Cgb_UpdateChannels
void Cgb_UpdateChannels(void)
Steps CGB note envelopes and writes changed pitch, volume and trigger registers, once a frame. Installed as the work's cgbUpdate callback by CgbAudio_Initialize; the mixer calls it.
Used by CgbAudio_Initialize.
MusicPlayer_SetPitchAndUpdateFrequency
void MusicPlayer_SetPitchAndUpdateFrequency(struct SoundPlayer *player, u16 scale)
Sets the tempo multiplier and updates the number of ticks advanced per frame.
Used by MusicCommand_SetPitchAndUpdateFrequency, MusicPlayer_StepVolumeAndPitchTowardTargets.
MusicPlayer_SetVolume
void MusicPlayer_SetVolume(struct SoundPlayer *player, u16 mask, u16 volume)
Sets the volume scale of active tracks selected by the bit mask and marks their output for recalculation. Called by the music layer's volume ramps and commands (sound.c).
Used by AudioCommand_Play, MusicCommand_SetVolume, MusicPlayer_StepVolumeAndPitchTowardTargets.
MusicPlayer_SetPitch
void MusicPlayer_SetPitch(struct SoundPlayer *player, u16 mask, s16 pitch)
Sets the semitone and fractional pitch offsets of selected active tracks and marks their pitch for recalculation. Called by the music layer's pitch ramps and commands (sound.c).
Used by MusicCommand_SetPitch, MusicPlayer_StepVolumeAndPitchTowardTargets.
MusicPlayer_SetPan
UNUSED void MusicPlayer_SetPan(struct SoundPlayer *player, u16 mask, s8 pan)
Sets the stereo pan offset of selected active tracks. Nothing in ☀️ calls it.
MusicTrack_ClearModulation
void MusicTrack_ClearModulation(struct SoundTrack *track)
Resets the LFO phase and amount, marking the affected output for recalculation.
Used by MusicPlayer_SetLfoSpeed, MusicPlayer_SetModulationDepth.
MusicPlayer_SetModulationDepth
void MusicPlayer_SetModulationDepth(struct SoundPlayer *player, s32 selectedTracks, s32 depthArgument)
Sets modulation depth on selected active tracks, resetting zero-depth modulation.
MusicPlayer_SetLfoSpeed
void MusicPlayer_SetLfoSpeed(struct SoundPlayer *player, u32 selectedTracks, u32 speedArgument)
Sets LFO speed on selected active tracks, resetting modulation when stopped.
MusicTrack_OperateWorkByte
void MusicTrack_OperateWorkByte(struct SoundPlayer *player, struct SoundTrack *track)
Executes a work-byte operation and consumes a branch address for comparisons.
Used by CgbAudio_Initialize.
MusicTrack_DispatchStreamCommand
void MusicTrack_DispatchStreamCommand(struct SoundPlayer *player, struct SoundTrack *track)
Reads an extended-command index and invokes its handler.
Used by CgbAudio_Initialize.
Runtime_CallWorkEntryWithArgs
void Runtime_CallWorkEntryWithArgs(struct SoundPlayer *player, struct SoundTrack *track)
Finishes a track through the base command table entry.
Used by gSound_ExtendedCommandTable.
MusicTrack_ReadVoiceTarget
void MusicTrack_ReadVoiceTarget(struct SoundPlayer *player, struct SoundTrack *track)
Reads an unaligned little-endian voice target address from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetVoiceKind
void MusicTrack_SetVoiceKind(struct SoundPlayer *player, struct SoundTrack *track)
Reads the voice kind from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetVoiceAttack
void MusicTrack_SetVoiceAttack(struct SoundPlayer *player, struct SoundTrack *track)
Reads the voice attack rate from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetVoiceDecay
void MusicTrack_SetVoiceDecay(struct SoundPlayer *player, struct SoundTrack *track)
Reads the voice decay rate from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetVoiceSustain
void MusicTrack_SetVoiceSustain(struct SoundPlayer *player, struct SoundTrack *track)
Reads the voice sustain level from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetVoiceRelease
void MusicTrack_SetVoiceRelease(struct SoundPlayer *player, struct SoundTrack *track)
Reads the voice release rate from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetTailLevel
void MusicTrack_SetTailLevel(struct SoundPlayer *player, struct SoundTrack *track)
Reads the note tail volume from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetTailLength
void MusicTrack_SetTailLength(struct SoundPlayer *player, struct SoundTrack *track)
Reads the note tail duration from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetVoiceLength
void MusicTrack_SetVoiceLength(struct SoundPlayer *player, struct SoundTrack *track)
Reads the hardware note length from the sequence.
Used by gSound_ExtendedCommandTable.
MusicTrack_SetVoicePanOrSweep
void MusicTrack_SetVoicePanOrSweep(struct SoundPlayer *player, struct SoundTrack *track)
Reads the voice pan or CGB sweep setting from the sequence.
Used by gSound_ExtendedCommandTable.
Unions
PackedWord
union PackedWord
A word put together from its four bytes, lowest first.
| Field | Declared as | |
|---|---|---|
value | u32 value | |
byte0, byte1, byte2, byte3, part | struct { u32 byte0 : 8; u32 byte1 : 8; u32 byte2 : 8; u32 byte3 : 8; } part |
Used by MusicTrack_ReadVoiceTarget.
Macros
SOUND_PCM_BUFFER_SIZE
#define SOUND_PCM_BUFFER_SIZE 0x630
The PCM buffer's size in samples, a multiple of every frame length: the DMA plays it round and round.
Used by AudioEngine_SetPcmRate.
SOUND_FRAME_RATE_E4
#define SOUND_FRAME_RATE_E4 597275
The display's frame rate in ten-thousandths of a hertz: 59.7275 frames a second.
Used by AudioEngine_SetPcmRate.
SOUND_CYCLES_PER_FRAME
#define SOUND_CYCLES_PER_FRAME (228 * 1232)
CPU cycles in a frame: 228 lines of 1232 cycles.
Used by AudioEngine_SetPcmRate.
Globals, without a comment: gSound_FrameLengths, gSound_CommandTable, gSound_CgbPitchCodes, gSound_CgbFrequencySteps, gSound_NoisePitchCodes, gSound_Cgb3LevelCodes.
Declarations, without a comment: Sound_LoadCommandTable, MusicTrack_HandleNote, MusicPlayer_Tick.
sound.c
Functions
AudioCommand_Play
void AudioCommand_Play(s32 id)
Dispatches a packed cue: fade controls, allocated sound effects, fanfares, or background music with an optional silent start. Reached through the sound far-call table as AudioCommand_PlayFar, which the whole game calls to play music and sound effects; it updates the music layer's cue records.
Used by AudioTest_RunParameterController.
MusicPlayer_StepVolumeAndPitchTowardTargets
void MusicPlayer_StepVolumeAndPitchTowardTargets(void)
Restores BGM after a fanfare and steps its volume and combined tempo/pitch ramps once per VBlank, clamping each ramp when it crosses its target. Called by System_VBlankHandler through the sound far-call table.
AudioTest_RunParameterController
void AudioTest_RunParameterController(void)
Runs the audio test's three cue selectors and five mixer presets forever. Buttons play, fade or adjust the selected cue while frames keep advancing. Reached only through the sound far-call table's veneer; nothing in ☀️ names it.
Audio_InitializeRuntimeDefaults
void Audio_InitializeRuntimeDefaults(void)
Starts the sound driver, resets the BGM ramps (gMusicVolume and its kin) and clears all player cue records. Called by System_Initialize through the sound far-call table.
MusicCommand_SetPitchAndUpdateFrequency
void MusicCommand_SetPitchAndUpdateFrequency(u16 tempoScale)
Sets the BGM tempo scale directly; 0x100 preserves its native tempo. Called through the far-call table, by the Lemurian ship's sailing among others.
Used by SetSail.
MusicCommand_SetPitch
void MusicCommand_SetPitch(u16 pitch)
Applies a pitch offset to every active BGM track. Reached only through the sound far-call table's veneer.
Audio_SetWorkPairB
void Audio_SetWorkPairB(u16 targetScale, u16 step)
Sets the target and per-frame step of the combined BGM tempo/pitch ramp. Reached only through the sound far-call table's veneer.
MusicCommand_SetVolume
void MusicCommand_SetVolume(s16 volume)
Sets BGM volume immediately and cancels any outstanding volume ramp. Reached only through the sound far-call table's veneer.
Audio_SetMusicVolumeTargetAndStep
void Audio_SetMusicVolumeTargetAndStep(u16 targetVolume, u16 step)
Sets the BGM volume target and its per-frame adjustment. Reached only through the sound far-call table's veneer.
AudioCommand_GetStateByte
s32 AudioCommand_GetStateByte(void)
Returns the remaining delay before BGM can be restored after a fanfare.
Used by ColossoLogRollingStage_RunScriptedTransition, ColossoRiver_ShowMatchResult, ColossoRiver_ShowRoundIntroduction, ColossoWall_ShowBattleResultLettering, ColossoWall_ShowRoundStartLettering, FieldScene_RunScene3bcSequenceA.
AudioCommand_StopAllPlayers
void AudioCommand_StopAllPlayers(void)
Stops every sound player while preserving its state for a later resume.
AudioCommand_UpdateToggleMask
void AudioCommand_UpdateToggleMask(u32 command)
Replaces the audio command mask, or toggles its requested bits when flagged. Reached only through the sound far-call table's veneer.
AudioCommand_GetSecondaryStateByte
s32 AudioCommand_GetSecondaryStateByte(void)
Returns the last BGM cue or fade state selected by AudioCommand_Play.
AudioCommand_WaitForCompletion
void AudioCommand_WaitForCompletion(void)
Waits a frame at a time for fanfare restoration, giving up after 300 frames. Called by scenes before they go on after a fanfare (Sol Sanctum's quest acceptance among them).
AudioCommand_GetWidth
UNUSED s32 AudioCommand_GetWidth(s32 command)
Returns the mixer preset chosen by the cue dispatcher. Nothing in ☀️ calls it.
Also, functions without a comment: AudioCommand_ResumeAllPlayers.
tables.c
Types, without a comment: SoundFunc, SoundCommand.
Globals
gSound_PcmPitchCodes
const u8 gSound_PcmPitchCodes[]
PCM pitches: the high four bits hold the octave, the low four the note.
Used by Pcm_KeyToFrequency.
gSound_PcmFrequencySteps
const u32 gSound_PcmFrequencySteps[]
Frequencies by note at octave zero, in 32-bit fixed point.
Used by Pcm_KeyToFrequency.
gSound_FrameLengths
const u16 gSound_FrameLengths[]
Samples per frame for each playback frequency setting.
Used by AudioEngine_SetPcmRate.
gSound_CgbPitchCodes
const u8 gSound_CgbPitchCodes[]
CGB channel pitches.
Used by Cgb_KeyToFrequency.
gSound_CgbFrequencySteps
const s16 gSound_CgbFrequencySteps[]
Frequencies by note for CGB channels.
Used by Cgb_KeyToFrequency.
gSound_NoisePitchCodes
const u8 gSound_NoisePitchCodes[]
Noise channel pitches.
Used by Cgb_KeyToFrequency.
gSound_Cgb3LevelCodes
const u8 gSound_Cgb3LevelCodes[]
CGB channel 3 waveform volumes.
Used by Cgb_UpdateChannels.
gSound_ClockLengths
const u8 gSound_ClockLengths[]
Note durations in clock ticks.
gSound_ExtendedCommandTable
const SoundCommand gSound_ExtendedCommandTable[]
Extended commands; entries zero and three do nothing.
Used by MusicTrack_DispatchStreamCommand.
Also, globals without a comment: gSound_CommandTableTemplate.
Declarations, without a comment: MusicTrack_FinishSequence, MusicTrack_Goto, MusicTrack_CallPattern, MusicTrack_ReturnFromPattern, MusicTrack_Repeat, MusicTrack_SetPriorityFromCommand, MusicPlayer_SetTempoFromCommand, MusicTrack_SetKeyOffsetFromCommand, MusicTrack_SetVoiceFromCommand, MusicTrack_SetVolumeFromCommand, MusicTrack_SetPanFromCommand, MusicTrack_SetBendFromCommand, MusicTrack_SetBendRangeFromCommand, MusicTrack_SetLfoDelayFromCommand, MusicTrack_SetModulationTargetFromCommand, MusicTrack_SetTuneFromCommand, MusicTrack_WriteSoundRegisterFromCommand, SoundNote_Detach, SoundDriver_ClearBuffer.