1 files changed, 78 insertions, 0 deletions

diff --git a/yuvbench/CLAUDE.md b/yuvbench/CLAUDE.md
new file mode 100644
index 0000000..ee6ee4f
--- /dev/null
+++ b/yuvbench/CLAUDE.md
@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+yuvbench benchmarks YUV 4:2:0 → RGB24 color space conversion across multiple implementations. It loads a raw YUV file, runs each enabled backend through 100 warmup + 2500 timed iterations, and reports min/max/avg per-iteration timing in milliseconds.
+
+## Build Commands
+
+```bash
+# macOS (Apple Silicon)
+./build-macos-aarch64-clang.sh
+
+# Linux (x86_64)
+./build-linux-x86_64-gcc.sh
+```
+
+Both scripts create `build/` and produce `build/yuvbench`.
+
+## Running
+
+```bash
+./build/yuvbench images/jellybeans-256x256.yuv
+./build/yuvbench images/capitol-2950x1528.yuv
+./build/yuvbench images/capitol-2950x1528.yuv show   # pipe last frame to ffplay
+```
+
+Input filename must encode dimensions as `name-WIDTHxHEIGHT.yuv`.
+
+## Prepare Test Images
+
+```bash
+# Convert source images in images/src/ to raw YUV 4:2:0
+./images/convert.sh
+```
+
+## Architecture
+
+### Backend Plugin System
+
+Each backend is an optional compilation unit implementing the interface in `yuvbench.h`:
+
+```c
+typedef struct {
+    void (*init_fn)(Ctx *ctx);
+    void (*convert_fn)(Ctx *ctx);
+    void (*deinit_fn)(Ctx *ctx);
+} Backend;
+```
+
+`yuvbench.c:run_backend()` drives warmup + timing loops. Backends are compiled in via `-DYUVBENCH_<NAME>` preprocessor flags set in each build script.
+
+### Backends
+
+| Define | File | Platform | Notes |
+|--------|------|----------|-------|
+| `YUVBENCH_BAD` | `yuvbench_bad.c` | All | Naive BT.709 nested loop; reference baseline |
+| `YUVBENCH_ACCELERATE` | `yuvbench_accelerate.c` | macOS | vImage YUV→ARGB→RGB; caches conversion object |
+| `YUVBENCH_SWSCALE` | `yuvbench_swscale.c` | All | FFmpeg libswscale; SwsContext created in init |
+| `YUVBENCH_LIBYUV` | `yuvbench_libyuv.c` | Linux | Google libyuv `I420ToRAW()`; no init/deinit |
+
+### Timing (`kbench.h`)
+
+- macOS/ARM64: reads `CNTVCT_EL0` / `CNTFRQ_EL0` hardware registers directly
+- Linux: `clock_gettime(CLOCK_MONOTONIC)`
+
+### Adding a New Backend
+
+1. Create `yuvbench_<name>.c` implementing `init`, `convert`, `deinit` functions
+2. Guard the file body with `#ifdef YUVBENCH_<NAME>`
+3. Register it in `yuvbench.c` (see the `backends[]` array)
+4. Add `-DYUVBENCH_<NAME>` and any link flags to the relevant build scripts
+
+## Platform Notes
+
+- The `vk-asylum` branch contains a Vulkan compute shader backend (`build-shaders.sh`, `shaders.h`, `main.c`)
+- Assembly output for the Accelerate backend is emitted to `build/yuvbench_accelerate.S` on macOS builds