Label FadeOut and FadeIn routines

12 files changed, 113 insertions, 97 deletions

diff --git a/engine/copyright_screen.asm b/engine/copyright_screen.asm
index 41ae974..35a5329 100755
--- a/engine/copyright_screen.asm
+++ b/engine/copyright_screen.asm
@@ -25,7 +25,7 @@ FadeInCopyrightScreen: ; 0x8228
 	call SGBNormal

 	ld bc, $0050

 	call AdvanceFrames

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -67,7 +67,7 @@ DisplayCopyrightScreen: ; 0x8290
 	ret

 

 FadeOutCopyrightScreenAndLoadData: ; 0x82a8

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld hl, sHighScores

 	ld de, wRedHighScore1Points

diff --git a/engine/erase_all_data_menu.asm b/engine/erase_all_data_menu.asm
index ae0b780..7504cf5 100755
--- a/engine/erase_all_data_menu.asm
+++ b/engine/erase_all_data_menu.asm
@@ -31,7 +31,7 @@ CheckForResetButtonCombo: ; 0x8167
 	call Func_b66

 	call Func_588

 	call SGBNormal

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -106,7 +106,7 @@ HandleEraseAllDataInput: ; 0x81d4
 	ret

 

 ExitEraseAllDataMenu: ; 0x820f

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld hl, wCurrentScreen

 	inc [hl]

diff --git a/engine/field_select_screen.asm b/engine/field_select_screen.asm
index 2d5cd7c..0033488 100755
--- a/engine/field_select_screen.asm
+++ b/engine/field_select_screen.asm
@@ -29,7 +29,7 @@ LoadFieldSelectScreen: ; 0xd6dd
 	ld de, $0003

 	call PlaySong

 	call Func_588

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -81,7 +81,7 @@ ExitFieldSelectScreen: ; 0xd774
 .didntPressA

 	ld a, [hJoypadState]

 	push af

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld a, [wd8f6]

 	bit BIT_A_BUTTON, a

diff --git a/engine/high_scores_screen.asm b/engine/high_scores_screen.asm
index 1969f62..bc48dc7 100755
--- a/engine/high_scores_screen.asm
+++ b/engine/high_scores_screen.asm
@@ -169,7 +169,7 @@ Func_cb14: ; 0xcb14
 	call Func_d68a

 	ld bc, $03c9

 	call Func_d68a

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -184,7 +184,7 @@ Func_cb14: ; 0xcb14
 	call Func_d68a

 	ld bc, $03c9

 	call Func_d68a

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ld hl, wScreenState

@@ -943,7 +943,7 @@ Func_d159: ; 0xd159
 	ret

 

 ExitHighScoresScreen: ; 0xd171

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld hl, hSTAT

 	res 6, [hl]

diff --git a/engine/options_screen.asm b/engine/options_screen.asm
index 427e6d2..e29c96f 100755
--- a/engine/options_screen.asm
+++ b/engine/options_screen.asm
@@ -43,7 +43,7 @@ Func_c35a: ; 0xc35a
 	ld a, [wSoundTextCurrentSoundEffect]

 	hlCoord 7, 13, vBGMap

 	call RedrawSoundTestID

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -145,7 +145,7 @@ Func_c447: ; 0xc447
 	ret

 

 Func_c483: ; 0xc483

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld a, SCREEN_TITLESCREEN

 	ld [wCurrentScreen], a

diff --git a/engine/pinball_game.asm b/engine/pinball_game.asm
index 23c6490..d1459e5 100755
--- a/engine/pinball_game.asm
+++ b/engine/pinball_game.asm
@@ -61,7 +61,7 @@ GameScreenFunction_StartBall: ; 0xd87f
 	ld [wd7c1], a

 	call Func_b66

 	call Func_588

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -230,7 +230,7 @@ GameScreenFunction_EndBall: ; 0xdab2
 	ld a, [wd496]

 	and a

 	jr nz, .asm_db28

-	call Func_cb5

+	call FadeOut

 	ld a, [wd849]

 	and a

 	call z, Func_e5d

@@ -248,7 +248,7 @@ GameScreenFunction_EndBall: ; 0xdab2
 	call PlaySong

 	ld bc, $0004

 	call AdvanceFrames

-	call Func_cb5

+	call FadeOut

 	ld a, [wd849]

 	and a

 	call nz, Func_e5d

@@ -275,7 +275,7 @@ GameScreenFunction_EndBall: ; 0xdab2
 	call PlaySong

 	ld bc, $0004

 	call AdvanceFrames

-	call Func_cb5

+	call FadeOut

 	ld a, [wd849]

 	and a

 	call nz, Func_e5d

