Jorijn van der Graaf
bcdc885de8
Device
- Device::Initialize(required, optional) takes DeviceFeatures, the five
core feature structs vulkan10 to vulkan14. The library enables only what
its own shaders and code use. Device::enabledFeatures says what was
enabled, supportedFeatures what the GPU has, apiVersion the version in
use.
- shaderInt16, shaderFloat16, storageBuffer16BitAccess, scalarBlockLayout
and the uniform-buffer, storage-buffer and storage-image non-uniform
indexing bits are no longer enabled for everyone. An application whose
shaders take uint16_t spec constants passes
{.vulkan10 = {.shaderInt16 = VK_TRUE}}. scalarBlockLayout stays on with
the NVIDIA workaround, whose TLAS address may sit in a struct's tail
padding.
- Every GPU is weighed before one is chosen: Vulkan 1.3, the swapchain and,
below 1.4, maintenance5 extensions, the library's needs, the required
features. One that can't run the application is skipped, saying why when
it ranks higher. A CPU device runs it only when nothing else is listed,
and CRAFTER_GRAPHICS_DEVICE never falls back. A GPU two drivers both list
is tried through each.
- When no GPU qualifies, Initialize throws naming each GPU's gaps. It
destroys the instance it made, before any Wayland connection, so it can
be called again asking for less.
- maintenance5 is vulkan14's on a 1.4 GPU and VK_KHR_maintenance5's below.
CRAFTER_GRAPHICS_NO_VULKAN_1_4 runs as a 1.3 application, to exercise
that path on a 1.4 GPU.
- VK_KHR_spirv_1_4 and VK_KHR_shader_float_controls, core since 1.2, are no
longer enabled, nor VK_EXT_shader_atomic_float, which was enabled without
its feature struct. memoryDecompression's feature bit is queried before
it is enabled.
Shaders
- VulkanShader checks a module's capabilities, declared directly or
implicitly, against the enabled core features, the GPU's subgroup
operations and the optional groups, and throws naming the field to pass,
or saying the GPU lacks it. The tables are generated from vk.xml and
SPIR-V's grammar.
- WorkaroundNvidiaAS::Patch sized a row-major matrix push member by its
columns, so the TLAS address could land inside it.
Window
- The swapchain format is one whose own feature flags allow storage reads
and writes without a format, which since Vulkan 1.3 each format says for
itself; shaderStorageImageRead/WriteWithoutFormat are no longer required.
Tests
- DeviceFeatures: ResolveFeatures, ChooseDevice and CheckShaderCapabilities,
without a GPU.
- FeatureRequests: required and optional features end to end, the 1.3
path, and a retry after a refusal.
- PushConstantRewrite: a row-major mat3x4 push member.
- HeapASRead, HeapDynamicIndexHit, RTPassPushData and the ray-tracing
examples ask for the features their shaders use.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
109 lines
5.4 KiB
Markdown
109 lines
5.4 KiB
Markdown
# VulkanTriangle
|
||
|
||
The minimal ray-traced example. Renders a single static triangle through
|
||
`vkCmdTraceRaysKHR`. No UI.
|
||
|
||
## What it shows
|
||
|
||
- `Device::Initialize({.vulkan10 = {.shaderInt16 = VK_TRUE}})` + `Window` +
|
||
swapchain bring-up. The raygen takes the heap's buffer start as a
|
||
`uint16_t` spec constant, which needs `shaderInt16`; without asking for
|
||
it, loading the shader throws, naming the feature.
|
||
- 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
|
||
```
|
||
|
||
You should see a 1280×720 window with an RGB-barycentric triangle filling
|
||
roughly the centre. On the NVIDIA driver this works through an engine-side
|
||
workaround for a driver fault — see below.
|
||
|
||
## Native status — NVIDIA driver fault, worked around
|
||
|
||
On NVIDIA driver `610.43.02` (Vulkan 1.4) reading the acceleration
|
||
structure through `VK_EXT_descriptor_heap` aborts the device with
|
||
`VK_ERROR_DEVICE_LOST` on the first frame. This is a **driver-side fault**
|
||
in the brand-new descriptor-heap acceleration-structure path, not an engine
|
||
bug (full investigation in #7, summarised below).
|
||
|
||
**The engine works around it transparently** (issue #15). On the NVIDIA
|
||
proprietary driver only, `VulkanShader` rewrites the compiled SPIR-V at
|
||
module-load time so that every `OpLoad` of an `accelerationStructureEXT`
|
||
out of the heap becomes a load of the TLAS *device address* (from a
|
||
push-constant block) followed by
|
||
`OpConvertUToAccelerationStructureKHR` — which reads no descriptor and so
|
||
never touches the faulting path. `RTPass` feeds the active frame's TLAS
|
||
address in as push data. SPIR-V allows only one push-constant block per
|
||
entry point, so when a shader already declares one the TLAS address is
|
||
appended to *that* block (rather than adding a second, which would fail
|
||
validation — issue #18); shaders without a push constant get a freshly
|
||
synthesized single-member block. `raygen.glsl` and the example code are
|
||
unchanged; acceleration structures still bind into the heap normally. On
|
||
every other driver the workaround is inert. It's gated on
|
||
`Device::workaroundDescriptorHeapAS` and confined to one fenced block in
|
||
`interfaces/Crafter.Graphics-ShaderVulkan.cppm` so it can be deleted wholesale
|
||
once a fixed NVIDIA driver ships.
|
||
|
||
### Status on later drivers
|
||
|
||
On `615.78.08` the fault is still there. With the rewrite off
|
||
(`CRAFTER_GRAPHICS_NO_AS_WORKAROUND` set), `traceRayEXT` still loses the device,
|
||
and an inline ray query that reads the TLAS from the heap no longer faults but
|
||
renders nothing. Mesa's llvmpipe now advertises `VK_EXT_descriptor_heap` too
|
||
and renders the plain heap read correctly, which is a second implementation
|
||
backing the conclusion below. `tests/HeapASRead` renders this triangle through
|
||
both paths and checks the pixels; `HeapASRead --no-workaround` is the quick
|
||
check for a new driver, reporting each path on its own.
|
||
|
||
### The underlying fault (#7)
|
||
|
||
The fault was 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; at the time NVIDIA was the only
|
||
implementation on this machine that advertised it (llvmpipe did not), so
|
||
there was no second conformant implementation to cross-check against.
|
||
Mesa's llvmpipe has it now; see "Status on later drivers" above.
|
||
|
||
**Conclusion:** this is a driver-side fault in NVIDIA's
|
||
`VK_EXT_descriptor_heap` acceleration-structure path, not an engine bug, and
|
||
it should be reported to NVIDIA. Until a fixed driver ships, the SPIR-V
|
||
rewrite above keeps the native RT path working; once it does, remove the
|
||
workaround and the heap AS read becomes the direct path again.
|