Files
Neutron/docs/presentation-and-ui.md

81 lines
4.0 KiB
Markdown

# Persistent presentation and widescreen UI
User-requested modern presentation/layout, 2026-10-25. Original assets and hashes
remain unchanged. These policies are separate from original fade/progression recovery.
## Presentation lifetime
Program.Main owns RenderSession until application exit. Each Run replaces level,
controller and audio state; SDL window/title changes do not recreate the window.
Position, logical/drawable dimensions, focus and fullscreen state survive loading.
VulkanRenderer.ReplaceScene validates bounds and stages vertex/index buffers,
textures, sampler and descriptor pool/sets after DeviceWaitIdle. Instance, device,
surface, swapchain, targets, pipelines and layouts stay alive. Resize/fullscreen
changes still replace size-dependent swapchain/targets. SceneRevision increments
on success and RendererIdentity exposes core handles for verification.
Old scene resources remain available until staging succeeds. Failure cleans partial
new resources and restores the prior set. Invalid indices/RGBA are runtime-tested
to preserve revision, identities and rendering; allocation-failure rollback is
implemented without fault injection. Loading remains synchronous; source fades
and loading presentation remain unfinished.
## Uniform layout and pointer mapping
UiViewport uses scale=min(drawableWidth/640,drawableHeight/480). Logical dimensions
are drawable dimensions divided by that common scale. Art/glyph X/Y proportions
match while the3D scene fills the viewport.
| UI | Anchor |
| --- | --- |
| Objective pad/text/digit | Bottom-right delta from authored640x480 |
| Practice prompt/F1 menu | Centered authored canvas |
| F2 live panel | Top-left safe inset |
Original4:3 positions, objective edge clipping and strict practice hit regions
remain. Widescreen anchors are an explicit port policy. --width/--height choose
initial window/offscreen dimensions64..8192; subsequent loads retain actual size.
Mouse coordinates map from SDL logical dimensions into actual drawable pixels
before inverse modal mapping. Double precision avoids ultrawide cancellation that
turned boundary225 into225.00003. Fractional DPI with independently rounded pixel
dimensions uses the same mapping.
## Verification
UiViewport/Hud/DebugOverlay tests cover nine aspect/resolution fixtures,4:3
equivalence,16:9/21:9/32:9, square/portrait,1.5x/2x DPI and fractional rounded
drawable dimensions. They verify glyph/art proportions, anchors, centered layouts
and strict Yes/No boundaries. The full suite passes in
artifacts/persistent-widescreen-full-tests.log, including539 unchanged originals.
Actual headless lab/VR04/lab Run transitions retain one renderer with revisions
1/2/3 at1280x720, exact RETURN root/companion and zero Vulkan errors
(artifacts/persistent-practice-return.log).
Native GTX1070: six loads, one window/renderer at960x720,1280x720,1680x720,
2560x720 and fullscreen3440x1440. Checks assert unchanged window ID/bounds/focus,
renderer identities across loading, fullscreen retention/restored windowed bounds,
native practice pointer mapping, rejected-load retention and zero cumulative
validation errors. Captures were visually inspected. Evidence:
artifacts/window-transition-final.log and window-transitions/*.png. Existing F1/
force-control and F2 input checks also pass from widescreen startup sizes.
```
source scripts/env.sh
dotnet build
scripts/test-window-transitions.sh
```
The runner uses installed Xvfb/Xfwm with private X11/D-Bus and artifact-backed
configuration. Bare Xvfb lacks a window manager to honor fullscreen requests.
NEUTRON_WINDOW_TEST=1 scripts/test.sh can use an existing managed display. These
are test dependencies; the game adds none. Linux runtime/cross-publishing does
not establish new native Windows or original visual/gameplay equivalence.
Both platform self-contained builds pass. The packaged Linux executable also
passes1920x1080 lab/VR04/lab with one renderer and exact RETURN root/companion
(artifacts/package-persistent-return.log; validation layers unavailable for this
standalone invocation). Native source/fullscreen checks above enable validation.