# gizlang/render

Render scheduling and its host packet. No game state, UI framework, window, driver or global device is owned here.

```gizlang
import * as Render from "gizlang/render";
```

## Types

### `Level`

```gizlang
type Level = { width: i64; height: i64; depth: i64; body: bytes; }
```

One mip of a texture: its logical size and its packed texel blocks.

- `width`: `i64`
- `height`: `i64`
- `depth`: `i64`
- `body`: `bytes`

### `TextureFormat`

```gizlang
type TextureFormat = { width: i64; height: i64; bytes: i64; upload: bool; feature: string; }
```

A texel block and its device feature. Upload dimensions are logical pixels; packed bytes use whole blocks.

- `width`: `i64`
- `height`: `i64`
- `bytes`: `i64`
- `upload`: `bool`
- `feature`: `string`

### `Handle`

```gizlang
type Handle = { slot: i64; generation: i64; }
```

A resource slot and generation. Slot zero names the current surface texture and is never owned by an application.

- `slot`: `i64`
- `generation`: `i64`

### `Surface`

```gizlang
type Surface = { system: string; display: u64; window: u64; }
```

A window as a GPU draws into it (gizlang/window gives it, gizlang/webgpu open takes it): its SYSTEM ("xcb", "metal",
"wayland" or "win32"), the connection or module (DISPLAY: an xcb_connection_t, a wl_display, an HINSTANCE; 0 for
Metal) and the window (an X window id, a CAMetalLayer, a wl_surface, an HWND).

- `system`: `string`
- `display`: `u64`
- `window`: `u64`

### `Resource`

```gizlang
type Resource = { handle: Handle; kind: string; descriptor: Json; dependencies: Vec<Handle>; bytes: i64; }
```

Creation data using WebGPU's descriptor fields, with dependencies derived from its resource references.

- `handle`: `gizlang_render.Handle`
- `kind`: `string`
- `descriptor`: `gizlang_json.Json`
- `dependencies`: `Vec<gizlang_render.Handle>`
- `bytes`: `i64`

### `Command`

```gizlang
type Command = { method: string; args: Vec<Json>; }
```

One host API call inside a pass, using WebGPU method names and JSON arguments with reference(handle) objects.

- `method`: `string`
- `args`: `Vec<gizlang_json.Json>`

### `Pass`

```gizlang
type Pass = { name: string; kind: string; descriptor: Json; reads: Vec<Handle>; writes: Vec<Handle>; after: Vec<string>; commands: Vec<Command>; loads?: Vec<Handle>; }
```

A render, compute or copy pass. AFTER contains pass names; accesses govern ordering and initialization checks.

- `name`: `string`
- `kind`: `string`
- `descriptor`: `gizlang_json.Json`
- `reads`: `Vec<gizlang_render.Handle>`
- `writes`: `Vec<gizlang_render.Handle>`
- `after`: `Vec<string>`
- `commands`: `Vec<gizlang_render.Command>`
- `loads`: `_gizlang_sdk_core.Option<Vec<gizlang_render.Handle>>`

### `Upload`

```gizlang
type Upload = { handle: Handle; offset: i64; size: i64; destination: i64; }
```

A buffer update. OFFSET and SIZE refer to the packet's binary tail; DESTINATION is the byte offset in the GPU buffer.

- `handle`: `gizlang_render.Handle`
- `offset`: `i64`
- `size`: `i64`
- `destination`: `i64`

### `ImageUpload`

```gizlang
type ImageUpload = { handle: Handle; offset: i64; size: i64; width: i64; height: i64; depth: i64; x: i64; y: i64; z: i64; mip: i64; format: string; }
```

A tightly packed rectangle in a mip and consecutive depth/layer range, using the shared format's texel blocks.

- `handle`: `gizlang_render.Handle`
- `offset`: `i64`
- `size`: `i64`
- `width`: `i64`
- `height`: `i64`
- `depth`: `i64`
- `x`: `i64`
- `y`: `i64`
- `z`: `i64`
- `mip`: `i64`
- `format`: `string`

### `Resources`