@@ -299,7 +299,7 @@ TransitionToHighScoresScreen: ; 0xdb5d
 	call PlaySong

 	ld bc, $0004

 	call AdvanceFrames

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld hl, hSTAT

 	res 6, [hl]

diff --git a/engine/pinball_game/save_game.asm b/engine/pinball_game/save_game.asm
index e9d5e8f..644abb3 100755
--- a/engine/pinball_game/save_game.asm
+++ b/engine/pinball_game/save_game.asm
@@ -3,7 +3,7 @@ SaveGame: ; 0xda05
 	call PlaySong

 	ld bc, $0004

 	call AdvanceFrames

-	call Func_cb5

+	call FadeOut

 	ld a, [wd849]

 	and a

 	call nz, Func_e5d

diff --git a/engine/pokedex.asm b/engine/pokedex.asm
index 69af64c..8b624a4 100755
--- a/engine/pokedex.asm
+++ b/engine/pokedex.asm
@@ -65,7 +65,7 @@ LoadPokedexScreen: ; 0x2800e
 	ld de, $0004

 	call PlaySong

 	call Func_588

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -710,7 +710,7 @@ Func_284bc: ; 0x284bc
 	ret

 

 ExitPokedexScreen: ; 0x284f9

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld hl, hSTAT

 	res 6, [hl]

diff --git a/engine/select_gameboy_target_menu.asm b/engine/select_gameboy_target_menu.asm
index 9ee76bb..3f18b60 100755
--- a/engine/select_gameboy_target_menu.asm
+++ b/engine/select_gameboy_target_menu.asm
@@ -41,7 +41,7 @@ InitSelectGameboyTargetMenu: ; 0x800a
 	call ClearOAMBuffer

 	call Func_b66

 	call Func_588

-	call Func_bbe

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -229,7 +229,7 @@ CGBSelected_TileData: ; 0x8144
 	db $00  ; terminator

 

 EndSelectGameboyTargetMenu: ; 0x414e

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld hl, wCurrentScreen

 	inc [hl] ; set to SCREEN_ERASE_ALL_DATA

diff --git a/engine/titlescreen.asm b/engine/titlescreen.asm
index 63c8ce8..057e937 100755
--- a/engine/titlescreen.asm
+++ b/engine/titlescreen.asm
@@ -35,7 +35,7 @@ FadeInTitlescreen: ; 0xc00e
 	ld de, $0004

 	call PlaySong

 	call Func_588

-	call Func_bbe  ; this does the fading

+	call FadeIn

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -147,7 +147,7 @@ Func_c10e: ; 0xc10e
 	ld a, [wTitleScreenGameStartCursorSelection]

 	and a

 	jr z, .asm_c177

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld a, [wd7c2]

 	and a

@@ -223,7 +223,7 @@ Func_c1b1: ; 0xc1b1
 	ret

 

 Func_c1cb: ; 0c1cb

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld a, [wTitleScreenCursorSelection]

 	ld c, a

@@ -242,7 +242,7 @@ Data_c1e4: ; 0xc1e4
 	db SCREEN_OPTIONS

 

 GoToHighScoresFromTitlescreen: ; 0xc1e7

-	call Func_cb5

+	call FadeOut

 	call Func_576

 	ld a, SCREEN_HIGH_SCORES

 	ld [wCurrentScreen], a

diff --git a/home.asm b/home.asm
index 76d489a..7fd67fe 100755
--- a/home.asm
+++ b/home.asm
@@ -378,7 +378,8 @@ Func_3c3:
 	ld a, [rLCDC]
 	bit 7, a
 	jr z, .asm_03cf
-	call Func_cb5
+	call FadeOut
+	; Fades palettes in from white screen.
 	call Func_576
 .asm_03cf
 	ld hl, hSTAT
@@ -1803,14 +1804,16 @@ Func_b66: ; 0xb66
 	jr nz, .asm_ba8
 	ret
 
-Func_bbe: ; 0xbbe
+FadeIn: ; 0xbbe
+; Fades palettes in from white screen.
 	ld a, [hGameBoyColorFlag]
 	and a
-	jp nz, Func_c19
+	jp nz, FadeIn_GameboyColor
+	; Regular Gameboy
 	ld hl, hBGP
 	ld de, wBGP
 	ld b, $3
-.asm_bcc
+.loop
 	ld a, [de]
 	and $55
 	ld c, a
@@ -1821,13 +1824,13 @@ Func_bbe: ; 0xbbe
 	ld [hli], a
 	inc de
 	dec b
-	jr nz, .asm_bcc
+	jr nz, .loop
 	ld bc, $0002
 	call AdvanceFrames
 	ld hl, hBGP
 	ld de, wBGP
 	ld b, $3
-.asm_be9
+.loop2
 	ld a, [de]
 	and $aa
 	srl a
