hologram

what it does that other engines don't

Every effect below is computed from the physics rather than approximated by a shader trick, and every one is pinned by a host test against its closed-form answer.

Two facing mirror walls repeating a chrome sphere and red spheres into an infinite corridor above a checker floor

recursive mirrors

Facing mirrors produce a true infinite corridor, to any depth, at any viewing angle. Screen-space reflection structurally cannot draw this frame: it can only reflect what is already on screen. Here the rays really bounce, up to sixteen times.

A clear glass ball lens holding an inverted image of the checker floor behind it

glass by the Fresnel equations

The real pair, s and p computed separately, not Schlick's fit. Refraction, total internal reflection, and reflectance that climbs toward grazing incidence because physics says so and not because a parameter does. The checker floor hanging upside down inside the ball lens is the classic proof that the refraction is real.

Two glass balls in front of a white stripe, the larger tearing the stripe edge into an orange and cyan fringe

spectral light

Twelve wavelengths per pixel, each refracting at its own Cauchy n(lambda), folded to sRGB through the CIE 1931 colour matching functions. Crown glass fringes gently. Flint tears the same white edge into a spectrum about five times wider, which is exactly why camera lenses pair the two.

Two dark windows on a white wall, one showing a grey square and the other a deep blue square

polarization

Every ray carries a Stokes vector and every interface applies a Mueller matrix. Crossed polarizers go black. A third pane at 45 degrees between them brings back exactly one eighth. A waveplate writes interference colour because its retardance runs as 1/lambda.

The inside of a paraboloid dish flaring to white as the whole aperture reflects the sun at once

curved mirrors, quoted as optics quotes them

Apex, axis, vertex radius of curvature, conic constant, rim. Stand at a paraboloid's focus and every zone of the dish reflects your eye into the sun, so the whole aperture flashes at once: a solar furnace, seen from the inside.

$Two ruled panels diffracting sunlight, the right one carrying a full rainbow band$

diffraction gratings

The conical, off-plane vector form. The groove component of the direction is conserved, the dispersion component picks up m·lambda/d, and m = 0 falls out as exact specular. Orders sweep across a ruled panel as you walk, the way a CD tilts its colours.

the oracle

source/cpu_trace.c is a complete second tracer in plain C, and the three shaders under shaders/ are its statement-for-statement twins. The C version is allowed to be slow and obliged to be right: every optical law lands there first, held by host tests to closed-form answers. Then holo_oracle_diff() reads the presented GPU frame back and compares it to a CPU render of the same camera.

The CPU reference tracer's first picture: spheres on a checker floor under a gradient sky — The oracle's first picture, rendered by the plain C tracer.

That diff is the engine's central correctness mechanism. A change that lands in one tracer and not the others stops being a mystery and becomes a failing exit code. The bar is a mean error under 1/255 with fewer than 0.75% of pixels off by more than 8/255, and all eight examples pass on every proven path: the HLSL tracer runs 0.019 to 0.118 mean under D3D11, the GLSL one 0.027 to 0.251 under WebGL2 and 0.0001 to 0.080 natively on Linux, where Mesa's software rasteriser does the arithmetic the way the C oracle does and the agreement tightens to four decimal places. The outlier percentages track each other almost exactly, which is the number worth reading, since it says every tracer takes the same branches and culls the same rays.

The host tests assert physics rather than pixels: 382 checks across 8 suites covering Snell's angles into n=1.5 glass, the 41.81 degree critical angle, 4% reflectance at normal incidence, a vanishing p-component at Brewster's angle, Malus's law at five angles, the three-polarizer paradox to the exact eighth, BK7's Abbe number computing to its catalogue 64, a paraboloid focusing every zone at R/2, an ellipsoid imaging focus onto focus, Littrow retroreflection, and the conical invariant.

modules

linalg Vectors, and the optics that is vector arithmetic: reflection, Snell refraction, Fresnel, the grating equation

polar Stokes rows, Mueller matrices, Fresnel amplitudes with the TIR phase

spectrum Wavelength samples, Cauchy dispersion, CIE colour matching

geometry Rays against spheres, planes, rectangles and conic dishes

camera The camera as a ray generator

cpu_trace The reference tracer, the oracle

gpu_scene The scene as the shader's uniform block