```gizlang
class Resources { private slots: Vec<Slot> = []; private free: Vec<i64> = []; private released: Vec<Handle> = []; private used: i64 = 0; private limit: i64; private serial: i64 = 0; private editing: i64 = 0; constructor(limit: i64 = 268435456) { assert(limit> 0); this.limit = limit; } bytes(): i64 { return this.used; } available(): i64 { return this.limit-this.used; } transaction<T>(work: () => T throws string): T throws string { const slots = this.slots.map(slot => ({ ...slot })); const free = this.free.map(index => index); const released = this.released.map(handle => handle); const used = this.used; this.editing+ = 1; try { return work(); } catch (error: string) { this.slots = slots; this.free = free; this.released = released; this.used = used; throw error; } finally { this.editing- = 1; } } create(kind: string, descriptor: Json, bytes: i64 = 0): Handle throws string { if (!["buffer", "texture", "sampler", "shader", "renderPipeline", "computePipeline", "bindGroup", "bindGroupLayout", "pipelineLayout", "querySet"].includes(kind)) { throw "Unknown GPU resource kind"; } if (descriptor.kind !== "object" || bytes <0 || bytes> this.limit - this.used) { throw "Invalid GPU descriptor or memory budget"; } if (kind === "buffer" && handlePart(descriptor.field("size")) !== bytes) { throw "Buffer reservation differs from its descriptor size"; } if (kind === "texture" && bytes === 0) { throw "A texture needs a declared memory reservation"; } if (kind === "shader") { const name = reservedName(descriptor.field("code").text()); if (name !== "") { throw `The shader declares ${name },  a word WGSL reserves`; } } if (kind === "querySet") { const count = handlePart(descriptor.field("count")); if (count <1 || count> 4096 || count*8 !== bytes) { throw "Query reservation differs from its descriptor count"; } } if (!["buffer", "texture", "querySet"].includes(kind) && bytes !== 0) { throw "This GPU resource has no allocation storage"; } const reached = dependencies(descriptor); for (const dependency of reached) { this.get(dependency); } const index = this.free.length> 0 ? this.free[this.free.length - 1]: this.slots.length; const generation = this.serial + 1; if (generation> 9007199254740991) { throw "GPU resource generation exhausted"; } if (index <this.slots.length) { this.free.pop(); } const handle: Handle = { slot: index + 1, generation }; const resource: Resource = { handle, kind, descriptor, dependencies: reached, bytes }; const slot: Slot = { generation, resource, published: false, initialized: !["buffer", "texture", "querySet"].includes(kind), held: [] }; if (index === this.slots.length) { this.slots.push(slot); } else { this.slots[index] = slot; } this.serial = generation; this.used + = bytes; return handle; } buffer(size: i64, usage: i64): Handle throws string { return this.create("buffer", parseUnique(`{"size":${size }, "usage": ${ usage } }`)!, size); } get(handle: Handle): Resource throws string { const index = handle.slot - 1; if (index <0 || index> = this.slots.length || this.slots[index].generation !== handle.generation || this.slots[index].resource === undefined) { throw "Stale or unknown GPU resource"; } return this.slots[index].resource!; } release(handle: Handle): void throws string { const resource = this.get(handle); for (const slot of this.slots) { if (slot.resource !== undefined && slot.resource!.dependencies.some(dependency => equal(dependency, handle))) { throw "GPU resource still has dependents"; } } const index = handle.slot - 1; if (this.slots[index].published) { this.released.push(handle); } this.slots[index].resource = undefined; this.slots[index].initialized = false; this.slots[index].held = []; this.free.push(index); this.used - = resource.bytes; } recover(): void throws string { if (this.editing> 0) { throw "Cannot recover GPU resources during a declaration transaction"; } this.released = []; for (const index of range(0, this.slots.length)) { const slot = this.slots[index]; this.slots[index] = { ...slot, published: false, held: [], initialized: slot.resource !== undefined && !["buffer", "texture", "querySet"].includes(slot.resource!.kind) }; } } initialized(handle: Handle): bool throws string { if (equal(handle, surface())) { return false; } this.get(handle); return this.slots[handle.slot - 1].initialized; } invalidate(handle: Handle): void throws string { const resource = this.get(handle); if (!["buffer", "texture", "querySet"].includes(resource.kind)) { throw "This GPU resource has no mutable content"; } this.slots[handle.slot-1].initialized = false; this.slots[handle.slot-1].held = []; } publish(written: Vec<Handle>, sent: Vec<{ handle: Handle; held: Held; }>, drawn: Vec<Handle>): void throws string { if (this.editing> 0) { throw "Cannot publish GPU resources during a declaration transaction"; } for (const upload of sent) { const slot = this.slots[upload.handle.slot-1]; const end = upload.held.destination+upload.held.data.length; let held = slot.held.filter(other => other.destination> = end || other.destination+other.data.length <= upload.held.destination); if (slot.initialized) { held.push(upload.held); } this.slots[upload.handle.slot-1].held = held; } for (const handle of drawn) { if (handle.slot> 0) { this.slots[handle.slot-1].held = []; } } for (const index of range(0, this.slots.length)) { if (this.slots[index].resource !== undefined) { this.slots[index].published = true; } } for (const handle of written) { if (handle.slot> 0) { this.slots[handle.slot - 1].initialized = true; } } this.released = []; } holds(handle: Handle, destination: i64, data: bytes): bool throws string { this.get(handle); return this.slots[handle.slot-1].held.some(held => held.destination === destination && held.data === data); } pending(): Vec<Resource> throws string { let out: Vec<Resource> = []; let remaining: Vec<Resource> = []; let ready = new Set<string>(); for (const slot of this.slots) { if (slot.resource === undefined) { continue; } if (slot.published) { ready.add(key(slot.resource!.handle)); } else { remaining.push(slot.resource!); } } let after: Vec<Vec<i64>> = []; for (const resource of remaining) { let needs: Vec<i64> = []; for (const handle of resource.dependencies) { if (!ready.has(key(handle))) { needs.push(remaining.findIndex(other => equal(other.handle, handle))); } } after.push(needs); } for (const index of dependencyBatches(after, (left: i64, right: i64): bool => false).flat()) { out.push(remaining[index]); } return out; } retiring(): Vec<Handle> { return this.released; } }
```

