This is a high-precision diagnostic tool for identifying how different compositors manage frame scheduling and presentation under load. Built with Rust and WGPU, it uses a heavy raymarched shader to stress-test your display stack, exposing which environments maintain a smooth, responsive pipeline and which ones collapse into stutter and lag, even when the hardware is still fast enough to keep up.
- Pacing Detection: Captures micro-stutters invisible to raw FPS counters by measuring the precise gap between every hardware-level frame presentation.
- Compositor Benchmarking: Automatically identifies the "saturation threshold", the exact limit where the compositor fails to maintain perfect V-Blank alignment. The benchmark captures the moment a single hardware frame-slot is missed and report it.
- V-Sync Profiling: Catches "Back-Pressure", a glitch where missing one frame causes a pile-up that spikes input lag and makes the system feel sluggish.
For a detailed breakdown of the metrics and internal mechanics, see the Project Wiki:
To get accurate metrics, you must compile with the release profile to minimize CPU-side scheduling interference and driver overhead:
cargo build --release
./target/release/frame-test -c 30
| Argument | Description | Default |
|---|---|---|
-c, --cubes |
Number of hollow cubes to march. | 6 |
-z, --size |
Radius/Scale of the objects. | 0.5 |
-s, --speed |
Multiplier for rotation and oscillation. | 1.0 |
--red |
Red color component (0.0 to 1.0). | 0.18 |
--green |
Green color component (0.0 to 1.0). | 0.18 |
--blue |
Blue color component (0.0 to 1.0). | 0.18 |
-t, --threshold |
Frame-time delta limit (ms) for MSD (Missed Frames). | 25.0 |
-f, --format |
Force a specific wgpu::TextureFormat. Prints available options if invalid. |
None |
-m, --mode |
Force a specific wgpu::PresentMode (mailbox, immediate, fifo). |
mailbox (auto) |
--steps |
Maximum raymarching steps per fragment. Higher values increase GPU load. | 80 |
--connector |
DRM connector name (e.g. DP-1). Auto-selects if only one is active. |
Auto |
--frame-log |
Path to write high-res per-frame hardware telemetry (NDJSON). | None |
--csv |
Path to write rolling window metrics as CSV. | None |
--json |
Path to write rolling window metrics as NDJSON. | None |
--bench-secs |
Seconds per step. Enables benchmark mode when set. | None |
--bench-warmup |
Seconds to skip at start of each benchmark step (compositor warmup). | 2 |
--bench-max |
Maximum cube count to probe in benchmark mode. | 64 |
--shader |
Override shader selection (high for SDF, low for analytic). |
Auto |
--pll |
Enable PI controller to sync frame submission with hardware vblank.s. | false |
This project is licensed under the GNU General Public License v3.0. See the LICENSE file for the full text.