Sylpheed/docs/re/screen-transitions.md

What happens between two screens — a fade through black, and where its timing lives

Status: ✅ CONFIRMED. The quad and its ramp are decoded (a keyframe group on the disc, with a disc-wide check); the wall-clock timings are measured off the running game at 30 fps. One piece is undecodable from this field and is called out below.

Answers MISSION Q7.

The mechanism — decoded

Every title-side screen carries a full-screen untextured primitive that is black, and paints last: pteff00.prm in GP_TITLE, pfeff00.prm in GP_SAVE_LOAD. That it sorts last was already established (structures/ui-paint-order-key.md); what is new here is that its keyframe group is the transition.

The group is always four blocks, and always this shape:

block	alpha	meaning
1	0xff at t = T0	the screen starts black
2	0x00 at t = T1	ramp to fully clear — the screen fades in
3	0x00 at t = T2	clear; this is the resting pose, the quad is invisible
4	0xff, no time	ramp back to black — the screen fades out on exit

Read with the corpus's rule that a keyframe is the start of a ramp (structures/ui-resting-pose.md).

🔴 The table this section used to print was taken with a STALE READER, and both its numbers were wrong (corrected 2026-08-30). fade_quads.py read each pose's time from blk+36 — the next record's time word — so every time was shifted one slot and the last pose came out untimed (t=—). That is the same association the record-layout fix retired in the crate; the Python helper was never swept with it. Fixed, and controlled against the rebuilt screen info, which prints [0 12 70 80] for the same element:

$ tools/re-capture/fade_quads.py 4 5 6          # GP_TITLE
build 4 (title)      pteff00.prm   t=  0 α=255   t= 16 α=0   t=261 α=0   t=269 α=255
build 5 (main menu)  pteff00.prm   t=  0 α=255   t= 12 α=0   t= 70 α=0   t= 80 α=255
build 6 (EXTRAS)     pteff00.prm   t=  0 α=255   t= 12 α=0   t= 64 α=0   t= 74 α=255

Every pose is timed. There is no untimed keyframe, and the fade-out ramp is on the disc after all: 70 → 80 = 10 units for the main menu, 64 → 74 = 10 for EXTRAS, 261 → 269 = 8 for the title.

⚠️ And the fade-IN was mislabelled by the same shift. This page used to say the screen "holds black for 0.20 s, then fades in over 0.87 s (EXTRAS), 0.97 s (main menu) or 4.08 s (the title)". Those spans are T2 − T1 under the stale pairing — the stretch where the quad sits at α = 0, i.e. the screen fully visible and not fading at all. Read correctly the screen starts black at t = 0 and fades in over 12 units (0.20 s) on the menu and EXTRAS, 16 units (0.27 s) on the title. A port pacing its menu fade-in off the old number would have run it 5× too slow.

❔ The fade-OUT duration is not in this field

The fourth block has no time — a group's last block stops 4 bytes short and that word is already the next group's element index (ui_layout.rs documents the packing). So the disc gives the ramp's target (black) and not its length. That duration is measured below, and the port is authoring it.

The disc-wide check, and what it shows about overlays

Over every GP_*.pak, counting bundles that have a .prm element and ≥8 elements (screen-sized rather than a two-element fragment):

40 of 97 carry a 255 → 0 → 255 quad; 56 of the 60 found disc-wide have exactly 4 keyframes.

41 % sounds weak until it is read per pak, where it is nearly all-or-nothing:

pak	with quad / screen-sized
GP_MISSION_SELECT, GP_MOVIE_THEATER, GP_OPTIONS, GP_TUTORIAL, GP_SYSTEM	2/2 each
GP_BUNK, GP_CHALLENGE	6/6
GP_STAGE_CLEAR	4/4
GP_SAVE_LOAD	10/12
GP_TITLE	6/12
GP_DIALOG	0/133
GP_DEBRIEFING_PILOTLOG	4/102

