Batch opaque retail shadow geometry independently of surface materials

docs/render-batching-experiment.md

@@ -0,0 +1,84 @@
+# University render batching experiment
+
+The user authorized engine/content visual tradeoffs after the initial exact-output
+audit, while keeping resolution, MSAA, user settings and native gameplay timing
+unchanged. This first structural experiment targets redundant shadow submission;
+it does not yet simplify triangle geometry or lower shadow-map quality.
+
+## What the inventory established
+
+Read-only analysis used the same University v14 package and actual material builder
+as the preceding captures. Synthetic image handles in the inventory preserve
+canonical texture identity, sampler role and invalid-cube fallback; no GPU starts.
+
+| Quantity | Before | Experiment |
+|---|---:|---:|
+| Main world batches before visibility | 4,870 | 4,868 |
+| Opaque static world shadow casters/batches | 3,414 | 680 |
+| Opaque shadow triangles | 1,142,084 | 1,142,084 |
+| All main world triangles | 1,645,617 | 1,645,617 |
+
+Exact main-material consolidation saves only two batches (0.04%). It is not the
+large main-pass optimization suggested by the original material count. Further
+main-pass gains would require a different binding/submission strategy or an
+intentional content change, not merely removing unused material metadata.
+
+Opaque shadow batch count falls by about 80%. The remaining 1,414 masked, 12 blended
+and 28 fallback world batches retain their existing shadow paths. Consequently,
+the static-world caster candidate count is approximately 2,134 rather than 4,868
+after main consolidation, before per-view/cascade culling. These are resource
+counts, not measured draws, GPU time or an FPS improvement.
+
+The additional proxy meshes contain 1,358,304 vertices and 1,142,084 triangles:
+46,304,304 bytes (44.2 MiB) of position/normal/index payload. Allocator and renderer
+metadata are additional. This trades memory and some mesh preparation for fewer
+shadow candidates and material switches; only a runtime comparison can establish
+the net benefit. The 64 m cell size is a conservative initial experiment, not a
+measured optimum.
+
+## Implementation
+
+`RetailWorldMaterial::batch_key` compares every current uniform lane by float bits,
+texture/sampler-role handles, shared storage, alpha cutoff and culling state.
+Source-only metadata no longer forces separate identical retail batches. Blended
+geometry retains its old grouping and sorting centers. Batches needing generated
+tangents remain separate to avoid changing averaging across old boundaries.
+
+For opaque static retail meshes with no alpha rejection, `retail_shadow_geometry`
+assigns complete triangles to 64 m cells by centroid and separates one-sided and
+two-sided casters. Bounds come from the full vertex positions, including triangles
+that cross cell boundaries. The shadow meshes retain authored positions, normals,
+indices and winding. They use two shared opaque depth-capable StandardMaterials,
+so they do not bind all the world's surface textures for depth rendering.
+
+Original opaque main meshes receive `NotShadowCaster`; their shadow geometry is
+on reserved internal render layer 27. World lights whose masks contain layer 0
+also receive layer 27 before visibility processing. Main cameras do not receive
+that layer. The layer-28 player-only shadow light is unchanged. This also handles
+world point/spot lights; University itself contains no authored map lights.
+
+Alpha-tested foliage, transparent surfaces, unsupported/fallback materials, sky,
+backdrops and character meshes retain their prior paths. Collision, rails, physics,
+input sampling and simulation cadence are untouched. All proxy entities and meshes
+use the normal map asset ownership/retirement path, including abandoned preparation.
+
+## Verification and runtime acceptance
+
+Thirteen release tests passed for the map/render adapter, including new checks for
+effective material identity, distinct lightmap/blend groups, full boundary-crossing
+shadow triangles, exact normal bits, culling modes, reserved light/camera layers
+and proxy retirement. Two scene lifecycle tests and two character-lighting tests
+also passed. The separate ignored University inventory test passed exact triangle
+multiset equality for both main geometry and the opaque shadow geometry.
+
+No gameplay or GPU was started by the agent. Runtime acceptance still needs the
+private build to load and render correctly, especially main-world lighting on the
+skater, player shadows on the ground, foliage silhouettes, camera movement and
+map transitions. Compare shadow visibility, shadow queue/draw costs, render command
+generation, frame percentiles and memory against the preceding build. The previous
+EXE/PDB and captures remain available for comparison and rollback.
+
+The capture includes `main_opaque_pass_close` and `main_opaque_encoder_finish` CPU
+scopes added in the preceding build. They should identify whether the dominant
+main-pass command time is draw traversal or pass/encoder completion before a larger
+material binding redesign is attempted. No FPS gain is claimed from the inventory.