sound

struct SoundVoice

A voice a track plays its notes with: its kind and base key, the sample or wave it plays, and its attack, decay, sustain and release.

Field	Declared as
`kind`	`u8 kind`	bits: 7 rhythm \| 6 key split \| 3 fixed rate for PCM, bias rounding for CGB \| 2..0 CGB channel (0 PCM). A rhythm or split voice plays an entry of the voice table at target, chosen by the key (rhythm) or through the key map that attack's four bytes point to (split).
`baseKey`	`u8 baseKey`	Key a rhythm entry plays every note at.
`length`	`u8 length`	CGB sound length (NRx1); 0 plays until released.
`panOrSweep`	`u8 panOrSweep`	CGB channel 1's sweep (NR10) when bit 7 is clear and bits 6..4 are not; else no sweep. In a rhythm entry with bit 7 set, the note's pan is (value - 192) * 2.
`target`	`const void *target`	The PCM sample, the CGB wave pattern, duty or noise width, or for a rhythm or split voice its voice table.
`attack`	`u8 attack`	PCM: added to the envelope each frame until 255. CGB: frames a step. In a split voice, these four bytes are a pointer to its key map.
`decay`	`u8 decay`	PCM: envelope * decay / 256 a frame. CGB: frames a step.
`sustain`	`u8 sustain`	Level decay stops at: 0 to 255 for PCM, 0 to 15 for CGB.
`release`	`u8 release`	PCM: envelope * release / 256 a frame. CGB: frames a step.

Line 114

SoundNote

struct SoundNote

A PCM note, one of 12 the mixer renders: its state and envelope, its output levels, and its links to the other notes of its track. A track's note list holds CGB notes through this type too; the names from 0x0a to 0x1c come from the CGB layout (CgbNote).

Field	Declared as
`state`	`u8 state`	0 when free. bits: 7 start \| 6 released \| 4 looping \| 2 echo \| 1..0 phase (3 attack, 2 decay, 1 sustain, 0 release).
`kind`	`u8 kind`	The voice's kind; bits 2..0 nonzero for a CGB note.
`outRight`	`u8 outRight`	Velocity and track volume to the right, 0 to 255.
`outLeft`	`u8 outLeft`	Velocity and track volume to the left, 0 to 255.
`unk04`	`u8 unk04[2]`	The voice's attack (0x04) and decay (0x05).
`sustain`	`u8 sustain`	The voice's sustain level.
`unk07`	`u8 unk07[3]`	The voice's release (0x07), the key played (0x08) and the envelope level, 0 to 255 (0x09).
`peak`	`u8 peak`	For a PCM note, the mixer writes the envelope's right level here each frame; the name comes from CgbNote.peak.
`unk0b`	`u8 unk0b[0x0e]`	0x0b left level, 0x0c echo level, 0x0d echo frames, 0x10 gate in ticks, 0x11 the song's key, 0x12 velocity, 0x13 priority, 0x14 rhythm pan; the mixer keeps a PCM note's samples left in the word at 0x18.
`sustainLevel`	`u8 sustainLevel`	CgbNote.sustainLevel; inside the samples-left word for a PCM note.
`unk1a`	`u8 unk1a`	Inside the samples-left word for a PCM note.
`panBits`	`u8 panBits`	CgbNote.panBits; inside the samples-left word for a PCM note.
`channelBits`	`u8 channelBits`	CgbNote.channelBits; for a PCM note, the mixer's fractional sample position is the word at 0x1c.
`unk1d`	`u8 unk1d[0x0f]`	0x1d CGB update bits, 0x1e CGB length, 0x1f CGB sweep, 0x20 the word frequency, 0x24 the voice's target (the sample), 0x28 the next sample byte (mixer).
`track`	`struct SoundTrack *track`	The track whose list holds this note; NULL once detached.
`prev`	`struct SoundNote *prev`	The note started after this one in the track's list (nearer its head); NULL at the head.
`next`	`struct SoundNote *next`	The note started before this one in the track's list; NULL at the end.
`unk38`	`u8 unk38[8]`	Not named by TBS code.

