## This repository: Crafter.Graphics

The execution contexts to enumerate, beside the charter's:
- One source, several builds. `project.cpp` defines exactly one of
  `CRAFTER_GRAPHICS_WINDOW_WAYLAND`, `CRAFTER_GRAPHICS_WINDOW_WIN32` and
  `CRAFTER_GRAPHICS_WINDOW_DOM` from the target: native Linux (Wayland and
  Vulkan), `x86_64-w64-mingw32` (Win32 and Vulkan, gamepads through
  Windows.Gaming.Input), `wasm32-wasip1` (the DOM and WebGPU, through
  `additional/dom-env.js` and `additional/dom-webgpu.js`) and
  `aarch64-alpine-linux-musl` (Mesa Turnip: no descriptor heap, no ray
  tracing). Code behind one backend's `#ifdef` is still the range's code,
  and a change to one backend's half can leave the other's behind.
- One device, several paths, chosen at start-up: the descriptor heap or
  the bindless descriptor-set fallback (`CRAFTER_GRAPHICS_NO_DESCRIPTOR_HEAP`
  forces it), with each UI kernel's two SPIR-V builds; ray tracing or none
  (heap-only; `Device::stageMask` drops its stage without it); Vulkan 1.4
  or 1.3 (`CRAFTER_GRAPHICS_NO_VULKAN_1_4`); `swapchain_maintenance1` or
  not; GPU memory decompression or the CPU path
  (`Device::memoryDecompressionSupported`); the NVIDIA AS workaround on or
  off (`Device::workaroundDescriptorHeapAS`,
  `CRAFTER_GRAPHICS_NO_AS_WORKAROUND`); llvmpipe on a machine without a
  GPU.
- The GPU timeline. Three frames in flight, a fence each: what lives per
  frame is keyed by `Window::currentFrame`, what lives per swapchain image
  by `currentImage`, and the image count follows the present mode. A
  handle a frame in flight may still use is released through the deletion
  queue (freed `framesInFlight` frames later) or after a wait for the GPU;
  a freed descriptor slot is handed out again at once; a swapchain rebuild
  asked for from a listener mid-frame (`Resize`, `SetPresentMode`) waits
  for that frame's present, and `onResize` runs after it; a static owner
  is destroyed after the driver is gone. Within one dispatch, Vulkan
  orders nothing between workgroups.
- Re-entry from the platform. The Wayland listeners run inside
  `wl_display_dispatch`, `wl_display_dispatch_pending` and
  `wl_display_roundtrip`, which the frame loop, window creation,
  `Device::Initialize` and the clipboard's reads call. Windows calls the
  window procedure from the message loop and also synchronously from
  inside `CreateWindowEx`, `SendMessage` and `DefWindowProc`. The DOM's
  listeners in `dom-env.js` call the `__crafterDom_*` exports. A listener
  can resize, close or destroy the window it was called for.
  Windows.Gaming.Input reports gamepad connects and disconnects on threads
  of its own, queued under a lock until the event loop takes them.
- Shared state: `Device`'s statics are process-wide; `Device::frameCounter`
  is one clock for every window, which the deletion queue, the staging
  rings and the font atlas's eviction run on; the deletion queue is shared
  under `deletionMutex`. The caches keyed on a `Font*` alias a new font at
  a freed one's address unless `UIRenderer::InvalidateFont` ran.
- Data the GPU and JavaScript read: an item or header struct is mirrored
  byte for byte by a `std430` block in `shaders/ui-shared.glsl`, by the
  WGSL in `dom-webgpu.js` and by every shader that includes it, the
  examples' among them; one push block serves both builds, through
  `vkCmdPushDataEXT` on the heap and `vkCmdPushConstants` in the set
  build, within 256 bytes.
- Tests: each its own process, in parallel, with a 60 s timeout; every
  test that calls `Device::Initialize` needs a Wayland display, and one
  that lacks a capability exits 77 and pins nothing on that machine. A
  validation check counts only in a run where the layer loaded.

Semantics to read on disk rather than recall: the Vulkan headers and
registry (`include/vulkan/`, `registry/vk.xml`) and Vulkan-Utility-Libraries
as cloned (`~/.cache/crafter.build/external/Vulkan-Headers-<hash>/`,
`Vulkan-Utility-Libraries-<hash>/`; several clones may sit side by side);
the Wayland protocols (`/run/host/usr/share/wayland/wayland.xml`,
`/run/host/usr/share/wayland-protocols/`, the generated code in `lib/`) and
the client headers (`/run/host/usr/include/wayland-client*.h`,
`xkbcommon/`); the MinGW headers (`/run/host/usr/x86_64-w64-mingw32/include/`);
libc++ and clang as the host installs them (`/run/host/usr/include/c++/v1`,
`/run/host/usr/lib/clang/<major>/include`); the vendored stb and libevdev
in `lib/`; Crafter.Event, Crafter.Math and Crafter.Asset as cloned
(`~/.cache/crafter.build/external/<Name>-<hash>/`). The crafter-build
Flatpak compiles with an LLVM of its own, which is not readable from
here: where a semantic may differ between LLVM releases, the host's
headers settle it for the host's build only. The Vulkan specification's
valid-usage rules, the WebGPU and WGSL specifications and Microsoft's API
documentation are not on disk: a semantic only they settle is unverified.