@@ -1835,13 +1838,13 @@ Func_bbe: ; 0xbbe
 	ld [hli], a
 	inc de
 	dec b
-	jr nz, .asm_be9
+	jr nz, .loop2
 	ld bc, $0002
 	call AdvanceFrames
 	ld hl, hBGP
 	ld de, wBGP
 	ld b, $3
-.asm_c02
+.loop3
 	ld a, [de]
 	and $55
 	ld c, a
@@ -1853,50 +1856,54 @@ Func_bbe: ; 0xbbe
 	ld [hli], a
 	inc de
 	dec b
-	jr nz, .asm_c02
+	jr nz, .loop3
 	ld bc, $0002
 	call AdvanceFrames
 	ret
 
-Func_c19: ; 0xc19
-	ld b, $10
-.asm_c1b
+FadeIn_GameboyColor: ; 0xc19
+; Fades in to the target palette data in wPaletteData from wFadeBGPaletteData and wFadeOBJPaletteData
+; Fade is completed after 16 frames of incrementally updating the palettes.
+	ld b, 16 ; fade takes 16 frames to complete
+.loop
 	push bc
 	ld de, wPaletteData
-	ld hl, wd280
-	call Func_c2d
-	call Func_d61
+	ld hl, wFadeBGPaletteData
+	call FadeInStep
+	call SetFadedPalettes
 	pop bc
 	dec b
-	jr nz, .asm_c1b
+	jr nz, .loop
 	ret
 
-Func_c2d: ; 0xc2d
+FadeInStep: ; 0xc2d
+; de = base palette data
+; hl = faded palette data
 	ld a, b
 	cp $1
-	jr z, .asm_c49
-	ld c, $40
-.asm_c34
+	jr z, .lastStep
+	ld c, $40 ; total number of colors in BG and OBJ palettes
+.loop
 	push bc
 	ld a, [hli]
 	sub $42
 	ld c, a
 	ld a, [hld]
 	sbc $8
-	ld b, a
-	call Func_c60
+	ld b, a  ; subtracted 2 from each RGB value of the color
+	call GetNextFadedPalette
 	ld a, c
 	ld [hli], a
 	ld a, b
 	ld [hli], a
 	pop bc
 	dec c
-	jr nz, .asm_c34
+	jr nz, .loop
 	ret
 
-.asm_c49
-	ld c, $40
-.asm_c4b
+.lastStep
+	ld c, $40 ; total number of colors in BG and OBJ palettes
+.loop2
 	push bc
 	ld a, [hli]
 	sub $21
@@ -1904,32 +1911,36 @@ Func_c2d: ; 0xc2d
 	ld a, [hld]
 	sbc $4
 	ld b, a
-	call Func_c60
+	call GetNextFadedPalette
 	ld a, c
 	ld [hli], a
 	ld a, b
 	ld [hli], a
 	pop bc
 	dec c
-	jr nz, .asm_c4b
+	jr nz, .loop2
 	ret
 
-Func_c60: ; 0xc60
+GetNextFadedPalette: ; 0xc60
+; de = source palette data
+; bc = target palette RGB - 2
+; Places the resulting palette RGB into bc
 	push hl
 	ld a, [de]
-	and $1f
+	and %00011111  ; Target RGB Blue value
 	ld l, a
 	ld a, c
-	and $1f
+	and %00011111  ; Current faded RBG Blue value - 2
 	cp l
-	jr nc, .asm_c70
+	jr nc, .brighter
+	; set the current faded Blue value to the target blue value.
 	ld a, c
-	and $e0
+	and %11100000
 	or l
 	ld c, a
-.asm_c70
+.brighter
 	ld a, [de]
-	and $e0
+	and %11100000
 	ld l, a
 	inc de
 	ld a, [de]
@@ -1938,7 +1949,7 @@ Func_c60: ; 0xc60
 	srl a
 	rr l
 	ld a, c
-	and $e0
+	and %11100000
 	ld h, a
 	ld a, b
 	srl a
@@ -1978,17 +1989,19 @@ Func_c60: ; 0xc60
 	pop hl
 	ret
 
-Func_cb5: ; 0xcb5
+FadeOut: ; 0xcb5
+; Fades palettes out to a white screen.
 	ld a, [hGameBoyColorFlag]
 	and a
-	jp nz, Func_cee
+	jp nz, FadeOut_GameboyColor
+	; Regular Gameboy
 	ld hl, hBGP
 	ld b, $3
-.asm_cc0
+.loop
 	push bc
 	push hl
 	ld b, $3
-.asm_cc4
+.loop2
 	ld a, [hl]
 	and $55
 	ld c, a
@@ -2001,13 +2014,13 @@ Func_cb5: ; 0xcb5
 	add [hl]
 	ld [hli], a
 	dec b
