Document pause page switching

[Dragorn421]

No description provided.

[Dragorn421]

I will say this must be one of the worst bits of the pause menu code
I even forgot to copypaste some bits from the whole docs draft PR

Here are some explanations on what's going on:

KaleidoScope_DrawPages draws the item page in the -z direction, equip in -x, quest in +z and map in +x
this turns out as:

"scrolling" works by (approximately) the camera being in the center and rotating in increments of 90° to face a different page.

per KaleidoScope_SetView, the camera's at (where the camera points at) is always 0,0,0.
the eye coordinates (where the camera "is", "looks from") is what's animated to produce the "rotation" effect

when looking at a page and not scrolling, the eye coordinates are e.g. 64,0,0 (64 along +/- x/z) (hence this PR's #define PAUSE_EYE_DIST (64.0f))

when scrolling (and this is where this code really is cursed), KaleidoScope_UpdateSwitchPage (named so in this PR) updates the eye coordinates in increments read from the sPageSwitchEyeDx/z arrays
These arrays have entries for each combination of each page and the switch direction left/right, aka all nextPageMode; // (2 * prev pageIndex) + (scroll left ? 1 : 0) values

For example if currently on the map page, then the eye is on the opposite side of that page from 0,0,0, aka (since map page is towards +x) towards -x, eye=(-64,0,0)

Now if scrolling left, nextPageMode is set (see KaleidoScope_SwitchPage) to PAUSE_MAP * 2 + 1 == 3
sPageSwitchEyeDx[3] is 4, sPageSwitchEyeDz[3] is 4
the scrolling takes 16 frames (cf pauseCtx->switchPageTimer), so this makes the eye move (linearly) from (-64,0,0) to (-64 + 4*16,0,0 + 4*16)=(0,0,64), making the camera face towards -z, towards the item page, which is indeed left from the map page

This PR puts calculations in sPageSwitchEyeDx/Dz instead of the raw values.
For example sPageSwitchEyeDx[0 == 2*PAUSE_ITEM + 0] (scroll right from the item page) has:
-PAUSE_EYE_DIST * (PAUSE_MAP_X - PAUSE_ITEM_X) / 16, // PAUSE_ITEM right
scrolling right from the item page brings the view to the map page hence the usage of PAUSE_MAP_
the initial eye.x (when sitting on the item page) is -PAUSE_EYE_DIST * PAUSE_ITEM_X (be opposite from the page across 0,0,0)
we want a dx value such that (after the 16 frames of switching):
eye_x_map = eye_x_item + 16 * dx
aka -PAUSE_EYE_DIST * PAUSE_MAP_X = -PAUSE_EYE_DIST * PAUSE_ITEM_X + 16 * dx
aka dx = -PAUSE_EYE_DIST * (PAUSE_MAP_X - PAUSE_ITEM_X) / 16
and this generalizes for any two side by side pages and a scroll direction

---

there's also gPageSwitchNextButtonStatus which for some reason has different indexing logic and is used to set which buttons are dimmed on each page, it could just be indexed by target page but apparently they liked this weird indexing better

[engineer124]

What do these 3 numbers mean for the timer? The (4 * 16) appears a few times

[Dragorn421]

The timer increases in increments of 4
pauseCtx->switchPageTimer += 4 * ZREG(46);
(ZREG(46) is always 1)
-> hence 4*16

The if before this else has (4 * 16 * ZREG(47))
and ZREG(47) is always 1
-> so the 4*16*1 is for symmetry

I assume at some point the dev tried ZREG(47) == 2 or 3 (or whatever) then this else if would pass at (resp.) 1/2 or 1/3rd of the full animation but idk

(note inside this else if is dead code as the existing "

`ZREG(47)` is always 1 so this normally never happens

" comment tries to say, is it unclear?)

[Dragorn421]

16 is now a macro: PAGE_SWITCH_NSTEPS

[engineer124]

What's the PT here?

[Dragorn421]

It comes from this debug string

oot/src/overlays/misc/ovl_kaleido_scope/z_kaleido_scope_PAL.c

Line 514 in b3486b5

osSyncPrintf("kscope->kscp_pos+pt = %d\n", pauseCtx->pageIndex + pt);

PT values are for the pt variable

I guess I could rename it to direction or something maybe?

---

Pure guess with no proof: maybe "pt" stands for "page turn" 8)

[fig02]

Sorry for review delay. Distracted by retail, and also this stuff is pretty intimidating.

My comments may come from a place of ignorance, as I have not put as much time into learning how this system works as you have. But I guess its a good test for trying to make the docs understandable to someone new.

[Dragorn421]

I added a bunch more docs/comments, lmk if it helps

[fig02]

All of these explanations are what I needed, thanks.
Small suggestion with ascii art below