Used by AudioCommand_InvokeSlot34, AudioEngine_SetMode, AudioEngine_StopAllChannels.

Line 142

CgbNote

struct CgbNote

A note on one of the four CGB channels of the hardware: its state and envelope, its levels and pan, its frequency and its wave.

Field	Declared as
`state`	`u8 state`	CgbNoteState and CgbNotePhase; 0 when the channel is free.
`kind`	`u8 kind`	Channel number 1 to 4 at setup, then the voice's kind; bit 3 rounds the frequency to the sound bias's resolution on channels 1 to 3.
`outRight`	`u8 outRight`	Velocity and track volume to the right, 0 to 255.
`outLeft`	`u8 outLeft`	Velocity and track volume to the left, 0 to 255.
`attack`	`u8 attack`	Frames per attack step.
`decay`	`u8 decay`	Frames per decay step.
`sustain`	`u8 sustain`	Sustain level 0 to 15, scaled by peak.
`release`	`u8 release`	Frames per release step.
`key`	`u8 key`	The key played, before the track's pitch.
`level`	`u8 level`	Envelope level 0 to 15 written to the channel.
`peak`	`u8 peak`	Top of the envelope: (outRight + outLeft) / 16, at most 15 when one side plays.
`counter`	`u8 counter`	Frames left in the current envelope step.
`echoLevel`	`u8 echoLevel`	After release, the level held is peak * echoLevel / 256.
`echoLength`	`u8 echoLength`	Frames the echo lasts.
`unk0e`	`u8 unk0e[0x0b]`	0x10 gate in ticks, 0x11 the song's key, 0x12 velocity, 0x13 priority (a new note of higher priority takes the channel), 0x14 rhythm pan.
`sustainLevel`	`u8 sustainLevel`	(peak * sustain + 15) / 16.
`trigger`	`u8 trigger`	Value for NRx4: 7 restart, 6 length on, 2..0 frequency.
`panBits`	`u8 panBits`	NR51 bits this note sets: one side or both.
`channelBits`	`u8 channelBits`	This channel's NR51 bits: 0x11, 0x22, 0x44, 0x88.
`modified`	`u8 modified`	CgbNoteModified: what to write to the channel.
`length`	`u8 length`	The voice's length.
`sweep`	`u8 sweep`	Channel 1's NR10 sweep; 8 when none.
`frequency`	`u32 frequency`	Tone frequency from Cgb_KeyToFrequency (2048 added), or channel 4's NR43 value.
`wave`	`u32 *wave`	Channel 3: the 16-byte wave pattern. Channels 1 and 2: the duty, into NRx1's bits 7..6. Channel 4: the width, into NR43's bit 3.
`loadedWave`	`u32 *loadedWave`	Channel 3: the pattern last copied into wave RAM.
`unk2c`	`u8 unk2c[0x14]`	0x2c track, 0x30 prev and 0x34 next, as in SoundNote.

Used by AudioEngine_StopAllChannels, CgbAudio_Initialize, CgbNote_UpdatePanEnvelope, Cgb_UpdateChannels, gSound_CgbNotes.

Line 184

SoundTrack

struct SoundTrack

A track of a playing song: the song commands it runs, its voice and notes, and the pitch, volume, pan and modulation it gives them.

