substrate

lanesOf(t: string) → number

How many numbers one element of `t` occupies, or 0 when the type is carried as values rather than as numbers.

proc.substrate.lanesOf("Vec3") --> 3

tagForStride(t: string, stride: number) → string

The type tag to hold a run of `stride` numbers an element under. `t` is kept when its lanes agree with the stride — so an `Int` or a `Color` stays what it is — and otherwise the tag for that many lanes answers, which is what a run known only by its width is.

proc.substrate.tagForStride("Float", 3) --> "Vec3"

isNumeric(t: string) → boolean

Whether a column of `t` is backed by a substrate buffer.

bufferLayout(t: string) →

The substrate buffer element type a column of `t` is built from, and how many of them one element occupies. A type the buffer primitive expresses directly answers `per = 1`, and its buffer is one a batch write takes as it stands.

local kind, per = proc.substrate.bufferLayout("Vec3") --> "vec3", 1

elementOf(t: string) → string

The 32-bit word form a column of type `t` holds: `"i32"` for `Int`, `"u32"` for `UInt`, `"f32"` for every other type.

proc.substrate.elementOf("Int") --> "i32"

wgslOf(t: string) → string

The WGSL type one element of a column of type `t` is read as: `f32`, `i32` or `u32` for a column of one lane, `vec2<f32>`, `vec3<f32>` or `vec4<f32>` for more (`Color` and `Quat` are four lanes). The one mapping from procgen types to WGSL types: a specialization that names a column's type takes this.

proc.substrate.wgslOf("Vec3") --> "vec3<f32>"

packWords(element: string, values: { number }) → buffer

The words of `values` as the bytes of a run of `element`.

putWords(handle: any, element: string, values: { number }, firstWord: number) → boolean

`values` written into `handle` from word `firstWord`, in the words of `element`.

unpackWords(element: string, readback: any) → void

The numbers a read of `element` words answers: the words themselves as i32, u32 or f32.

elementOfColumn(self: ?) → string

element(self: ?) → string

The 32-bit word form the column's run holds: `"i32"`, `"u32"` or `"f32"`.

if col:element() == "i32" then ... end

mintSerial( ) → number

version(self: ?) →

What identifies this run, and what it is on: a serial unique to the column for the life of the VM, and a revision its writes bump. Two calls answering the same pair are the same values; a different pair is a run that has changed. Nothing is read to answer it.

local s, r = col:version()

dropFrom(self: ?, ofKey: string, runKey: string, registry: any) → void

dropMirror(self: ?) → void

forgetDevice( ) → void

Let go of every mirror after the render device is rebuilt. What each held stood on the device that went, so a run that reads one of those columns on the device puts it there again.

proc.substrate.forgetDevice()

forgetReads(self: ?) → void

Drop every read of this column's run, taken or in flight: the buffer is about to hold something else.

bumpRevision(self: ?) → void

assertType(t: string, where: string) → void

constant(t: string, value: any, count: number) → any

A column holding `value` at every element. It costs one value however many elements it stands for, and a write to any one of them materializes the run. type, the value itself for a type carried as values.

proc.substrate.Column.constant("Vec3", { 0, 1, 0 }, 1000000)

mintName(t: string, storage: string) → string

columnMoved( ) → void

columnMoves( ) → number

How many times a column that already stood has been let go of its run or given another, or a domain has had a column put in or taken out. A holder that read which runs a value's columns stand on at one count knows they stand there still while the count is the same: a column made afterwards changes no column that stood before.

local at = proc.substrate.columnMoves()

trafficOf(thread: any) → any

noteUpload(bytes: number) → void

noteReadback(bytes: number) → void

payloadBytes(payload: any) → number

The bytes a payload handed to a buffer's `write` carries, in each form the write takes: a Luau `buffer`, a binary string, an array of numbers, or an array of per-record arrays.

countTraffic(handle: any, words: number) → void

Count what a device buffer moves: its writes as uploads, its reads as readbacks. `words` is the buffer's whole length in 32-bit words.

write(h: any, payload: any, ...: any) → void

writeU32(h: any, payload: any, ...: any) → void

writeBytes(h: any, payload: any, ...: any) → void

read(h: any, offset: number?, len: number?) → void

countTraffic(handle: any, opts: { type: string, len: number }) → any

Count what a device buffer made outside this module moves between the CPU and the device — a buffer a shader owns (`shaderRef:createBuffer`) — into `proc.substrate.traffic`. Every buffer `createBuffer` makes is counted already.

local dst = proc.substrate.countTraffic(shader:createBuffer("dst", opts), opts)

createBuffer(opts: { [string]: any }) → any

A substrate buffer, as `substrate.createBuffer` makes it, whose traffic between the CPU and the device — when it lives on the device — is counted into `proc.substrate.traffic`. The one way procedural code makes a buffer, so what every node moves is known without the node saying.

local tile = proc.substrate.createBuffer({ name = "t.tile", type = "f32", len = 256, kind = "gpu" })

traffic( ) →

What the calling thread has moved between the CPU and the device through procedural columns since it began: `{ uploads, uploadBytes, readbacks, readbackBytes }`. Two readings taken around a piece of work on the same thread give what that work moved, whatever other threads moved meanwhile.

local before = proc.substrate.traffic()

trafficCounts( ) →

The calling thread's `traffic()` counts a step's statistics read, as numbers rather than a table: uploads, read-backs and device buffers made.

local uploads, readbacks, allocations = proc.substrate.trafficCounts()

isCountColumn(v: any) → boolean

Whether a value is a count a Column holds as one word: what a domain's `.count` answers while its count is on the device.

