Skip to content

About

A real-time GPU particle laboratory in C++23 and OpenGL 4.6, with compute-shader simulation, soft instanced billboards, and interactive ImGui controls

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

GPU Particle Singularity

A small real-time particle laboratory built with C++23 and OpenGL 4.6. Particles orbit, drift toward a central attractor, and regenerate in a continuous loop. Compute shaders handle their entire lifecycle; instanced, camera-facing billboards turn that state into soft light.

Learning project and AI assistance

This is an educational repository documenting my approach to learning C++ and graphics programming. I use AI to brainstorm ideas, plan the project, and write code incrementally. At each step, I study and review the implementation, working through the concepts and design decisions behind it. The code is AI-assisted, and I have personally worked through all of it and understand how it works. Building that understanding is the purpose of the project and the central part of this learning method.

Blue and warm-colored particles swirling around a central attractor against a dark background

Captured from the current renderer with the default 4,097 particles and seed 12,345. The control panel is omitted from this capture. Capture details.

This personal graphics project explores the path from a GPU simulation to a rendered pixel, with explicit OpenGL calls and a compact C++ codebase. The singularity is an artistic force field, not a model of black-hole physics.

Stack: C++23 · OpenGL 4.6 / GLSL 4.60 · GLFW · GLAD2 · GLM · Dear ImGui · CMake · Catch2

What it does

  • GPU particle lifecycle. A compute shader initializes and respawns particles in an annular emitter, using the visible seed and a persistent random state per particle.
  • A tunable force field. Softened central attraction, tangential swirl, and drag shape the motion. Particles respawn when their lifetime expires, they enter the core radius, or they escape the simulation bounds.
  • Stable time stepping. Semi-implicit Euler integration runs at 120 Hz, with bounded catch-up work after a slow frame. Pause, single-step, and reset make the behavior inspectable.
  • Procedural soft particles. One instanced quad per particle, a radial opacity mask, and lifetime-dependent color, size, and fading. Additive blending needs no particle sorting or image textures. A diagnostic point mode remains available.
  • Interactive controls. Adjust the emitter, forces, particle count, palette, and size through Dear ImGui. Invalid edits keep the last valid settings active; count requests respect queried GPU limits.

Try it

You need an OpenGL 4.6-capable GPU and driver, a C++23 compiler, CMake 3.25+, Ninja, and Git. The repository uses pinned vcpkg dependencies. Windows x64 uses MSVC; Linux x64 uses GCC or Clang with X11/XWayland. macOS is unsupported.

Windows

Run these commands in an x64 Visual Studio developer PowerShell with CMake and Ninja on PATH:

git clone https://github.com/yernende/gpu-particle-singularity.git
cd gpu-particle-singularity
git clone --depth 1 --branch 2026.07.29 https://github.com/microsoft/vcpkg.git .tools/vcpkg
.\.tools\vcpkg\bootstrap-vcpkg.bat -disableMetrics
cmake --preset windows-msvc-release
cmake --build --preset windows-msvc-release
.\out\build\windows-msvc-release\gpu-particle-singularity.exe

Linux

Install the X11 build prerequisites, then:

git clone https://github.com/yernende/gpu-particle-singularity.git
cd gpu-particle-singularity
git clone --depth 1 --branch 2026.07.29 https://github.com/microsoft/vcpkg.git .tools/vcpkg
.tools/vcpkg/bootstrap-vcpkg.sh -disableMetrics
cmake --preset linux-gcc-release
cmake --build --preset linux-gcc-release
./out/build/linux-gcc-release/gpu-particle-singularity

See the build and development guide for Debug builds, VS Code setup, portable CMake/Ninja, sanitizers, and static analysis.

Explore the laboratory

The application starts with 4,097 particles, seed 12,345, a fixed camera, and soft billboard rendering. The intentionally non-round count also exercises the compute shader's final, partially filled work group.

Control Behavior
Pause / Single step Freeze motion or advance one 1/120-second simulation step while paused.
Reset particles Re-emit the current population from the displayed seed and valid settings; preserve count and pause state.
Reset parameters Restore parameter defaults while keeping the current population and active count. Apply the pending count separately.
Seed Used at the next particle reset or population recreation.
Pending count / Apply particle count Change the count and initialize a new buffer when the applied count differs from the active count.
Emitter Tune spawn geometry, lifetime, and initial motion for future respawns. Reset particles applies them to everyone; core/escape thresholds affect existing particles.
Forces Tune attraction, softening, swirl, and drag at the next simulation substep.
Rendering Change billboard size and birth/death colors, or switch to diagnostic points.
Diagnostics Inspect the active count, buffer size, work groups, frame rate, and validation messages.