Field	Declared as
`flags`	`u8 flags`	SoundTrackFlag. bits: 7 active \| 6 reset \| 3..2 pitch to update \| 1..0 volume to update.
`unk01`	`u8 unk01[7]`	0x01 ticks until the next command, 0x02 pattern depth (0 to 3), 0x03 repeat count, 0x04 gate of the last note in ticks, 0x05 its key, 0x06 its velocity, 0x07 the last command byte from 0xBD up, which a byte below 0x80 repeats.
`pitchHi`	`u8 pitchHi`	Whole semitones of the track's pitch, read as signed and added to each note's key (a sum below 0 plays key 0).
`pitchLo`	`u8 pitchLo`	The pitch's fraction, 0 to 255 in 1/256 semitone, passed as the fine pitch to the key-to-frequency step.
`keyOffsetA`	`s8 keyOffsetA`	Semitones, from the song's key-shift command.
`keyOffsetB`	`s8 keyOffsetB`	Semitones, from MusicPlayer_SetPitch.
`tune`	`s8 tune`	The tune command's byte - 64: 1/64 semitone.
`fine`	`u8 fine`	1/256 semitone, from MusicPlayer_SetPitch.
`bend`	`s8 bend`	The bend command's byte - 64: full bend is bendRange.
`bendRange`	`u8 bendRange`	Semitones a full bend reaches; 2 at reset.
`outVolumeA`	`u8 outVolumeA`	Right volume: (pan + 128) * scaled volume / 256.
`outVolumeB`	`u8 outVolumeB`	Left volume: (127 - pan) * scaled volume / 256.
`volume`	`u8 volume`	The song's volume command, scaled by volumeScale / 32.
`volumeScale`	`u8 volumeScale`	0 to 64 (full, the reset value): a player volume or fade level of 0 to 0x100 divided by 4.
`pan`	`s8 pan`	The pan command's byte - 64, -64 to 63; doubled for output.
`panOffset`	`s8 panOffset`	Added to the doubled pan, from MusicPlayer_SetPan.
`modAmount`	`s8 modAmount`	The LFO's output, modDepth * wave / 64: added to the pitch in 1/16 semitone, to the pan, or scaling the volume by (amount + 128) / 128.
`modDepth`	`u8 modDepth`	0 to 255, from the modulation command or MusicPlayer_SetModulationDepth; 0 stops the LFO and clears modAmount.
`modTarget`	`u8 modTarget`	SoundModulationTarget.
`lfoSpeed`	`u8 lfoSpeed`	LFO phase step a tick, 22 at reset; 0 stops the LFO and clears modAmount.
`lfoPhase`	`u8 lfoPhase`	0 to 255, wrapping; the wave is phase over 0 to 63, 128 - phase over 64 to 191 and phase - 256 over 192 to 255, so -64 to 64.
`unk1b`	`u8 unk1b[3]`	0x1b LFO delay in ticks (song command), 0x1c its countdown, reloaded by each note, 0x1d track priority added to the player's for its notes.
`tailLevel`	`u8 tailLevel`	Each new note's echo level.
`tailLength`	`u8 tailLength`	Each new note's echo length in frames.
`notes`	`struct SoundNote *notes`	The notes this track started, newest first, linked through SoundNote.next; PCM notes from SoundWork.pcmNotes and CGB notes. NULL ends the list or leaves it empty.
`voice`	`struct SoundVoice voice`	Copied from the player's voice table by the voice command, or set a field at a time by extended commands.
`unk30`	`u8 unk30[0x10]`	Not named by TBS code; zeroed with the first 64 bytes at reset.
`cursor`	`const u8 *cursor`	The next command byte in the song's data, from the header's track pointer; a track's commands end at a finish command (0xB1).
`unk44`	`u8 unk44[0x0c]`	Cursors to return to after each of up to three nested patterns.

Used by MusicPlayer_Initialize, MusicPlayer_ResetActiveTracks, MusicPlayer_SetLfoSpeed, MusicPlayer_SetModulationDepth, MusicPlayer_SetPan, MusicPlayer_SetPitch, MusicPlayer_SetVolume, MusicPlayer_StartSong, MusicPlayer_StepFade, MusicPlayer_Stop, MusicTrack_CalcOutput, MusicTrack_ClearModulation, MusicTrack_DispatchStreamCommand, MusicTrack_OperateWorkByte, MusicTrack_ReadVoiceTarget, MusicTrack_SetTailLength, MusicTrack_SetTailLevel, MusicTrack_SetVoiceAttack, MusicTrack_SetVoiceDecay, MusicTrack_SetVoiceKind, MusicTrack_SetVoiceLength, MusicTrack_SetVoicePanOrSweep, MusicTrack_SetVoiceRelease, MusicTrack_SetVoiceSustain, Runtime_CallWorkEntryWithArgs.

