---
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/
    └── …
```