Restructure agent setup

2026-07-05 19:00:24 +01:00
parent 1e0c195f42
commit 79c5d368bf
5 changed files with 230 additions and 61 deletions
@@ -0,0 +1,74 @@
+---
+name: prism-rhi
+description: RHI (Rendering Hardware Interface) patterns — compile-time dispatch, by-value desc structs, wapp array aliases, backend file layout
+license: MIT
+compatibility: opencode
+metadata:
+  domain: rendering
+---
+## What I do
+
+Captures the RHI conventions for Prism: how backends are dispatched, how descriptor structs and arrays are handled, and how the files are organized.
+
+## When to use me
+
+Use this when working on any file in `scratchpad/rhi/` or `src/prism/rhi/`, or when creating a new backend (Vulkan, D3D12, Metal).
+
+## Conventions
+
+### Backend dispatch
+
+Backend selection is compile-time via `-D PR_RHI_VULKAN` / `-D PR_RHI_D3D12` / `-D PR_RHI_METAL`. The umbrella header `pr_rhi.h` includes the appropriate alias file:
+
+```c
+#if defined(PR_RHI_VULKAN)
+#  include "vulkan/pr_rhi_vk_aliases.h"
+#elif defined(PR_RHI_D3D12)
+#  include "d3d12/pr_rhi_d3d12_aliases.h"
+#elif defined(PR_RHI_METAL)
+#  include "metal/pr_rhi_metal_aliases.h"
+#else
+#  error "Define one of: PR_RHI_VULKAN, PR_RHI_D3D12, PR_RHI_METAL"
+#endif
+```
+
+Each `_aliases.h` file maps generic names to backend-specific names:
+
+```c
+#define prRhiCreateDevice       prRhiCreateDeviceVk
+#define prRhiCreateSwapchain    prRhiCreateSwapchainVk
+#define prRhiCreateBuffer       prRhiCreateBufferVk
+// …
+```
+
+Backend implementations are suffixed with the backend name: `pr_rhi_vk_device.c`, `pr_rhi_vk_swapchain.c`, etc.
+
+### Desc structs
+
+All descriptor structs are passed **by value**, not `const *`:
+
+```c
+// correct
+PrRhiDevice *prRhiCreateDevice(PrRhiPhysicalDevice *pdev, PrRhiSurface *surface,
+                                PrRhiDeviceDesc desc, WpAllocator *alloc);
+
+// wrong
+PrRhiDevice *prRhiCreateDevice(PrRhiPhysicalDevice *pdev, PrRhiSurface *surface,
+                                const PrRhiDeviceDesc *desc, WpAllocator *alloc);
+```
+
+### File layout
+
+```
+scratchpad/rhi/
+├── pr_rhi.h              ← umbrella header (API declarations + backend dispatch)
+├── pr_rhi_types.h        ← shared types (enums, element types, array aliases, desc structs, opaque handles)
+├── vulkan/
+│   ├── pr_rhi_vk.h       ← Vulkan backend header (opaque struct defs + Vk-suffixed decls)
+│   └── pr_rhi_vk_aliases.h ← #define alias mapping
+├── d3d12/
+│   └── …
+└── metal/
+    └── …
+```
+