Line 275

SequenceHeader

struct SequenceHeader

A song's header: its track count, priority and mode, its voices, and where each track's commands start.

Field	Declared as
`trackCount`	`u8 trackCount`	At most 16; 0 in the empty songs.
`unk01`	`u8 unk01`	0 in every song; ags-music refuses another block count.
`priority`	`u8 priority`	Becomes the player's priority.
`mode`	`u8 mode`	With bit 7 set, passed to AudioEngine_SetMode (bits 6..0 the reverb); ags-music's reverb field.
`voices`	`const struct SoundVoice *voices`	The voice table its tracks choose from.
`tracks`	`const u8 *tracks[1]`	Each track's first command, trackCount of them.

Used by MusicPlayer_StartSong.

Line 339

SoundPlayer

struct SoundPlayer

A player, which plays one song: its header and status, its tracks, its tempo and fade.

Field	Declared as
`header`	`const struct SequenceHeader *header`	The song playing or last played.
`status`	`u32 status`	bits: 31 paused \| 15..0 tracks active after the last tick. Set to SOUND_PLAYER_PAUSED alone when no track is left.
`trackCount`	`u8 trackCount`	Tracks this player owns, at most 16.
`priority`	`u8 priority`	The song's priority.
`unk0a`	`u8 unk0a`	The last command run: its byte - 0xB1.
`checkPriority`	`u8 checkPriority`	Nonzero: a song of lower priority does not replace a playing one. From gSound_PlayerSlots, 0 for every player.
`ticks`	`u32 ticks`	Song ticks played since the song started.
`unk10`	`u8 unk10[8]`	Not named by TBS code.
`workBytes`	`u8 *workBytes`	gSound_WorkBytes, which the work-byte command uses.
`tempo`	`u16 tempo`	Twice the tempo command's byte; 150 at start.
`tempoScale`	`u16 tempoScale`	256 plays at the song's tempo.
`tempoStep`	`u16 tempoStep`	tempo * tempoScale / 256, added to tempoCount each frame.
`tempoCount`	`u16 tempoCount`	Each 150 in it runs one tick, so a tempoStep of 150 is a tick a frame.
`fadePeriod`	`u16 fadePeriod`	Frames between fade steps; 0 when not fading.
`fadeCounter`	`u16 fadeCounter`	Frames left until the next fade step.
`fadeVolume`	`u16 fadeVolume`	bits: 8..4 level, 0 to 0x100 in steps of 16 \| 1 fade in \| 0 pause at the end (SoundFadeFlag).
`unk2a`	`u8 unk2a[2]`	Not named by TBS code.
`tracks`	`struct SoundTrack *tracks`	trackCount tracks.
`voices`	`const struct SoundVoice *voices`	The song's voice table.
`lock`	`u32 lock`	SOUND_LOCK when free; raised while the player is changed or ticked.
`nextTick`	`void (nextTick)(struct SoundPlayer player)`	The tick routine and player that were first in the chain before this player was added; this player's tick runs them first.
`nextTickPlayer`	`struct SoundPlayer *nextTickPlayer`	Passed to nextTick.

Used by Audio_Initialize, Audio_PlayOrResumeSound, Audio_PlaySoundIfInactive, Audio_ResumePlayer, Audio_ResumeSound, Audio_StopSound, MusicPlayer_BeginFadeOut, MusicPlayer_FadeIn, MusicPlayer_FadeOut, MusicPlayer_FadeOutPause, MusicPlayer_Initialize, MusicPlayer_ResetActiveTracks, MusicPlayer_Resume, MusicPlayer_SetFadeParameters, MusicPlayer_SetLfoSpeed, MusicPlayer_SetModulationDepth, MusicPlayer_SetPan, MusicPlayer_SetPitch, MusicPlayer_SetPitchAndUpdateFrequency, MusicPlayer_SetVolume, MusicPlayer_StartSong, MusicPlayer_StepFade, MusicPlayer_Stop, MusicTrack_CalcOutput, MusicTrack_DispatchStreamCommand, MusicTrack_OperateWorkByte, MusicTrack_ReadVoiceTarget, MusicTrack_SetTailLength, MusicTrack_SetTailLevel, MusicTrack_SetVoiceAttack, MusicTrack_SetVoiceDecay, MusicTrack_SetVoiceKind, MusicTrack_SetVoiceLength, MusicTrack_SetVoicePanOrSweep, MusicTrack_SetVoiceRelease, MusicTrack_SetVoiceSustain, Runtime_CallWorkEntryWithArgs, gMusicPlayerBgm, gMusicPlayerFanfare, gSound_Player3.

