Document audio functions.

6 files changed, 45 insertions, 66 deletions

diff --git a/audio/engine_1.asm b/audio/engine_1.asm
index 9a83e563..0eb4d5d7 100644
--- a/audio/engine_1.asm
+++ b/audio/engine_1.asm
@@ -525,7 +525,7 @@ Audio1_unknownmusic0xef: ; 0x9407
 	call Audio1_GetNextMusicByte
 	push bc
 	ld b, a
-	call Func_22ec
+	call DetermineAudioFunction
 	pop bc
 	ld a, [wDisableChannelOutputWhenSfxEnds]
 	and a
@@ -681,7 +681,7 @@ asm_94fd
 	and a
 	jr nz, .asm_9508
 	ld b, d
-	call Func_22ec
+	call DetermineAudioFunction
 .asm_9508
 	pop bc
 	pop de
@@ -1293,7 +1293,7 @@ Audio1_ApplyDutyCycle: ; 0x980d
 	ret
 
 Audio1_GetNextMusicByte: ; 0x9825
-	call Func_2288
+	call GetNextMusicByte
 	ret
 
 Audio1_GetRegisterPointer: ; 0x9838
@@ -1366,7 +1366,7 @@ Audio1_PlaySound:: ; 984e (2:584e)
 	jp nc, .playSfx
 
 .playMusic
-	call Func_22aa
+	call InitMusicVariables
 	jp .playSoundCommon
 
 .playSfx
@@ -1428,7 +1428,7 @@ Audio1_PlaySound:: ; 984e (2:584e)
 	jr c, .asm_99a3
 	ret
 .asm_99a3
-	call Func_22c0
+	call InitSFXVariables
 .asm_9a2b
 	ld a, c
 	and a
@@ -1437,7 +1437,7 @@ Audio1_PlaySound:: ; 984e (2:584e)
 	jp .sfxChannelLoop
 
 .stopAllAudio
-	call Func_22d6
+	call StopAllAudio
 	ret
 
 .playSoundCommon
diff --git a/audio/engine_2.asm b/audio/engine_2.asm
index e2f12bdc..a5cec3ee 100644
--- a/audio/engine_2.asm
+++ b/audio/engine_2.asm
@@ -10,7 +10,7 @@ Audio2_PlaySound:: ; 218bb (8:58bb)
 	jr z, .asm_218d5
 	jp nc, Audio2_218db
 .asm_218d5
-	call Func_22aa
+	call InitMusicVariables
 	jp Audio2_21940
 
 Audio2_218db: ; 218db (8:58db)
@@ -72,7 +72,7 @@ Audio2_218db: ; 218db (8:58db)
 	jr c, .asm_21930
 	ret
 .asm_21930
-	call Func_22c0
+	call InitSFXVariables
 	ld a, c
 	and a
 	jp z, Audio2_21940
@@ -80,7 +80,7 @@ Audio2_218db: ; 218db (8:58db)
 	jp .asm_218f4
 
 Audio2_2193c: ; 2193c (8:593c)
-	call Func_22d6
+	call StopAllAudio
 	ret
 
 Audio2_21940: ; 21940 (8:5940)
@@ -208,7 +208,7 @@ Audio2_OverwriteChannelPointer: ; 219e6 (8:59e6)
 
 INCLUDE "audio/sfx/pokeflute_ch1_ch2.asm"
 	
-Audio2_219f8:: ; 219f8 (8:59f8)
+Audio2_InitMusicVariables:: ; 219f8 (8:59f8)
 	xor a
 	ld [wUnusedC000], a
 	ld [wDisableChannelOutputWhenSfxEnds], a
@@ -281,7 +281,7 @@ Audio2_219f8:: ; 219f8 (8:59f8)
 	ld [rNR50], a
 	ret
 
-Audio2_21ab7:: ; 21ab7 (8:5ab7)
+Audio2_InitSFXVariables:: ; 21ab7 (8:5ab7)
 	xor a
 	push de
 	ld h, d
@@ -369,7 +369,7 @@ Audio2_21ab7:: ; 21ab7 (8:5ab7)
 	ld [rNR10], a
 	ret
 
-Audio2_21b3f:: ; 21b3f (8:5b3f)
+Audio2_StopAllAudio:: ; 21b3f (8:5b3f)
 	ld a, $80
 	ld [rNR52], a
 	ld [rNR30], a