CPU ownership of one surface's resource declarations and budget. The host owns their actual device objects.

- `slots`: `Vec<gizlang_render.Slot>`
- `free`: `Vec<i64>`
- `released`: `Vec<gizlang_render.Handle>`
- `used`: `i64`
- `limit`: `i64`
- `serial`: `i64`
- `editing`: `i64`

### `Graph`

```gizlang
class Graph { private passes: Vec<Pass> = []; private uploads: Vec<Upload> = []; private images: Vec<ImageUpload> = []; private payload: bytes = b""; private consumed: bool = false; private editing: i64 = 0; transaction<T>(resources: Resources, work: () => T throws string): T throws string { if (this.consumed) { throw "Render graph was already consumed"; } const passes = this.passes.map(pass => pass); const uploads = this.uploads.map(upload => upload); const images = this.images.map(image => image); const length = this.payload.length; this.editing+ = 1; try { return resources.transaction(work); } catch (error: string) { this.passes = passes; this.uploads = uploads; this.images = images; this.payload = this.payload.slice(0, length); throw error; } finally { this.editing- = 1; } } add(pass: Pass): void throws string { if (this.consumed) { throw "Render graph was already consumed"; } if (pass.name === "" || this.passes.some(one => one.name === pass.name) || !["render", "compute", "copy"].includes(pass.kind) || pass.descriptor.kind !== "object") { throw "Invalid render pass"; } if (!(pass.loads ?? []).every(handle => pass.writes.some(other => equal(handle, other)))) { throw "A loaded attachment must be a pass output"; } this.passes.push(pass); } upload(handle: Handle, data: bytes, destination: i64 = 0): void throws string { if (this.consumed) { throw "Render graph was already consumed"; } if (destination <0 || destination % 4 !== 0 || data.length % 4 !== 0) { throw "Unaligned GPU buffer upload"; } for (const previous of this.uploads) { if (!equal(handle, previous.handle)) { continue; } const first = Math.maxI64(destination, previous.destination); const end = Math.minI64(destination+data.length, previous.destination+previous.size); if (first> = end) { continue; } if (data.slice(first-destination, end-destination) !== this.payload.slice(previous.offset+first-previous.destination, previous.offset+end-previous.destination)) { throw "Conflicting buffer updates in one render graph; batch instances into one draw"; } if (destination === previous.destination && data.length === previous.size) { return; } } let payload = this.payload; this.payload = b""; this.uploads.push({ handle, offset: payload.length, size: data.length, destination }); payload+ = data; this.payload = payload; } texture(resources: Resources, format: string, width: i64, height: i64, depth: i64, layers: i64, levels: Vec<Level>): Handle throws string { let size: i64 = 0; for (const level of levels) { size+ = level.body.length; } const dimension = depth> 0 ? "3d": "2d"; const extent = depth> 0 ? depth: layers; return this.transaction(resources, (): Handle throws string => { const handle = resources.create("texture", parseUnique(`{"size":[${width }, ${ height }, ${ extent }], "dimension": "${ dimension }", "format": "${ format }", "mipLevelCount": ${ levels.length }, "usage": ${ TEXTURE_COPY_DST | TEXTURE_BINDING } }`)!, size); for (const mip of range(0, levels.length)) { const level = levels[mip]; this.image(handle, level.body, level.width, level.height, 0, 0, mip, 0, level.depth, format); } return handle; }); } image(handle: Handle, pixels: bytes, width: i64, height: i64, x: i64 = 0, y: i64 = 0, mip: i64 = 0, z: i64 = 0, depth: i64 = 1, format: string = "rgba8unorm"): void throws string { if (this.consumed) { throw "Render graph was already consumed"; } const block = textureFormat(format); if (!block.upload || x <0 || y <0 || z <0 || mip <0 || mip> 14 || x%block.width !== 0 || y%block.height !== 0 || pixels.length !== textureSize(format, width, height, depth)) { throw "Invalid texture block upload"; } let payload = this.payload; this.payload = b""; this.images.push({ handle, offset: payload.length, size: pixels.length, width, height, depth, x, y, z, mip, format }); payload+ = pixels; this.payload = payload; } packet(resources: Resources, measure: bool = false): bytes throws string { if (this.consumed) { throw "Render packet was already consumed"; } if (this.editing> 0) { throw "Cannot publish a render graph during a transaction"; } let initialized = new Set<string>(); let written: Vec<Handle> = []; let uploads: Vec<Upload> = []; let payload = b""; let sent: Vec<{ handle: Handle; held: Held; }> = []; let drawn: Vec<Handle> = []; for (const upload of this.uploads) { const resource = resources.get(upload.handle); if (resource.kind !== "buffer" || upload.destination> resource.bytes || upload.size> resource.bytes - upload.destination) { throw "Upload exceeds its GPU buffer"; } const data = this.payload.slice(upload.offset, upload.offset+upload.size); if (resources.holds(upload.handle, upload.destination, data)) { continue; } uploads.push({ ...upload, offset: payload.length }); payload+ = data; sent.push({ handle: upload.handle, held: { destination: upload.destination, data } }); if (upload.destination === 0 && upload.size === resource.bytes) { initialized.add(key(upload.handle)); written.push(upload.handle); } } let complete = new Set<string>(); let touched: Vec<Handle> = []; let images: Vec<ImageUpload> = []; for (const image of this.images) { images.push({ ...image, offset: payload.length }); payload+ = this.payload.slice(image.offset, image.offset+image.size); const resource = resources.get(image.handle); if (resource.kind !== "texture" || resource.descriptor.field("format").text() !== image.format || resource.descriptor.field("sampleCount").integerOr(1) !== 1) { throw "Texture upload format or sample count differs"; } const extent = resource.descriptor.field("size").list(); const levels = resource.descriptor.field("mipLevelCount").integerOr(1); const divisor = 1 <<image.mip; if (extent.length <2 || image.mip> = levels) { throw "Texture upload needs a declared mip and extent"; } const width = Math.maxI64(1, extent[0].integer()/divisor); const height = Math.maxI64(1, extent[1].integer()/divisor); const layers = extent.length> 2 ? extent[2].integer(): 1; const depth = resource.descriptor.field("dimension").text() === "3d" ? Math.maxI64(1, layers/divisor): layers; const block = textureFormat(image.format); if (image.x+image.width> width || image.y+image.height> height || image.z+image.depth> depth || image.width%block.width !== 0 && image.x+image.width !== width || image.height%block.height !== 0 && image.y+image.height !== height) { throw "Texture upload exceeds its mip or block boundary"; } if (!touched.some(handle => equal(handle, image.handle))) { touched.push(image.handle); } if (image.x === 0 && image.y === 0 && image.width === width && image.height === height) { for (const layer of range(image.z, image.z+image.depth)) { complete.add(`${key(image.handle) }/${ image.mip }/${ layer }`); } } } for (const handle of touched) { const resource = resources.get(handle); const extent = resource.descriptor.field("size").list(); const levels = resource.descriptor.field("mipLevelCount").integerOr(1); const layers = extent.length> 2 ? extent[2].integer(): 1; let all = true; for (const mip of range(0, levels)) { const depth = resource.descriptor.field("dimension").text() === "3d" ? Math.maxI64(1, layers/(1 <<mip)): layers; for (const layer of range(0, depth)) { if (!complete.has(`${key(handle) }/${ mip }/${ layer }`)) { all = false; } } } if (all) { initialized.add(key(handle)); written.push(handle); } } let ordered: Vec<Pass> = []; for (const pass of this.passes) { if (pass.after.some(name => !this.passes.some(other => other.name === name) || name === pass.name)) { throw "Unknown render pass dependency"; } } const after = this.passes.map(pass => pass.after.map(name => this.passes.findIndex(other => other.name === name))); const batches = dependencyBatches(after, (left: i64, right: i64): bool => { const a = this.passes[left]; const b = this.passes[right]; return intersects(a.writes, [...b.reads, ...b.writes, ...(b.loads ?? [])]) || intersects([...a.reads, ...(a.loads ?? [])], b.writes); }); for (const chosen of batches.flat()) { const pass = this.passes[chosen]; for (const handle of pass.reads) { if (pass.writes.some(other => equal(handle, other)) && (equal(handle, surface()) || resources.get(handle).kind !== "buffer")) { throw "A pass must not sample and write the same texture"; } } let reached = dependencies(pass.descriptor, true); for (const command of pass.commands) { for (const argument of command.args) { reached = [...reached, ...dependencies(argument, true)]; } } let visited = new Set<string>(); let at: i64 = 0; while (at <reached.length) { const handle = reached[at]; at+ = 1; if (visited.has(key(handle))) { continue; } visited.add(key(handle)); const declaration = resources.get(handle); if (["buffer", "texture", "querySet"].includes(declaration.kind) && ![...pass.reads, ...pass.writes].some(access => equal(access, handle))) { throw `Undeclared GPU pass resource: ${pass.name }`; } reached = [...reached, ...declaration.dependencies]; } for (const handle of [...pass.reads, ...pass.writes]) { if (!equal(handle, surface())) { resources.get(handle); } } for (const handle of [...pass.reads, ...(pass.loads ?? [])]) { if (!initialized.has(key(handle)) && !resources.initialized(handle)) { throw `Read before GPU initialization: ${pass.name }`; } } for (const handle of pass.writes) { initialized.add(key(handle)); written.push(handle); drawn.push(handle); } ordered.push(pass); } let out = b""; let temporary: Vec<Handle> = []; resources.transaction((): void throws string => { let timings: { buffer: Handle; names: Vec<string>; } | undefined = undefined; const measured = ordered.filter(pass => pass.kind !== "copy"); if (measure && measured.length> 0) { if (measured.length> 2048 || measured.some(pass => pass.descriptor.field("timestampWrites").kind !== "null")) { throw "Graph timing needs at most 2048 passes without application timestamp writes"; } const count = measured.length*2; const size = count*8; const queries = resources.create("querySet", parseUnique(`{"type":"timestamp","count":${count } }`)!, size); const resolved = resources.buffer(size, BUFFER_QUERY_RESOLVE | BUFFER_COPY_SRC); const buffer = resources.buffer(size, BUFFER_MAP_READ | BUFFER_COPY_DST); temporary = [buffer, resolved, queries]; let index: i64 = 0; ordered = ordered.map(pass => { if (pass.kind === "copy") { return pass; } const descriptor = pass.descriptor.with("timestampWrites", parseUnique(`{"querySet":${encode(reference(queries)) }, "beginningOfPassWriteIndex": ${ index }, "endOfPassWriteIndex": ${ index+1 } }`)!); index+ = 2; return { ...pass, descriptor, writes: [...pass.writes, queries] }; }); ordered.push({ name: "$profile-resolve", kind: "copy", descriptor: parseUnique("{}")!, reads: [queries], writes: [resolved, buffer], after: [], commands: [{ method: "resolveQuerySet", args: [reference(queries), parseUnique("0")!, parseUnique(`${count }`)!, reference(resolved), parseUnique("0")!] }, { method: "copyBufferToBuffer", args: [reference(resolved), parseUnique("0")!, reference(buffer), parseUnique("0")!, parseUnique(`${size }`)!] }] }); timings = { buffer, names: measured.map(pass => pass.name) }; } const packet: Packet = { version: 1, resources: resources.pending(), releases: resources.retiring(), uploads, images, passes: ordered, timings }; const header = utf8(encode(packet)); if (header.length> 16777216) { throw "Render packet metadata exceeds 16 MiB"; } out = b"GIZGPU01"; writeU32LE(out, u64(header.length)); out+ = header; out+ = payload; }); resources.publish(written, sent, drawn); this.consumed = true; for (const handle of temporary) { resources.release(handle); } return out; } }
```