GP_TITLE's 6 of 12 is the interesting row, and it is not a gap. The six that carry the quad are exactly the six screen builds — title, main menu and EXTRAS, English and Japanese. The six that do not are exactly the six overlays: the PRESS Ⓐ BUTTON plate and the two DELTASABER plates (ui-title-build-map.md). An overlay composited onto a screen has no transition of its own, so it has no fade quad — which is independent corroboration that those builds are overlays rather than screens. GP_DIALOG's 0/133 says the same thing about dialog boxes.

The timing — measured

Recorded with ffmpeg -f x11grab -framerate 30 over the game surface, mean frame luminance per frame; raw data in captures/transitions/transition-luminance.csv, filmstrip in transition-filmstrip.png.

	main menu → EXTRAS (Ⓐ)	EXTRAS → main menu (Ⓑ)
press → first visible change	0.07 s	0.37 s
fade-out to black	0.367 s	0.400 s
pure black (luminance 0.02)	0.233 s	0.167 s
luminance rise until settled	0.567 s	1.467 s

The fade-out is the number the file cannot give, and it comes out the same both ways: ~0.4 s, i.e. ~24 units under Q1's rule.

The black hold is consistent with the file's 12 units (0.20 s) but does not confirm it — the plateau spans the tail of the outgoing screen's fade-out and the head of the incoming screen's black, and this measurement cannot separate them.

⚠️ The luminance rise is not the quad's ramp

The two columns differ by 2.6× where the quad's declared ramps differ by only 1.12× (58 units vs 52). The filmstrip says why: the background reappears first and the labels arrive after it, so what the luminance curve is timing is the incoming screen's own element animations, not the fade quad. Quoting 1.47 s as "the main menu's fade" would be wrong. The quad's ramp is decoded; the screen's build-in is a separate, longer thing.

For the port

