The luv workshop wiki
A workshop, not an authority #H7QK3M
This wiki is a place to develop an understanding of GPU programming, engine design, and implementation. Its first subject was the shape of WebGPU and the work hidden beneath that shape. The little block world now adds a second path: how a live Common Lisp game might understand worlds, materialized data, measurement, simulation, and presentation without prematurely becoming a framework.
Neither resemblance to WebGPU nor presence in the current luv implementation makes something correct. WebGPU is a landmark: we want to understand the problems its design addresses and the consequences of its answers. Luv may adopt, simplify, alter, or reject those answers. Likewise, current luv code is a live experiment. It can supply observations and case studies, but must not be used as ground truth to justify itself.
The pages try to keep three voices distinct:
- WebGPU semantics describe an externally observable contract.
- Implementation consequences explain work some implementation must do to uphold that contract. A particular mechanism is usually not mandated.
- Questions for luv are invitations, not decisions already made.
Claims about intention deserve special care. The specification is good evidence for the contract and some rationale, but a historical claim about why the working group chose a design may require proposals, issues, meeting notes, or mailing-list archaeology. An attractive retrospective explanation is not automatically a historical fact.
Source-study pages use a parallel discipline: distinguish a mechanism observed in code, a claim made by its documentation, and our reading of what it might teach luv. The block-world synthesis pages distinguish those forms of evidence from tentative vocabularies and experiments still to be tried.
Mentioned in: What this page studies, What this page studies, Moppe is evidence, a tuning library, and a legacy
String figures #F2N8VX
An addressable piece of discourse is a figure. For now a figure is an Org
heading with a stable six-character ID property. Files gather figures by
subject; they do not provide their identities. A figure can move, acquire a
better title, or be substantially revised while its identifier remains the
same.
A plain mention such as #D3H7VK passes a figure into another passage. Org's
standard [[id:D3H7VK]] form is also available when a clickable link is more
useful than the light notation. We can derive lookup, outgoing links,
backlinks, dangling references, and code-to-discourse links from these
mentions; any such index should be disposable rather than another source of
truth.
Common Lisp gives us an especially cheap future notation. A WIKI package
could export figure symbols, allowing source to mention 'wiki:D3H7VK without
a reader macro. We should first let real uses teach us whether a symbol means
only a stable reference, a resolvable object, source metadata, or something
else. Comments and docstrings containing #D3H7VK already participate in the
discourse without changing Lisp semantics.
Mentioned in: Why ASDF, and how the wiki slots into it, Spinneret as the HTML layer, A fluid dual system: code contributes to the wiki
Work marks #W3K9MK
Some figures are also work marks: tiny roadmap entries that live in the same wiki page as the design they move forward. A work mark is an Org heading with:
- a status keyword in the title:
NEXT,TODO,WAIT,DONE, orIDEA; - a stable six-character
IDproperty, so code, commits, and other pages can mention it as#W3K9MKstyle text; - one coherent iteration of scope, not a project-management breakdown; and
- short
Intent,Evidence, andDone whenparagraphs or lists.
The status words are deliberately small. NEXT is the current best small bet.
TODO is committed enough to keep visible but not selected. WAIT needs
outside information or another completed step. DONE records the evidence
that closed the loop. IDEA is a tempting possibility that should not steer
implementation yet.
Work marks should not duplicate code review, issues, or test output. They are the wiki's memory of why a step exists, what would count as progress, and what evidence changed its status. When implementation changes the plan, update the nearby work mark instead of appending a disconnected status page.
Mentioned in: Light work marks, The Org subset the reader understands
Paths into the initial material #S9D4KC
The following are starting paths rather than a table of settled doctrine. A useful first crossing is from the timeline distinction #T4V8QM to the
ownership phases in #L8R2WF, then to Vulkan's logical/physical destruction
split #D3H7VK and the frame slots that became pacing clients #M6P8XW. That
path explains why “the Lisp object is no longer wanted,” “the API object is
destroyed,” and “the backend may release the allocation” are not the same
event. Mentioned in: Sheaf: six characters address anything, resolved through the graphEngineering the implementation #0L51TG
GPU semantics and implementation #G4R8PU
MTL4Compiler, argument
tables, the live luvcraft pipeline, and its remaining backend-local work.The little block world #B7W3LD
self.eval to replay-probed image commits.frontier repository as an operational account of worklist traversal:
unfolding, result reservation, memoization, admission, scheduling, and
commitment. It then distinguishes discover-once, monotone relaxation, and
invalidation work across lighting, terminal walls, fluids, fire, signals,
navigation, ecology, and chunk production.The wiki itself #2RRDHC
org-file components, and the Spinneret rendering choices.
Both resource implementations now give destroy this shape. While a backend queue is live, the operation first transfers a complete native teardown into a FIFO retirement ledger, tagged with the resource's last submitted use, and only then marks the wrapper destroyed. The ledger runs the eligible prefix as the queue…
The caller can finish describing a command before the queue accepts it, and the queue can accept it before the GPU finishes executing it. These are orders of events, not necessarily distinct OS threads: The generic submit documentation states the consequence directly: returning does not mean GPU completion; the…
One GPU resource participates in several overlapping lifetimes: – application code can still reach its Lisp wrapper; – the wrapper is logically valid for new operations; – an encoder or finished command may retain it as a recorded dependency; – a queue submission may retain it for work the GPU can still execute; and –…
The Vulkan canvas keeps a bounded ring of frame slots. Each slot owns an image-acquisition binary semaphore and, while occupied, the frame's command buffer plus its queue submission index. Reusing a slot waits for the queue frontier to reach that index, then destroys the retained command buffer. Render-finished…