Catcrafts/Crafter.Graphics
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Crafter.Graphics/examples/VulkanTriangle/README.md
catbot 464cb66063 docs(vulkan-rt): record native descriptor-heap AS read as a driver fault 
Investigated the VK_ERROR_DEVICE_LOST on the native VulkanTriangle (#7).
Verified the engine side is correct and validation-clean: the BLAS/TLAS
build finishes before render (FinishInit waits), the built instance is
well-formed (identity transform, mask=0xFF, correct BLAS ref), and
vkWriteResourceDescriptorsEXT stores the TLAS device address at the
expected heap offset (confirmed by dumping the heap bytes). Khronos
validation 1.4.350 reports zero errors.

The fault is isolated to reading the acceleration structure through
VK_EXT_descriptor_heap:
- images/buffers via the same heap render fine (trace disabled -> the
  raygen imageStore path renders a full gradient);
- both traceRayEXT and inline rayQueryEXT (no SBT) fault identically on
  the AS read;
- reproduces with the AS descriptor at heap byte 0 / shader index 0 (no
  offset/stride ambiguity) and regardless of pAddressRange size.

NVIDIA 610.43.02 is the only descriptor_heap implementation available
(llvmpipe lacks the extension), so there is no second implementation to
cross-check. Conclusion: driver-side fault in NVIDIA's brand-new
VK_EXT_descriptor_heap acceleration-structure path; should be reported to
NVIDIA. The traceRayEXT call is left active so the example stays a
faithful reproducer. Documented in both READMEs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-31 22:21:57 +00:00

3.6 KiB
Raw Blame History

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

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.