Merge pull request #1691 from adriadam10/docs/architecture-shader-registration

docs(architecture): describe shader compilation at registration

docs/dev/ARCHITECTURE.md

@@ -48,22 +48,36 @@ flowchart LR
 ## Graphics
 
 ```mermaid
-flowchart LR
-    game["Game:<br/>command buffers"] --> submit["libSceAgcDriver/Submit<br/>DCB / ACB"]
-    submit --> pm4["Execution/Pm4:<br/>state, draws,<br/>dispatches"]
-    pm4 -- "shader + state" --> cache{"Compiled variant<br/>in memory or<br/>on disk?"}
-    cache -- yes --> vk
-    cache -- no --> dec
+flowchart TB
+    subgraph init["Game initialization"]
+        direction LR
+        create["libSceAgc:<br/>create shader,<br/>link stages,<br/>primitive state"] --> reg["libSceAgcDriver:<br/>RegisterShader,<br/>Resolve*Abi"]
+    end
 
     subgraph recompiler["core/shader/recompiler"]
+        direction LR
         dec["RdnaDecoder"] --> cf["ControlFlow:<br/>graph + structurize"]
         cf --> tr["Translation:<br/>RDNA to IR"]
         tr --> opt["Optimization:<br/>SSA, resources,<br/>bindings"]
         opt --> spv["SpirvBackend:<br/>emit SPIR-V"]
     end
 
-    spv --> vk["libSceAgcDriver/Graphics:<br/>Vulkan pipeline"]
+    subgraph frame["Each frame"]
+        direction LR
+        game["Game:<br/>command buffers"] --> submit["libSceAgcDriver/Submit<br/>DCB / ACB"]
+        submit --> pm4["Execution/Pm4:<br/>state, draws,<br/>dispatches"]
+        pm4 -- "user data +<br/>descriptors" --> inv["Invocation:<br/>specialization constants,<br/>descriptor heaps, BDA"]
+        inv --> vk["libSceAgcDriver/Graphics:<br/>Vulkan pipeline"]
+    end
+
+    init -- "code + static ABI" --> disk{"Compiled artifact<br/>on disk?"}
+    disk -- no --> recompiler
+    disk -- yes --> art["Prepared artifact:<br/>SPIR-V with no<br/>resource values"]
+    recompiler --> art
+    art -- "looked up at<br/>draw / dispatch" --> frame
 ```
 
-- [`Recompiler.cpp`](../../core/shader/recompiler/Recompiler.cpp) runs the stages in this order. With `ANYPS5_ENABLE_SPIRV_TOOLS`, the SPIR-V is also validated and optimized with SPIRV-Tools.
-- `ShaderRecompiler::Recompile` keeps compiled variants in memory, and `ShaderDiskCache` stores them on disk so later runs reuse them.
+- Shaders are compiled when the game registers them, not when they are first drawn. [`ShaderRegistry.cpp`](../../core/libs/prx/libSceAgcDriver/Execution/src/Driver/Shaders/ShaderRegistry.cpp) runs `Driver::RegisterShader` for every shader the game creates, and `Resolve*Abi` when libSceAgc links stages or sets the primitive state. Each one compiles the artifact for that static ABI (stage, wave size, push constant layout, linked stages).
+- An artifact does not depend on the resources bound at draw time. The shader reads them at runtime, as on the PS5: buffers, images and samplers from descriptor arrays and typed heaps indexed at runtime, and user data from the shader data block defined in [`RuntimeAbi.hpp`](../../core/shader/recompiler/RuntimeAbi.hpp).
+- At a draw or dispatch, the driver looks up the prepared artifact and fails if there is none. Only compute shaders the game never registered are compiled at that point. The draw supplies the invocation: the specialization constants listed in [`PipelineSpecialization.hpp`](../../core/shader/recompiler/PipelineSpecialization.hpp), the descriptors and the push constants. Each distinct set of constants produces one specialized SPIR-V module, kept in memory.
+- [`Recompiler.cpp`](../../core/shader/recompiler/Recompiler.cpp) runs the stages in this order. With `ANYPS5_ENABLE_SPIRV_TOOLS`, the SPIR-V is also validated and optimized with SPIRV-Tools. `ShaderDiskCache` stores the artifacts on disk so later runs skip the recompilation.