-	jr nz, .asm_cc4
+	jr nz, .loop2
 	ld bc, $0002
 	call AdvanceFrames
 	pop hl
 	pop bc
 	dec b
-	jr nz, .asm_cc0
+	jr nz, .loop
 	xor a
 	ld hl, hBGP
 	ld [hli], a
@@ -2017,25 +2030,28 @@ Func_cb5: ; 0xcb5
 	call AdvanceFrames
 	ret
 
-Func_cee: ; 0xcee
-	ld hl, wd280
+FadeOut_GameboyColor: ; 0xcee
+; Fades out to white RGB colors from the currently-loaded palettes.
+; Fade is completed after 16 frames of incrementally updating the palettes.
+	ld hl, wFadeBGPaletteData
 	ld de, rBGPI
-	call Func_d9d
-	ld hl, wd2c0
+	call LoadCurrentPalettesIntoFadePalettes
+	ld hl, wFadeOBJPaletteData
 	ld de, rOBPI
-	call Func_d9d
-	ld b, $10
-.asm_d02
+	call LoadCurrentPalettesIntoFadePalettes
+	ld b, 16 ; fade takes 16 frames to complete
+.loop
 	push bc
-	ld hl, wd280
-	call Func_d11
-	call Func_d61
+	ld hl, wFadeBGPaletteData
+	call FadeOutStep
+	call SetFadedPalettes
 	pop bc
 	dec b
-	jr nz, .asm_d02
+	jr nz, .loop
 	ret
 
-Func_d11: ; 0xd11
+FadeOutStep: ; 0xd11
+; hl = faded palette data
 	ld b, $40
 .asm_d13
 	ld a, [hl]
@@ -2092,21 +2108,22 @@ Func_d11: ; 0xd11
 	jr nz, .asm_d13
 	ret
 
-Func_d61: ; 0d61
+SetFadedPalettes: ; 0d61
+; Sets the current palette data to the faded palettes.
 	ld a, [rIE]
 	res 0, a
 	ld [rIE], a
-	ld hl, wd280
+	ld hl, wFadeBGPaletteData
 	ld de, rBGPI
 	ld a, $80
 	ld [de], a
 	inc de
-.asm_d71
+.waitForVBlank
 	ld a, [rLY]
 	cp $90
-	jr c, .asm_d71
+	jr c, .waitForVBlank
 	ld b, $10
-.asm_d79
+.loadBGColorsLoop
 	ld a, [hli]
 	ld [de], a
 	ld a, [hli]
@@ -2116,13 +2133,13 @@ Func_d61: ; 0d61
 	ld a, [hli]
 	ld [de], a
 	dec b
-	jr nz, .asm_d79
+	jr nz, .loadBGColorsLoop
 	inc de
 	ld a, $80
 	ld [de], a
 	inc de
 	ld b, $10
-.asm_d8b
+.loadOBJColorsLoop
 	ld a, [hli]
 	ld [de], a
 	ld a, [hli]
@@ -2132,13 +2149,15 @@ Func_d61: ; 0d61
 	ld a, [hli]
 	ld [de], a
 	dec b
-	jr nz, .asm_d8b
+	jr nz, .loadOBJColorsLoop
 	ld a, [rIE]
 	set 0, a
 	ld [rIE], a
 	ret
 
-Func_d9d: ; 0xd9d
+LoadCurrentPalettesIntoFadePalettes: ; 0xd9d
+; hl = destination for palette data
+; de = source of palettes (rBGPI or rOBPI)
 	ld b, $0
 	ld c, e
 	inc c
diff --git a/wram.asm b/wram.asm
index d749592..193a119 100755
--- a/wram.asm
+++ b/wram.asm
@@ -47,10 +47,7 @@ wStageCollisionMap:: ; 0xc700
 	ds $300
 
 wca00::
-	ds $63
-
-wca63:: ; 0xca63
-	ds $9d
+	ds $100
 
 wcb00:: ; 0xcb00
 	ds $500
@@ -59,17 +56,17 @@ SECTION "WRAM Bank 1", WRAMX, BANK[1]
 
 wOAMBuffer:: ; 0xd000
 	ds $a0
-
 wOAMBufferEnd:: ; 0xd0a0
-	ds $160
 
+SECTION "WRAM Bank 1.1", WRAMX [$d200], BANK [1]
 wPaletteData:: ; 0xd200
 	ds $80
 
-wd280:: ; 0xd280
+; This buffer holds the intermediate palette data when fading to a new palette.
+; The target palette is held in wPaletteData.
+wFadeBGPaletteData:: ; 0xd280
 	ds $40
-
-wd2c0:: ; 0xd2c0
+wFadeOBJPaletteData:: ; 0xd2c0
 	ds $40
 
 wPartyMons:: ; 0xd300