skate-3-rust-engine/docs/cpu-material-binding-experiment.md

CPU material binding experiment

Withdrawn after the user's runtime test. Build bea625f exited with native access violation 0xC0000005 about 11.4 seconds after launch, shortly after map initialization, on an RTX 5090 using Vulkan. The report contains no native stack or module map, so it cannot establish the faulting subsystem or blame the driver. The binding-array change is treated as a suspected regression, not a confirmed root cause. Passing Naga tests did not establish runtime safety.

The recovery revision restores the exact pre-v6 main/depth shader source and original uniform, texture and storage bindings. It removes the array shader library and adds a regression assertion that RetailWorldMaterial has no bindless descriptor or slot count. The v5 shadow proxies remain disabled. Recovery does not claim an FPS improvement or a confirmed crash fix until the user runs it. The remaining sections describe the withdrawn experiment for reference.

The user reports poor FPS while looking into University and good FPS looking out of the map, still CPU bound. The map being resident does not establish that every triangle is drawn. The captured CPU render work is the actionable bottleneck.

The v4 audit capture university-audit-7802-28261.json recorded 4,918 frames in 20 seconds without dropped trace events. Mean command generation was 1.782 ms per frame; the main opaque encoder finish accounted for 0.995 ms, versus 0.349 ms in opaque draw traversal. The v5 shadow batch capture university-shadow-batches-12344-4318.json recorded 3,309 frames without dropped events. Main encoder finish remained 1.012 ms per frame. Shadow visibility fell from 0.466 to 0.349 ms, but that did not address the dominant main-pass cost. These are different workloads, not a controlled performance comparison.

A discarded CPU wall-occlusion prototype split at most 256 coarse batches and used conservative whole-AABB occlusion against real opaque wall triangles. Its static inward view culled only 55 of 3,512 candidates while costing about 1.15 ms. It was removed before shipping; adding that CPU cost was unjustified.

Implementation

RetailWorldMaterial now uses Bevy's bindless material allocator, with a resource limit of 64 per slab. Materials share texture/sampler arrays and a packed parameter buffer. The existing shared frame/shadow state remains a buffer reference. This reduces distinct material binding groups and allows compatible meshes to share multidraw batches. Pipeline, mesh allocation and resource capacity still constrain batching; this is not a promise of a 64-fold draw reduction.

The main and depth/shadow shaders use the material slot stored in Bevy's mesh instance data. Both retain the original bindings when Bevy reports that bindless resources are unsupported. The common shader module is permanently loaded using Bevy's shader-library macro so custom imports resolve at runtime. The shading body, alpha rejection, geometry and texture content are preserved. No user graphics setting, native physics, input or simulation cadence changes.

The unsuccessful v5 extra shadow meshes and their light-layer adjustment are removed from the active renderer. Normal world meshes cast shadows again. The data-only shadow experiment remains test-only for historical reproducibility.

Trace configuration includes retail_bindless: true means the device supports the selected material-array path, false means fallback, null means device data was unavailable. This indicates capability selection, not measured draw counts.

Validation and acceptance

GPU-free shader tests compose the actual material shaders and real Bevy vertex interfaces, using fixtures for unrelated lighting resources/functions. They validate six combinations: main, shadow depth and depth with normal/motion output, each with bindless enabled and disabled. A separate test checks the Rust-generated resource index table and buffer bindings against the shader contract.

The release shader tests passed (both tests, six shader variants). Eleven world adapter tests and two scene lifecycle tests passed; the offline map inventory test remains ignored in this ordinary regression run. Four tracing regression tests also passed, for 19 targeted tests in total.

Runtime pipeline creation, appearance and FPS remain unverified until the user runs the private executable. The agent does not launch gameplay. Compare v4 and v6 from the same stationary inward-facing view with identical settings, then the same route. Inspect retail_bindless, main opaque encoder finish, total command generation and frame percentiles. Keep the earlier executables for rollback.

The private v6 static-CRT release executable compiled successfully from bea625f9878148347e0fda0529bd0d6ba7b1a327. Its embedded revision, matching PDB presence and Windows-system-only PE imports were checked without executing it. EXE SHA-256: cd52c92a709372f95a41d27f6fea794867c1e651f9b8f9d693662ff898dc7325. The local TRACE-UNIVERSITY-BINDLESS.bat launcher uses the existing extracted University/assets and captures 20 seconds after F9. Earlier builds remain intact. Existing compiler warnings remain; this build does not establish a measured FPS gain.