• a screen change is: fade the outgoing screen to black over ~0.4 s, hold black briefly, then fade the incoming screen in over its own declared ramp while its elements play their own keyframes;
• the fade-in ramp is read from the file (T1 − T0 on the screen's fade quad);
• the ~0.4 s fade-out and the black hold are authored from this page — the disc does not carry them.

✅ Which quantity the ~0.4 s is — measured 2026-08-29

Asked by the port: is 0.4 s (a) the ramp from the hold to the exit pose, i.e. exactly the missing duration of that untimed keyframe, (b) several keyframes' worth, or (c) something the game does independently of the group?

It is (a) — and it is bigger than the fade quad. Two facts.

🔴 1. "There is exactly one untimed keyframe, and every element has it" — REFUTED 2026-08-30. It was a STALE BINARY.

That claim came from screen info, and the copy of sylpheed-cli in this container was built 2026-08-29 12:38, before the keyframe-record-layout fix landed. The old parser shifted every time by one slot and could not time a group's final pose, so it printed a trailing -. Rebuilt, the same element reads:

stale  pteff00.prm  4 kf  rest t=70   [12:0,0  70:0,0  80:0,0  -:0,0]
fresh  pteff00.prm  4 kf  rest t=12   [ 0:0,0  12:0,0  70:0,0  80:0,0]

Four timed poses. There is no untimed keyframe and no unknown duration, so the question this section was answering — "is 0.4 s the missing duration of that untimed keyframe" — no longer has its subject. The argument below (the ratio test) is untouched and still shows the content fading rather than a quad arriving; what is dead is the framing around it.

✅ And the number is now decoded. pteff00.prm's final ramp is 70 → 80 = 10 units ≈ 0.167 s, not the ~24 units this page authored. That confirms the port agent's reading; I tried to refute it against the bytes and could not.

🔴 So the measured ~0.4 s is NOT the ramp alone — 0.4 s is ~24 units against a decoded 10. Something else occupies the other ~14 units.

✅ What the other ~14 units are — MEASURED 2026-08-30, and it is not a hold

This page previously guessed: "that the remainder is exactly the black hold is arithmetic that fits (14 units = 0.233 s), not a measurement". It has now been measured, and the guess was wrong. There is no black hold inside the fade-out.

Instrument. fade_decompose.sh boots to the main menu, arms the UI draw capture there, then presses Ⓑ, so one 260-frame window contains the whole screen change. fade_envelope.py reads the fade quad's alpha per submitted frame. The quad is identified, not guessed at: a .prm primitive carries no tex[base=…], and this element paints last (paint-order key), so it is the last full-screen untextured quad of a frame. Taking merely the last full-screen quad picks up textured backdrops and gives a different answer.

Control. The quad's ramp is decoded (10 units), so the instrument can be checked before it is believed. At Q1's 2 units per rendered frame, 10 units is 5 frames. Measured: the quad is absent at frame 39 and α=255 at frame 43 — 4 submitted-frame steps, with one unlogged frame inside the span. Agreement to within that one frame. An instrument that could not reproduce the decoded ramp could not be trusted on the undecoded remainder.

The measurement (data/fade-envelope-menu-to-title.txt):

frame 34   content elements begin fading      (a 255 quad appears and decays)
      35..41   255 223 207 175 95 31 15       the content fade
frame 40   the BLACK QUAD first appears, α=102
      41   α=127
      43   α=255                              fully black
      45   last frame the menu draws
frame 46   6 draws (vs 12) — ONE frame of black
      47+  the title's build starts

✅ The ~14 extra units are the content elements' own fade-outs, which start six frames BEFORE the quad's ramp and overlap it. The blackout runs frame 34 → 43 = 9 submitted frames ≈ 0.30 s at 30 Hz, of which the quad's ramp is the last 4. That is the same quantity the filmstrip measured as 0.367–0.400 s with coarser timing, and it decomposes as overlap, not sequence.

✅ The inter-screen black is ONE frame (46), not ~14 units. The draw count collapses from 12 to 6 for exactly one frame and the incoming build starts at 47.

📌 For the port: a transition is not "ramp the black quad for 10 units, then hold black for 14". It is "start the content elements fading, and 6 frames later ramp the black quad over its declared 10 units on top of them". Authoring it as a hold puts a sixth of a second of dead black in the middle of every screen change that the game does not have.

⚠️ Reach. One transition (main menu → title, via Ⓑ), one run. The frame axis has gaps — 232 --- frame headers over frames 3…260, so ~10 % of submitted frames carry no UI draw — which is ±1 frame on any span quoted here and is why the ramp is given as 4 steps rather than a duration to three digits. Whether the six-frame lead is constant across screens, or is a property of these elements' keyframes, is not measured.

elements	final untimed block	what it does
pteff00.prm (the fade quad)	a = 255	goes black
pteff10, pteff12, ptbtn01…05, ptmsg	a = 0	fade out
ptframe1, ptframe2	a = 255	hold, and get covered
ptbase, pteff05, ptloop*, pteff02.prm	single keyframe	hold

2. The capture shows the content fading, not just a black quad arriving. This has a null hypothesis that discriminates: under (c) — the game blackens the frame independently — every region is scaled by the same 1 − α, so the ratio between a button region and a background region is constant through the fade-out. Under (a) it must fall, because the buttons ramp to a = 0 while the background elements hold at 255 and are only dimmed.

Measured on transition-filmstrip.png, button column ÷ upper-right background art, frame by frame through the fade-out:

frame     0      1      2      3      4      5
ratio  6.495  5.574  3.105  2.125  1.935   (black)

A 3.4× monotonic fall. Constant is refuted. The buttons really are fading independently of the overall dim, exactly as their declared final block says. (The incoming screen runs it in reverse, 2.22 → 3.47 over frames 7–12.)

⚠️ Reach. The filmstrip is downsampled and the "button" region unavoidably contains some background, so the ratio is a direction, not a clean alpha measurement. It refutes the constant-ratio null decisively; it does not by itself pin the 0.4 s to ±0.05 s. And it is measured on one transition pair.

For the port

Write one authored constant — the duration of the final untimed keyframe, ~0.4 s / ~24 units — and play the group to its end on every element. Do not model the exit as a black rectangle fading over a frozen screen: the buttons and labels ramp to transparent at the same time, and that difference is visible.