75 lines
2.3 KiB
Markdown
75 lines
2.3 KiB
Markdown
---
|
|
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/
|
|
└── …
|
|
```
|
|
|