smoothlife/plans/05_gpu_resources_and_fft_proof.md

Macrostep 05 — GPU resources and 2-D FFT proof

Objective

Build a narrow, safe GPU layer under the raylib context and prove both selectable FFT algorithms against CPU oracles: the standard default and retained LegacyPackedUnitary. Do not implement the complete simulator until resource safety, stage fidelity, and numerical parity are demonstrated.

Dependencies

Macrosteps 00–04 complete.

Phase 5.1 — Capability and backend policy

Substep 5.1.1 — Capability report

Probe and record:

• OpenGL and GLSL versions;
• maximum 2-D texture size, texture units, and draw buffers;
• R32F and RG32F texture/render-target support;
• framebuffer completeness;
• timer-query availability;
• estimated resource budget.

Backend::Auto with FftAlgorithm::Standard falls back to CPU with a visible explanation. LegacyPackedUnitary is an explicit GPU-only request; unsupported capabilities or shapes fail clearly and never silently substitute the standard algorithm.

Substep 5.1.2 — Portability target

Primary path: desktop OpenGL 3.3 core-compatible GLSL. Do not copy legacy compatibility constructs (gl_TexCoord, ftransform, gl_FragColor, implicit shader versions). GLES/Web is a later secondary target.

Phase 5.2 — Isolated resource layer

Substep 5.2.1 — Unsafe boundary

Place all raw OpenGL/rlgl operations in src/gpu/resource/. Public wrappers are RAII-managed, non-cloneable owners of:

• texture IDs and format/extent metadata;
• framebuffers and attachment ownership;
• shader programs and uniform locations;
• fullscreen pass geometry;
• optional timer queries.

Every creation checks errors/completeness. Every custom pass flushes/restores raylib state according to a documented protocol.

Substep 5.2.2 — Ping-pong discipline

Make sampling a current render target impossible through the safe pass API. A pass declares read textures and a distinct write target; debug mode asserts no alias. This prevents legacy feedback-loop defects across all later variants.

Substep 5.2.3 — Shader assets

Embed release shaders and fail shader compilation/link with source name plus complete log. Support explicit development overrides only. Add shader preprocessing for shared curve/palette code if it produces deterministic, debuggable output.

Phase 5.3 — GPU data layouts

Use 2-D textures as the portable baseline:

• scalar fields: R32F;
• standard full-complex fields: RG32F at logical extent;
• legacy packed fields: RG32F at the historical half-x packed extent;
• 1-D later: one row;
• 2-D: direct layout;
• 3-D later: tiled z-slice atlas.

Define exact texel-center and logical-to-physical mappings. Compute shaders and native 3-D render targets may be optional optimizations, never the only correctness path.

Phase 5.4 — Standard 2-D FFT implementation

Substep 5.4.1 — Standard algorithm spike

Select Stockham autosort or a conventional staged radix-2 butterfly after comparing pass count, addressing clarity, and driver portability. Use integer texelFetch; never rely on filtering or normalized-coordinate rounding.

Substep 5.4.2 — Transform passes

Implement:

• real-to-complex copy;
• x and y forward stages;
• x and y inverse stages;
• exactly one 1/(Nx·Ny) inverse scale;
• round-trip readback harness.

Cache twiddles/plans by shape. Require power-of-two GPU extents initially and report this distinction from the more flexible CPU backend.

Substep 5.4.3 — Spectral convolution

Upload or generate kernel spectra, multiply state spectrum by disk/ring spectra, inverse transform, and normalize by sampled sums consistent with CPU convention. Reuse the state forward FFT for both kernels.

Phase 5.5 — Legacy packed-unitary 2-D FFT

Substep 5.5.1 — CPU stage oracle

Implement a small, clear CPU oracle for adjacent-real packing, packed-spectrum conversion, historical plan entries, unitary butterflies, and inverse unpacking. It exists for fixtures and diagnosis, not as a production CPU backend.

Substep 5.5.2 — Modern GPU port of the historical algorithm

Retain the algorithmic behavior while rewriting its infrastructure:

• adjacent x samples packed into real/imaginary components;
• historical half-x complex layout and conjugate/Nyquist handling;
• bit-reversal and twiddle plan stages for x/y;
• forward/inverse unitary scaling at each stage;
• ping-pong FFT scratch textures;
• convolution multiplier sqrt(Nx·Ny)/kernel_sum.

Use GLSL 330, integer texel addressing, embedded shaders, checked resources, and the common safe pass API. Do not copy compatibility-profile GLSL or resource hazards.

Substep 5.5.3 — Algorithm-specific constraints

Require power-of-two extents and enough texture/FBO resources. Keep standard and legacy plans, spectra, and scratch caches separate. Changing FftAlgorithm is a cold transactional rebuild and invalidates integration history.

Phase 5.6 — Numerical proof harness

For each algorithm and test field, read back explicit stages:

• input complex copy;
• forward spectrum;
• inverse round trip;
• disk/ring spectral products;
• M and N.

Compare to CPU with max absolute, mean absolute, and L2 error. Include zero, constant, impulse, checkerboard, random seeded, and asymmetric patterns at multiple small powers of two.

Initial targets:

• standard round-trip max error ≤1e-4;
• standard convolution max error ≤2e-4 on agreed fixtures;
• legacy packed stage outputs match the CPU stage fixtures within documented f32 tolerances;
• legacy final convolution agrees with direct/standard CPU convolution within 2e-4 on agreed fixtures;
• constant-field density error is small enough to preserve the documented tolerance.

Tolerances must be measured and recorded per GPU/driver class before broadening; never hide systematic normalization errors behind a loose bound.

Phase 5.7 — Lifecycle and failure testing

• Recreate FFT resources repeatedly across sizes.
• Simulate allocation/shader failures and preserve the CPU backend.
• Check for GL errors and incomplete FBOs in debug validation mode.
• Verify no resource growth after repeated switches.
• Confirm no synchronous readback in the normal frame path.
• Preflight memory estimates before allocation and retain the prior valid backend on failure.

Deliverables

• GPU capability report and automatic fallback policy.
• Auditable unsafe/RAII resource layer.
• Validated standard and legacy packed-unitary 2-D GPU FFT/convolution proofs.
• Legacy packing/plan/unitary CPU stage oracle.
• Per-algorithm stage-comparison harness and initial GPU benchmark metadata.

Exit gate

• Standard CPU/GPU round trip and convolution tolerances pass on the reference environment.
• Legacy packing, plans, scaling, round trip, spectra, and convolution pass their stage/final tolerances.
• Resource alias checks prevent read/write feedback.
• Shader and allocation failures are actionable and non-destructive.
• Repeated recreation shows no incomplete framebuffer or resource leak.
• GPU simulation work does not begin until the 2-D proof is stable.