isCountValue(v: any) → boolean

Whether a value stands for one number held on the device: a count Column, or a Field made only of counts and constants (arithmetic over a count). `readCount` reads either.

onCountRead(hook: ((any, number) → void

Say what to do with every count read where a number is needed: the evaluator records the read of a cook being recorded as a list, so a replay asks it again.

readCount(col: any) → number

The number a count Column holds, read back at the point that needs a number. The read is one read-back, counted in `traffic().countReads` apart from the reads a node makes of its own, and reported to the hook of `onCountRead`.

local n = proc.substrate.readCount(geometry.point.count)

ownerSlot( ) → any

currentOwner( ) → string

mintOwner(kind: string) → string

A fresh owner name, unique for the life of the VM, for what makes runs and lets go of them together (`proc.substrate.withOwner`).

local owner = proc.substrate.mintOwner("cache")

withTraceback(err: any) → string

An error raised inside an owner's work, with the stack it was raised on.

restoreOwner(slot: any, previous: any, ok: boolean, ...: any, owner: ?, fn: ?) →

Call `fn(...)` with every device run a column makes during it held for `owner`, on this thread, and answer what `fn` answers. `owner` is a name, or a function answering the name when a run is made. A run's owner lets go of it with `substrate.releaseOwner(owner)`.

proc.substrate.withOwner(owner, function() return proc.eval(graph) end)

withOwner(owner: any, fn: (...any) → void

holdFor(owner: any) → void

Hold every device run a column makes on this thread, for the rest of the thread's life, for `owner` — a name, or a function answering it when a run is made. What a worker thread doing one owner's work calls once.

proc.substrate.holdFor(function() return cacheOwner end)

owner( ) → string

The owner device runs made on this thread now are held for, or nil.

standsAsRun(usage: BufferUsage?) → boolean

A column's device run is a run of the arenas' pages, held for the thread's owner, unless it is read as vertices or indices, which a buffer of its own holds.

makeBuffer(t: string, count: number, storage: "cpu" | "gpu", usage: BufferUsage?) → any

own(self: ?) → void

Give a CPU column a buffer of its own before it is written, when a clone shares the one it holds. A clone of a CPU run shares its buffer until one of the holders writes, so a cook that carries a geometry forward by cloning it copies nothing; the copy is paid by the holder that writes, once, and it is a copy of bytes rather than a number per component through Luau. The holders of one shared buffer count themselves in a cell of their own, apart from any column, because any of them — the one that minted the buffer included — may be the one that leaves.

numbers(t: string, count: number, values: { number }?) → any

A numeric column of `count` elements, backed by a substrate buffer. `values`, when given, is the flat `count * lanes` run written into it.

proc.substrate.Column.numbers("Vec3", 2, { 0,0,0, 1,0,0 })

gpu(t: string, count: number, usage: BufferUsage?) → any

A numeric column whose buffer lives in GPU storage — the same handle a compute dispatch binds. Reading one back on the CPU is a readback, so a column meant to be read asks for it here.

proc.substrate.Column.gpu("Vec3", 30000, { "readback" })

scratch(t: string, count: number) → any

A numeric column in GPU storage whose run may have held another column's: its elements hold nothing the caller did not write. It is for a run a dispatch writes — every element, or the elements a count bounds. Its run is a range of the device arenas' pages, which a range released a few frames ago is handed out again as, so making one costs no device allocation.

local out = proc.substrate.Column.scratch("Vec3", 4096)

adopt(self: ?, owner: string) → void

Hold this column's device runs for `owner` from now on (`substrate.setOwner`): its own run, the mirror it keeps of a run the CPU holds, or the indices an interned column stands on, and the mirror it makes later (`Column.gpuMirror`). What something keeping the column longer than the owner that made it — a cache several makers read — calls when it takes the column in.

col:adopt(proc.sharedCacheOwner(key))

bufferName(self: ?) → string

The name this column's run lives under in the substrate, or nil for a column whose backing is not a named device buffer. A device binding names its source buffer rather than holding a handle, so this is what lets a run already on the device be bound as the source of something else — placing a domain's elements from the columns that already hold their transform, rather than reading the run back to write it per element.

local name = column:bufferName()

runOwner(self: ?) → any

anyLive( ) → boolean

Whether any run is live: some registration rewrites a run in place as the time it is a function of moves. A cook with no live run to follow asks nothing of the columns it handles.

if proc.substrate.anyLive() then followRuns() end

noteWritten(self: ?) → void

Note that a kernel wrote this column's run in place: every read of the run taken before, by this column or any other holder of the run, stops being an answer. What a pass writing into a run that already stands calls for each run it writes.

col:noteWritten()

runWrites(self: ?) → number

How many times this column's run has been written in place: the writes noted on the column that minted the run, and the notes of every write counter the run has joined since it joined.

writeCount(self: ?) → number

How many times this column's run has been written in place, by any holder of it: what a read of the run taken before is checked against. It only grows.

local before = col:writeCount()

writeCounter( ) → any

A write counter: one count a set of runs share, so a pass that writes all of them (a recorded list replayed) notes the write once instead of once per run. `counter:join(col)` adds a column's run to the set, `counter:note()` counts one write of every run in it, and `counter:release()` takes every run out, each keeping the writes it was counted. A run's `writeCount()` is its own noted writes and the notes of every counter it is in, so a run written outside the set is counted as before.

local counter = proc.substrate.writeCounter(); counter:join(col); counter:note()

join(self: any, col: any) → void

Add the run of `col` to the runs this counter counts writes of, from its next note on. A run already in it, and a column holding no run on the device, are left as they are.

counter:join(col)

note(self: any) → void

Count one write of every run in this counter: every read of any of them taken before stops being an answer.

counter:note()

release(self: any) → void

Take every run out of this counter, each keeping the writes it was counted as its own; later notes count nothing.

counter:release()

countRead( ) → void

noteIfLive(self: ?) → void

markLive(self: ?, registration: any) → void

Declare this GPU run to be rewritten in place by `registration`, which is what `live` answers for it and for every clone of it. A registration names the live registrations of the runs it reads in `deps`, and either the compiled kernel that rewrites it (`kernel`, `buffers`, `count`, `paramsRun`, `values`, `live`) or a `rewrite(clock)` that brings it to a new time. A rewrite that queues the same dispatches over the same runs whatever the clock says carries `record = true`, and is recorded on its first rewrite and replayed after (`proc.device.record`); what holds the rewritten runs lets the recording go with `proc.fieldc.releaseRecording(registration)`. One registration may stand for several runs one rewrite writes together.

out:markLive({ deps = {}, rewrite = function(clock) end })

live(self: ?) → any

The registration that rewrites this run in place, or nil for a run nothing rewrites.

local reg = col:live()

liveReads( ) → number

How many times the calling thread has read a live run — or a live value — on the CPU. Two equal answers mean it took no snapshot of one in between, whatever other threads read meanwhile.

local before = proc.substrate.liveReads()

noteLiveRead( ) → void

Count one CPU read of a live value — what a value that stands for a live run's input, rather than a run itself, reports when it is sampled.

proc.substrate.noteLiveRead()

noteRewrite( ) → void

Say that live runs were rewritten on the device: a read of one taken before this no longer holds, and the next read of it comes back again.

proc.substrate.noteRewrite()

values(t: string, arr: { any }, count: number?) → any

A column backed by an array of values — the backing a type the buffer primitive cannot express takes: text, a reference, a handle, a record. element with no value, such as an entity without the component a record column carries. Left out, it is the array's length.

proc.substrate.Column.values("String", { "a", "b" })

proc.substrate.Column.values("Record", records, #ids)

interned(t: string, values: { any }, index: any) → any

A column carried as values whose elements are placed on the device as numbers: each element is an index into `values`, the distinct values the column holds, and `index` is that run of indices — a Float column, on the CPU or the device. A pass over elements moves the indices and carries the same `values`; a reader on the CPU gets each element's value exactly as it gets one from `Column.values`.

local labels = proc.substrate.Column.interned("String", { "oak", "pine" }, idx)

intern(self: ?) → any

This column as indices into its distinct values (`Column.interned`), which is how a column carried as values is placed on the device: it keeps what it is when it already is one, and a column carried as values is interned once — its distinct values in the order they first appear — and remembers the answer. A text is distinct by its characters, any other value by its identity.

local idx = col:intern():index()

index(self: ?) → any

The run of indices an interned column holds: one Float per element, each an index into its distinct values.

local run = col:index():gpuMirror()

withIndex(self: ?, index: any) → any

The same distinct values over a new run of indices — what a pass that moved an interned column's indices hands on. The column holds `index`.

local kept = col:withIndex(proc.device.gather(col:index():gpuMirror(), keep, n, cap))

distinct(self: ?) →

The distinct values an interned column indexes into, 1-based.

type(self: ?) → string

The column's element type tag.

lanes(self: ?) → number

Numbers per element, 0 for a column carried as values.

count(self: ?) → number

Element count.

isGpu(self: ?) → boolean

Whether the column's buffer lives in GPU storage.

isConstant(self: ?) → boolean

Whether the column is one value standing for every element, which holds no run.

gpuMirror(self: ?) → any

This column's run in GPU storage — itself when it already lives there, else a mirror the column keeps. A compute dispatch binds GPU storage, so a run the CPU holds is uploaded once and the mirror is what a dispatch reads. The mirror belongs to the column: it is dropped the moment anything takes the right to write the buffer under it, and freed when the column is released. So a run that does not change is uploaded once however many dispatches read it, and a run that does not outlive its column does not outlive it on the device either. A column something keeps longer than the owner that made it (`Column.adopt`) keeps its mirror for that keeper, whenever the mirror is made. Answers nil for a column carried as values, which has no run to mirror, and for one the device refused storage for.

local run = col:gpuMirror()

deviceWords(self: ?) → any

The run in GPU storage that holds this column's own 32-bit words (`element()`): a `kernel` binding of `i32` or `u32` reads an `Int` or `UInt` column through it. A column already in GPU storage is itself; a CPU column keeps a mirror of its words that goes with it, as `gpuMirror`'s does.

local run = col:deviceWords()

releaseHolds(col: any) → void

Let go of the runs `col` keeps alive on something else's behalf: a dispatch that wrote it read them, and a dispatch reports only that it was QUEUED; a rewrite that writes it again reads them too.

holdsRuns(v: any) → boolean

Whether a value a column carries holds runs of its own: a Geometry or a Column.

ownedCopy(v: any) → any

The copy of a value a column that owns its values keeps: a Geometry or a Column is cloned (its runs held once more), anything else is held as itself.

release(self: ?) → void

Free the column's buffer. Reachable as `__proc_release`, the node cache's hook on a superseded entry.

materialize(self: ?) → void

A constant column becomes a written one the moment an element differs from the rest, which is the whole of what the backing decides.

buffer(self: ?) → any

The substrate buffer behind a numeric column — the handle `entity.batchWrite`, `nx` and a compute dispatch all take. A constant column materializes here.

entity.batchWrite(binding, "Transform", "position", col:buffer())

readBuffer(self: ?) → any

The buffer for a READ, which is the one path that does not drop the remembered run — it is the path that fills it.

mirrorHolds(self: ?, at: any) → boolean

A read of a column's run is remembered on the column, stamped with what the run had been through when the read was asked for: the writes into it in place, and - for a run rewritten on the device (`markLive`) - the count of rewrites. What was read holds while neither has moved since.

pendingRead(self: ?, slot: string) → void

The read of this column in flight, or a new one asked for when the run has been written since the one in flight was; and the stamp it was asked for at.

keepRun(self: ?, run: any, at: any) → any

keepBytes(self: ?, bytes: any, at: any) → any

prefetch(self: ?, asBytes: boolean?) → boolean

Ask for this column's run to come back to the CPU without waiting for it, and answer whether it has: true once a read that still holds has arrived, after which `read` answers without waiting. A column the CPU already holds answers true at once. What a reader that must not wait — a frame's tick — polls before it reads.

if col:prefetch() then use(col:read()) end

awaitPrefetch(self: ?, asBytes: boolean?) → boolean

Wait until this column's run is on the CPU, as `prefetch` answers it: the read is asked for if it is not in flight and the task parks on the read itself, so it resumes in the frame the device answered where the engine can wait on the device. A read the engine gave up raises with its reason.

col:awaitPrefetch(true); use(col:readBytes())

valueArray(self: ?) →

The array of values behind a column carried as values, materializing a constant backing.

tryRead(self: ?) →

The run this column holds IF it can be answered without waiting — a CPU buffer always can, and a GPU one only once its readback has landed. nil means the device still has it. This is what a read that CANNOT wait uses. A readback takes frames, and waiting for one means yielding; a metamethod cannot yield, so the flat-array view a geometry presents is built on this and says what to do instead.

local run = col:tryRead()

readLater(columns: { [string]: any }) → any

Read columns back to the CPU without waiting for them, each answer about the frame its read was asked in. `poll()` answers the numbers of every column, by name (`lanes` per slot, as `read` answers them), once the reads asked for together have all landed, and nil until they have; whenever no read is in flight it asks for the columns as they stand now. A read the engine gave up is asked for again. A run the device rewrites frame after frame is read here as the value of one frame, and takes no live read: what takes the answer holds it as that frame's. `release()` lets go of the columns, which the reader holds while it reads them.

local later = proc.substrate.readLater({ total = count }); local landed = later.poll()

ask( ) → void

poll( ) → void

release( ) → void

readBytes(self: ?) → buffer

The run this column holds, AS BYTES — the same memory the buffer has, without a number per element passing through Luau on the way. That is the difference between a copy and a walk: `read` builds one Luau value per component, and a run of five thousand vec3s is fifteen thousand of them made, held and collected every time it is read. This answers the block, which is what another buffer's `writeBytes` takes.

dst:buffer():writeBytes(src:readBytes())

read(self: ?) →

The numbers of a column. A column that carries a live count (an appended output, a column of a geometry whose class counts its live elements on the device) answers the live elements only: the slots past the count are never in the answer, and the count is read back once for it.

readSlots(col: any) →

Every slot of a column's run, the ones past a live count included: what a mirror of the run holds.

readAllSlots(self: ?) → void

stride(self: ?) → number

How many numbers one element holds — what a field calls the same question. A column IS a field whose values have already been read, so an op that samples a field samples a column without knowing which it was given.

sample(self: ?, id: number) →

The value at element `id`, under the name a field answers to.

capacityOf(col: any) → number

The capacity a live count is bounded by: the one-word column an appended output or a count made on the device holds, or a clone of one (a clone shares the run, and the capacity is the run's).

local most = proc.substrate.capacityOf(kept.indices_count)

atCapacity(fn: () →

Run `fn` with every live count (the one-word column an appended output or a device-made count holds) sampling as the capacity it is bounded by, and answer what `fn` returns. A Field built over live counts, sampled inside it, answers the largest value it can take: the capacity a count derived on the device is allocated for. The device count itself is never read.

local most = proc.substrate.atCapacity(function() return field:sample(0) end)

materialize(self: ?, count: number?) →

The flat run of `count` elements, under the name a field answers to. A column already holds it, so this is the read rather than a walk of one sample per element.

get(self: ?, id: number) →

The value at element `id` (0-based): `lanes` numbers for a numeric column, the value itself for one carried as values. Per-element reads are for a small column or a probe; a column of any size is handed to a kernel or a batch write whole.

local x, y, z = col:get(7)

set(self: ?, id: number, ...: any) → any

Write element `id`. A constant column materializes here, and no reader of either form can tell which it was given.

col:set(7, 1, 2, 3)

writeRun(self: ?, first: number, values: { number }) → any

Write `values`, a flat run of whole elements, into this column from element `first` on. This is how the pass that owns a GPU-resident column writes it — a solver placing the particles it spawned into the slots it holds — and the write lands behind every dispatch already queued over the column. A CPU column takes it too.

col:writeRun(12, { 0, 1, 0,  0, 2, 0 })

isShared(self: ?) → boolean

Whether every element holds one shared value — true for a column still on its constant backing. What a reader gets is the same either way.

clone(self: ?) → any

A copy with its own backing. A constant column copies as a constant one, so sharing survives the copy at the cost of one value.

gatherKernel(lanes: number) → string

gatherOnDevice(self: ?, keep: { number }, n: number) → any

concatKernel( ) → string

concat(t: string, parts: { any }, counts: { number }, absent: { number }?) → any

One column holding `parts` end to end, each covering the element count `counts` gives it. A part that is nil covers its elements with `absent`, or zeros without one (for a column carried as values, with nothing). Runs the device holds are laid end to end on the device; runs the CPU holds are copied there.

local P = proc.substrate.concat("Vec3", { a:column("point", "P"), b:column("point", "P") }, { 4, 9 })

relaxKernel(device: any) → string

relaxPoints(column: any, iterations: number, radius: number, strength: number) → any

Push every point off its neighbours inside `radius`, `iterations` times, on the device, finding them through a spatial grid. What a scatter runs to even itself out.

local relaxed = proc.substrate.relaxPoints(P, 5, 0.4, 0.5)

release( ) → void

gather(self: ?, keep: { number }) → any

A column of the same type holding the elements `keep` names, in that order — what a filter, a sort and a delete all come down to.

local kept = col:gather({ 0, 3, 4 })

newDomain(name: string, count: number) → any

name(self: ?) → string

The domain's name: "point", "vertex", "primitive" or "detail".

count(self: ?) → number

How many elements the domain holds.

column(self: ?, name: string) → any

The column named `name`, or nil.

setColumn(self: ?, name: string, column: any) → any

Attach `column` under `name`.

removeColumn(self: ?, name: string) → any

Drop the column named `name`, freeing its buffer.

setHoldsIds(self: ?, name: string, flag: boolean) → any

Say whether the column named `name` holds the `id`s of this geometry's points: a join of geometries moves such a column's values with the ids they name, and a selection leaves no value naming a point it removed. The mark belongs to the attribute, so a node that rewrites the column keeps it, and it goes when the column is removed.

holdsIds(self: ?, name: string) → boolean

Whether the column named `name` is marked as holding point `id`s.

names(self: ?) → void

Every attribute name on the domain, sorted, so iteration is the same on every run and a cook key over them is stable.

liveCount(self: ?) → any

How many of the domain's elements are live, as a count on the device — or nil when every element counted by `count()` is. A domain whose membership is decided on the device (the particles a solver keeps, the points a compaction kept) holds its runs at a capacity `count()` answers and its live count here, so no pass reads it back to know how many there are: a kernel over the domain reads the count where it is and leaves every element past it alone.

setLiveCount(self: ?, count: any?) → any

Set the live count (see `liveCount`), or clear it with nil. The domain holds the count it is given.

setCount(self: ?, n: number) → any

Set the domain's element count. A constant column covers the new count at no cost; a written one keeps the buffer it has.

new( ) → any

An empty geometry: no points, no vertices, no primitives, one detail element.

local g = proc.substrate.Geometry.new()

fromPositions(positions: { number }) → any

A geometry holding `positions` as its points and nothing else — what a source op makes. One buffer write, no growth pass.

proc.substrate.fromPositions({ 0,0,0, 1,0,0 })

setPointNumbers(g: any, name: string, t: string, values: { number }) → any

Attach a point column under `name` — the shorthand a source op writing an attribute alongside its positions takes.

proc.substrate.setPointNumbers(g, "normal", "Vec3", nrm)

domainOf(self: ?, name: string) → any

domain(self: ?, name: string) → any

The domain named `name`.

count(self: ?, name: string?) → number

How many elements a domain holds — and, with no domain named, how many POINTS, which is what a geometry standing in space is a count of. Vertices and primitives are structure over those points, so they are asked for by name.

g:count() == g:count("point")

liveCount(self: ?, name: string?) → any

The live count of a domain on the device (see `Domain.liveCount`), or nil when every element `count` answers is live.

setLiveCount(self: ?, name: string, count: any?) → any

Set a domain's live count on the device, or clear it with nil.

column(self: ?, domain: string, name: string) → any

The column named `name` on `domain`, or nil.

setColumn(self: ?, domain: string, name: string, column: any) → any

Attach `column` under `name` on `domain`.

setHoldsIds(self: ?, class: string, name: string, flag: boolean) → any

Mark the column `name` of `class` as holding the `id`s of this geometry's points (or clear the mark). A join of geometries moves a marked column's values with the ids they name, and a selection sets a value that names a removed point to -1.

g:setHoldsIds("point", "target", true)

holdsIds(self: ?, class: string, name: string) → boolean

Whether the column `name` of `class` is marked as holding point `id`s.

idColumns(self: ?, class: string) →

The names of the columns of `class` that are marked as holding point `id`s, sorted.

names(self: ?, domain: string) → void

Sorted attribute names on `domain`, edge included.

edgeAttrs(self: ?) → void

An EDGE is the unordered point pair a primitive uses — derived from the primitives by `topology.edges` rather than stored, which is why it is not one of the four domains. A value ON one is held here, beside them: its rows are the derived list's, so a topology change rebuilds the list and what was indexed against the old one no longer names anything in the new.

ownsRun(value: any) → boolean

Whether an edge value is a Column, which the geometry owns and lets go of.

dropEdgeValue(self: ?, name: string, keep: any?) → void

Let go of the edge value standing under `name` unless it is `keep`.

attributeNames(self: ?, class: string) →

The attribute names in a class — every column except the intrinsics that hold the geometry itself.

detailColumn(value: any) → any

A detail value is held as itself: one element carrying whatever was set, which is what a label, a count or a table means on the whole geometry. The column a detail value is held in. It owns a copy of a Geometry or a Column it is given, which goes with the column; the caller keeps what it handed in.

setAttribute(self: ?, class: string, name: string, value: any) → any

Write a named attribute on a domain class. A column is stored as it stands; a field is read onto one, which is where a chain behind it is spent; a detail value is held as itself.

getAttribute(self: ?, class: string, name: string) → any

Read a named attribute. An element class answers the column, which is what a field is asked for too; detail answers the value it was set with.

removeAttribute(self: ?, class: string, name: string) → any

Drop a named attribute, freeing what it held.

elementCount(self: ?, class: string) → number

How many elements an attribute class has. An edge is the unordered point pair a primitive uses rather than a row of its own, so its count is derived — `proc.ops.topology.elementCount(g, "edge")` answers it.

edgeStamp(self: ?) → string

What an edge derivation reads: the counts of the three element classes and the version of every run the faces are made of, live counts included.

edges(self: ?) → any

The geometry's edges on the device — each unordered point pair a side of its fan triangles joins, numbered as `proc.ops.topology` numbers them (see `proc.device.edges`). Derived on the first ask and held until the faces they come from change; the geometry lets them go with its own runs.

local edges = g:edges(); print(edges.capacity)

position(self: ?, id: number) → void

Where point `id` is, as `x, y, z`.

local x, y, z = g:position(0)

attributeAt(self: ?, name: string, id: number) →

The point attribute `name` at point `id`, as its components — what `g:getAttribute("point", name):sample(id)` answers, in one call.

setDetail(self: ?, name: string, value: any) → any

Write a value that covers the whole geometry.

getDetail(self: ?, name: string) → any

A value covering the whole geometry, or nil.

detailNames(self: ?) → void

The names of the values covering the whole geometry, sorted.

vertexCount(self: ?) → number

How many points the geometry holds — the elements `positions` runs over.

triangleCount(self: ?) → number

How many triangles the geometry holds — the elements `indices` runs over, counting an n-gon as the fan it draws as.

carryBetween(src: any, dst: any, a: { number }, b: { number }, w: { number }) → any

Carry `src`'s point attributes onto `dst`'s points, each of which lies between two of `src`'s: point k of `dst` is `w[k]` of the way from point `a[k]` to point `b[k]`. Numbers are blended between the two; a value that cannot be blended is taken from the nearer. `P` and `id` are the destination's own.

proc.substrate.carryBetween(curve, samples, { 0, 0 }, { 1, 1 }, { 0.25, 0.75 })

carry(src: any, dst: any, by: { [string]: any }?) → any

Carry `src`'s attributes onto `dst`. A domain `by` names an index list for is GATHERED by it — element k of the result reads source element `by[k + 1]`, which is the one operation a filter, a split, a weld and a remap all come down to, and it runs where the column lives. A domain with no list carries its columns as they stand, and one named `false` is left alone — that is the domain whose values the op computes rather than reads, an average across a weld among them. The intrinsics are never carried: the op that changed the topology wrote those itself. list an array of 0-based source indices.

proc.substrate.carry(g, out, { point = srcPoint, primitive = srcFace })

release(self: ?) → void

Free every buffer this geometry's columns hold.

addPoints(self: ?, positions: { number }) → any

Add `count` points at `positions` (a flat `count * 3` array), each with an id nothing else in this geometry carries. Ids are identity: a filter renumbers indices and every id it keeps stays what it was.

g:addPoints({ 0,0,0, 1,0,0, 2,0,0 })

addPrimitive(self: ?, pointIndices: { number }) → number

Add one primitive made of the points `pointIndices` names, in order. It creates one vertex per entry, each naming the point it reads, and the primitive's run over them.

g:addPrimitive({ 0, 1, 2 })

curveFlags(self: ?) → void

Which primitives are curves: the `curve` column, 1 on a curve and 0 (or absent) on a face. nil when the geometry holds no curve.

addCurve(self: ?, pointIndices: { number }, closed: boolean?) → number

Add one curve: a primitive running through the points `pointIndices` names, in order. A curve is a line rather than a surface — a mesh built from the geometry draws its faces and not its curves, and the ops that sample, sweep or grow along lines read its curves — while its points are points like any other, so every point and field op moves them.

g:addCurve({ 0, 1, 2, 3 }, false)

fromCurves(positions: { number }, curves: { any }) → any

A geometry of curves over one set of points: `positions` are the points, and each entry of `curves` is one curve through them — the point indices it runs through, in order, and whether it closes. Curves may share points, the way a branch starts where its parent passes. Every column is written once.

proc.substrate.fromCurves({ 0,0,0, 1,0,0, 1,1,0 }, { { points = { 0, 1, 2 } } })

isCurve(self: ?, prim: number) → boolean

Whether primitive `prim` is a curve rather than a face.

curveCount(self: ?) → number

How many of the geometry's primitives are curves.

drawVersion(self: ?) → string

Which version of its shape the geometry draws as: the versions of every column a mesh is built from, as one string. The same string exactly while none of them has been written, so a mesh built from the geometry stands for as long as this answers what it did when the mesh was made. A mesh is built with normals, and a geometry carrying none is given them here, the way `toMeshArgs` would, so the answer is the same before its mesh is made as after.

if g:drawVersion() ~= held.version then rebuild() end

curves(self: ?) →

Every curve the geometry holds, in primitive order: the primitive, the point indices it runs through and whether it closes.

for _, c in ipairs(g:curves()) do print(#c.points) end

curvePositions(self: ?, curve: any) →

The positions a curve runs through, flat, in its order.

primitivePoints(self: ?, prim: number) →

The point indices a primitive uses, in order.

vertexPrimitive(self: ?, v: number) → number

Which primitive uses vertex `v`, derived from the primitive runs.

clone(self: ?) → any

A copy whose domains and columns are its own. Ops return copies so a memoized input stays as the cook that made it left it.

sameValue(a: any, b: any) → boolean

Whether two values held on the CPU are the same value: equal plain values, or tables holding the same values under the same keys.

mergeOnDevice(parts: { any }, absent: ((string) → void

Parts merged on the device: in every domain, each part's live elements laid after the live elements of the parts before it, at an offset the device sums, in runs as long as every part's capacity together. A vertex's point and a primitive's first vertex are moved past the live elements of the parts before them, by counts the device holds. An element's `id` becomes its id times the part count plus its part's index, as on the CPU; a point's `slot` is moved past the capacities of the parts before it, so each point keeps one place in the whole; and an attribute whose values index the labels a part's detail names is moved past the labels of the parts before it, the labels laid end to end the same way.

basesOf( ) → void

Where each part's elements start in every domain, and how many there are in all.

placeAll(at: { [string]: { any } }, held: boolean, domains: { string }) → void

Every part's run of every column placed end to end in the merged runs, the runs a part holds in one pass per part and domain, over `domains`; `held` says whether each merged run holds what its placement reads.

dep(col: any) → boolean

rewrite(_clock: any) → void

release(_self: any) → void

mergesOnDevice(parts: { any }) → boolean

Whether a merge of these parts is one for the device: a part counts some domain's elements there, or holds a run there.

merge(parts: { any }, absent: ((string) →

Every part laid end to end in one geometry: each domain's elements in part order, every column any part carries (a part without one fills its elements with the value `absent` names for the column, or zeros), the vertices re-pointed at their own part's points and the primitives at their own part's vertices. Ids stay identity: an element's id is its own id times the part count plus its part's index, so every element of a part keeps one id however the other parts change. The detail values are the first part's. Parts that count any domain's elements on the device, or hold runs there, are merged there: in every domain each part's live elements after the live elements before it, the whole counted on the device, the indices into another domain moved past that domain's elements before them, a point's `slot` moved past the capacities of the parts before it, and an attribute indexing the labels a part's detail names moved past the labels before it. carries no column named so hold: `proc.translate.absentValue` gives every element the rest its components stand at.

local both = proc.substrate.Geometry.merge({ a, b })

countOnDevice(device: any, d: any) → any

A domain's live count, or its count held on the device.

copyToPoints(sources: { any }, points: any, opts: { variant: string?, skip: { [string]: boolean }? }?) → any

A copy of a source stamped at every point, all in one geometry, on the device. Each point's copy is its source scaled by the point's `scale`, turned by its `orient` (a quaternion x, y, z, w) and moved to its `P`; a point without one stands at no scale or turn. With several sources each point's `variant` attribute names the one it takes (0 is the first); a point naming none of them takes no copy. The copies lie in point order, in every domain: their corners name their own copy's points, their faces their own copy's corners, and their normals turn with them. A source point's own `orient` is turned by its copy's and its Vec3 `scale` multiplied by it, so instances copied onto points keep their own turn and size inside the copy's. Every other point attribute stands on each point of its copy, over a source's own attribute of that name; one carried as values (text, records) is carried as its indices into the values it holds (`Column.intern`). The copies' ids and slots are their own places. The whole runs where the points are: nothing is read back, the points' live count bounds every pass, and how many copies there are in all is a count on the device, so a population a solver moves copies on every frame without a pause. A geometry whose counts the CPU cannot know — several sources, or points counted on the device — carries its live counts there. attribute that names each point's source, and point attributes the copies take nothing from.

local rocks = proc.substrate.Geometry.copyToPoints({ rock }, scattered)

temp(col: any) → any

perPoint(name: string, t: string, value: { number }) → any

A point's placement, one per point, on the device.

onDevice(self: ?) → boolean

Whether any column the geometry draws from is held on the device: its positions, its corners, its faces or its live counts. A geometry that is becomes a mesh with `toDeviceMesh`, which leaves it there.

if g:onDevice() then local m = g:toDeviceMesh("rock") end

toDeviceMesh(self: ?, name: string?, opts: { measure: boolean? }?) → any

The geometry as the renderer takes it, built on the device: a vertex buffer and an index buffer the renderer draws from where they are, the way `toMeshArgs` lays them out — one GPU vertex per point when no corner carries a normal or uv of its own, one per corner otherwise, and every face fanned from its first corner. Normals come from the corners, else the points, else the faces. Two numbers come back to size the draw and frame it: how many triangles there are, and the positions' extent, both asked for before either is waited on. With `measure = false` neither is waited on and the mesh is ready the moment this returns: the draw covers every index the index run holds, those past the last face being empty triangles that draw nothing. The extent is still asked for, and comes back as `extent`, two runs whose reads are on their way: the caller states it on the mesh (`renderer.mesh.update` with `aabbMin` / `aabbMax`) once they arrive, since the extent is what the mesh is culled against and framed by. count and the extent. runs the mesh draws from, which the caller releases after the mesh, and — not measured — `extent = { least, most }`, the positions' least and greatest lanes on their way back, which the caller releases once read. nil when the geometry has no triangles; one not measured has as many triangles as its corners allow.

local built = g:toDeviceMesh("rock"); local mesh = renderer.mesh.create(built.args)

local card = g:toDeviceMesh("card", { measure = false })

temp(col: any) → any

releaseTemps( ) → void

toMeshArgs(self: ?, name: string?) →

The geometry as the renderer takes it: one GPU vertex per VERTEX, and triangles over them. A GPU vertex carries one position, one normal and one UV, so a point read by two primitives that disagree about any of those is two GPU vertices. That is what the vertex domain is: the split lives there, and this is where it is spent. A point every primitive agrees about still costs one vertex each, which is the price of a format that carries no sharing. `normal` and `uv` are read from the vertex domain first, then the point domain, so a mesh that splits its normals says so per vertex and one that does not says so once per point. With neither, the normals are computed from the faces. A primitive of more than three vertices is fanned.

renderer.mesh.create(g:toMeshArgs("rock"))

channel(vertexName: string, pointName: string, lanes: number) → void

A per-vertex channel is read as it stands; a per-point one is spread onto the vertices that read those points.

recalcNormals(self: ?) → any

Recompute the per-point normal column `N` from the primitives: each face's unnormalized cross product, which carries twice its area, is added to every point it touches and the sum is normalized — so a large face weighs on a shared point in proportion to how much of it there is. A point no primitive gives a direction gets (0, 1, 0).

bounds(self: ?) → void

Axis-aligned bounds over the live points, as `{ min = {x,y,z}, max = {x,y,z} }`: the least and greatest of every lane, folded on the device and read back as those six numbers. A geometry with no live point is bounded by the origin.

viewRun(self: ?, domain: string, name: string) → void

`positions`, `indices`, `normals` and `uvs` name the same geometry the domains hold, read as the flat arrays a mesh algorithm walks. They are DERIVED: the columns are the storage and these are a view of it, drained on the first read after the geometry changes and held until it changes again. `positions` is the POINT run, so `indices` addresses points — an algorithm that welds, subdivides or cuts reads the sharing the point domain records rather than the split a GPU vertex buffer imposes. `toMeshArgs` is the other view, where a vertex is a GPU vertex, and that is the one the renderer takes. A column's run, for a view that cannot wait for one. A column the device still holds raises here, naming the one call that brings it back — because a readback takes frames, waiting for one yields, and a metamethod that yields ends the script with a message about a C-call boundary rather than about the geometry it was reading.

leading(col: any, n: number) → any

The first `n` elements of a column, on the CPU.

prefetch(self: ?) → boolean

Ask for everything `drain` reads to come back to the CPU without waiting for it, and answer whether it all has — after which `drain` answers without waiting. What a frame's tick polls before it drains a geometry.

if g:prefetch() then g = g:drain() end

drain(self: ?) → any

Bring every column the device holds back to the CPU, so the flat arrays derived from them can be read. This is what a mesh algorithm written over `positions` and `indices` pays to run on the CPU, paid ONCE and where it can be seen, rather than per column inside a read that cannot wait. A domain whose live elements are counted on the device (`Domain.liveCount`) is read as exactly those: its count comes back with its runs, and what is answered is a copy holding that many elements, since a CPU reader walks `count()` of them.

g = g:drain()

stand(col: any, state: { touched: boolean }) → any

A stand-in for a Column on the device that answers its structure and records the first ask for its numbers.

__index(_t: any, key: any) → void

structureOfGeometry(g: any, state: { touched: boolean }) → any

A geometry whose columns on the device are stand-ins (see `stand`).

counted( ) → any

structureOf(value: any) →

What `value` looks like to a reader that asks only for structure: every geometry it holds with its columns on the device standing in as columns that answer their type, width, length and run and nothing else. Asking for the numbers of one, or for the count of a class counted on the device, sets `state.touched`; the reader is then handed `drainAll` instead. A part, or a stand-in left in what the reader answers, has no such view.

local view, state = proc.substrate.structureOf(inputs.geometry)

visit(v: any) → any

holdsStandIn(value: any) → boolean

Whether a value an op answered holds a stand-in for a column on the device (`structureOf`).

visit(v: any, depth: number) → boolean

drainAll(value: any) → any

Bring every geometry `value` holds back to the CPU (`Geometry.drain`): a geometry itself, the sources and points of an instance set, and every element of an array. What a CPU reader is handed, so the flat arrays it walks can be read; a value holding nothing on the device costs a walk of its columns and no readback. A geometry counted on the device is answered as the copy `Geometry.drain` makes, and a value holding one as a copy holding that, so what `value` itself holds is left as it stands.

local g = proc.substrate.drainAll(inputs.geometry)

visit(v: any) → any

fromPointCloud(pc: any) → any

A geometry holding the points of a `PointCloud` value: its positions as the point run, each attribute on the point domain, each detail as a detail value. What a socket declared as anything but `PointCloud` is handed.

local g = proc.substrate.fromPointCloud(proc.PointCloud.new({ 0,0,0 }))

toPointCloud(g: any) → any

The `PointCloud` value a geometry's points make: their positions, each point attribute as the column holding it, each detail value. What a socket declared as `PointCloud` is handed. Columns the device holds are brought back first, since the value reads its positions as an array.

local pc = proc.substrate.toPointCloud(g)

viewOf(self: ?) → any

A held view is valid while the columns it was derived from are the SAME columns. A column is replaced rather than written in place — an op builds a new one and attaches it — so comparing identities answers exactly, and a geometry keeps no back-pointer to be walked or kept alive by.

derivePositions(self: ?) → void

The point positions, flat.

deriveIndices(self: ?) → void

Triangles over POINT indices: every primitive's run, fanned. An algorithm reading this sees the same triangles `toMeshArgs` draws, addressed by point.

derivePointChannel(name: string) → void

A per-POINT channel, which is what a flat array parallel to `positions` means. A geometry that splits the channel per vertex says so on the vertex domain, and that split is `toMeshArgs`'s to spend.

deriveAttrs(self: ?) → any

The attributes by class, as the tables an algorithm walks when it carries them across a topology change: name -> column for the element classes, and name -> value for detail. It is a READ of the columns — writing an attribute is `setAttribute`, which is the one place a column lands on a domain. `edge` is here and always empty: an edge is the unordered point pair a primitive uses rather than a row of its own, so nothing stores a column on it, and a walk over the classes finds it rather than failing on it.

__index(self: ?, key: any) → void