diff --git a/audio/engine_3.asm b/audio/engine_3.asm
index 7aa446cd..71416dbc 100644
--- a/audio/engine_3.asm
+++ b/audio/engine_3.asm
@@ -12,7 +12,7 @@ Audio3_PlaySound:: ; 7d10d (1f:510d)
 	jr z, .asm_7d127
 	jp nc, Audio3_7d12d
 .asm_7d127
-	call Func_22aa
+	call InitMusicVariables
 	jp Audio3_7d192
 
 Audio3_7d12d: ; 7d12d (1f:512d)
@@ -74,7 +74,7 @@ Audio3_7d12d: ; 7d12d (1f:512d)
 	jr c, .asm_7d182
 	ret
 .asm_7d182
-	call Func_22c0
+	call InitSFXVariables
 	ld a, c
 	and a
 	jp z, Audio3_7d192
@@ -82,7 +82,7 @@ Audio3_7d12d: ; 7d12d (1f:512d)
 	jp .asm_7d146
 
 Audio3_7d18e: ; 7d18e (1f:518e)
-	call Func_22d6
+	call StopAllAudio
 	ret
 
 Audio3_7d192: ; 7d192 (1f:5192)
diff --git a/home/audio.asm b/home/audio.asm
index d22990fb..f65a8485 100644
--- a/home/audio.asm
+++ b/home/audio.asm
@@ -23,7 +23,7 @@ PlayDefaultMusicCommon:: ; 2118 (0:2118)
 	jr z, .walking
 	cp $2
 	jr z, .surfing
-	call Func_21c8
+	call CheckForNoBikingMusicMap
 	jr c, .walking
 	ld a, $d2 ; MUSIC_BIKE_RIDING
 	jr .next
@@ -67,26 +67,26 @@ PlayDefaultMusicCommon:: ; 2118 (0:2118)
 	ld [wNewSoundID], a
 	jp PlaySound
 
-Func_21c8:: ; 21c8 (0:21c8)
+CheckForNoBikingMusicMap:: ; 21c8 (0:21c8)
 ; probably used to not change music upon getting on bike
 	ld a,[wCurMap]
 	cp ROUTE_23
-	jr z,.asm_21e1
+	jr z, .found
 	cp VICTORY_ROAD_1
-	jr z,.asm_21e1
+	jr z, .found
 	cp VICTORY_ROAD_2
-	jr z,.asm_21e1
+	jr z, .found
 	cp VICTORY_ROAD_3
-	jr z,.asm_21e1
+	jr z, .found
 	cp INDIGO_PLATEAU
-	jr z,.asm_21e1
+	jr z, .found
 	and a
 	ret
-.asm_21e1
+.found
 	scf
 	ret
 
-Func_21e3:: ; 21e3 (0:21e3)
+UpdateMusic6Times:: ; 21e3 (0:21e3)
 	ld c,$6
 .loop
 	push bc
@@ -97,34 +97,6 @@ Func_21e3:: ; 21e3 (0:21e3)
 	dec c
 	jr nz, .loop
 	ret
-	
-;Func_235f:: ; 235f (0:235f)
-;	ld a, [wAudioROMBank]
-;	ld b, a
-;	cp BANK(Music2_UpdateMusic)
-;	jr nz, .checkForBank08
-;.bank02
-;	ld hl, Music2_UpdateMusic
-;	jr .asm_2378
-;.checkForBank08
-;	cp BANK(Music8_UpdateMusic)
-;	jr nz, .bank1F
-;.bank08
-;	ld hl, Music8_UpdateMusic
-;	jr .asm_2378
-;.bank1F
-;	ld hl, Music1f_UpdateMusic
-;.asm_2378
-;	ld c, $6
-;.asm_237a
-;	push bc
-;	push hl
-;	call Bankswitch
-;	pop hl
-;	pop bc
-;	dec c
-;	jr nz, .asm_237a
-;	ret
 
 CompareMapMusicBankWithCurrentBank:: ; 21f5 (0:21f5)
 ; Compares the map music's audio ROM bank with the current audio ROM bank
