diff options
| -rw-r--r-- | README.md | 28 | ||||
| -rw-r--r-- | branding/screenshot_1.png | bin | 566012 -> 0 bytes | |||
| -rw-r--r-- | branding/screenshot_2.png | bin | 916806 -> 0 bytes | |||
| -rw-r--r-- | docs/README.md | 27 | ||||
| -rw-r--r-- | docs/architecture.md | 300 | ||||
| -rw-r--r-- | docs/physics.md | 373 |
6 files changed, 710 insertions, 18 deletions
@@ -1,10 +1,6 @@  -Donut is a real-time renderer for Sagittarius A* (Sgr A*) that traces light through the curved spacetime surrounding the black hole. Each pixel is represented by a light ray originating from the camera. The ray is integrated through the Schwarzschild metric, allowing the renderer to reproduce gravitational lensing and the distortion of the surrounding accretion disk and background. The renderer runs on the GPU using compute shaders, allowing the scene to be explored interactively in real time. - -## Screenshots - - +Donut is a real-time renderer for Sagittarius A* (Sgr A*) that traces light through the curved spacetime surrounding the black hole. Each pixel is represented by a light ray originating from the camera. The ray is integrated through the Schwarzschild metric, allowing the renderer to reproduce gravitational lensing and the distortion of the surrounding accretion disk and background. The renderer runs entirely on the GPU — one ray per pixel, traced in a full-screen fragment shader — allowing the scene to be explored interactively in real time. ## Physics Donut uses the Schwarzschild solution to describe the spacetime around Sgr A*. The metric is (with $r_s = \frac{2GM}{c^2}$): @@ -13,28 +9,24 @@ $$ ds^2 = -\left(1-\frac{r_s}{r}\right)dt^2 +\left(1-\frac{r_s}{r}\right)^{-1}dr^2 -+r^2(d\theta^2+\sin^2\theta,d\phi^2), ++r^2(d\theta^2+\sin^2\theta\,d\phi^2), $$ -Light rays are propagated along null geodesics of this metric. The resulting equations are integrated numerically using fourth-order Runge-Kutta (RK4), with the ray represented in spherical coordinates along with its derivatives and conserved quantities. The Schwarzschild metric provides conserved energy and angular momentum along each geodesic. These quantities are used during integration rather than explicitly evolving every coordinate of the ray. +Light rays are propagated along null geodesics of this metric. The geodesic equations are integrated numerically, the ray represented in spherical coordinates together with its derivatives. The Schwarzschild metric provides a conserved energy along each geodesic, which supplies the time component of the motion so that the $t$ coordinate never has to be integrated explicitly. Each ray is integrated step by step until it reaches the event horizon, intersects an object or the accretion disk, or escapes the region being rendered. -The integration uses adaptive step sizes. Rays passing through regions of strong curvature require smaller steps, while rays far from the black hole can be advanced more quickly. Rays that are clearly escaping are terminated early to avoid unnecessary computation. RK4 was chosen to provide sufficient accuracy for the rapidly changing trajectories near the black hole while still being practical to run for large numbers of rays on the GPU. +The integration uses adaptive step sizes, and this is where most of the accuracy comes from. Rays passing through regions of strong curvature near the photon sphere take very small steps, while rays far from the black hole are advanced across near-flat space in a few large strides. Rays that are clearly escaping are terminated early to avoid unnecessary computation, so rays near the black hole receive far more computation than rays already leaving the gravitational field. The curvature of spacetime changes the direction of each ray as it passes around the black hole. Rays passing close to the photon sphere can undergo large deflections or orbit the black hole several times before escaping. This produces the distorted background, multiple images of the accretion disk, and the bright lensing structures surrounding the shadow. ## Rendering -For each pixel, Donut generates a ray from the camera using its position, orientation, field of view, and aspect ratio. The ray is then converted into the coordinates used by the geodesic integrator and propagated through the scene. During integration, the renderer checks for intersections with the black hole, accretion disk, and other scene objects. Rays that escape are sampled against the background environment. The accretion disk is represented as a volumetric medium rather than a flat textured surface. Its density is generated procedurally using 3D noise, giving it a cloud-like structure, and the disk rotates according to Keplerian orbital motion. Since the disk is viewed through curved spacetime, different parts of it can reach the camera along multiple paths around the black hole. The resulting image includes gravitational lensing, gravitational redshift, and Doppler shifting from the rotating disk. The final pixel color is determined from the ray's path, its intersection with the scene, and the relativistic effects accumulated along the way. The entire process is performed on the GPU using compute shaders, allowing thousands of rays to be integrated simultaneously. - -The geodesic equations are integrated using fourth-order Runge-Kutta (RK4): +For each pixel, Donut generates a ray from the camera using its position, orientation, field of view, and aspect ratio. The ray is then converted into the coordinates used by the geodesic integrator and propagated through the scene. During integration, the renderer checks for intersections with the black hole, accretion disk, and other scene objects. Rays that escape are sampled against the background environment. The accretion disk is a thin, opaque, self-luminous surface in the equatorial plane, with a Novikov–Thorne temperature profile that is hottest just outside the inner edge and cools outward, coloured as a redshifted blackbody; an optional turbulence overlay modulates its brightness. Its gas orbits at relativistic Keplerian speed (reaching half the speed of light at the innermost stable orbit), so the disk is Doppler-brightened on the side rotating toward the camera. Since the disk is viewed through curved spacetime, different parts of it can reach the camera along multiple paths around the black hole. The resulting image includes gravitational lensing, gravitational redshift, and Doppler shifting from the rotating disk. The final pixel color is determined from the ray's path, its intersection with the scene, and the relativistic effects accumulated along the way. The entire process runs on the GPU as a full-screen fragment shader, tracing every pixel's ray in parallel. -$$ -y_n+ -\frac{h}{6} -(k_1+2k_2+2k_3+k_4). -$$ +The full equations of motion, the accretion-disk and redshift models, and the integration scheme are documented in [docs/physics.md](docs/physics.md). -RK4 has a local truncation error of $O(h^5)$ and a global error of $O(h^4)$, making it suitable for maintaining accurate trajectories without requiring extremely small steps everywhere. Adaptive stepping and early termination are used alongside RK4 to keep the cost of tracing rays manageable. Rays near the black hole receive more computation than rays that are already far from the gravitational field. -\ +## Documentation +For a deeper explanation of how Donut works, see the [`docs/`](docs/) folder: +- [docs/physics.md](docs/physics.md) — the physics and mathematics: null geodesics and the equations of motion, the numerical integrator, the event horizon / photon sphere / ISCO, the Novikov–Thorne accretion disk, gravitational + Doppler redshift and relativistic beaming, and the observable quantities the renderer can measure. +- [docs/architecture.md](docs/architecture.md) — how the program is built: the portable OpenGL/Vulkan RHI, the two renderers, the unified scene-and-simulation world, the rendering pipeline, the Dorico-style tabs, and the physical-value export pipeline. ## License Donut is released under the MIT License. diff --git a/branding/screenshot_1.png b/branding/screenshot_1.png Binary files differdeleted file mode 100644 index 7175ab6..0000000 --- a/branding/screenshot_1.png +++ /dev/null diff --git a/branding/screenshot_2.png b/branding/screenshot_2.png Binary files differdeleted file mode 100644 index 2aece5d..0000000 --- a/branding/screenshot_2.png +++ /dev/null diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..fa5d6ed --- /dev/null +++ b/docs/README.md @@ -0,0 +1,27 @@ +# 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 tabs, 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. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..4eb4153 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,300 @@ +# The Architecture of Donut + +How Donut is put together as a program: how the code is layered, how the same +rendering runs on two graphics APIs, how a frame is drawn, and how the editor, the +live simulation, and the data export fit together. + +For the physics behind the image itself, see [`physics.md`](physics.md). + +## Contents + +- [Overview](#overview) +- [The RHI: one interface, two backends](#the-rhi-one-interface-two-backends) +- [A frame, end to end](#a-frame-end-to-end) +- [The two renderers](#the-two-renderers) +- [Scene and Simulation: one world](#scene-and-simulation-one-world) +- [The rendering pipeline](#the-rendering-pipeline) + - [Progressive resolution and supersampling](#progressive-resolution-and-supersampling) +- [The workspace: tabs](#the-workspace-tabs) +- [The export pipeline](#the-export-pipeline) +- [The build system](#the-build-system) + +## Overview + +Donut is split into a few pieces with distinct jobs, so the physics, the platform, +and the interface can change independently. + +```mermaid +flowchart TD + App["Application<br/>thin shell + main loop"] + App --> Scene["Scene<br/>the document/world:<br/>objects, black hole, cameras"] + App --> UI["UILayer / Workspace<br/>the tabbed ImGui interface"] + App --> RP["RenderPath<br/>device-side rendering"] + App --> Dev["RHI::Device<br/>the GPU, abstracted"] + + RP --> SR["SceneRenderer<br/>raster world editor"] + RP --> BHR["BlackHoleRenderer<br/>geodesic ray tracer"] + RP --> Dev + + Dev -.implemented by.-> GL["OpenGLDevice"] + Dev -.implemented by.-> VK["VulkanDevice<br/>MoltenVK"] + + UI -.reads/writes.-> Scene + SR -.reads.-> Scene + BHR -.reads.-> Scene +``` + +| Component | File | Responsibility | +| --- | --- | --- | +| `Application` | [`src/core/application.cpp`](../src/core/application.cpp) | Owns everything; runs the main loop; handles input, resize, vsync, fullscreen; exposes actions to the UI | +| `Scene` | [`src/scene/scene.h`](../src/scene/scene.h) | The world as plain data — placed objects, black-hole/disk parameters, the editor and simulation cameras, the HDRI path | +| `UILayer` / `Workspace` | [`src/ui/ui_layer.cpp`](../src/ui/ui_layer.cpp) | The tabbed interface; returns which view is live and drives the scene through `AppActions` | +| `RenderPath` | [`src/rendering/render_path.cpp`](../src/rendering/render_path.cpp) | Turns the scene into pixels on whatever device is active; owns the two renderers and the environment cubemap | +| `RHI::Device` | [`src/rendering/rhi.h`](../src/rendering/rhi.h) | The portable GPU interface every backend implements | + +Two things carry most of the weight here. `Scene` is plain data with no knowledge +of the backend or the UI, and everything that touches the GPU goes through one +narrow interface (the RHI). The `Application` stays thin: it hands the document to +`Scene`, the pixels to `RenderPath`, and the controls to `UILayer`. + +## The RHI: one interface, two backends + +Donut runs on both OpenGL and Vulkan (through MoltenVK on macOS) from one codebase. +All rendering is written once against an abstract Render Hardware Interface in the +`Donut::RHI` namespace, and each API supplies an implementation. + +```mermaid +flowchart LR + Renderers["SceneRenderer<br/>BlackHoleRenderer<br/>written once"] --> RHI["RHI::Device / CommandList<br/>Buffer · Texture · Pipeline · RenderTarget"] + RHI --> GL["platform/opengl/<br/>OpenGLDevice"] + RHI --> VK["platform/vulkan/<br/>VulkanDevice"] + GL --> GLAPI[("OpenGL")] + VK --> VKAPI[("Vulkan / MoltenVK")] +``` + +The interface (in [`rhi.h`](../src/rendering/rhi.h)) is small and shaped for modern +GPUs: + +- `Device` is the factory and frame driver: `create_buffer`, `create_texture`, + `create_cubemap_from_hdri`, `create_render_target`, `create_pipeline`; + `begin_frame` / `end_frame`; `set_vsync`, `resize`, `wait_idle`; the ImGui hooks; + and the export helpers `run_offscreen`, `read_render_target`, + `read_render_target_float`. +- `CommandList` records work: `begin_render_pass` / `end_render_pass` (a `nullptr` + target means the swapchain), `bind_pipeline`, `set_viewport`, `bind_uniform`, + `bind_texture`, `bind_vertex_buffer`, `draw`. +- `Buffer`, `Texture`, `Pipeline` and `RenderTarget` are opaque GPU resources. +- `Format` is `{ None, Swapchain, RGBA8, RGBA16F, RGBA32F, D32 }`. `Swapchain` + means whatever the presented image is, resolved per backend; `RGBA32F` is what + makes raw floating-point export possible. + +The backend is chosen once at startup, before the window exists, since the two APIs +want the window created differently: + +```mermaid +sequenceDiagram + participant A as Application ctor + participant S as SettingsManager + participant W as Window (GLFW) + participant D as RHI::Device + A->>S: read graphics.render_api + alt Vulkan + A->>A: vulkan_prepare_glfw (GLFW_NO_API) + end + A->>W: create window + A->>D: create_vulkan_device or create_opengl_device + A->>D: init(native window) +``` + +Because the renderers only ever see the RHI, the same draw code gives +pixel-identical output on both backends. That parity is checked by rendering to an +off-screen target and comparing the read-back pixels. + +## A frame, end to end + +The main loop is `Application::run`: poll events, render, then let vsync pace the +frame or sleep to hit the target FPS. Each frame is assembled in +`Application::render_frame`: + +```mermaid +sequenceDiagram + participant Dev as Device + participant UI as UILayer + participant In as Input + participant RP as RenderPath + Dev->>Dev: begin_frame(clear) → CommandList + Dev->>Dev: imgui_new_frame + Note over RP: update the active camera's projection + UI->>UI: draw(ctx) → returns active View + In->>In: update_input(view) — orbit / FPS camera + RP->>RP: sync_hdri — reload cubemap if changed + RP->>RP: render(cmd, scene, view, w, h, moving, time) + Dev->>Dev: end_frame — submit + present +``` + +The `View` the UI returns — `None`, `Scene` or `BlackHole` — decides which +viewport is live and therefore what `RenderPath` draws. The `moving` flag, true +while the user is dragging or flying the camera, triggers the progressive-resolution +path described below. + +## The two renderers + +`RenderPath` owns two independent renderers, both written purely against the RHI. + +`SceneRenderer` ([`scene_renderer.cpp`](../src/rendering/scene_renderer.cpp)) is the +world editor: a conventional rasteriser that draws the placed spheres, the ground +grid, the selection outline and gizmo, and a near-black black-hole marker at the +origin, sized to the horizon and ringed with an amber accretion-glow outline so it +reads against the dark background. This is what you manipulate on the Scene tab. + +`BlackHoleRenderer` ([`black_hole_renderer.cpp`](../src/rendering/black_hole_renderer.cpp)) +is the geodesic ray tracer. It runs the physics shader from [`physics.md`](physics.md) +as a full-screen fragment pass into an off-screen target, then presents that target +to the screen. This is the expensive work, and it runs only on the Simulation tab +and during export. + +`RenderPath::render` routes to the right one based on the `View`: + +```mermaid +flowchart TD + R{View?} + R -->|Scene| SP["Swapchain pass:<br/>SceneRenderer.render + ImGui"] + R -->|None| EP["Swapchain pass:<br/>empty viewport + ImGui"] + R -->|BlackHole| GP["Off-screen geodesic pass →<br/>blit to swapchain + ImGui"] +``` + +## Scene and Simulation: one world + +The editor and the simulation are the same world, not two separate scenes. The +constant `SCENE_UNITS_PER_RS = 3.0` connects them: three editor grid units equal +one Schwarzschild radius. `SceneRenderer` draws the black-hole marker's horizon at +that radius, and `BlackHoleRenderer` takes every placed `SceneObject`, multiplies +its position and radius by $\text{SagA\_rs}/3$ to reach physical metres, and uploads +them into the shader's `Objects` uniform (up to 16 spheres). + +So a sphere placed on the Scene tab shows up in the same spot on the Simulation +tab, except now the curved rays bend around the hole and lens it, and it can appear +stretched, doubled, or smeared into an arc. The spheres are passive lit objects, +planets and the like; they don't exert their own gravity, only the black hole bends +light. + +## The rendering pipeline + +When the Simulation view is active, `BlackHoleRenderer::render_geodesic` does three +things each frame: + +1. Fills the uniforms (`fill_uniforms`): the camera basis and FOV; the + black-hole/disk parameters (radii converted to metres, temperature, brightness, + turbulence); the integration budget (`quality_steps`, clamped 1000–15000); and + the scene objects. +2. Picks the off-screen target by the `moving` flag (below) and runs the geodesic + fragment shader over a full-screen quad into it. +3. Blits that target to the swapchain (`blit`) with a present pipeline, flipping + vertically where needed so OpenGL and Vulkan agree on orientation, then draws the + ImGui overlay on top. + +Inside the shader, each pixel builds a ray from the camera basis, FOV and aspect, +marches the geodesic (see [physics](physics.md#the-equations-of-motion)), and shades +from whatever it hit: the opaque disk's redshifted blackbody, the black shadow, a +lit object, or the background. The background is the HDRI loaded as a cubemap +(`create_cubemap_from_hdri`); escaped rays sample it at a mip level chosen from how +fast neighbouring rays diverge (`ddx`/`ddy`), so the strongly lensed background +blurs rather than aliasing into a shimmering fan. The colour channel is then +tone-mapped with an ACES filmic curve. + +### Progressive resolution and supersampling + +Interactivity trades against quality through resolution and sample count, not by +touching the physics: + +| State | Off-screen target | Samples per pixel | +| --- | --- | --- | +| Camera moving | `GEO_LO` = 480 × 270 | 1 | +| Camera settled | `GEO_HI` = 960 × 540 | 4× rotated-grid supersampling | + +The integration budget is the same in both states, because the disk needs a high +step count to resolve at steep poses and lowering it during motion makes it +flicker. When the camera stops, the renderer switches to the larger target and the +fragment shader averages four sub-pixel samples in a rotated-grid ("4-rook") pattern +before tone-mapping, which cleans up the near-horizontal lensed edges and the thin +photon ring. + +## The workspace: tabs + +The interface follows Dorico's mode tabs: separate workspaces, one active at a +time, each returning a `View` so the renderer knows what to draw. + +| Tab | View | For | +| --- | --- | --- | +| Setup | `None` | Display & quality: vsync, target FPS, resolution, fullscreen, UI scale, HDRI selection, integration quality, early-exit distance | +| Scene | `Scene` | The world builder: place, select and transform objects with a gizmo; orbit the editor camera around the black-hole marker | +| Simulation | `BlackHole` | The live lensed view — the only place the geodesic tracer runs; tune the black hole and disk; orbit or fly (FPS) the camera | +| Export | `None` | Choose which observable channels, at what resolution and format, then render them to disk | + +Tabs whose view is `None` have no live 3-D viewport, so `Application::update_input` +skips camera handling for them. + +## The export pipeline + +Export writes out the physical quantities Donut computes, not just a screenshot. It +is driven by `RenderPath::export_frame` +([`render_path.cpp`](../src/rendering/render_path.cpp)) and the RHI's off-screen +helpers. + +```mermaid +flowchart LR + Cfg["ExportConfig<br/>channels · resolution · format"] --> Loop + subgraph Loop["for each enabled channel"] + direction TB + RT["create_render_target<br/>RGBA8 (PNG) or RGBA32F (raw)"] --> OS["run_offscreen:<br/>render_export(channel, raw)"] + OS --> RB["read_render_target(_float)"] + RB --> WR["write PNG / PFM / CSV"] + end + WR --> Files["exports/donut_[channel]_[timestamp].[ext]"] +``` + +A few points worth knowing: + +- The export always renders the settled view (`moving = false`) from the simulation + camera, at the requested resolution, whatever the live window is doing. +- Any combination of colour, redshift $g$, emission temperature and impact parameter + (the observables from [physics](physics.md#observable-channels)) can be exported in + one pass. +- PNG requests use an `RGBA8` target and the standard shader pipeline + (`m_geo_pipeline`), giving a viewable tone-mapped or false-coloured image. PFM and + CSV requests use an `RGBA32F` target and an HDR pipeline variant + (`m_geo_pipeline_hdr`), so the file holds the actual floating-point values: $g$ as + a ratio, temperature in Kelvin, impact parameter in $r_s$, colour as linear HDR + radiance. For the disk-only channels, the alpha channel carries a validity mask (1 + where a ray hit the disk, 0 elsewhere). +- Formats are PNG via `stb_image_write`, PFM (Portable Float Map — raw RGB float, + the usual choice for HDR data) via a small writer, and CSV for the scalar channels, + one grid value per cell. +- `run_offscreen` records a transient command buffer, submits it and waits, with no + swapchain and no frame pacing. The target is then read back on the CPU and written + to a timestamped file under `exports/`. + +## The build system + +Donut uses premake5 to generate GNU Makefiles. Both backends compile into one +binary; the choice between them is made at runtime from the saved settings, so +there is no separate "OpenGL build" and "Vulkan build". + +Generate and build (arm64 macOS): + +```bash +premake5 gmake && make config=debug-macosx +``` + +`premake5 clean` is wired up as a custom action that removes the generated build +output (`bin/`, `bin-int/`, the Makefiles) along with the transient runtime files +(`logs/`, `config/`, `imgui.ini`), for a genuine from-scratch reset. + +Vendored third-party code lives under `ext/`. The portable renderers and the RHI +are under `src/rendering/`, with the two backends under `src/platform/opengl/` and +`src/platform/vulkan/`. + +--- + +See [`physics.md`](physics.md) for the maths behind the image, and the top-level +[`README.md`](../README.md) for a project overview. diff --git a/docs/physics.md b/docs/physics.md new file mode 100644 index 0000000..4877f64 --- /dev/null +++ b/docs/physics.md @@ -0,0 +1,373 @@ +# The Physics of Donut + +Everything Donut draws comes from tracing light backward through the curved +spacetime around a black hole. This document works through the physics and maths +of that trace, in roughly the order the shader applies it, with references to the +code in [`assets/shaders/geodesic.slang`](../assets/shaders/geodesic.slang) — +symbol names below (`InitRay`, `GeodesicRHS`, `DiskEmission`) all live in that file. + +For the software side — how the shader gets fed, the render backends, the tabs +and the export path — see [`architecture.md`](architecture.md). + +## Contents + +- [Overview](#overview) +- [Units and scale](#units-and-scale) +- [The Schwarzschild metric](#the-schwarzschild-metric) +- [Null geodesics and conserved quantities](#null-geodesics-and-conserved-quantities) +- [The equations of motion](#the-equations-of-motion) +- [Numerical integration](#numerical-integration) +- [The three critical radii](#the-three-critical-radii) +- [The accretion disk](#the-accretion-disk) +- [Redshift, Doppler beaming and colour](#redshift-doppler-beaming-and-colour) +- [The impact parameter](#the-impact-parameter) +- [Observable channels](#observable-channels) + +## Overview + +A black hole isn't drawn like ordinary geometry. For each pixel Donut casts a ray +from the camera and follows it *backward* until one of four things happens: it +crosses the event horizon, it strikes the accretion disk, it hits a placed object, +or it escapes to the background sky. Mass bends the path of light, so the rays +curve, and that one effect produces the whole picture: the dark shadow, the bright +ring wrapped around it, the far side of the disk folded up over the top of the +hole, and the Doppler-brightened leading edge. + +```mermaid +flowchart LR + A[Camera pixel] --> B[Build ray direction] + B --> C{March the geodesic<br/>through curved spacetime} + C -->|falls in| D[Event horizon<br/>black shadow] + C -->|hits disk| E[Accretion disk<br/>redshifted blackbody] + C -->|hits object| F[Placed sphere<br/>shaded] + C -->|escapes| G[Background sky<br/>HDRI environment] + D --> H[Pixel colour] + E --> H + F --> H + G --> H +``` + +## Units and scale + +Donut works in geometric units, $G = c = 1$. Mass then carries units of length, +and the Schwarzschild radius reduces to + +$$ +r_s = \frac{2GM}{c^2} = 2M, \qquad\text{so}\qquad M = \frac{r_s}{2}. +$$ + +One number describes the hole. For Sagittarius A* the shader fixes it as + +``` +static const float SagA_rs = 1.269e10; // metres (M ≈ 4.3×10⁶ M☉) +``` + +Every distance the integrator handles is a physical length in metres, written as a +multiple of `SagA_rs`, so the critical radii come out as constants: + +``` +R_PHOTON = 1.5 * SagA_rs // photon sphere (3M) +R_ISCO = 3.0 * SagA_rs // ISCO (6M) +``` + +The scene editor uses a friendlier grid. The constant `SCENE_UNITS_PER_RS = 3.0` +(in [`src/scene/scene_types.h`](../src/scene/scene_types.h)) sets three grid units +to one Schwarzschild radius. When the renderer hands a placed object to the shader +it scales the position by $\text{SagA\_rs}/3$ to get metres, so the editor and the +simulation always agree on where things sit. + +## The Schwarzschild metric + +Sgr A* is treated as a non-rotating, uncharged black hole, whose spacetime is the +exact Schwarzschild solution of Einstein's equations. In spherical coordinates +$(t, r, \theta, \phi)$ the line element is + +$$ +ds^2 = -\left(1-\frac{r_s}{r}\right)dt^2 + + \left(1-\frac{r_s}{r}\right)^{-1}dr^2 + + r^2\left(d\theta^2 + \sin^2\theta\, d\phi^2\right). +$$ + +The factor that keeps recurring is abbreviated + +$$f(r) = 1 - \frac{r_s}{r},$$ + +which is `float f = 1.0 - SagA_rs / r;` in the code. As $r \to r_s$, $f \to 0$ and +the metric coefficients diverge. That divergence is a coordinate artifact rather +than a real singularity, but it is why the integrator stops a ray once it reaches +$r \le r_s$ instead of pushing through. + +## Null geodesics and conserved quantities + +Light follows null geodesics, the curves with $ds^2 = 0$. The metric has no +explicit dependence on $t$ or $\phi$ (a time-translation symmetry and an axial +rotation symmetry), so two quantities stay constant along every ray: + +$$ +E = f(r)\,\frac{dt}{d\lambda} +\qquad\text{(energy)}, \qquad\qquad +L_z = r^2\sin^2\theta\,\frac{d\phi}{d\lambda} +\qquad\text{(axial angular momentum)}, +$$ + +with $\lambda$ an affine parameter along the ray. `InitRay` sets both at the +camera: it turns the camera-space ray direction into the spherical components +$(\dot r, \dot\theta, \dot\phi)$, then computes + +``` +ray.L = r*r * sin(theta) * dphi; // angular momentum +dt_dL = sqrt(dr*dr/f + r*r*(dtheta² + sin²θ·dphi²)); +ray.E = f * dt_dL; // energy +``` + +`E` is put to work during integration: `GeodesicRHS` reads the time component +$\dot t = E/f$ from it, so the $t$ coordinate never has to be integrated on its +own — one fewer equation per step. `L` is computed at initialisation as the ray's +angular momentum but isn't fed back into the equations of motion; the azimuthal +motion is carried directly by $\dot\phi$. + +For a null geodesic the affine parameter has an arbitrary overall scale, and the +ray's shape — which is all the image depends on — doesn't change with it, so the +exact normalisation of `E` is only a convention. + +## The equations of motion + +Marching a ray means solving the geodesic equation +$\ddot x^\mu + \Gamma^\mu_{\alpha\beta}\dot x^\alpha \dot x^\beta = 0$ for the +Schwarzschild metric. `GeodesicRHS` writes it as a first-order system in the six +ray variables $(r,\theta,\phi,\dot r,\dot\theta,\dot\phi)$. The three positions +advance by their velocities, + +$$\dot r,\qquad \dot\theta,\qquad \dot\phi,$$ + +and the three velocities accelerate with the curvature: + +$$ +\ddot r = -\frac{r_s}{2r^2}\,f\,\dot t^2 + + \frac{r_s}{2r^2 f}\,\dot r^2 + + r\left(\dot\theta^2 + \sin^2\theta\,\dot\phi^2\right), +\qquad \dot t = \frac{E}{f}, +$$ + +$$ +\ddot\theta = -\frac{2}{r}\,\dot r\,\dot\theta + + \sin\theta\cos\theta\,\dot\phi^2, +$$ + +$$ +\ddot\phi = -\frac{2}{r}\,\dot r\,\dot\phi + - 2\cot\theta\,\dot\theta\,\dot\phi. +$$ + +The terms are the Christoffel symbols of the metric. In $\ddot r$ the first term +is the inward pull of gravity (it carries $\dot t^2$, hence the energy); the rest +are the centrifugal contributions from angular motion. The $\theta$ and $\phi$ +equations are the angular-momentum couplings that hold the ray to its orbital +plane and sweep it around the hole. The code is a direct transcription: + +``` +d2.x = -(SagA_rs/(2r²))·f·dt_dL² + (SagA_rs/(2r²f))·dr² + r·(dtheta² + sin²θ·dphi²); +d2.y = -2·dr·dtheta/r + sin(theta)·cos(theta)·dphi²; +d2.z = -2·dr·dphi/r - 2·(cos/sin)(theta)·dtheta·dphi; +``` + +## Numerical integration + +There is no closed form for a general ray, so the integrator advances it in steps. + +`RK4Step` takes one step. It evaluates `GeodesicRHS` once, advances the six +variables by `dL` times their rates, and recomputes the Cartesian position from +the new spherical coordinates. That is a single forward-Euler stage, despite the +name: only the first slope `k1` is evaluated, where a genuine fourth-order step +would also compute `k2`, `k3` and `k4` at intermediate points. Moving to real RK4 +is the obvious accuracy upgrade; as it stands, almost all of the accuracy comes +from the step-size control instead. + +`CalculateAdaptiveStepSize` chooses the step length. A fixed step would waste time +far from the hole and lose the trajectory near it, so the step scales with distance +from the photon sphere: + +$$ +\Delta\lambda = \operatorname{clamp}\!\left(0.02\,\max(r - r_\text{photon},\,0),\; \Delta_\text{min},\; \Delta_\text{max}\right), +\qquad +\begin{aligned} +\Delta_\text{min} &= 10^6\\ +\Delta_\text{max} &= 2\times10^{10} +\end{aligned} +$$ + +Far out, the ray is in near-flat space and crosses it in a handful of long +strides. Near the photon sphere, where the path bends hardest and mistakes show +the most, the step shrinks to follow the curve. A second clamp forces the step +down to the disk's half-thickness whenever the ray is near the disk plane, so a +thin, nearly edge-on disk is never stepped straight over. + +A ray's march ends on the first of these: + +| Condition | Meaning | +| --- | --- | +| $r \le r_s$ (`Intercept`) | Fell through the horizon → shadow (black) | +| Crossed / entered the disk slab | Hit the opaque disk → emit its colour | +| `InterceptObject` (every 5 steps) | Hit a placed sphere → shade it | +| $r > $ `earlyExitDistance` ($2\times10^{12}$) | Left the rendered region → sample the sky | +| $\dot r > 0$ and $r > 50\,r_s$ | Outbound in flat space, direction frozen → sample the sky early | +| step count exceeds the budget | Up to `quality_steps` (default 15000, clamped 1000–15000) | + +The step budget is the same whether the camera is moving or settled. At steep, +strongly-lensed poses the disk only resolves with a high step count, so cutting it +during motion would make the disk flicker. Responsiveness during a drag comes from +the rendering resolution and sample count instead — a smaller target and one sample +per pixel while moving, sharpening to full resolution and 4× supersampling once the +camera settles (see +[`architecture.md`](architecture.md#progressive-resolution-and-supersampling)). + +## The three critical radii + +Three radii set up everything you see: + +```mermaid +flowchart LR + subgraph one[" "] + direction LR + H["Event horizon<br/>r = rₛ = 2M"] --- P["Photon sphere<br/>r = 1.5 rₛ = 3M"] --- I["ISCO<br/>r = 3 rₛ = 6M"] + end +``` + +The **event horizon** at $r_s = 2M$ is the point of no return; the set of +directions whose rays end there is the black shadow. The **photon sphere** at +$\tfrac{3}{2}r_s = 3M$ is where light can circle the hole on unstable orbits, so +rays passing near it loop around once or more before escaping — this makes the thin +photon ring against the shadow and the folded multiple images of the disk. The +**ISCO** at $3r_s = 6M$ is the innermost stable circular orbit, inside which matter +can't hold a steady orbit; it is the disk's inner edge, and `DiskEmission` clamps +the inner radius with `max(disk.disk_r1, R_ISCO)`. + +## The accretion disk + +Donut models the disk as a thin, opaque, self-luminous slab in the equatorial +plane ($y = 0$), not a volumetric cloud. A ray hits it the first time it crosses +the midplane (or grazes into the slab of half-thickness `disk.thickness`) inside +the radial band $[r_\text{in}, r_\text{out}]$, and that surface's emission is the +pixel colour. The default band runs from $3\,r_s$ to $12\,r_s$. + +A steady thin accretion disk radiates with a flux that rises from zero at the +inner edge, peaks just outside it, and tails off with radius: + +$$ +F(r) \;\propto\; \frac{1}{r^3}\left(1 - \sqrt{\frac{r_\text{in}}{r}}\right). +$$ + +This is the Novikov–Thorne / Shakura–Sunyaev thin-disk profile. Its peak sits at +$r/r_\text{in} \approx 1.36$ with value `FLUX_PEAK = 0.0569`, which normalises it. +A blackbody's flux goes as $T^4$ (Stefan–Boltzmann), so the local temperature is + +$$ +T(r) = T_\text{peak}\left(\frac{F(r)}{F_\text{peak}}\right)^{1/4}, +$$ + +where $T_\text{peak}$ is the tunable `disk.temperature`, 4800 K by default: + +``` +flux = max((1 - sqrt(1/xr)) / (xr*xr*xr), 0); xr = rc / r_in +Tn = pow(flux / FLUX_PEAK, 0.25); // normalised temperature, peak ≈ 1 +Temit = disk.temperature * Tn; +``` + +An optional turbulence overlay (the `turbulence` parameter, `disk.disk_num`) +modulates the brightness with animated fractal noise to suggest churning gas. It +never changes the fact that the disk is an opaque surface. + +## Redshift, Doppler beaming and colour + +The disk is hot gas on relativistic orbits, deep in the gravity well. Two effects +shift its light on the way to the camera, and both collapse into a single redshift +factor $g$ (observed frequency over emitted). + +The gas moves on prograde circular geodesics. For Schwarzschild, the locally +measured orbital speed is + +$$ +v = \sqrt{\frac{M}{r - 2M}} = \sqrt{\frac{r_s/2}{r - r_s}}, +$$ + +which is exactly $0.5\,c$ at the ISCO. The velocity vector is +$\boldsymbol\beta = v\,\hat\phi$, tangent to the orbit. Combining the gravitational +and time-dilation shift of a circular orbit with the relativistic Doppler shift +from that motion gives + +$$ +g = \frac{\sqrt{\,1 - \tfrac{3}{2}\,\dfrac{r_s}{r_c}\,}}{1 - \boldsymbol\beta\cdot\hat n}, +$$ + +where $\hat n$ points along the photon toward the observer and $r_c$ is the +cylindrical radius of the emission point. The numerator is the gravitational part +(it vanishes at the photon sphere $r_c = \tfrac{3}{2}r_s$, where even orbiting +light is infinitely redshifted); the denominator is the Doppler part, which +brightens and blueshifts the side turning toward the camera and dims and redshifts +the receding side. As a check, $g \to \sqrt{1/2}$ at the ISCO, matching the code. + +Two things follow from $g$, both physical: + +$$ +T_\text{obs} = g\,T_\text{emit} +\qquad\text{(colour: a redshifted blackbody)}, +\qquad\qquad +I_\text{obs} = g^4\,I_\text{emit} +\qquad\text{(relativistic beaming)}. +$$ + +The colour is the Planckian blackbody colour at the observed temperature, +`Blackbody(g · Temit)`, using a Tanner-Helland fit to the Planckian locus. The +brightness keeps the physical $g^4$ beaming — the real approaching/receding +asymmetry — while the enormous $T^4$ radial range is compressed to $T_n^2$ for +display, so the colour gradient across the disk stays visible instead of collapsing +to a single saturated ring: + +``` +bright = pow(Tn, 2.0) * pow(g, 4.0) * edge; // edge = soft inner/outer falloff +colour = Blackbody(g * Temit) * bright; +``` + +That $T_n^2$ in place of the physical $T_n^4 = F$ is the one intentional +concession to legibility; the rest of the disk model is the genuine relativistic +result. + +## The impact parameter + +A ray's impact parameter $b$ is the perpendicular distance from the hole's centre +to the straight line the ray would have followed with no gravity — the quantity +that sets how strongly it deflects. Donut reads it straight off the camera geometry +(in units of $r_s$): + +$$ +b = \frac{\lVert \mathbf{r}_\text{cam} \times \hat d\,\rVert}{r_s}, +$$ + +with $\mathbf{r}_\text{cam}$ the camera position relative to the hole and $\hat d$ +the pixel's ray direction. Rays whose $b$ is near the critical value (about +$\tfrac{3\sqrt3}{2}r_s$) are the ones that skim the photon sphere and build the +ring. + +## Observable channels + +The renderer already computes these physical quantities while tracing, so it can +output them directly instead of only the final colour. The shader's `outputChannel` +picks which quantity each pixel reports, and `rawOutput` picks whether to write the +raw floating-point value (for analysis) or a false-coloured / tone-mapped version +(for viewing): + +| Channel | Quantity | Notes | +| --- | --- | --- | +| 0 | Colour | The final tone-mapped HDR radiance — the normal image | +| 1 | Redshift $g$ | Disk pixels only; validity flagged in alpha | +| 2 | Emission temperature $T_\text{emit}$ (K) | Disk pixels only; validity in alpha | +| 3 | Impact parameter $b$ ($r_s$) | A per-ray geometric quantity, defined everywhere | + +The raw channels are what make the export usable as data rather than just imagery; +[`architecture.md`](architecture.md#the-export-pipeline) covers how they are +rendered off-screen and written to PFM or CSV. + +--- + +See also [`architecture.md`](architecture.md) for how the renderer is built, from +the portable GPU layer up through the tabs and the export pipeline. |
