4.1 KiB
This repository: Crafter.Graphics
The Crafter engine's graphics library: one C++ module, Crafter.Graphics,
one partition per file. On native targets it is a Vulkan 1.3+ renderer
built around VK_EXT_descriptor_heap, with a bindless descriptor-set
fallback, hardware ray tracing, a compute-shader UI and a Wayland or Win32
window; on wasm32-* the same C++ surface runs in a browser over WebGPU,
through the JS bridge in additional/. The stated design is README.md
(the manual), AGENTS.template.md (the contributor guide; AGENTS.md is
written from it and the dependencies' notes by every crafter-build run,
and is not in the tree), AGENTS.consumer.md (the notes consumers' agents
get) and the driver investigations in examples/VulkanTriangle/README.md
and examples/Sponza/README.md. The guide's "Design rules" are the
owner's decisions: a range that departs from one without saying so is a
finding; whether one should change is the owner's call, not a defect of
the range.
The layers: the partitions (interfaces/, implementations/), where the
target picks the backend in project.cpp and there is no runtime switch
and no abstraction layer: where the backends' APIs differ, the call site
#ifdefs. Every partition exists on every target, its body gated. The UI
kernels in shaders/, each compiled twice from one source, for the
descriptor heap and for the descriptor-set build (.sets.spv), which
UIFallbackParity holds pixel-identical, with their WGSL counterparts
baked into additional/dom-webgpu.js. project.cpp: the dependencies, the partition
and implementation lists, the shader builds and every test. The examples:
the in-tree consumers, GLSL and WGSL side by side. UIDispatchHeader
and the item structs are frozen and grow only through their reserved
flags bits and _pad, and UIFusedHeader is a separate contract, for
DispatchFused; a component is a stateless function over
buffers the user owns, never a hook or a virtual; the library enables only
the device features its own shaders use.
Search first: Device::EnqueueDeletion for a handle a frame in flight may
still use; VulkanBuffer::Stage for a staged re-upload;
DescriptorHeapVulkan's slots (AllocateBufferSlots, BufferSlot,
AddSwapchainSlot); the barrier builders (SwapchainStageUnion,
SwapchainWriterAccess, BuildSwapchainInterPassBarrier,
BuildTlasWriteBarrier, BuildTlasReadBarrier) and Device::stageMask;
ImageVulkan::Create and VulkanTransition;
Device::Initialize(required, optional) for a feature an application's
shader needs; UIRenderer's helpers, Rect::SubRect and Inset; the
decode helpers in shaders/ui-shared.glsl; the vendored lib/ (stb,
libevdev, the generated Wayland protocol code); Crafter.Event,
Crafter.Math and Crafter.Asset as cloned under
~/.cache/crafter.build/external/ or checked out beside this repository,
and the Vulkan headers and Vulkan-Utility-Libraries cloned there too.
What belongs in one of the three dependencies lands there first (the
commit guidelines), not as a local copy here. A driver workaround takes
the shape of the one there is: a Device flag, one fenced block, a kill
switch, a probe test and a status note.
Commit shape here, as the history shows and design rule 11 asks for the
examples and tests: a change travels in one commit with its test, the
examples and tests it breaks, and the README, AGENTS.template.md and
AGENTS.consumer.md text it makes untrue; a bug fix ships with a test
that fails before the fix (the testing instructions).
Compatibility: the consumers are the examples, each a LocalProject of
../../project.cpp, and the owner's applications, which pull master
unpinned and get AGENTS.consumer.md on their next build. Design rule 11
prefers the clean breaking change to a compatibility shim, so a break is
no finding by itself; a break the range does not carry through every
example, test and consumer-facing document in this tree is. The
environment switches AGENTS.consumer.md lists, the GLSL contract user
shaders #include from ui-shared.glsl and the shader file names
ComputeShader::Load resolves are contracts too.