NReagan Notes & TODOs

1. SIMD / CPU Math (libs/pl_math.h)

Zero deps + cross-platform: each item below = AVX2 path + NEON path + scalar fallback, gated by #if defined(__AVX2__) / __ARM_NEON / else, plus a microbench across all three. Plan ~2 weekends per item.

• Establish per-ISA dispatch pattern + a pl_simd.h header with shared macros / typedefs (no abstraction layer — just consistent conventions)
• pl_mat4_mul + microbench (canonical warmup)
• Batched pl_mat4_transform (transform N points)
• Quaternion ops (pl_mul_quat, pl_norm_quat)
• Vec4 batch ops (dot, cross, normalize over arrays)
• Batched 4x / 8x frustum-plane test for AABBs (ECS culling) — first real-world impact
• Vertex skinning path
• AABB / ray intersection helpers
• Build-flag policy doc: AVX2 as x86 baseline, AVX-512 gated, NEON as ARM baseline

2. Benchmarking Infrastructure

No Google Benchmark — homegrown, header-only, in PilotLight style.

• Cross-platform high-resolution timer (clock_gettime / mach_absolute_time / QueryPerformanceCounter)
• Homegrown microbench harness under tests/ (warmup, repetition, min/median/p99) — build alongside section 1
• Hot-path microbenchmarks: matrix ops, frustum tests, AABB tests, skinning
• Frame-time macro-benchmark with p50/p95/p99 tracking
• Regression-detection script runnable from CI

3. Profiling & Instrumentation

• Perfetto / chrome-tracing JSON export from pl_profile_ext (just a JSON serializer, no dep)
• Flamegraph export (folded-stack text format)
• Lift the hardcoded 4-thread cap in pl_profile_ext / pl_stats_ext
• GPU timestamp queries in pl_profile_ext (Vulkan VK_QUERY_TYPE_TIMESTAMP + Metal MTLCounterSampleBuffer)
• Per-pass GPU timing surfaced through the existing CPU profiler API
• Frame-graph visualization in the debug UI

4. Small Wins (existing TODOs in source)

• pl_ui_widgets.c — FIXME-OPT markers (text edit memmove inefficiency)
• pl_model_loader_ext.c — delete unused entities on unload
• pl_renderer_internal.c — optimize the "check all rects" iteration
• pl_renderer_internal.c — cascade shadow layout wastes space
• pl_renderer_internal.c — handle shadow atlas overflow > 4096

5. GPU Compute Primitives (new pl_gpu_primitives_ext)

Native Vulkan + Metal compute shaders — no CUDA, no external lib.

• Block-level parallel reduction kernel (PMPP ch. 10)
• Device-wide parallel reduction
• Block-level inclusive / exclusive scan (PMPP ch. 11)
• Device-wide scan via decoupled look-back or scan-then-fan
• Stream compaction built on scan
• Histogram kernel
• Radix sort (key-only first, then key/value)
• Tests + benchmarks for each primitive vs scalar baseline

6. GPU Compute Features

• Compute-based bloom rewrite using groupshared / threadgroup memory
• GPU frustum culling compute pass → indirect draw buffer
• GPU occlusion / hi-Z culling
• GPU particle system (compute spawn + simulate + sort + render)
• FFT compute kernel (foundation for ocean / convolutional effects)
• Compute-based mesh shading path for static geometry

7. Concurrency / Job System (pl_job_ext)

• Stress tests under thread sanitizer (baseline before changes)
• Lock-free MPMC queue in libs/
• Work-stealing scheduler (Chase-Lev deque, per-thread queues)
• Job dependency graph API
• Benchmark suite comparing old vs new scheduler
• Fiber-based job continuations (advanced)

8. Memory / GPU Allocator (pl_gpu_allocators_ext)

• Allocator usage stats exposed through pl_stats_ext
• Arena / linear allocator surfaced in the public CPU API
• Sub-allocation strategy for the buddy allocator (small-block coalescing)
• Defragmentation pass for long-lived allocations

9. Async Compute

• Metal parallel command encoder utilization audit
• Cross-queue semaphore / event helpers
• Separate Vulkan async compute queue
• Overlap culling + post-FX with previous frame's raster pass
• Async transfer queue for staging uploads

---

References

Books

• Programming Massively Parallel Processors — Hwu, Kirk, Hajj (4th ed) — primary text for sections 5 & 6
• Computer Architecture: A Quantitative Approach — Hennessy & Patterson (7th ed) — Ch. 4 (data-level parallelism)
• Computer Systems: A Programmer's Perspective — Bryant & O'Hallaron (3rd ed) — memory hierarchy + optimization chapters
• Modern Parallel Programming with C++ and Assembly Language — Kusswurm — primary text for section 1
• C++ Concurrency in Action — Williams — primary text for section 7
• Effective Modern C++ — Meyers

Reference manuals

• Intel Intrinsics Guide — https://www.intel.com/content/www/us/en/docs/intrinsics-guide/
• Agner Fog's optimization manuals — https://www.agner.org/optimize/
• uops.info — instruction latency/throughput data
• ARM NEON Intrinsics Reference

Blogs (technique)

• Daniel Lemire — https://lemire.me/blog/
• Wojciech Muła — http://0x80.pl/
• Geoff Langdale (branchfree) — https://branchfree.org/

Source to read (read, don't vendor)

• Google Highway (google/highway) — portable SIMD; teaches AVX + NEON + SVE side-by-side, even though we won't depend on it
• simdjson — exemplary AVX2 + NEON code with both ISA paths
• ggml / llama.cpp — modern perf-critical x86 + ARM, no-deps philosophy similar to PilotLight
• sse2neon — SSE → NEON translation header; reading it teaches ISA equivalences
• CUB / CUTLASS — reference implementations for section 5 primitives (CUDA, read-only)
• Thrust — high-level patterns on CUB

GPU profiling tools (external, used alongside the app)

• Nsight Compute / Nsight Systems (Nvidia)
• Xcode Instruments → GPU trace (Metal)
• RenderDoc — frame capture

Conference talks

• Andreas Fredriksson — "SIMD at Insomniac Games" (CppCon)
• Fedor Pikus — "Branchless Programming in C++" (CppCon)
• Sean Parent — "Better Code: Concurrency"