Files
Neutron/docs/orbit-camera.md
T

39 lines
2.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Orbit camera handedness correction
2026-11-03. User reports the world flips when using orbit inspection.
This is a modern camera bug; no new original-binary interpretation is needed.
## Cause and correction
Program used System.Numerics CreateLookAt/CreatePerspectiveFieldOfView for
inspection, both right-handed. Gameplay and source geometry use positive-Z
left-handed camera space. At the same eye/target/up, swapping the paired view
and perspective conventions reverses screen X. The old orbit view therefore
mirrored the world relative to gameplay. Vulkan's shared M22 viewport flip is
still required for screen Y; removing that would introduce another inversion.
OrbitCamera now owns the inspector eye/view/projection calculation and uses
CreateLookAtLeftHanded/CreatePerspectiveFieldOfViewLeftHanded. The caller applies
the same single Vulkan Y correction as gameplay. Existing orbit positions,
elevation limits, zoom, field of view and depth range are retained. Gameplay,
scripted and Rocketship cameras keep their existing math.
## Verification
ProjectionTests covers36 combinations of four azimuths, three elevations and
three aspect ratios (4:3,16:9,21:9). Tests independently construct forward/right/up
vectors and verify centered target, screen directions, positive-Z forward and
Vulkan0..1 near/far depth. Existing all35 level clip mappings and actual outside
geometry regression also pass. Main .NET build passes.
Before/after960×720 llvmpipe model captures show the horizontal reflection;
mirroring the old image matches the corrected view to under.0012 mean intensity
per RGB channel, versus2.68–4.77 without reflection. Both runs enable Vulkan
validation and report zero errors. Captures were inspected. The two-frame lab
gameplay readbacks before/after are byte-identical with the same copied assets.
Generated evidence: artifacts/orbit-camera/{projection.log,build.log,before.log,
after.log,comparison.log,comparison.png,gameplay-before.log,gameplay-after.log}.
The first test compile had an ambiguous target-typed Vector4 overload; specifying
Vector4 fixed it before validation. Package/native window results follow after
rebuild; native Windows remains a separate runtime check.