Jorijn van der Graaf
234fcce099
Window - CreateSwapchain asked for exactly numFrames (3) images whatever the surface said, read them into a three-element array, and keyed the command buffers, the fences and the descriptor-heap copy holding "its" swapchain image by the acquired image index. A swapchain of another size fell back to FIFO (asked for MAILBOX or IMMEDIATE) or threw, and a surface whose minimum is above three got a create info below it (#160). Mesa's MAILBOX needs four images: Turnip on phoc, llvmpipe on any Wayland compositor. - The present mode is picked first, then the swapchain is sized by SwapchainCapabilities: the surface's counts for that mode where the instance has surface_maintenance1. With swapchain_maintenance1 the swapchain names its mode (VkSwapchainPresentModesCreateInfoKHR), which is what makes the mode's own count the one that applies, at creation and to the forward progress of a UINT64_MAX acquire; without it the stricter of the mode's and the surface's counts for all modes. It asks for numFrames or that minimum where more, never past the maximum (SwapchainMinImageCount). Turnip's FIFO keeps its three images and MAILBOX gets four. The FIFO fallback and presentModeUnfit are gone. - images, imageViewInfos (was imageViews: they are create-infos), the made imageViews that descriptor sets take, imageInitialised and the render-finished semaphores are per image, as many as the driver made. The views are made once per swapchain. The semaphores only grow, since a present of the old swapchain may still wait on one. - Frames in flight stay numFrames, keyed by currentFrame, frameCounter % numFrames: the command buffer, the fence, the acquire semaphore, the heap copy (or set), RenderingElement3D::tlases, the frameIdx a pass is recorded with. currentImage is the acquired image. currentBuffer is gone, so code that used it stops compiling instead of picking the wrong one; RenderPass::Record's frameIdx keeps its name and is now the frame slot, as RenderPass.cppm says. - The frame's fence is waited before the acquire. The acquire semaphores need no spare then, and a frame waits for exactly the one numFrames before it, which the deletion queue and the staging rings count on and fences keyed by image did not promise once images come back out of order. The swapchain slots are written before the fence is reset. - From the acquire to the present the window is recording: a Resize or SetPresentMode from a listener (a VSync key ticked in onUpdate) takes effect after the present, through RebuildSwapchain, together with a present that found the swapchain out of date. Rebuilding mid-frame used to destroy the image the frame was drawing into; with images sized per swapchain it would also index past the new one's end. DescriptorHeapVulkan - Frames and images pair up differently from frame to frame, so no heap copy can keep one swapchain image. AddSwapchainSlot(slot, window) lists an image slot as that window's swapchain image, and Window::Render writes the image a frame acquired into its window's listed slots in that frame's copy, or its set, before onUpdate, skipping a slot that holds it already. A slot is one window's, so two windows can share a heap without writing each other's slots under each other's frames in flight. A slot listed during a frame its window records is written at once. A slot past the heap's image slots, an empty ImageSlot's 0xFFFF among them, is refused. Freeing a slot unlists it, as does initialising the heap in either binding model. WriteImageSet, the one use of which this replaces, is gone, and with it the per-frame dimension of setImageViews. Device - VK_KHR_surface_maintenance1 (or EXT) and VK_KHR_get_surface_capabilities2 are enabled where the loader has them (surfaceMaintenance1Supported, vkGetPhysicalDeviceSurfaceCapabilities2KHR), and the matching swapchain_maintenance1 with its feature where the device has it (swapchainMaintenance1Supported). - DistinctGpus groups the physical devices by GPU as CRAFTER_GRAPHICS_DEVICE numbers them, for ChooseGpu and tests. UI - UIRenderer lists its output slot instead of writing every copy itself, and again on every resize; the resize listener is gone on both backends. The headers' frameIdx is currentFrame. Examples - VulkanTriangle, Sponza, SponzaBench and RTVolume list their output slot and write only the per-frame TLASes. They wrote imageViews[f] into copy f once, which a resize left pointing at destroyed images. Tests - SwapchainImageCount: SwapchainMinImageCount on the numbers drivers report; every offered mode keeps its mode and gets what the window asks for; every frame presents the colour it drew, read back a texel per frame; a switch and a resize asked for during a frame wait for its present; a slot listed during a frame holds its image at once; two windows on one heap draw their own colours. The frame checks run again in child processes, through CRAFTER_GRAPHICS_DEVICE, on a GPU whose swapchains have more images than frames (this one, else llvmpipe), in each binding model the parent didn't cover; a child skips only for a GPU that can't run the library, and checks it runs the model it was asked for. - FrameLoopSync checks the frame slot follows the frame counter and counts the swapchain's own images. HeapASRead, HeapDynamicIndexHit and RTPassPushData list their swapchain slot and drop their resize rewrites. Docs - README, AGENTS.md and AGENTS.consumer.md: frames and images, the swapchain slots, rebuilds held to the present, the new optional groups. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
111 lines
5.6 KiB
Markdown
111 lines
5.6 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
|
||
per-frame TLAS device addresses, and `AddSwapchainSlot` for the output
|
||
image, which the window writes with the swapchain image each frame
|
||
draws into.
|
||
- `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.
|