# donut documentation

deeper documentation for donut, the real-time schwarzschild black-hole renderer.
the top-level [`README.md`](../README.md) is the overview; the two documents here
go into how it actually works.

- **[physics.md](physics.md)** — the physics and maths. tracing light through
  curved spacetime: the schwarzschild metric, null geodesics and the equations of
  motion, the numerical integrator and its adaptive step, the event horizon /
  photon sphere / isco, the novikov–thorne accretion disk, gravitational and
  doppler redshift with relativistic beaming, and the observable quantities the
  renderer can measure. tied throughout to
  [`assets/shaders/geodesic.slang`](../assets/shaders/geodesic.slang).

- **[architecture.md](architecture.md)** — how the program is built. the code's
  layering (application / scene / renderpath / uilayer), the portable rhi that lets
  the same rendering run on opengl and vulkan, the frame loop, the unified
  scene-and-simulation world, the rendering pipeline (progressive resolution,
  supersampling, environment lighting, tone-mapping), the docking ui, the export
  pipeline, and the build system.

for each pixel, donut casts a ray from the camera and follows it backward through
the curved spacetime around sagittarius a\*. rays that fall past the horizon are
the shadow; rays that graze the photon sphere wind around it into the bright ring;
rays that strike the hot orbiting disk pick up its shifted glow; rays that escape
read the background sky. that trace is one gpu shader, fed by a small portable
graphics layer so it runs identically on both backends.