One frame's render/compute passes and uploads. Independent from World, Canvas and the app that owns its surface.

- `passes`: `Vec<gizlang_render.Pass>`
- `uploads`: `Vec<gizlang_render.Upload>`
- `images`: `Vec<gizlang_render.ImageUpload>`
- `payload`: `bytes`
- `consumed`: `bool`
- `editing`: `i64`

## Functions

### `textureFormat`

```gizlang
function textureFormat(name: string): TextureFormat throws string
```

The block layout and device feature of the WebGPU texture format NAME; an unknown name throws.

Effects: fail, alloc.

### `textureSize`

```gizlang
function textureSize(format: string, width: i64, height: i64, depth: i64 = 1): i64 throws string
```

Packed bytes for one logical mip rectangle, including compressed edge blocks and depth/layers.

Effects: fail, alloc.

### `surface`

```gizlang
function surface(): Handle
```

The presentation texture of the active surface, resolved once for each submitted frame.

### `reference`

```gizlang
function reference(handle: Handle): Json
```

A typed reference in a WebGPU descriptor. The host resolves it to a GPU object, never a process address.

Effects: fail, alloc.

### `textureView`

```gizlang
function textureView(handle: Handle, descriptor: Json = { kind: "object", keys: [], values: [] }): Json
```

A texture view, including optional mip/layer/aspect selection. Views share their texture's allocation.