Line 352

SoundWork

struct SoundWork

The sound driver's work: its lock, the mixer's rate and buffers, the PCM and CGB notes, and the routines the driver calls.

Field	Declared as
`lock`	`u32 lock`	SOUND_LOCK when free; raised while the driver changes it.
`transferCountdown`	`volatile u8 transferCountdown`
`reverb`	`u8 reverb`	0 to 127 (mode bits 6..0); 0 skips the reverb pass.
`pcmNoteCount`	`u8 pcmNoteCount`	PCM notes in use, 8 at start (mode bits 11..8).
`volume`	`u8 volume`	PCM volume 0 to 15, 15 at start (mode bits 15..12).
`rate`	`u8 rate`	1 to 12, indexes gSound_FrameLengths (mode bits 19..16).
`unk09`	`u8 unk09`	Not named by TBS code.
`cgbTick`	`u8 cgbTick`	Counts 14 down to 0 once a CGB update; at 0 the envelopes take an extra step.
`transferPeriod`	`u8 transferPeriod`	Frames the buffers hold: 0x630 / frameSamples.
`maxLines`	`u8 maxLines`	Nonzero: the mixer stops taking notes once the scanline passes this many lines after its start. Sound_MaxLines, 0.
`unk0d`	`u8 unk0d[3]`	Not named by TBS code.
`frameSamples`	`u32 frameSamples`	Samples mixed a frame, from gSound_FrameLengths.
`outputRate`	`u32 outputRate`	Samples a second: frameSamples * 59.7275, rounded.
`rateStep`	`u32 rateStep`	2^23 / outputRate, rounded; a note's frequency times it is its step a sample.
`cgbNotes`	`struct CgbNote *cgbNotes`	gSound_CgbNotes; NULL before CGB setup.
`tick`	`void (tick)(struct SoundPlayer player)`	First of the chain of player ticks run each mixer frame; NULL for none.
`tickPlayer`	`struct SoundPlayer *tickPlayer`	Passed to tick.
`cgbUpdate`	`void (*cgbUpdate)(void)`	Run each mixer frame: Cgb_UpdateChannels.
`cgbMute`	`void (*cgbMute)(u8 channel)`	CgbChannel_Mute, channel 1 to 4.
`cgbFrequency`	`s32 (*cgbFrequency)(u8 kind, u8 key, u8 fine)`	Cgb_KeyToFrequency.
`commands`	`SoundCommand *commands`	gSound_CommandTable.
`noteOn`	`void (noteOn)(u32 command, struct SoundPlayer player, struct SoundTrack *track)`	MusicTrack_HandleNote, run for song bytes from 0xCF up with the byte - 0xCF.
`unk3c`	`void (*unk3c)(void)`	Set to Audio_EmptyCallback by AudioEngine_Initialize; no TBS code reads it by name.
`unk40`	`u8 unk40[0x10]`	Not named by TBS code.
`pcmNotes`	`struct SoundNote pcmNotes[12]`	pcmNoteCount of them play.
`buffers`	`s8 buffers[2][0x630]`	Right (0, DMA 1 to FIFO A) and left (1, DMA 2 to FIFO B) samples, transferPeriod frames of frameSamples each.

Used by AudioEngine_Initialize, AudioEngine_ResumeDirectSound, AudioEngine_SetMode, AudioEngine_SetPcmRate, AudioEngine_StopAllChannels, AudioEngine_SuspendDirectSound, CgbAudio_Initialize, Cgb_UpdateChannels, MusicPlayer_Initialize, gSound_Work.

