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>
The window's record of the composing text it was last told (TextStrings().shown)
was cleared only by the compositor's leave. An app that disables and enables
the text input to reset the input method — after it committed the composing
word itself — then never heard of a later composition equal to that word: the
done handler reports a preedit only when it differs from the record. The
disable path clears the record and the pending flags now, as the leave does,
so the first composition after an enable is reported whatever it is.
DescriptorHeapVulkan
- The buffer region started at images * imageDescriptorSize /
bufferDescriptorSize, rounded down. A descriptor_heap array indexes
the heap from byte 0 in strides of its descriptor size, so buffer slot
0 has to sit on a whole buffer descriptor past the images. Where the
image descriptors were not a whole number of buffer descriptors, the
first buffer descriptors overwrote the last image descriptors. Where
they were less than one, the start was bumped to descriptor 1, but the
heap was still sized as if the buffers began right after the images,
so the last buffer descriptors went into the implementation's reserved
range. Every descriptor size is a power of two, so both cases need
image descriptors smaller than buffer descriptors, which NVIDIA (32
and 16 bytes) and llvmpipe (64 and 16) do not have. The start now
rounds up and the heap is sized from it (#163).
- The reserved range sat at a multiple of imageDescriptorAlignment only,
where vkCmdBindResourceHeapEXT also wants bufferDescriptorAlignment
(VUID-vkCmdBindResourceHeapEXT-pBindInfo-11435 and -11436). It now
starts on a multiple of the larger. The buffer descriptors need no more
than the rounding: each alignment is at most its descriptor size, so a
whole number of descriptors is aligned.
- bufferStartElement is 16 bits and took the division unchecked, so an
image region past 65535 buffer descriptors (16384 images on llvmpipe)
wrapped the buffer region around onto the images. Slot counts whose
buffer indices do not fit 16 bits, 0xFFFF being the empty slot, now
throw, naming the counts. A heap without buffer slots has no buffer
region, which starts at 0 as in descriptor-set mode, so image-only
heaps have no index to fit.
- On a driver that reserves nothing (llvmpipe), a heap without sampler
slots was a zero-size buffer, which every Initialize(1, 1, 0) made,
and Window::Render bound its address each frame. Each heap now holds at
least one descriptor, as each binding does in descriptor-set mode. That
grows NVIDIA's sampler heap by one descriptor when no sampler slots are
asked for; the resource heaps of the slot counts in the tree keep their
layouts byte for byte.
- ComputeLayout holds the arithmetic, pure over the descriptor-heap
properties, and Initialize goes through it. GetBufferOffset and
GetBufferOffsetElement, which had their own copies of the old
arithmetic and never had a caller, are gone.
- Bind(cmd, frame) binds a frame's heaps with the reserved ranges
Initialize stored, or in descriptor-set mode the frame's descriptor
set. Window::Render and the RTVolume example worked the reserved-range
offset out from the heap's size with the image-alignment mask, and
call Bind now. The window's per-heap cache of bind structs goes with
it: keyed on the heap pointer, it kept binding the old buffers after a
re-Initialize that reallocated them. The heap still ends with its
reserved range, so code that derives the offset from the size keeps
getting the right one.
Tests
- DescriptorHeapLayout: the issue's two layouts, the reserved range where
buffer descriptors are aligned more strictly than image ones, every
legal combination of descriptor sizes and alignments up to 256 bytes,
no heap empty, the NVIDIA and llvmpipe layouts, the 16-bit limit and
image-only heaps. Pure CPU, no device. Against the old arithmetic it
fails 12 of its 18 checks.
Docs
- README.md's heap bullet and AGENTS.consumer.md say how to bind the
heap outside the frame loop, and the consumer notes that Initialize
throws when buffer indices would pass 16 bits. AGENTS.md lists
ComputeLayout among the functions the pure-logic tests drive.
Closes#163.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Window
- The constructor made a fractional scale, a toplevel decoration and a
viewport from Device::fractionalScaleManager, Device::manager and
Device::wpViewporter without looking at them. Device::handle_global
binds those globals only when the compositor advertises them, and
Initialize requires only wl_shm, wl_compositor and xdg_wm_base, so on a
compositor without one of the three (GNOME's Mutter has no
xdg-decoration) the constructor handed libwayland a null proxy and
crashed before the window existed (#162). Each object is now made only
when its global is there, which Resize and the destructor already
assumed.
- The fractional scale needs the viewporter too: the preferred scale is
applied through the viewport, which shows the buffer's physical pixels at
width/scale x height/scale. A surface without a viewport is as large as
its buffer, so there the scale stays 1, which keeps pointer and touch
positions, configure sizes and the text-input caret, all converted by
it, in physical pixels; the compositor scales the window up on a HiDPI
output. A scale that changes after the constructor is still applied only
by the next resize, which is #165.
- Without xdg-decoration the window has no title bar, since the library
draws no client-side decorations.
Device
- The optional globals say they are optional, and that a request on a
null proxy crashes.
Tests
- WindowOptionalGlobals: hides xdg-decoration, wp_viewporter and
wp_fractional_scale_v1 from the Window one at a time and all at once,
by nulling the Device statics after Initialize, and renders, resizes
and closes a window each time without a protocol error. Before the fix
it crashed on the window without xdg-decoration. A global the compositor
does not offer is reported as a SKIP line, since the path that uses it
goes untested there.
README
- Which Wayland protocols the window needs, and what it does without the
optional ones.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
Win32
- WM_MOUSEMOVE is handled again: c9ebd44 put the WM_CHAR case where it
was, so currentMousePos stopped following the mouse and onMouseMove
never fired. Positions are read signed (GET_X_LPARAM), since under
capture they run past the client area.
- onMouseEnter and onMouseLeave. The first move over the client area
after a leave is the enter, and arms the TME_LEAVE whose WM_MOUSELEAVE
is the leave. An enter counts only once that is armed, a leave only
after an enter, and a move past the client area is a move only.
- A press captures the mouse, so a drag that leaves the window still
sends its moves and its release, as Wayland's implicit grab does.
Losing the capture releases what is held, and a button-up without its
press fires nothing.
- WM_CLOSE fires onClose and clears open, as xdg_toplevel.close does,
instead of destroying the HWND under the swapchain. WM_DESTROY no
longer posts WM_QUIT, which nothing read.
- ~Window detaches the HWND and destroys it. It stayed on screen, and its
messages went to the freed Window. WndProc hands messages without a
Window to DefWindowProc, and looks the Window up again after an event
that more work follows, in case a listener destroyed it.
- The constructor's message pump leaves input queued for StartSync: the
WM_MOUSEMOVE sent when a window appears under the cursor made an
onMouseEnter nobody could hear yet. The mouse state is reset before
the platform code, no longer after it.
- A window after the first finds its class registered, which showed an
error box.
- The wheel remainder is the window's, no longer a function static that
every window shared, and a leave drops it.
Window
- PointerEnter, PointerMove, PointerLeave and PointerScroll hold the rules
both native backends report the pointer by. An enter puts the entry
position in currentMousePos before onMouseEnter fires, and is followed
by a move, on Wayland too now. scrollRemainder replaces
Device::scrollDetentRemainder, and mouseInside is shared.
Tests
- PointerEnterLeave: enter, move and leave through the wl_pointer
callbacks.
- PointerWin32: posts a real HWND the messages above and pumps them as
StartSync does. Built for x86_64-w64-mingw32 it runs under Wine, and is
skipped where Wine is not on PATH.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
BuildTLAS
- A rebuild for a new instance count or build preference used to create a
new acceleration structure and destroy the old one at once, though the
command buffer being recorded could still use it (a scene and then a
model built in one setup). The acceleration structure now spans its whole
storage buffer, and a rebuild that fits builds into it again, so the
handle and tlases[i].address stay the same and nothing is destroyed. A
TLAS that outgrows its storage gets new storage and a new handle; the old
handle goes to the deletion queue ahead of the storage it lives in. It is
queued after the scratch is resized, and its address goes with it, so a
Resize or create that throws leaves no address of a queued acceleration
structure behind.
- The barrier before the build also orders earlier traces and compute ray
queries of the TLAS, which a refit or a rebuild in place would otherwise
overwrite while they read it (BuildTlasWriteBarrier). Its source access
mask holds no read bit: one does nothing, but makes synchronization
validation 1.4.363 report the second of two builds in one command buffer
as a write-after-write hazard.
- TlasReadBarrier is now TlasBarrier, shared by both barriers.
- Documented: call BuildTLAS once every earlier submission that used
tlases[index] has completed, and when the address stays the same.
TlasWithBuffer
- Moves hand the acceleration structure over, and destroying or assigning
over one queues it ahead of its storage. The implicit members dropped the
handle over freed storage, or left two owners and a moved-from TLAS that
refit through buffers it no longer had.
Tests
- TLASLifetime: destroying, moving, move-assigning and resetting a
TlasWithBuffer.
- TLASHighWaterMark skips without ray tracing. It asserts the acceleration
structure is rebuilt in place on a shrink or a growth within capacity,
that the old handle is queued before its storage on a growth past it, and
that builds in one command buffer keep the handle while they fit, queue
it once when one outgrows the storage, and free it only on its retire
frame.
- TLASBuildBarrier checks the barrier before the build too.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Window
- updateInterval runs Update on the window's own clock while the
compositor sends no frame callbacks (hidden, minimized): the Wayland loop
is a poll() loop, and the Win32 loop sleeps until the next update. Both
read the interval each pass.
- SetPresentMode (FIFO, Mailbox, Immediate). A mode the surface lacks, or
whose swapchain has other than numFrames images (Mesa's Mailbox has four),
falls back to FIFO until the mode is set again.
- AddPollFd / RemovePollFd wake the Wayland loop on the app's descriptors.
- The swapchain has TRANSFER_DST where the surface allows it.
- CaptureNextFrame replaces SaveFrame: it records the copy in the frame,
before the present, where SaveFrame read an image already presented. A
frame unwound past before the write still frees the readback buffer.
- Inter-pass barriers on the swapchain image carry the access masks of the
stages the passes use.
Deferred deletion (issue #101)
- VulkanBuffer, Mesh, VulkanShader, ComputeShader and PipelineRTVulkan hand
their handles to the deletion queue from their destructors and moves, as
a frame in flight may still use them; a static owner goes after the
driver has torn down. VulkanShader and PipelineRTVulkan move and can't be
copied; re-Load and re-Init queue the old pipeline.
- The queue and its mutex are never destroyed, and the queue takes handles
from any thread; Device::frameCounter is atomic. Both the queue and the
staging rings count frames as one window renders them (documented).
- DrainDeletions also lets every buffer's staging ring start over: without
a Window nothing else reclaims either, so an app without one calls it
after waiting for its work.
Meshes and buffers
- A Mesh rebuild queues the old acceleration structure and builds into the
same storage after a barrier, so the BLAS address stays put when it fits.
The refit and rebuild barriers cover compute ray queries too.
- RTBuildOptions::noDuplicateAnyHit. Mesh::geometryFlags replaces opaque,
and the refit and rebuild fallbacks keep the flags.
- A re-upload into a buffer a frame in flight may read (UploadDeviceLocal
of the same size, UploadDeviceLocalRange) copies on the GPU, after those
reads, through a per-frame staging ring; on ReBAR it used to write the
buffer in place. Empty uploads record nothing.
- A compressed Mesh::Build that keeps its buffers decompresses into them
after the reads of frames in flight, and the hit shaders and ray queries
wait for the decompress as well as the BLAS build. Its vertex buffer
takes a ranged refit's copies.
- Mesh move-assigns (queueing the BLAS it replaces), so it can be replaced
in place or erased from a vector.
- VulkanBuffer::Create asks for a device address only for buffers with
SHADER_DEVICE_ADDRESS usage, as vkGetBufferDeviceAddress requires; the
others have address 0. UIRenderer::RegisterBuffer refuses those.
- Build inputs are synchronized as shader reads.
Other
- RTPass pushes the app's own push data and traces at an explicit size.
- DescriptorHeapVulkan hands freed slot ranges out again (they leaked), and
keeps its free lists sorted.
- ImageVulkan's mip chain clamps each level to 1 texel: a non-square
image's shorter side went to 0.
- VulkanShader throws on a missing file instead of failing in bad_alloc.
- CRAFTER_GRAPHICS_DEVICE picks the GPU by its number among the distinct
GPUs Vulkan lists; anything but such a number is an error.
- The debug messenger prints info messages only with
CRAFTER_GRAPHICS_VALIDATION set.
- Windows: the WinRT gamepad code moved to a C file (mingw-w64's WinRT
headers don't compile as C++), -lcombase dropped, a reference leak fixed.
- project.cpp honours --local for Crafter.Event, Math and Asset, as Asset
does for Math, and builds every test through one helper, projectArgs
included.
- Tests: DebugMessengerSeverity, DeletionQueueThreads, DeviceSelection,
HeapSlotReuse, MeshLifetime, MipChainNonSquare, PipelineLifetime,
RTPassPushData, SwapchainTransferDst, UploadInFlight, VulkanBufferAddress,
VulkanShaderLifetime, WindowUpdateClock; others extended.
Breaking: SaveFrame is CaptureNextFrame; Mesh::opaque is geometryFlags; a
buffer without SHADER_DEVICE_ADDRESS usage has no address; frameCounter is
std::atomic.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The SPIR-V rewrite for NVIDIA's descriptor-heap acceleration-structure
read fault (#7, #15) was keyed on the driver ID alone, so nothing could
check whether a newer driver still needs it. With
CRAFTER_GRAPHICS_NO_AS_WORKAROUND set, to any value like the other
CRAFTER_GRAPHICS_* switches, Device leaves it off. On 615.78.08 it is
still needed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The TLAS instance and metadata buffers were sized to the instance
count, so building before anything was in the scene created zero-size
buffers. That is invalid usage: NVIDIA fails the allocation with
VK_ERROR_OUT_OF_DEVICE_MEMORY and BuildTLAS threw, leaving the TLAS with
a buffer handle that has no memory behind it.
Both buffers now get at least one slot, and the scratch buffer at least
one byte, since an empty TLAS may report no scratch at all. An empty
TLAS is valid to trace against; every ray misses.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
BuildTLAS ended with an execution-only barrier from the
acceleration-structure build to the ray-tracing and compute shader
stages. That orders the commands, but without a memory barrier the
build's writes are never made available and visible to the traceRayEXT
and rayQueryEXT reads recorded after it in the same command buffer,
which is the documented per-frame flow (BuildTLAS in onUpdate, then
RTPass): the trace may read a stale or half-written BVH.
The barrier now carries ACCELERATION_STRUCTURE_WRITE ->
ACCELERATION_STRUCTURE_READ. BuildTlasReadBarrier builds it as pure CPU
logic, so a test can check it without a GPU, as with the swapchain
barriers.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
~FontAtlas destroyed the image while frames that sample it could still
run (HelloUI declares the atlas after the window, so it goes first); it
waits on the queue now, as the descriptor heap does. The DOM build got
the two new Window methods as no-ops, like the other backend-specific
ones.
enable resets the input method's state, so sending it with every caret
move (an application keeps the cursor rectangle current while typing)
dropped the composition at each keystroke: enable now goes once per
focus and a moved caret sends its rectangle alone; disable only takes
back an enable. The compositor's leave ends both, and a window still
showing composing text hears onPreedit("") then. A finger's up and motion
go to the window it went down on, not the window of the latest down. The
seat creates its pointer and keyboard once, as it already did the touch:
capabilities come again when a device appears or goes, and a second
keyboard proxy delivered every key twice.
wl_surface_frame_done re-armed the frame callback through its local and
left the member stale, so the destructor could not cancel it and a done
already queued would dispatch into the freed window; the member now
names the live callback and the destructor destroys it. The destructor
also flushed a null display for a window created without
Device::Initialize (tests do that) and freed never-created command
buffers (a default-constructed Window after Initialize); both guarded.
And wp_scale was one inline static for every window, which the destructor
destroyed on behalf of all of them: it is a member now, like the viewport.
With the touch positions in an inline static std::unordered_map and the
text input's strings in inline static std::strings, clang 23.1 crashed
compiling Device.cpp for aarch64-alpine-linux-musl against that sysroot's
libc++ 22 — in LazyCallGraph at -O3, in the ThinLTO bitcode writer at -O0
(a dangling global); the native build was fine. The fingers now live in a
constant-initialised array of slots and the strings in function-local
statics of the implementation unit; nothing else changes.
A window can now say that a text field has the focus and where its caret
is — Window::SetTextInput(active, caret rectangle in physical pixels,
purpose) — which is what opens the on-screen keyboard on a phone (Maliit
under KWin, squeekboard under phoc). What the input method produces comes
back as events: committed text as onTextInput, the composing text as
onPreedit (empty clears it), deletions around the cursor as
onTextInputDelete; done() applies them in the protocol's order. The state
a window wants is remembered and sent again whenever the keyboard focus
returns to it. The protocol's client code is generated with wayland-scanner
1.26.0 from wayland-protocols' text-input-unstable-v3.xml, under lib/ like
the others.
The seat's wl_touch was never bound, so a touchscreen could not drive a
window at all. Every finger is now reported through onTouchDown, onTouchMove,
onTouchUp and onTouchCancel (TouchPoint: the compositor's id and the
position in physical pixels). The first finger down also enters the window —
Device::focusedWindow and the pointer serial the clipboard needs — presses
the left button, moves it and releases it when it lifts, so an application
written for a pointer works on a phone as it is.
ComputeShader::Load built a VulkanShader on the stack and let it go with
its VkShaderModule still alive: nothing in the library destroys one. A
process that loads the UI shaders once never noticed; one that creates a
window again and again (an app that hides and re-shows its window) leaked
five modules per window. Vulkan allows destroying the module as soon as the
pipeline is created, so Load does, on success and on failure alike.
A Window could be created but never destroyed: the constructor's command
buffers, semaphores, fences, swapchain and Vulkan surface, and on Wayland
the viewport, fractional scale, decoration, xdg toplevel, xdg surface and
wl_surface stayed alive, and Device::windows kept a dangling pointer the
pointer listeners still compared against. An app that hides its window
and shows it again — a resident messaging app closing to a notification
— needs the window to go for real.
The destructor waits for the device, frees and destroys the Vulkan objects
in dependency order (the swapchain before the surface), releases the
Wayland objects from the cursor down to the wl_surface, flushes, and
removes the window from Device::windows and the focus pointers. The
decoration object the constructor used to leak is a member now. The frame
callback member is left alone: wl_surface_frame_done destroys the callback
it is handed and re-arms through its own local, so the member may name a
freed one.
keyboard_enter and keyboard_leave were empty and keyboard_key dereferenced
Device::focusedWindow, which only a pointer-enter sets: the first key
event in a window the pointer never entered — every key on a touch phone,
or a key typed while the pointer hovers another window — dereferenced a
null pointer, and keys typed after the pointer left went nowhere.
Keyboard focus is its own thing in Wayland. wl_keyboard.enter now resolves
its surface to the Window into Device::keyboardWindow, leave clears it
together with the held keys (their releases happen elsewhere) and stops
the repeat, and keyboard_key and TickKeyRepeats deliver to that window and
drop a key that has none.
Device::Initialize required twelve device extensions with no capability
check. Mesa Turnip (Adreno) lacks six of them: VK_EXT_descriptor_heap,
VK_KHR_shader_untyped_pointers, VK_EXT_device_fault and the three ray
tracing extensions. vkCreateDevice failed there, so not even a UI-only
program could start, although the UI path is compute-only and needs
nothing else that Turnip is missing.
The descriptor heap, ray tracing and device fault are now optional
groups, detected at start-up from the extension list and the feature
bits (Device::descriptorHeapSupported, rayTracingSupported,
deviceFaultSupported). Ray tracing needs the heap; on a device without
it the ray tracing entry points throw a message naming the cause.
Without the heap the same bindless slots live in one update-after-bind
descriptor set per frame, owned by DescriptorHeapVulkan: binding 0
storage images, 1 sampled images, 2 samplers, 3 storage buffers. Slot
allocation, the slot handles, UIDispatchHeader and the UIRenderer API
are unchanged; buffer slots simply stop being offset. Window::Render
binds that frame's set where it binds the heap, every compute pipeline
shares the heap object's pipeline layout, and push data travels as push
constants.
Each UI kernel is built twice from one source. ui-shared.glsl declares
its resources through UI_HEAP_* macros that expand to descriptor_heap
or, with CRAFTER_GRAPHICS_DESCRIPTOR_SETS defined, to set/binding.
<name>.comp.spv and <name>.comp.sets.spv ship side by side and
ComputeShader::Load picks one. The heap build of every shader is
byte-identical to before.
Breaking:
- ComputeShader::Load takes the heap as a second argument.
- DescriptorHeapVulkan is no longer copyable or movable.
- Custom UI shaders declare heap resources with the UI_HEAP_* macros
and are registered twice in project.cpp (see the README).
- project.cpp uses Shader::defines and Shader::variant, so it needs a
crafter-build that has them (Crafter.Build master, fe38cc1 or later).
Also:
- maintenance5 is enabled as a feature, not only as an extension:
every VulkanBuffer already relied on VkBufferUsageFlags2CreateInfo.
- Barrier stage masks drop RAY_TRACING_SHADER on devices without ray
tracing, and ImageVulkan::Create resolves its default consumer stage
to COMPUTE_SHADER there.
- Window refuses a swapchain whose image count is not numFrames
instead of writing past images[]. The limitation itself is #160.
- CRAFTER_GRAPHICS_NO_DESCRIPTOR_HEAP forces the fallback on a driver
that has the heap, so it can be exercised on a desktop GPU.
Verified on an RTX 4090 in both modes under the validation layer, and
on a Fairphone 6 (Turnip, Adreno 810, postmarketOS), where the fallback
is the only path.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
CRAFTER_PRESENT_IMMEDIATE selects IMMEDIATE (then MAILBOX) when the
surface offers it, instead of the default FIFO. Needed to measure
steady-state frame throughput without the compositor's vblank cap; FIFO
remains the default when the variable is unset.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Two distinct validation errors the native frame loop emitted, both
originating in Crafter.Graphics with no consumer-side influence.
Problem 1 — per-frame acquire-barrier access/stage mismatch. The
acquire->GENERAL barrier hardcoded dstAccessMask =
SHADER_WRITE|TRANSFER_WRITE but used the per-pass stage union as its dst
stage mask. For an all-compute frame the union narrows to COMPUTE_SHADER,
which does not support TRANSFER_WRITE, so VUID-02820 fired every frame.
Derive the access mask from the same stage union via a new
SwapchainWriterAccess() helper (mirroring SwapchainStageUnion), and apply
it to both the acquire dst and present src masks for symmetry.
Problem 2 — mid-session StartInit/FinishInit (and GetCmd/EndCmd) reuse the
shared drawCmdBuffers[currentBuffer]. With no steady-state wait-idle the
loop's last submission of that buffer may still be in flight when scene
setup runs (building map meshes / acceleration structures), so the old
code re-began (VUID-00049) and re-submitted (VUID-00071) a pending buffer,
and resources freed in the StartInit..FinishInit bracket could still be
referenced by it. Drain the queue at the start of StartInit/GetCmd before
re-recording; setup is rare, so a wait-idle is fine (FinishInit/EndCmd
already wait-idle at the end).
Tests: extend SwapchainBarrierScope with SwapchainWriterAccess coverage
(pure CPU), and add SetupCmdBufferReuse — a real-frame-loop regression
test driving a compute pass plus interleaved mid-session StartInit rounds,
asserting the validation layer stays silent. Verified both halves fail
(reproducing the exact VUIDs) when their respective fix is reverted.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
When `updating` is false (paused / minimized / stopped), the FIFO
present no longer paces StartSync()'s message loop, so the bare
PeekMessage(PM_REMOVE) spin pinned a core at 100% while uselessly
re-running Gamepad::Tick() (mutex + per-pad COM reads) and
onBeforeUpdate every iteration.
Block on MsgWaitForMultipleObjectsEx with a short timeout while
!updating: the loop now wakes on input or every ~16ms, eliminating the
busy-spin while preserving gamepad polling / onBeforeUpdate at a sane
rate (e.g. to detect a controller button asking to resume). The
updating path is unchanged — present remains vsync-gated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
BuildTLASUpload pushed GPU-driven (transformOwnedByGpu) runs one element
at a time — a separate FlushDeviceRange of the 16 strided metadata bytes
per element — each paying WebGPU validation / encode / JS-boundary cost,
while the CPU-driven arm already batched contiguously.
Upload the whole active instance range in a single writeBuffer instead.
Pushing the (stale) transform bytes for GPU-driven slots is harmless: the
only supported way to drive a transform from the GPU is the manual
Upload -> physics compute pass -> Build sequence, and that compute pass
runs after this upload and rewrites the transform on the GPU before the
TLAS build reads it. For the in-repo (all-CPU) usage the bytes uploaded
are identical to before — with one CPU-driven run the old loop already
emitted exactly this single FlushDeviceRange(0, 0, primitiveCount*64).
Verified: native suite (24 passed) and the RTStress wasm example (512
ray-traced instances) render correctly through the new path.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The metadata mirror is padded to kNPadded (65536) but only primitiveCount
slots are live. metadataBuffer.FlushDevice() wgpuWriteBuffer'd all 256 KB
through the WASM->JS staging path every frame (~100-250x waste for a
few-hundred-instance scene). Switch to the existing FlushDeviceRange
overload — the same one the instanceBuffer loop directly above uses —
sized to primitiveCount * sizeof(uint32_t). The Vulkan parallel already
sizes its flush to primitiveCount, so this was WebGPU-specific.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
UIRenderer::Dispatch built a fresh std::vector<uint32_t> with reserve on
every call, paying one malloc+free per dispatch. Custom compute dispatches
run per-frame, so make the vector thread_local and clear() it each call:
capacity grows to the high-water mark once and is reused thereafter,
eliminating the per-frame allocation churn. Behavior is identical.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
FontAtlas::Update used a single union bounding box for the dirty rect.
Scattered new glyphs landing on different shelves produced a tall union
box that re-uploaded mostly-unchanged texels between the shelves.
Track a dirty span per shelf instead and issue one tight UpdateRegion /
wgpuWriteAtlasRegion copy per armed span. A shelf packs glyphs
left-to-right at a fixed top, so each span stays a contiguous X run
capped by the shelf height. The whole-atlas zero-clear in Initialize
keeps using the existing dirtyRect span. `dirty` is now the OR of every
span and is cleared together with them in Update.
Verified: full test suite green (23 passed); HelloUI text renders
crisply on the WebGPU backend through the new multi-span upload path.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
DrawInputField re-measured the cursor prefix via Font::GetLineWidth on
every frame of a focused field, even though only the blink (caretVisible)
changes frame-to-frame — value, cursorPos and fontSize are stable across
the vast majority of frames.
Cache the measured prefix WIDTH on the InputField, keyed on (prefix bytes,
fontSize). A cheap byte compare of the cached prefix guards the expensive
per-glyph UTF-8 decode + advance accumulation. The cache is mutable so the
const-ref draw fn can refresh it.
The absolute caretX is deliberately NOT cached: it adds the layout-
dependent textX (rect.x + paddingX) each frame, so caching it would give a
relocated field a stale caret. Caching the width keeps that correct.
Adds tests/InputFieldCaretCache pinning: the cached caret matches the
uncached GetLineWidth oracle across states, a redraw (cache hit) is
identical to the miss, the cache invalidates on value/cursorPos/fontSize
changes, the blink never moves the caret, and a relocated field shifts the
caret by exactly the rect delta.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
At kMaxShapedRuns (8192) UIRenderer::ShapeText did a full shapedRuns_.clear().
A stream of unique strings (FPS counters, timers) alongside many stable labels
periodically nuked every stable entry, forcing a full-UI reshape the next frame.
Track recency with an auxiliary std::list<const ShapedRunKey*> (front = most
recently used) holding pointers to the keys owned by the node-based map. A hit
splices its entry to the front; an overflow pops the least-recently-used entry
from the back and erases just that one — both O(1). The hot set of labels,
reshaped every frame, stays at the front and survives, so the churn of unique
strings only recycles the cold tail. Output is byte-identical either way.
InvalidateFont now drops matching entries from both the map and the LRU list.
Adds ShapedRunCacheSize()/IsShapedRunCached() introspection hooks (the policy
isn't observable through output or atlas.dirty) and a ShapeTextCache test that
asserts the cache plateaus at a fixed cap (evict-one, not clear-all), the hot
label survives a churn past the cap, and an untouched cold string is evicted.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ShapeText built ShapedRunKey{..., std::string(utf8)} before find()
unconditionally — even on cache hits, on the per-frame onBuild path.
N labels meant N string copies + hashes (+ frees for non-SSO strings)
every frame, partially defeating the run cache.
Add is_transparent hash + equality functors on shapedRuns_ and probe
with a borrowing ShapedRunViewKey {const Font*, float, array<float,4>,
string_view}. The owning std::string is now materialised only on a
miss, for emplace. Cache hits copy and hash no string.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
BuildTLAS rebuilt the host instance+metadata buffers with an O(n) copy of
every 64 B VkAccelerationStructureInstanceKHR + metadata entry every frame,
unconditionally, then flushed the whole high-water capacity (VK_WHOLE_SIZE)
on both buffers. At the millions-of-instances target that copy dominates the
CPU frame, and the whole-buffer flush costs on non-coherent BAR/VRAM.
Add a generation counter so only changed host-authored fields are copied, and
feed the same dirty span into the ranged FlushDevice(offset, bytes) overload:
- RenderingElement3D::hostDataVersion + MarkHostDataDirty() (bumps a global
monotonic counter). TlasWithBuffer::uploadedVersion records, per frame, the
version last copied into each slot. A slot is copied only when its element
advanced past the recorded version; version 0 ("untracked") reads dirty every
frame, so callers that don't opt in keep the prior copy-every-frame behaviour.
Globally-unique versions make this correct under relocation (Remove's
swap-and-pop, and remove+add that nets the same count on the refit path)
without tracking element identity. The reset on every topology change covers
buffer reallocation and the reshuffled element->slot mapping.
- The dirty [first, last] envelope drives both the copy and the flush: a new
VulkanBuffer::FlushDevice(cmd, access, stage, offset, bytes) overload flushes
+ barriers just that span for instanceBuffer, and the ranged
FlushDevice(offset, bytes) for metadataBuffer. When nothing is dirty both are
skipped — the skipped HOST->build barrier only ever ordered host writes, never
the application's compute-written GPU-owned transform (that compute->build
ordering is the caller's, and is unchanged).
Constraint honoured: transformOwnedByGpu transforms are still never host-copied.
The API field/method are mirrored on the WebGPU class for source portability
(the WebGPU build re-uploads its small mirror wholesale and ignores the version).
New test TLASInstanceDirtyTracking drives the real RT device and reads back the
host-mapped buffers to assert: tracked elements upload once then skip until
re-marked, untracked elements always upload, and relocation on the refit path
re-uploads exactly the moved slots — with zero validation-layer errors over the
ranged flush.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Mesh::Refit re-uploaded the entire vertex array every frame on the
in-place UPDATE path (full host write + flush + barrier on the direct
path; full re-stage + copy on the staged path), even when only a handful
of vertices moved.
Add VulkanBuffer::UploadDeviceLocalRange — a dirty-range counterpart to
UploadDeviceLocal that writes/flushes/stages/copies and barriers only the
half-open element range [offset, offset+count) of an already-allocated
device-local buffer. It picks direct-map vs staged-copy from the memory
type the buffer was actually allocated with (not the sub-range size, which
PreferDirectDeviceWrite would mis-route), and the direct path's ranged
flush is rounded to nonCoherentAtomSize and clamped to the allocation size
(mappedSize is now recorded for every buffer, not just mapped ones).
Add a dirty-range Refit overload taking the full vertex/index arrays plus
a (dirtyVertexOffset, dirtyVertexCount) window. The full-span Refit now
delegates to it with the whole array as the window. On the in-place UPDATE
path only the declared window is uploaded — the rest of the device buffer
retains last refit's positions; when an UPDATE isn't possible it falls
back to the full-span rebuild, which is why the full arrays are still
passed. The WebGPU/DOM backend keeps API symmetry: it has no hardware AS,
so it ignores the window and rebuilds the host BVH from the full geometry.
BLASBuildOptions exercises the dirty-range refit on the direct path, the
staged path, and the count-change rebuild fallback, asserting AS-handle /
blasAddr stability and zero Vulkan validation errors.
Resolves#119
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The inter-pass and acquire/present barriers in the frame loop set both
stage masks to ALL_COMMANDS, and the inter-pass dependency used a
queue-wide VkMemoryBarrier — fully serialising against every pipeline
stage and flushing all caches every frame, when all the next pass needs
is the swapchain image the previous one wrote.
Replace the inter-pass global VkMemoryBarrier with an image memory
barrier scoped to the swapchain image's single colour subresource (as
the intra-pass UI barrier already does), and derive the barrier stage
masks per pass: RenderPass::SwapchainStage() is overridden by UIRenderer
(COMPUTE_SHADER) and RTPass (RAY_TRACING_SHADER), so a compute->compute
edge only serialises COMPUTE while an RT pass pulls in RAY_TRACING — the
acquire/present frame-edge masks use the real union of the frame's
passes (SwapchainStageUnion). The base default and the empty-passes
fallback are the conservative COMPUTE | RAY_TRACING | TRANSFER union, so
a polymorphic or un-overridden pass can only be over- not
under-synchronised.
Adds SwapchainBarrierScope (pure CPU) pinning the per-pass derivation,
the union narrowing, and the inter-pass barrier scope; FrameLoopSync
already drives the real GPU frame loop with validation enabled.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ImageVulkan kept its host-visible staging `buffer` (sized w*h, persistently
mapped) alive for the whole life of the image and Destroy() never freed it, so
static textures (e.g. Sponza albedo) pinned HOST_VISIBLE / small-BAR memory
forever.
Update now releases the staging via VulkanBuffer::DeferredClear() right after
recording the buffer→image copy — the same fence-keyed deletion queue
(#101/#102) the compressed Mesh path already uses — so it is freed once the
upload submit's frame has cleared. A new `streamed` flag (set by FontAtlas)
keeps the persistent map for images re-uploaded from a CPU-side staging buffer
every frame; its uploads go through UpdateRegion, which never releases. Destroy
now also frees any staging the image still owns, gated on a live handle so a
released static texture can't double-free.
Adds tests/ImageStagingRelease driving the real upload + readback on a headless
device: asserts the staging is enqueued (not pinned), the image reads back
byte-equal (released staging outlived the submit), the entry retires only after
framesInFlight frames, and a streamed image keeps then frees its staging.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ReclaimDeletions ran an O(n) walk + survivor compaction over the whole
deletion queue every frame. frameCounter is monotonic, so retireAfter is
non-decreasing down the queue and the entries ready to reclaim are always
a contiguous prefix. Switch deletionQueue from std::vector to std::deque
and pop the ready prefix off the front, stopping at the first entry still
in flight — O(ready) instead of O(queue).
Resolves#116
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
