Home

hologram

An optics-first 3D game engine: a real-time spectral ray tracer where light obeys physics. This wiki is the reference; the README is the introduction.

hologram exists because the effects its games are built on (recursive mirrors, dispersion, polarization, focusing, diffraction) are precisely the ones a rasterizer cannot compute and can only imitate. Every optical law here is derived from its physics, held by a host test to a closed-form answer, and then held again, pixel by pixel, against a second independent implementation.

Where to start

• The optics covers every law the engine implements, with the formulas, the sign conventions, and the test that pins each one. Start here if you want to know whether the physics is right.
• Architecture covers the twin tracers, the chain-and-fork walk, the oracle diff, and the uniform block.
• Writing a game: three callbacks and a scene.
• Scene reference: every field of every primitive.
• Shader constraints documents the fxc defects the walk is shaped around. Read before restructuring anything in the shader.
• Testing: what the 236 checks actually assert.
• Milestones: how the engine was built, M0 through M9.

Conventions used throughout

Units	Metres, seconds, micrometres for wavelength.
Handedness	Right-handed, y up. Cameras look down forward; -z is into the default view.
Directions	Unit unless a comment says otherwise. A ray's dir points along propagation, so an incident ray points into the surface it hits.
Normals	Point out of the surface on the arriving side. Every holo_ray_* flips them to meet the ray, so dot(normal, ray.dir) < 0 always holds at a hit.
Refraction	eta = n_from / n_to.
Colour	The tracer works in linear radiance and encodes sRGB at one place: the shader's final output, mirrored in the oracle's comparison.
Wavelength	Micrometres everywhere (0.5893 is the sodium D line).

Status

All milestones M0 through M9 are complete. 236 host checks pass; eight GPU examples agree with the CPU oracle between 0.02 and 0.12 mean error per 255 levels. The engine targets Windows/D3D11 today; see Architecture § Portability for what a second backend needs.