Crafter.Graphics/examples/VulkanTriangle/README.md

# VulkanTriangle

The minimal ray-traced example. Renders a single static triangle through
`vkCmdTraceRaysKHR`. No UI.

## What it shows

- `Device::Initialize()` + `Window` + swapchain bring-up.
- A `DescriptorHeapVulkan` sized for one image + one buffer slot, with
  slot ranges allocated via the bump-allocator API
  (`AllocateImageSlots`, `AllocateBufferSlots`).
- A `PipelineRTVulkan` built from raygen / miss / closesthit SPIR-V
  shaders compiled at build time.
- `Mesh::Build` constructing a BLAS and `RenderingElement3D::BuildTLAS`
  the per-frame TLAS.
- Direct descriptor writes via `vkWriteResourceDescriptorsEXT` for the
  swapchain views and TLAS device addresses.
- `RTPass{&pipeline}` plugged into `window.passes` — the canonical
  way to add ray tracing to a window in this library.

It's the smallest sensible test of the bindless `VK_EXT_descriptor_heap`
+ ray-tracing path.

## Run

```bash
cd examples/VulkanTriangle
crafter-build -r
```

On a working driver you should see a 1280×720 window with a triangle
filling roughly the centre. **On the current NVIDIA driver the native
build aborts with `VK_ERROR_DEVICE_LOST` the moment `traceRayEXT` runs —
see below.**

## Native status — known driver fault (`VK_ERROR_DEVICE_LOST`)

On NVIDIA driver `610.43.02` (Vulkan 1.4) the native build aborts with
`VK_ERROR_DEVICE_LOST` on the first frame as soon as the shader reads the
acceleration structure. `VK_EXT_device_fault` reports an invalid GPU read
(address `~0xffff…`) plus instruction-pointer faults inside the
ray-tracing shader. Commenting out the `traceRayEXT` call makes the crash
disappear (the dispatch + `imageStore` path renders a solid colour fine).

This was investigated thoroughly and traced to the **acceleration-structure
read through `VK_EXT_descriptor_heap`**, *not* to the engine's RT setup:

- The BLAS/TLAS build is correct and finishes before rendering
  (`Window::FinishInit` does `vkQueueWaitIdle`). The built TLAS instance
  has an identity transform, `mask = 0xFF`, and the correct BLAS device
  address.
- The AS descriptor is written correctly — `vkWriteResourceDescriptorsEXT`
  stores the TLAS device address at the expected heap byte offset (verified
  by dumping the raw heap bytes after the write).
- The Khronos validation layers (1.4.350, current) report **zero** errors
  for the whole frame, including the SBT regions handed to
  `vkCmdTraceRaysKHR`.
- Storage images and buffers bound through the **same** descriptor heap
  work — with `traceRayEXT` removed, the raygen shader's `imageStore`
  renders correctly, so the heap binding / image path is sound.
- Both the ray-tracing pipeline (`traceRayEXT`) **and** inline ray query
  (`rayQueryEXT`, which uses no shader binding table) fault identically
  when they read the acceleration structure from the heap. That isolates
  the fault to the AS-via-heap read, not the SBT or the RT pipeline.
- The fault reproduces even with the AS descriptor written at heap byte 0
  and read at shader index 0 (no descriptor offset/stride ambiguity), and
  is unaffected by the `pAddressRange` size.
- `VK_EXT_descriptor_heap` is brand new; on this machine NVIDIA is the only
  implementation that advertises it (llvmpipe does not), so there is no
  second conformant implementation to cross-check against.

**Conclusion:** this is a driver-side fault in NVIDIA's
`VK_EXT_descriptor_heap` acceleration-structure path, not an engine bug. It
should be reported to NVIDIA. The `traceRayEXT` call is intentionally left
in `raygen.glsl` so this stays a faithful one-file reproducer; the example
will start rendering the triangle again once a fixed driver ships.