From 95723af6a57174a7fc35b5eef85f29649e513e9f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 9 Aug 2026 08:29:30 +0000 Subject: [PATCH] docs: link performance issues to benchmark harnesses Co-authored-by: codegirl007 --- ...erministic-sprite-performance-benchmark.md | 39 ++++++++++++++----- .../issues/add-order-safe-texture-batching.md | 15 +++++++ .../issues/enable-sdl-gpu-buffer-cycling.md | 14 +++++++ .../issues/profile-optimized-sprite-builds.md | 10 +++++ .../prototype-instanced-sprite-rendering.md | 16 ++++++++ .../issues/simplify-draw-sprite-clip-math.md | 12 ++++++ Makefile | 11 +++++- 7 files changed, 106 insertions(+), 11 deletions(-) diff --git a/.github/issues/add-deterministic-sprite-performance-benchmark.md b/.github/issues/add-deterministic-sprite-performance-benchmark.md index 7d4386e..12636c9 100644 --- a/.github/issues/add-deterministic-sprite-performance-benchmark.md +++ b/.github/issues/add-deterministic-sprite-performance-benchmark.md @@ -97,25 +97,46 @@ and report backend details. Add a non-interactive benchmark target with two explicitly separate workloads. -Add dedicated Makefile targets that always build optimized benchmark code: +The committed harnesses are: ```make -PERF_ITERATIONS ?= 2000000 -PERF_FRAMES ?= 1000 +PERF_ODIN_FLAGS ?= -debug -o:speed perf-draw: - odin run examples/draw_bench \ + odin run benchmarks/draw_sprite \ -collection:pkg=. \ - -debug -o:speed \ - -define:PERF_ITERATIONS=$(PERF_ITERATIONS) + $(PERF_ODIN_FLAGS) \ + -define:PERF_ITERATIONS=$(PERF_DRAW_ITERATIONS) perf-frame: - odin run examples/frame_bench \ + odin run benchmarks/sprite_frame \ -collection:pkg=. \ - -debug -o:speed \ - -define:PERF_FRAMES=$(PERF_FRAMES) + $(PERF_ODIN_FLAGS) \ + -define:PERF_FRAMES=$(PERF_FRAME_FRAMES) \ + -define:PERF_SCENARIO=$(PERF_FRAME_SCENARIO) ``` +Run the standard workloads with: + +```bash +# CPU-only draw preparation. +make perf-draw + +# Complete frame: 128 visible sprites sharing one texture. +make perf-frame PERF_FRAME_SCENARIO=0 + +# Complete frame: every second sprite is fully offscreen. +make perf-frame PERF_FRAME_SCENARIO=1 + +# Complete frame: 128 sprites alternate between two texture objects. +make perf-frame PERF_FRAME_SCENARIO=2 +``` + +Every invocation prints the Git commit, Odin version, compiler flags, workload +configuration, every trial, and the median. `perf-frame` waits for GPU idle +after warm-up and after each measured frame batch so outstanding work is +included. + ### CPU queue benchmark - Construct `App`, `Character_Data`, and `Sprite` with real baked metadata. diff --git a/.github/issues/add-order-safe-texture-batching.md b/.github/issues/add-order-safe-texture-batching.md index f6e1efb..c06a52a 100644 --- a/.github/issues/add-order-safe-texture-batching.md +++ b/.github/issues/add-order-safe-texture-batching.md @@ -28,6 +28,21 @@ A temporary paired benchmark used: Sorting and grouping improved median frame time by approximately **1.9%**. Hardware drivers with higher draw-call overhead may show a different result. +## Reproduction harness + +Run the committed alternating-texture workload on the baseline and candidate +commits: + +```bash +make perf-frame \ + PERF_FRAME_SCENARIO=2 \ + PERF_ODIN_FLAGS="-debug -o:speed" +``` + +Keep all `PERF_FRAME_*` values unchanged. The baseline should produce one +texture run per sprite; the candidate should reduce runs only inside explicit +reorder-safe groups. Compare `median_ms_per_frame` and verify rendered output. + ## Suggested fix Add an explicit batch group to queued sprites. Group `0` keeps strict submission diff --git a/.github/issues/enable-sdl-gpu-buffer-cycling.md b/.github/issues/enable-sdl-gpu-buffer-cycling.md index 0da4c7d..0daf5a8 100644 --- a/.github/issues/enable-sdl-gpu-buffer-cycling.md +++ b/.github/issues/enable-sdl-gpu-buffer-cycling.md @@ -32,6 +32,20 @@ A temporary paired benchmark used: Cycling improved median frame time by approximately **0.7%**. This is a small performance change, but it also follows SDL's documented resource-reuse model. +## Reproduction harness + +Run the committed full-frame harness on the baseline commit and candidate +commit: + +```bash +make perf-frame \ + PERF_FRAME_SCENARIO=0 \ + PERF_ODIN_FLAGS="-debug -o:speed" +``` + +Keep all `PERF_FRAME_*` values unchanged. Compare `median_ms_per_frame`; the +harness waits for GPU idle before stopping each trial timer. + ## Suggested fix Cycle both resources that are fully overwritten each frame: diff --git a/.github/issues/profile-optimized-sprite-builds.md b/.github/issues/profile-optimized-sprite-builds.md index d856368..dbb7923 100644 --- a/.github/issues/profile-optimized-sprite-builds.md +++ b/.github/issues/profile-optimized-sprite-builds.md @@ -74,6 +74,16 @@ make flame FLAME_EXAMPLE=crowd make flame FLAME_EXAMPLE=crowd FLAME_ODIN_FLAGS="-debug -o:none" ``` +Reproduce the isolated build-mode comparison with the committed CPU harness: + +```bash +make perf-draw PERF_ODIN_FLAGS="-debug -o:none" +make perf-draw PERF_ODIN_FLAGS="-debug -o:speed" +``` + +Both runs print the Git commit, Odin version, compiler flags, every trial, and +the median nanoseconds per draw. + Consider applying an explicit optimization mode to performance-oriented example runs as well. Plain `odin run` currently uses Odin's unoptimized default. diff --git a/.github/issues/prototype-instanced-sprite-rendering.md b/.github/issues/prototype-instanced-sprite-rendering.md index 61621c3..b216897 100644 --- a/.github/issues/prototype-instanced-sprite-rendering.md +++ b/.github/issues/prototype-instanced-sprite-rendering.md @@ -39,6 +39,22 @@ The paired benchmark used ten order-alternated samples of 400 frames: Instancing improved median frame time by approximately **1.1%** on Vulkan/Lavapipe with 128 sprites. +## Reproduction harness + +Run the committed visible full-frame workload on baseline and candidate commits: + +```bash +make perf-frame \ + PERF_FRAME_SCENARIO=0 \ + PERF_FRAME_SPRITES=128 \ + PERF_ODIN_FLAGS="-debug -o:speed" +``` + +Keep all other `PERF_FRAME_*` values unchanged and compare +`median_ms_per_frame`. To test 512 or more sprites, first raise the engine's +`MAX_SPRITES` and associated buffer capacities on the candidate branch, then +set `PERF_FRAME_SPRITES` to the same value. + ## Suggested fix Treat this as a prototype gated by larger sprite counts or a demonstrated diff --git a/.github/issues/simplify-draw-sprite-clip-math.md b/.github/issues/simplify-draw-sprite-clip-math.md index 29192e8..3e9f9bf 100644 --- a/.github/issues/simplify-draw-sprite-clip-math.md +++ b/.github/issues/simplify-draw-sprite-clip-math.md @@ -55,6 +55,18 @@ Environment: - Optimized with `-debug -o:speed` - Linux x86-64 +## Reproduction harness + +Run the committed CPU harness on the baseline commit and again after applying +the suggested fix: + +```bash +make perf-draw PERF_ODIN_FLAGS="-debug -o:speed" +``` + +Keep `PERF_DRAW_ITERATIONS`, `PERF_DRAW_WARMUP`, and `PERF_DRAW_TRIALS` +unchanged between commits. Compare `median_ns_per_draw`. + ## Suggested fix Compute clip scaling once and construct corners from the unique coordinates: diff --git a/Makefile b/Makefile index 5619d81..0b0f5fa 100644 --- a/Makefile +++ b/Makefile @@ -16,6 +16,7 @@ FLAME_PREFIX := $(FLAME_OUT_DIR)/$(FLAME_EXAMPLE)-$(FLAME_STAMP) PERF_DRAW_ITERATIONS ?= 2000000 PERF_DRAW_WARMUP ?= 10000 PERF_DRAW_TRIALS ?= 7 +PERF_ODIN_FLAGS ?= -debug -o:speed PERF_FRAME_SPRITES ?= 128 PERF_FRAME_FRAMES ?= 400 PERF_FRAME_WARMUP ?= 100 @@ -71,13 +72,19 @@ check: odin check examples/clips -collection:pkg=. perf-draw: - odin run benchmarks/draw_sprite -collection:pkg=. -debug -o:speed \ + @echo "git_commit=$$(git rev-parse HEAD)" + @echo "odin_version=$$(odin version)" + @echo "odin_flags=$(PERF_ODIN_FLAGS)" + odin run benchmarks/draw_sprite -collection:pkg=. $(PERF_ODIN_FLAGS) \ -define:PERF_ITERATIONS=$(PERF_DRAW_ITERATIONS) \ -define:PERF_WARMUP=$(PERF_DRAW_WARMUP) \ -define:PERF_TRIALS=$(PERF_DRAW_TRIALS) perf-frame: - odin run benchmarks/sprite_frame -collection:pkg=. -debug -o:speed \ + @echo "git_commit=$$(git rev-parse HEAD)" + @echo "odin_version=$$(odin version)" + @echo "odin_flags=$(PERF_ODIN_FLAGS)" + odin run benchmarks/sprite_frame -collection:pkg=. $(PERF_ODIN_FLAGS) \ -define:PERF_SPRITES=$(PERF_FRAME_SPRITES) \ -define:PERF_FRAMES=$(PERF_FRAME_FRAMES) \ -define:PERF_WARMUP_FRAMES=$(PERF_FRAME_WARMUP) \