Effects: fail, alloc.

### `constructor`

```gizlang
constructor(limit: i64 = 268435456)
```

The maximum declared GPU allocation bytes. The host validates actual descriptor sizes independently.

Effects: fail, read, write, alloc.

## Methods

### `Resources.bytes`

```gizlang
bytes(): i64
```

Bytes reserved by live resources.

Effects: fail, read.

### `Resources.available`

```gizlang
available(): i64
```

Unreserved bytes available for new declarations in this owner.

Effects: fail, read.

### `Resources.transaction`

```gizlang
transaction<T>(work: () => T throws string): T throws string
```

Applies synchronous declaration edits atomically and returns what WORK made. Publication and recovery cannot occur inside an edit.

### `Resources.create`

```gizlang
create(kind: string, descriptor: Json, bytes: i64 = 0): Handle throws string
```

Creates a declaration after validating its kind, dependencies and memory budget.

Effects: fail, read, write, alloc.

### `Resources.buffer`

```gizlang
buffer(size: i64, usage: i64): Handle throws string
```

A buffer of SIZE bytes for USAGE (the BUFFER_ flags).

Effects: fail, read, write, alloc.

### `Resources.get`

```gizlang
get(handle: Handle): Resource throws string
```

A live declaration. The presentation texture has no application-owned declaration.