Line 390

PlayerSlot

struct PlayerSlot

An entry of the player table: a player, its tracks and track count, and its priority check.

Field	Declared as
`player`	`struct SoundPlayer *player`
`tracks`	`struct SoundTrack *tracks`	trackCount tracks for the player.
`trackCount`	`u8 trackCount`
`unk09`	`u8 unk09`	0 in every entry; not named by TBS code.
`checkPriority`	`u16 checkPriority`	Copied to the player's checkPriority; 0 everywhere.

Used by Audio_PlayOrResumeSound, Audio_PlaySound, Audio_PlaySoundIfInactive, Audio_ResumeSound, Audio_StopSound, gSound_PlayerSlots.

Line 440

SongEntry

struct SongEntry

An entry of the song table: a song's header and the player table entry that plays it.

Field	Declared as
`header`	`const struct SequenceHeader *header`
`slot`	`u16 slot`	Index into gSound_PlayerSlots; AudioCommand_Play gives slot 7's songs the first player from 7 down to 4 with no active track, else 7.
`unk06`	`u16 unk06`	The same value as slot in every entry; not named by TBS code.

Used by Audio_PlayOrResumeSound, Audio_PlaySound, Audio_PlaySoundIfInactive, Audio_ResumeSound, Audio_StopSound, gSound_SongTable.

Line 450

Enumerations

SoundDriverLimit

enum SoundDriverLimit

Value	=
`SOUND_PCM_NOTE_CAPACITY`	`12`	The PCM notes in SoundWork.pcmNotes; mode changes and AudioEngine_StopAllChannels clear all 12, though only pcmNoteCount play.
`SOUND_CGB_CHANNEL_COUNT`	`4`	CGB channels, numbered 1 to 4.
`SOUND_PLAYER_TRACK_LIMIT`	`16`	Most tracks a player takes; MusicPlayer_Initialize caps its count here, and the track masks of the MusicPlayer_Set routines are 16 bits.

Line 91

Also, enumerations without a comment: SoundModulationTarget, SoundFadeFlag, CgbNoteState, CgbNotePhase, CgbNoteModified, SoundTrackFlag, SoundPlayerFlag, SoundTrackWorkOperation.

Types

SoundCommand

typedef void (*SoundCommand)(struct SoundPlayer *player, struct SoundTrack *track);

A command table entry: the driver calls it with the player and the track.

Used by CgbAudio_Initialize, Runtime_CallWorkEntryWithArgs, gSound_CommandTable, gSound_ExtendedCommandTable.

Line 48

Macros

SOUND_COMMAND_CAST

#define SOUND_COMMAND_CAST(type, routine) ((type)(void (*)(void))(routine))

Converts between SoundCommand and a table entry that takes other parameters, through the generic function type so neither cast warns.

Used by AudioCommand_InvokeSlot34, AudioCommand_InvokeSlot35, CgbAudio_Initialize.

Line 52

SOUND_COMMAND_FINISH

#define SOUND_COMMAND_FINISH 0

Entries of gSound_CommandTable, in gSound_CommandTableTemplate's order. A song byte from 0xB1 to 0xCE runs entry (byte - 0xB1) for its track; bytes from 0xCF up start notes through the work's noteOn instead, so entries 30 to 35 are the driver's helper tail, reached only by its own calls. Unused entries hold MusicTrack_FinishSequence. @{ Byte 0xB1: ends the track, releasing and unlinking its notes.

Used by Runtime_CallWorkEntryWithArgs.

Line 61

SOUND_COMMAND_WORK_BYTE

#define SOUND_COMMAND_WORK_BYTE 8

Byte 0xB9, installed by CgbAudio_Initialize: an operation, a work byte and an operand; sets, adds to or compares a byte of the player's workBytes (SoundTrackWorkOperation), jumping like GOTO when a comparison holds.

Used by CgbAudio_Initialize.

Line 66