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

CPU material binding experiment

v8: repaired material-array shader

The v6 native access violation was reproduced without launching gameplay: an isolated Vulkan pipeline compilation using the v6 material fragment shader exited with 0xC0000005 at Device::create_render_pipeline. The test used the same RTX 5090, NVIDIA 616.56 and Vulkan backend reported by the user. The original shader compiled in the same harness. Inlining the v6 shading body also compiled, narrowing the trigger to that shader's function/resource-argument structure rather than map simulation or residency. This does not establish a specific driver instruction or rule out additional issues in the full game.

v8 retains material-array batching but replaces the large shade function taking textures and samplers as arguments. Sampling helpers now receive only the material slot and coordinates; they access global texture/sampler arrays at the sampling site. One shading body serves both bindless and fallback paths. Existing shading operations, texture selection, alpha rejection and user settings are retained.

Validation on that GPU passed for both bindless and fallback modes:

• Native compilation of the main and shadow pipelines.
• Offscreen main-pass drawing with 8x MSAA, command submission and pixel readback. Material slots 0 and 1 produced the expected [64,64,64,255] and [191,191,191,255] pixels; fallback produced the expected first value.
• Six Naga shader variants and the Rust material index/buffer contract.
• Eleven world adapter regressions.

The GPU probes use real retail shaders and Bevy vertex interfaces, with small fixtures for unrelated lighting resources. They validate the reproduced pipeline crash and basic material-array execution, not the entire Bevy render graph or game. The two GPU tests are ignored by ordinary test runs and require explicit opt-in. SKATE_SHADER_PROBE_FALLBACK=1 selects the fallback probe; the default tests the array path. The test-only SKATE_SHADER_PROBE_SOURCE can point to a directory with v6-retail_world.wgsl and v6-retail_material_bindings.wgsl extracted from bea625f to reproduce the old compiler crash using the main pipeline probe.

CPU batching is enabled again in v8. No FPS gain is claimed until a matched user capture measures main opaque encoder finish, total command generation and frame times. No gameplay was launched during this work.

Private v8 release build de37c6e16722e2e68259e458cc12d5f78aeb71cb compiled with static CRT. The embedded revision, PDB presence and system-only DLL imports were verified without executing the game. EXE SHA-256: b5c6d46b5861c3e34d75d47e061318f3ea3b69b7c8cb2aca87074fd7b2621532. TRACE-UNIVERSITY-CPU-FIX.bat launches this build against the existing assets and records 20 seconds after F9. The former bindless launcher also selects v8; the recovery launcher still selects v7 for comparison. Existing compiler warnings remain. Headless GPU checks above passed; gameplay/FPS acceptance is still pending.

v6/v7 history

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.

Recovery build 0b89cb8f47838bb1b7532a88f4bd3822c6d26ec6 compiled in release with static CRT. Both shader regression tests passed (three original shader variants plus the non-bindless material contract). Its embedded revision and system-only DLL imports were checked without gameplay execution. SHA-256: ef9b2c8f0b51d80e43f2928eb3b7aba948fff4e4225d91c78435b38699a30b2e. The private v7 recovery launcher is ready; the former bindless launcher now also points to v7. The v6 binary remains preserved but is no longer selected by it.

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.