Effects: fail, read.

### `Resources.release`

```gizlang
release(handle: Handle): void throws string
```

Releases only a resource that no live declaration depends on. The host defers physical destruction.

Effects: fail, read, write, alloc.

### `Resources.recover`

```gizlang
recover(): void throws string
```

Marks declarations for reconstruction after device loss. Buffer/texture content must be uploaded again.

Effects: fail, read, write, alloc.

### `Resources.initialized`

```gizlang
initialized(handle: Handle): bool throws string
```

Whether data was written before this frame.

Effects: fail, read.

### `Resources.invalidate`

```gizlang
invalidate(handle: Handle): void throws string
```

Invalidates CPU-owned content after an asset changes. Its next read must follow a new upload or graph write.

Effects: fail, read, write, alloc.

### `Resources.publish`

```gizlang
publish(written: Vec<Handle>, sent: Vec<{ handle: Handle; held: Held; }>, drawn: Vec<Handle>): void throws string
```

SENT are the packet's uploads in order and DRAWN the buffers its passes write: a pass write makes held bytes unknown.

Effects: fail, read, write, alloc.

### `Resources.holds`

```gizlang
holds(handle: Handle, destination: i64, data: bytes): bool throws string
```

Whether the buffer of HANDLE holds DATA at DESTINATION already, so an upload of them changes nothing.

Effects: fail, read.

### `Resources.pending`

```gizlang
pending(): Vec<Resource> throws string
```

Unpublished declarations in dependency order, including slots reused since the previous frame.

Effects: fail, read, write, console, io, alloc.

### `Resources.retiring`

```gizlang
retiring(): Vec<Handle>
```

Handles to retire after the submitted GPU work finishes.

Effects: fail, read.

### `Graph.transaction`

```gizlang
transaction<T>(resources: Resources, work: () => T throws string): T throws string
```

Stages resources and uploads together and returns what WORK made; a failed conversion leaves neither stale graph entries nor allocations.

### `Graph.add`

```gizlang
add(pass: Pass): void throws string
```

Appends a pass. Clear ownership and names are checked before any GPU submission.

Effects: fail, read, write, alloc.

### `Graph.upload`

```gizlang
upload(handle: Handle, data: bytes, destination: i64 = 0): void throws string
```

Adds one aligned buffer update to the frame's binary tail; no JSON/base64 copy of the data.

Effects: fail, read, write, alloc.

### `Graph.texture`

```gizlang
texture(resources: Resources, format: string, width: i64, height: i64, depth: i64, layers: i64, levels: Vec<Level>): Handle throws string
```

A sampled texture of LEVELS (mip 0 first), declared and uploaded in one transaction: the one texture upload of
decoded images and KTX2 files. DEPTH > 0 makes a 3D texture; else LAYERS is its array layers.

Effects: fail, read, write, console, io, alloc.

### `Graph.image`

```gizlang
image(handle: Handle, pixels: bytes, width: i64, height: i64, x: i64 = 0, y: i64 = 0, mip: i64 = 0, z: i64 = 0, depth: i64 = 1, format: string = "rgba8unorm"): void throws string
```

Uploads packed uncompressed or BC/ETC2/ASTC blocks without another decoder, transfer path or resource manager.

Effects: fail, read, write, alloc.

### `Graph.packet`

```gizlang
packet(resources: Resources, measure: bool = false): bytes throws string
```

Compiles the graph and consumes its publication changes. Consume the returned packet exactly once.

Effects: fail, read, write, console, io, alloc.

## Constants

### `FORMAT_SOURCE`