The panel can be moved, resized, or collapsed using its title bar to leave the scene visible.

View the control panel

The Particle Laboratory controls positioned beside the particle scene

How it works

flowchart TD
    CPU["C++: controls, validation, fixed-step clock"] -->|uniforms and dispatch| Compute["Compute shader: emit, integrate, respawn"]
    Compute -->|write| Buffer["Particle SSBO · binding 0"]
    Buffer --> Barrier["glMemoryBarrier · SHADER_STORAGE_BARRIER_BIT"]
    Barrier --> Vertex["Vertex shader: read SSBO, expand one quad per instance"]
    Vertex --> Fragment["Fragment shader: soft disc and lifetime fade"]
    Fragment --> Blend["Additive blending → framebuffer → ImGui"]
Loading

The CPU allocates the buffer and submits work; it does not update or upload an array of particles every frame. The same SSBO is written by compute and read by the vertex shader. Each particle occupies 48 bytes in a std430 layout: position + age, velocity + lifetime, and a four-component unsigned random-state field. C++ assertions verify the 48-byte size and member offsets.

Each compute work group has 256 invocations. A bounds check handles the last partial group, and each invocation owns one particle, so updates need no inter-particle synchronization. The CPU issues glMemoryBarrier(GL_SHADER_STORAGE_BARRIER_BIT) after each dispatch to make its writes visible to later SSBO accesses, including the next simulation step and rendering.

For rendering, gl_InstanceID selects a particle and gl_VertexID selects one of six quad corners. Expanding the corners in view-space X/Y keeps the billboard facing the camera without a mesh vertex buffer. The fragment shader supplies a soft radial mask; blending uses GL_SRC_ALPHA, GL_ONE. Depth testing stays enabled and particle depth writes are disabled, then the pass restores state before ImGui. This version has no opaque core geometry to occlude the particles.

Source map

File Responsibility
main.cpp Context lifetime, frame loop, simulation/render order, and smoke mode.
gps_demo.cpp Embedded GLSL, compute dispatch, billboard drawing, and the control panel.
particle_gpu.hpp The shared CPU/GLSL layout contract.
particle_buffer.cpp SSBO ownership, allocation, and buffer limits.
shader_program.cpp Shader compilation, linking, and RAII ownership.
fixed_step_accumulator.cpp Bounded simulation stepping.
particle_settings.cpp Parameter validation.

Validation

ctest --preset windows-msvc-release
.\out\build\windows-msvc-release\gpu-particle-singularity.exe --smoke-test

On Linux, use ctest --preset linux-gcc-release and ./out/build/linux-gcc-release/gpu-particle-singularity --smoke-test.

The CPU suite covers settings, command-line options, fixed-step timing, and work-group math. The smoke test creates a real OpenGL context, initializes the GPU particle state, renders three frames, and checks OpenGL errors. It is a short rendering check, not a visual regression test or a performance benchmark.

The current milestone was checked on Windows / MSVC / NVIDIA GeForce RTX 3060 Ti on September 20, 2026: Debug and Release builds, 16/16 tests in each, and both GPU smoke tests passed. The screenshots were captured separately from the running simulation.

CI configures Windows MSVC tests, Linux Clang ASan/UBSan tests, and the explicit macOS rejection check. GPU smoke tests require a suitable graphics context and are run separately from that workflow.

Project status and scope

This repository is preserved as a soft-billboard particle simulation milestone: the implementation reached Feature 7 of the original learning roadmap. The longer TODO records that stopping point and keeps the remaining experiments available for a future revisit.

The opaque central sphere, broader GPU boundary/smoke tests, and the planned 65,536-particle default were left for later. The current core radius affects particle capture only. There is no N-body interaction, relativistic physics, bloom, trails, or orbit camera; the focus is the compute-to-render pipeline and its C++/OpenGL implementation.

License

MIT · Aleksandr Olekhnovich

About

A real-time GPU particle laboratory in C++23 and OpenGL 4.6, with compute-shader simulation, soft instanced billboards, and interactive ImGui controls

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages