Both landed on master while the guide was being written: ExampleShaders
compiles every example shader with glslang and needs no GPU,
WindowOptionalGlobals needs a compositor. The test section names the
tests in each group, so it names these two as well.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
AGENTS.md
- Guidance for agents and contributors working on Crafter.Graphics: the
layout and the partitions by backend, the dev environment and the
targets, the build and test commands, how tests are declared and what
each group needs, code style, the design rules the code embodies,
commit conventions, security notes and gotchas. It carries the
dependency-notes section crafter-build 3.0.0 writes, holding
Crafter.Math's notes.
AGENTS.consumer.md
- What an agent working in a consumer needs: depending on the library,
the program shape and the frame order, device features, lifetimes, the
heap and its descriptor-set fallback, buffers and images, the UI tiers,
custom compute shaders, ray tracing, input, the DOM build, the
environment variables, testing a consumer, and which example to copy.
crafter-build injects it into consumers' AGENTS.md on their builds.
Both were reviewed against the code. The review found that --timing no
longer compiles (#178), which both files note.
Co-Authored-By: Claude Fable 5.1 <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>
examples/Sponza no longer built natively (#164). Its closest-hit declared a
descriptor_heap sampler2D, which glslang has rejected since c8253623
("Reject descriptor_heap combined image samplers"), and main.cpp wrote it
through VkResourceDescriptorDataEXT::pCombinedImageSampler, which that union
no longer has: the descriptor heap has no combined image samplers. Both went
unnoticed because nothing builds the examples.
Sponza
- closesthit.glsl declares texture2D and sampler heap arrays and joins them
where it samples, as ui-shared.glsl and HeapDynamicIndexHit do. The
sampler slot is a second spec constant beside the image slot, so the
shader assumes nothing about where the host put it, and a constant index
keeps the example running on NVIDIA 610.43.02 (see its README). The
comment no longer says the image slot is offset by bufferStartElement;
only buffer slots are.
- main.cpp gives the heap a sampler slot, writes the albedo as a
SAMPLED_IMAGE from a view create-info, and writes the sampler into the
sampler heap from a VkSamplerCreateInfo with vkWriteSamplerDescriptorsEXT,
as UIRenderer::RegisterSampler does. SamplerVulkan's VkSampler had no use
left. The sampler keeps its linear filtering and repeat addressing and
drops anisotropy, which a hit shader cannot use: it samples at LOD 0,
without derivatives.
Docs
- README.md and examples/Sponza/README.md quote the new declarations, and
the Sponza README says why the texture and the sampler are two
descriptors. Its texture2DArray materials pattern declared a
descriptor_heap sampler2DArray, which glslang rejects as well; it now
joins a texture2DArray and a sampler.
- examples/SponzaBench/README.md drops its caveat that Sponza does not
compile.
Tests
- ExampleShaders compiles every GLSL shader under examples/ with glslang as
crafter-build does for the example (Vulkan rules, SPIR-V 1.4, shaders/ on
the include path, and the descriptor-set build where the example
registers one), so a glslang that starts rejecting one fails a test
rather than an example build nobody runs. It fails on Sponza's old
closest-hit and needs glslang only.
Closes#164.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Examples
- CustomShader did not build for wasm32-wasip1: its DOM branch still set
UICustomBinding::_pad, which 097cc37 (#27) turned into format. The
invalid designator left the bindings array of incomplete type, so the
Load call after it found no overload either. The designator is dropped
rather than renamed, as HDRBloom does: format is 0 for anything but a
StorageTexture binding, and a buffer binding has no texel format to
give. The native branch was never affected.
- Every other example with a DOM path (HelloUI, HelloDom, HDRBloom,
RayQueryPick, RTMultiShadow, RTStress, RTVolume, VulkanTriangle,
Sponza) builds for wasm at this commit. Nothing builds them
otherwise, which is how this one fell behind.
Closes#158.
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 heap acceleration-structure read still needs the rewrite on
615.78.08; the READMEs say so and point at HeapASRead --no-workaround
for checking a newer driver. Dynamic descriptor indexing in hit shaders
is fixed there, which the README and the Sponza and SponzaBench notes
now say, and the VulkanTriangle investigation no longer contradicts
itself about llvmpipe, which advertises VK_EXT_descriptor_heap now.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LoadImageItem, LoadGlpyhtem, LoadCircleItem and LoadQuadItem in
ui-shared.glsl worked around NVIDIA losing the device when a whole
struct is loaded from a descriptor-heap storage buffer. No kernel here
calls them any more (they read members straight into shared memory), and
NVIDIA 615.78.08 no longer has the fault: every UI kernel rewritten to
whole-struct loads renders the same frame. Shaders that called them read
the item directly instead.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On NVIDIA 610.43.02, selecting a descriptor-heap descriptor with a
runtime index in a hit shader lost the device, for storage buffers and
sampled images alike, which is why the examples use spec constants
there. HeapDynamicIndexHit renders two instances whose closest-hit picks
a buffer and a texture by a runtime index: one instance uses the same
set across every wave, the other a different set in every other pixel
column, so neighbouring lanes select different descriptors. It passes
on 615.78.08 and on llvmpipe.
On NVIDIA drivers older than 615.78.08 it skips rather than abort the
suite. With validation on it also renders in a child process with
validation off, since GPU-assisted validation hides the fault.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
HeapASRead renders a triangle, tracing half the frame with traceRayEXT
and ray querying the other half, both reading the TLAS out of the
descriptor heap, and checks the read-back pixels. The test runner runs
it through the engine's normal path, so on NVIDIA it covers the rewrite
too: an inherited CRAFTER_GRAPHICS_NO_AS_WORKAROUND is cleared, and the
test checks the rewrite is on exactly where the driver needs it.
HeapASRead --no-workaround is the check for a newer driver. Each path
renders in its own child process with the rewrite off and validation
off (GPU-assisted validation instruments the shaders), so a device loss
on one doesn't hide the other. On 615.78.08 traceRayEXT still loses the
device and the ray query renders nothing.
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>
TLASEmptyBuild builds frame 0's TLAS with no elements registered and
checks it is a real acceleration structure, then adds an instance and
removes it again, rebuilding each time. Before the fix the first build
threw on NVIDIA (VK_ERROR_OUT_OF_DEVICE_MEMORY).
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>
RenderingElement3D::tlases was a plain static array, so its buffers
were freed by its static destructor at process exit. The Vulkan driver
and layers are loaded during Device::Initialize, after the array was
constructed, so their own statics are torn down first, and destroying
the buffers then called into freed driver and layer state: every
ray-traced app run with CRAFTER_GRAPHICS_VALIDATION segfaulted on exit
inside the validation layer. TLASHighWaterMark and
TLASInstanceDirtyTracking worked around it by tearing frame 0's TLAS
down by hand before returning.
tlases now refers to an array that is never destroyed, the choice
Device already makes for the device itself, and exit reclaims the
memory. Indexing it is unchanged for callers. The hand teardown in the
two tests goes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TLASBuildBarrier drives BuildTlasReadBarrier with no GPU device: the
dependency starts at the acceleration-structure build, reaches the
ray-tracing and compute shader stages, and carries the
acceleration-structure write -> read memory dependency that the old
execution-only barrier lacked.
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>
The Linux gamepad backend included <libevdev/libevdev.h> from
/usr/include/libevdev-1.0 and linked the system libevdev, but the
Flatpak SDK crafter-build runs in (org.freedesktop.Sdk 26.08) ships no
libevdev headers, so Crafter.Graphics stopped building there.
lib/libevdev now carries libevdev 1.14.0 (MIT), built once as its own
static library that Crafter.Graphics depends on. As part of cfg it would
be compiled again in every test configuration, since they copy
cfg.cFiles.
libevdev's generated event-names.h names every input code by its macro,
so the library compiles against the kernel input headers that table was
generated from (lib/libevdev/kernel-headers), not the target's. That
directory is deliberately not called include: Crafter.Build puts every
include directory of a dependency on its consumers' include path, where
those headers would shadow each consumer's own <linux/input.h>. The
paths are absolute because Crafter.Build only resolves the returned
configuration's paths against the project root.
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.
FontAtlas::Initialize creates an ImageVulkan and nothing ever called its
Destroy(): every atlas left its 1024x1024 image, memory and view behind.
The atlas now owns the image for its lifetime and is no longer copyable.
ImageVulkan's handles start as VK_NULL_HANDLE and Destroy() resets them,
so an atlas that was never initialised, or an image destroyed by hand
before the atlas goes, is a no-op in the destructor.
The owner waits for the GPU before the atlas goes and, in sets mode,
destroys the descriptor heap that holds the image's view before the atlas.
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.
UIFallbackParity renders one scene through both binding models and
compares the frames. It starts itself twice, once as is and once with
CRAFTER_GRAPHICS_NO_DESCRIPTOR_HEAP, so the fallback cannot drift from
the heap path on a machine that never takes it. The scene reaches what
HelloUI does not: the four standalone kernels next to the fused one, a
sampled image with two samplers indexed per item, an image slot and a
sampler slot that are freed and registered again, a resize, an image
created with ImageVulkan::Create's default consumer stage, and a
generic Dispatch whose push payload is not a whole number of words.
On a driver without the heap both runs take the fallback, and the test
then only checks that the scene renders. Validation errors raised
while rendering fail a run, which only bites when
CRAFTER_GRAPHICS_VALIDATION is set. They are counted before the frame
capture because Window::SaveFrame raises one itself (#157).
UIFusedShader now also compiles and validates the descriptor-set build
of the fused kernel and pins its push-constant layout: both builds are
fed the same UIFusedHeader bytes.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
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>
Headless benchmark around the native Sponza RT scene: times setup and a
measured Render() loop over the full multi-mesh atrium, prints BENCH
metrics, and exits. Includes run-bench.sh and a README documenting the
methodology and the measured net gain from #40 to current master.
Co-Authored-By: Claude Opus 4.8 <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>
WebGPUBuffer::EnqueueReadback / PollReadback always copied the full
buffer `size` GPU→staging→wasm. Over-provisioned event-queue buffers
(e.g. Forts3D's GPU physics event drain) paid the full-capacity copy
every drain even when only a small live prefix held data.
Add an optional `byteCount` parameter (default 0 = whole buffer, so the
existing full-buffer callers are unchanged) bounding the readback to the
live prefix. Pass the same byteCount to the paired PollReadback so the
matching number of bytes lands in `.value`.
JS bridge: the staging buffer is now sized to the full device-buffer
capacity (not the first call's byteSize) so a varying prefix length never
overflows it, while the copyBufferToBuffer + mapAsync/getMappedRange are
bounded to the requested prefix — that's where the copy saving lands.
Verified end-to-end in the browser via RayQueryPick: the full readback
still resolves correctly, and a follow-up 8-byte prefix read copies only
hit+customIndex while primitiveIndex keeps its poison sentinel, proving
the copy was bounded. Native `crafter-build test` suite: 24 passed.
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>