```gizlang
const FORMAT_SOURCE = `{
  "r8unorm": [1, 1, 1, true, ""],
  "r8snorm": [1, 1, 1, true, ""],
  "r8uint": [1, 1, 1, true, ""],
  "r8sint": [1, 1, 1, true, ""],
  "r16unorm": [1, 1, 2, true, "texture-formats-tier1"],
  "r16snorm": [1, 1, 2, true, "texture-formats-tier1"],
  "r16uint": [1, 1, 2, true, ""],
  "r16sint": [1, 1, 2, true, ""],
  "r16float": [1, 1, 2, true, ""],
  "rg8unorm": [1, 1, 2, true, ""],
  "rg8snorm": [1, 1, 2, true, ""],
  "rg8uint": [1, 1, 2, true, ""],
  "rg8sint": [1, 1, 2, true, ""],
  "r32uint": [1, 1, 4, true, ""],
  "r32sint": [1, 1, 4, true, ""],
  "r32float": [1, 1, 4, true, ""],
  "rg16unorm": [1, 1, 4, true, "texture-formats-tier1"],
  "rg16snorm": [1, 1, 4, true, "texture-formats-tier1"],
  "rg16uint": [1, 1, 4, true, ""],
  "rg16sint": [1, 1, 4, true, ""],
  "rg16float": [1, 1, 4, true, ""],
  "rgba8unorm": [1, 1, 4, true, ""],
  "rgba8unorm-srgb": [1, 1, 4, true, ""],
  "rgba8snorm": [1, 1, 4, true, ""],
  "rgba8uint": [1, 1, 4, true, ""],
  "rgba8sint": [1, 1, 4, true, ""],
  "bgra8unorm": [1, 1, 4, true, ""],
  "bgra8unorm-srgb": [1, 1, 4, true, ""],
  "rgb10a2uint": [1, 1, 4, true, ""],
  "rgb10a2unorm": [1, 1, 4, true, ""],
  "rg11b10ufloat": [1, 1, 4, true, ""],
  "rgb9e5ufloat": [1, 1, 4, true, ""],
  "rg32uint": [1, 1, 8, true, ""],
  "rg32sint": [1, 1, 8, true, ""],
  "rg32float": [1, 1, 8, true, ""],
  "rgba16unorm": [1, 1, 8, true, "texture-formats-tier1"],
  "rgba16snorm": [1, 1, 8, true, "texture-formats-tier1"],
  "rgba16uint": [1, 1, 8, true, ""],
  "rgba16sint": [1, 1, 8, true, ""],
  "rgba16float": [1, 1, 8, true, ""],
  "rgba32uint": [1, 1, 16, true, ""],
  "rgba32sint": [1, 1, 16, true, ""],
  "rgba32float": [1, 1, 16, true, ""],
  "stencil8": [1, 1, 1, false, ""],
  "depth16unorm": [1, 1, 2, false, ""],
  "depth24plus": [1, 1, 4, false, ""],
  "depth24plus-stencil8": [1, 1, 8, false, ""],
  "depth32float": [1, 1, 4, false, ""],
  "depth32float-stencil8": [1, 1, 8, false, "depth32float-stencil8"],
  "bc1-rgba-unorm": [4, 4, 8, true, "texture-compression-bc"],
  "bc1-rgba-unorm-srgb": [4, 4, 8, true, "texture-compression-bc"],
  "bc2-rgba-unorm": [4, 4, 16, true, "texture-compression-bc"],
  "bc2-rgba-unorm-srgb": [4, 4, 16, true, "texture-compression-bc"],
  "bc3-rgba-unorm": [4, 4, 16, true, "texture-compression-bc"],
  "bc3-rgba-unorm-srgb": [4, 4, 16, true, "texture-compression-bc"],
  "bc4-r-unorm": [4, 4, 8, true, "texture-compression-bc"],
  "bc4-r-snorm": [4, 4, 8, true, "texture-compression-bc"],
  "bc5-rg-unorm": [4, 4, 16, true, "texture-compression-bc"],
  "bc5-rg-snorm": [4, 4, 16, true, "texture-compression-bc"],
  "bc6h-rgb-ufloat": [4, 4, 16, true, "texture-compression-bc"],
  "bc6h-rgb-float": [4, 4, 16, true, "texture-compression-bc"],
  "bc7-rgba-unorm": [4, 4, 16, true, "texture-compression-bc"],
  "bc7-rgba-unorm-srgb": [4, 4, 16, true, "texture-compression-bc"],
  "etc2-rgb8unorm": [4, 4, 8, true, "texture-compression-etc2"],
  "etc2-rgb8unorm-srgb": [4, 4, 8, true, "texture-compression-etc2"],
  "etc2-rgb8a1unorm": [4, 4, 8, true, "texture-compression-etc2"],
  "etc2-rgb8a1unorm-srgb": [4, 4, 8, true, "texture-compression-etc2"],
  "etc2-rgba8unorm": [4, 4, 16, true, "texture-compression-etc2"],
  "etc2-rgba8unorm-srgb": [4, 4, 16, true, "texture-compression-etc2"],
  "eac-r11unorm": [4, 4, 8, true, "texture-compression-etc2"],
  "eac-r11snorm": [4, 4, 8, true, "texture-compression-etc2"],
  "eac-rg11unorm": [4, 4, 16, true, "texture-compression-etc2"],
  "eac-rg11snorm": [4, 4, 16, true, "texture-compression-etc2"],
  "astc-4x4-unorm": [4, 4, 16, true, "texture-compression-astc"],
  "astc-4x4-unorm-srgb": [4, 4, 16, true, "texture-compression-astc"],
  "astc-5x4-unorm": [5, 4, 16, true, "texture-compression-astc"],
  "astc-5x4-unorm-srgb": [5, 4, 16, true, "texture-compression-astc"],
  "astc-5x5-unorm": [5, 5, 16, true, "texture-compression-astc"],
  "astc-5x5-unorm-srgb": [5, 5, 16, true, "texture-compression-astc"],
  "astc-6x5-unorm": [6, 5, 16, true, "texture-compression-astc"],
  "astc-6x5-unorm-srgb": [6, 5, 16, true, "texture-compression-astc"],
  "astc-6x6-unorm": [6, 6, 16, true, "texture-compression-astc"],
  "astc-6x6-unorm-srgb": [6, 6, 16, true, "texture-compression-astc"],
  "astc-8x5-unorm": [8, 5, 16, true, "texture-compression-astc"],
  "astc-8x5-unorm-srgb": [8, 5, 16, true, "texture-compression-astc"],
  "astc-8x6-unorm": [8, 6, 16, true, "texture-compression-astc"],
  "astc-8x6-unorm-srgb": [8, 6, 16, true, "texture-compression-astc"],
  "astc-8x8-unorm": [8, 8, 16, true, "texture-compression-astc"],
  "astc-8x8-unorm-srgb": [8, 8, 16, true, "texture-compression-astc"],
  "astc-10x5-unorm": [10, 5, 16, true, "texture-compression-astc"],
  "astc-10x5-unorm-srgb": [10, 5, 16, true, "texture-compression-astc"],
  "astc-10x6-unorm": [10, 6, 16, true, "texture-compression-astc"],
  "astc-10x6-unorm-srgb": [10, 6, 16, true, "texture-compression-astc"],
  "astc-10x8-unorm": [10, 8, 16, true, "texture-compression-astc"],
  "astc-10x8-unorm-srgb": [10, 8, 16, true, "texture-compression-astc"],
  "astc-10x10-unorm": [10, 10, 16, true, "texture-compression-astc"],
  "astc-10x10-unorm-srgb": [10, 10, 16, true, "texture-compression-astc"],
  "astc-12x10-unorm": [12, 10, 16, true, "texture-compression-astc"],
  "astc-12x10-unorm-srgb": [12, 10, 16, true, "texture-compression-astc"],
  "astc-12x12-unorm": [12, 12, 16, true, "texture-compression-astc"],
  "astc-12x12-unorm-srgb": [12, 12, 16, true, "texture-compression-astc"]
}
`
```