@@ -207,7 +179,7 @@ PlaySound:: ; 2238 (0:2238)
 .noFadeOut
 	xor a
 	ld [wNewSoundID], a
-	call Func_22ec
+	call DetermineAudioFunction
 	jr .done
 .fadeOut
 	ld a,b
@@ -223,7 +195,7 @@ PlaySound:: ; 2238 (0:2238)
 	pop hl
 	ret
 
-Func_2288:: ; 2288 (0:2288)
+GetNextMusicByte:: ; 2288 (0:2288)
 	ld a,[H_LOADEDROMBANK]
 	push af
 	ld a, [wAudioROMBank]
@@ -249,63 +221,70 @@ Func_2288:: ; 2288 (0:2288)
 	ld a,e
 	ret
 
-Func_22aa:: ; 22aa (0:22aa)
+InitMusicVariables:: ; 22aa (0:22aa)
 	push hl
 	push de
 	push bc
-	homecall Audio2_219f8 ; 8:59f8
+	homecall Audio2_InitMusicVariables ; 8:59f8
 	pop bc
 	pop de
 	pop hl
 	ret
 	
-Func_22c0:: ; 22c0 (0:22c0)
+InitSFXVariables:: ; 22c0 (0:22c0)
 	push hl
 	push de
 	push bc
-	homecall Audio2_21ab7 ; 8:5ab7
+	homecall Audio2_InitSFXVariables ; 8:5ab7
 	pop bc
 	pop de
 	pop hl
 	ret
 	
-Func_22d6:: ; 22d6 (0:22d6)
+StopAllAudio:: ; 22d6 (0:22d6)
 	push hl
 	push de
 	push bc
-	homecall Audio2_21b3f
+	homecall Audio2_StopAllAudio
 	pop bc
 	pop de
 	pop hl
 	ret
 	
-Func_22ec:: ; 22ec (0:22ec)
+DetermineAudioFunction:: ; 22ec (0:22ec)
 	ld a,[H_LOADEDROMBANK]
 	push af
 	ld a,[wAudioROMBank]
 	call BankswitchCommon
+; determine the audio function, based on the bank
 	cp BANK(Audio1_PlaySound)
 	jr nz, .checkForBank08
-.bank02
+; bank 02 (audio 1)
 	ld a, b
 	call Audio1_PlaySound
 	jr .done
+
 .checkForBank08
 	cp BANK(Audio2_PlaySound)
 	jr nz, .checkForBank1F
-.bank08
+; bank 08 (audio 2)
 	ld a, b
 	call Audio2_PlaySound
 	jr .done
+
 .checkForBank1F
 	cp BANK(Audio3_PlaySound)
 	jr nz, .bank20
+; bank 1f (audio 3)
 	ld a, b
 	call Audio3_PlaySound
 	jr .done
+
 .bank20
+; invalid banks will default to XX:6bd4
+; this is seen when encountering Missingno, as its sprite dimensions overflow to wAudioROMBank
 	ld a,b
-	call Func_82bd4
+	call Audio4_PlaySound
 .done
 	pop af
 	call BankswitchCommon
diff --git a/home/overworld.asm b/home/overworld.asm
index d9949d5c..65f053af 100644
--- a/home/overworld.asm
+++ b/home/overworld.asm
@@ -1992,7 +1992,7 @@ LoadMapData:: ; 1241 (0:1241)
 	ld a,[wFlags_D733]
 	bit 1,a
 	jr nz,.restoreRomBank
-	call Func_21e3 ; music related
+	call UpdateMusic6Times ; music related
 	call PlayDefaultMusicFadeOutCurrent ; music related
 .restoreRomBank
 	pop af
diff --git a/yellow/main.asm b/yellow/main.asm
index ca6826e7..e9c5bbf8 100755
--- a/yellow/main.asm
+++ b/yellow/main.asm
@@ -832,7 +832,7 @@ SECTION "bank20",ROMX,BANK[$20]
 	dr $80000,$80f14
 
 SurfingPikachu1Graphics:  INCBIN "gfx/surfing_pikachu_1.t4.2bpp"
-Func_82bd4: ; 82bd4 (20:6bd4)
+Audio4_PlaySound: ; 82bd4 (20:6bd4)
 	dr $82bd4,$84000
 
 SECTION "bank2f",ROMX[$5000],BANK[$2F]