67 lines
4.1 KiB
Markdown
67 lines
4.1 KiB
Markdown
|
## 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
|
||
|
|
`#ifdef`s. 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.
|