kavan010's black_hole: a ray traced C++ simulation split across CPU and GPU

A repository that shows its own homework

The README opens by telling you the code is raw and that everything lives in a src and bin structure in case you want to copy the files, then lists what the author intends to do. The list is a to-do, not a feature list: add ray tracing to the gravity simulation to simulate gravitational lensing, simulate an accretion disk using ray tracing plus halos, demonstrate the trapdoor in spacetime that a black hole is using a spacetime grid, and optionally try to make it run in realtime.

That framing matters, because it tells you how much weight to put on the feature claims. The README then carries an edit marker reading After completion of project followed by nothing, which suggests the author considered the work finished and left the header behind. Meanwhile the tree already contains `ray_tracing.cpp`, so at least one item on that list shipped without the list being updated.

The repository has 2,621 stars and 409 forks, no topics, no homepage, and no license field at all. There are no releases, so no version numbers to reason about. The last push was 2026-04-07, which is recent enough that the code is not abandoned, but there is no changelog and no release history to track progress against.

The tree tells you the architecture

Fourteen entries at the root, and the names do most of the explaining.

`2D_lensing.cpp` is the 2D lensing implementation. `black_hole.cpp` and `geodesic.comp` are the 3D path. `CPU-geodesic.cpp` is a fallback or comparison implementation. `ray_tracing.cpp` is the tracing logic. `grid.vert` and `grid.frag` are the vertex and fragment shaders for the spacetime grid, which lines up with the third item on the author's to-do list. `CMakeLists.txt` and `vcpkg.json` are the build definition and the dependency manifest.

Then there are three entries that belong in a different conversation. `black_hole.exe` is a compiled Windows binary checked into version control. `Gravity_Sim.zip` is an archived build. `vs_code/` is an editor directory that is usually but not always ignored.

A committed executable and an archived zip alongside source is the kind of thing that makes a repository feel unfinished in a way that has nothing to do with the physics. It also means anyone browsing the tree can download a binary whose provenance is only as good as the author's word, which is a poor trade in a project with no license and no releases. If you are here for the source, ignore those three entries.

Why the GPU path is split in two

The README's explanation of the code is two sentences and they are the most valuable content here.

For 2D, the instruction is simple: run `2D_lensing.cpp` with the necessary dependencies installed. For 3D, `black_hole.cpp` and `geodesic.comp` work together to run the simulation faster using the GPU. The mechanism is a uniform buffer object, abbreviated UBO in the README, which carries data from the host program into the compute shader so the shader can do the heavy calculations.

That split is the standard approach and it is worth understanding even if you never run this code. A gravitational lensing simulation has to trace, for every pixel, how a light ray curves around the mass. Done naively on the CPU that is an enormous amount of arithmetic per frame. Handing it to a compute shader means thousands of rays evaluated in parallel, which is what makes a full-screen lensing effect feasible at interactive rates at all.

The readme also says it sends the data over a UBO and `geodesic.comp` runs heavy calculations using that data. If you want to learn the technique, `CPU-geodesic.cpp` next to the shader is a useful pairing: same math, two execution models.

Building it, and the apt path for people in a hurry

The documented route is vcpkg, and the README is unusually careful about the one step people get wrong.

git clone https://github.com/kavan010/black_hole.git

The clone step is followed by changing into the directory, running `vcpkg install`, then `vcpkg integrate install`, which prints the toolchain file path you need next. That printed path is not optional decoration: it goes into the configure step as `CMAKE_TOOLCHAIN_FILE`.

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Then `cmake --build build`, and the executables land in the build folder. The stated requirements are a C++ compiler supporting C++ 17 or newer, CMake, vcpkg and Git.

The apt section exists because vcpkg is a step too many for a lot of people, and it is the more useful half of this README:

sudo apt update
sudo apt install build-essential cmake \
	libglew-dev libglfw3-dev libglm-dev libgl1-mesa-dev

That gives you GLEW, GLFW, GLM and the OpenGL development files so the `find_package` calls in `CMakeLists.txt` can resolve. After installing, the README says to run the plain `cmake -B build -S .` and `cmake --build build`, with no toolchain argument needed. If you are on Debian or Ubuntu, skip vcpkg entirely.

The author's own caveat is the most useful line

The README ends with an admission that changes how you should treat everything above it. The author writes that it should work with the necessary dependencies installed, however they have only run it on Windows with their own GPU, so they are not sure.

That single sentence explains several things. The 2D path is the one that will build anywhere, because it does not depend on a working GPU compute pipeline. The 3D path depends on `geodesic.comp`, which means a GLSL compute shader, which means a driver and hardware combination the author tested on exactly one machine. There is no CI configuration in the tree, no test directory and no platform matrix, so nobody else has verified it either.

The README also closes by offering a more detailed explanation of how the code works, with a smiley. That is an invitation rather than documentation, and it is the honest position: this is a small personal project with a clear idea, written by someone who says outright that they were not sure it would run on your machine.

None of that makes it worth less. A compact gravitational lensing renderer, with the host and device split clearly separated and a working 2D mode for people without a suitable GPU, is a reasonable thing to have written. It just is not a library, and the README never pretends otherwise.

Where this fits next to other black hole renderers

There is a category of black hole visual that circulates online, usually a shader or a small program that ray traces light around a Schwarzschild-like metric and produces the characteristic disc, the bright lensed ring and the shadow in the middle. This repository is a member of that category, and the differences between members are mostly about how much of the physics is faked.

What you can tell from this tree is that it takes the numerical route rather than the purely visual one. There is a dedicated compute shader, a separate CPU geodesic implementation, and grid vertex and fragment shaders for the spacetime visualisation. That is more machinery than a single fragment shader doing per-pixel deflection with a closed-form approximation, and it also means more ways to get a wrong answer that still looks plausible.

The accretion disk and halo work on the author's to-do list is the part that would decide it against the competition. A black hole render with the lensing but no disk is a geometry demo; with a disk that is Doppler-beamed and redshifted by the disk's own rotation, it is a physics visualisation. The README describes the disk as simulated using the ray tracing plus the halos, so the intent is there.

For an actual starfield with a physically motivated singularity rather than a shader approximation, the alternatives in this space are usually more mature. For reading how the GPU split works in about forty lines of shader, this repository is fine and much smaller.

Editorial conclusion

This repository is worth reading rather than running, and the README says as much when it asks whether you would like an in depth explanation of how the code works. There is no release, no tagged version and no license field, so there is nothing to install and no stated terms, which means treat the code as reference material unless the author tells you otherwise. What the project does give you is a compact account of how a black hole renderer is put together: a uniform buffer feeding a compute shader for the heavy geodesic work, a separate CPU path, a 2D mode that removes the complexity entirely, and an apt path for people who would rather not set up vcpkg. Start with 2D_lensing.cpp, since it is the version that will actually build on a laptop.

Frequently asked questions

Official sources

1. Issues
2. kavan010/black_hole on GitHub
3. README