collision Capsule-vs-walls walking with gravity

timestep Fixed-step accumulator, ported from magnolia

display The only file that talks to sokol: window, device, quad, uniforms, frame readback

input Keys held and mouse look, folded per frame

oracle The GPU-vs-CPU frame diff, and the dump that holds an out-of-process tracer to it

the examples

Each milestone left a runnable demo behind.

ExampleWhat it shows

m0_windowA window, a fullscreen quad, uniforms arriving every frame.

m1_cpuThe CPU tracer's first picture, written to a PPM.

m2_gpuThe same scene traced on the GPU, held to the oracle.

m3_mirrorsFacing mirror walls, a chrome sphere, a polished floor, all recursing.

m4_glassA ball lens holding the checker floor upside down inside it.

m5_spectralCrown and flint glass in front of one white stripe.

m6_polarizationThe three-polarizer paradox, and a waveplate's interference colour.

m7_roomThe vertical slice: a room of mirrors, glass, a polarizer and a flint ball that you walk through in first person.

m8_furnaceA paraboloid with its focus at eye height on the path. Walk into it.

m9_spectrumTwo ruled gratings throwing the sun's orders back at you.

The walkable room: mirrored side walls, a large refracting ball, pink spheres and warm beige walls — m7_room, the vertical slice. Crystal Mirror Maze is now being built on this frame.

m7_room, m8_furnace and m9_spectrum are interactive: click to capture the mouse, WASD to walk, Space to jump, T to toggle spectral tracing, Escape to release the mouse.

Every GPU example also accepts --diff, which renders the same frame through the CPU tracer and compares. The exit code is the verdict.

about

An optics-first 3D game engine by magmacrunch media. The games it exists for, starting with Crystal Mirror Maze, are built entirely from analytic primitives (planes, rectangles, spheres, conics) and rendered at low resolution by design. Closed-form intersections at 640x480 are exactly the workload a fullscreen-shader ray tracer can afford in real time, and a tracer is the only renderer in which curved mirrors, refraction, dispersion and polarization come out correct rather than faked.

C99 engine and one tracer in three dialects, HLSL for D3D11, GLSL for GL and GLES3/WebGL2, MSL for Metal, on sokol for the window, GPU device and swapchain. Windows ships and Linux is proven: all eight examples pass the oracle natively on GL as well as under D3D11, and the unmodified Windows binary also passes under Wine given Microsoft's d3dcompiler_47.dll beside it. The Metal dialect is written and type-checked, and has not yet met a Metal device. The tracing runs on the GPU as a fullscreen-quad fragment shader over a scene of analytic primitives delivered in one uniform block, on a fixed-timestep simulation ported from magnolia. Games compile the engine's sources directly, magnolia-style: there is no library build and no package registry, and a game is three callbacks and a scene.

building

Requires Visual Studio on Windows, or any C compiler on Linux. No other dependencies, since sokol is vendored.

build.bat          # Windows: every example into build\
build.bat test     # builds and runs the host tests
./build.sh test    # the same, on Linux or macOS

Run the examples from the repository root. They read shaders\trace.hlsl at startup, so you can edit the tracer and relaunch without recompiling.

a scene is a literal

One sphere from the vertical slice, verbatim:

{ .center = { 0.0f, 1.0f, -2.0f }, .radius = 1.0f,
  .albedo = { 1, 1, 1 }, .transmit = 1.0f,
  .ior = 1.62f, .disperse = 0.02f },

not in the engine, by design

No editor, no ECS, no general physics engine, no mesh import, no skinned animation, no GUI toolkit, and there will never be triangles. Neither target game needs any of them, and each would cost more than it returns. Scenes are built in code from primitives, and collision is a capsule against axis-aligned walls.

the name

Named after the Dag Henderson track "hologram of a dream", published by magmacrunch music.

GitHub Wiki Reference

PolyForm Noncommercial 1.0.0 · Copyright 2026 magmacrunch media. Any noncommercial purpose is permitted, and commercial use is reserved to magmacrunch media. This differs deliberately from magmacrunch's Apache-2.0 2D engines: those are infrastructure for anyone, while hologram is the optics engine under magmacrunch's own games. Vendored sokol headers, by Andre Weissflog, keep their zlib licence.

Modules Reference

Wiki