WebGPU texture formats: block width, block height, block bytes, upload support and required device feature. The browser
host consumes this same JSON (gizapp/surface `giz/gpu-formats.js`); the SDK bundle holds .giz files only.

### `BUFFER_MAP_READ`

```gizlang
const BUFFER_MAP_READ = 1
```

The CPU maps it to read.

### `BUFFER_COPY_SRC`

```gizlang
const BUFFER_COPY_SRC = 4
```

A copy reads it.

### `BUFFER_COPY_DST`

```gizlang
const BUFFER_COPY_DST = 8
```

A copy or a write fills it.

### `BUFFER_INDEX`

```gizlang
const BUFFER_INDEX = 16
```

It holds indices.

### `BUFFER_VERTEX`

```gizlang
const BUFFER_VERTEX = 32
```

It holds vertices.

### `BUFFER_UNIFORM`

```gizlang
const BUFFER_UNIFORM = 64
```

A shader reads it as uniforms.

### `BUFFER_STORAGE`

```gizlang
const BUFFER_STORAGE = 128
```

A shader reads and writes it as storage.

### `BUFFER_QUERY_RESOLVE`

```gizlang
const BUFFER_QUERY_RESOLVE = 512
```

Queries resolve into it.

### `TEXTURE_COPY_DST`

```gizlang
const TEXTURE_COPY_DST = 2
```

A copy or a write fills it.

### `TEXTURE_BINDING`

```gizlang
const TEXTURE_BINDING = 4
```

A shader samples it.

### `TEXTURE_RENDER_ATTACHMENT`

```gizlang
const TEXTURE_RENDER_ATTACHMENT = 16
```

A pass renders into it.

