gizlang/render
Render scheduling and its host packet. No game state, UI framework, window, driver or global device is owned here.
import * as Render from "gizlang/render";Types
Level
type Level = { width: i64; height: i64; depth: i64; body: bytes; }One mip of a texture: its logical size and its packed texel blocks.
width:i64height:i64depth:i64body:bytes
TextureFormat
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:i64height:i64bytes:i64upload:boolfeature:string
Handle
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:i64generation:i64
Surface
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:stringdisplay:u64window:u64
Resource
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.Handlekind:stringdescriptor:gizlang_json.Jsondependencies:Vec<gizlang_render.Handle>bytes:i64
Command
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:stringargs:Vec<gizlang_json.Json>
Pass
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:stringkind:stringdescriptor:gizlang_json.Jsonreads: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
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.Handleoffset:i64size:i64destination:i64
ImageUpload
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.Handleoffset:i64size:i64width:i64height:i64depth:i64x:i64y:i64z:i64mip:i64format:string
Resources
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:i64limit:i64serial:i64editing:i64
Graph
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:bytesconsumed:boolediting:i64
Functions
textureFormat
function textureFormat(name: string): TextureFormat throws stringThe block layout and device feature of the WebGPU texture format NAME; an unknown name throws.
Effects: fail, alloc.
textureSize
function textureSize(format: string, width: i64, height: i64, depth: i64 = 1): i64 throws stringPacked bytes for one logical mip rectangle, including compressed edge blocks and depth/layers.
Effects: fail, alloc.
surface
function surface(): HandleThe presentation texture of the active surface, resolved once for each submitted frame.
reference
function reference(handle: Handle): JsonA typed reference in a WebGPU descriptor. The host resolves it to a GPU object, never a process address.
Effects: fail, alloc.
textureView
function textureView(handle: Handle, descriptor: Json = { kind: "object", keys: [], values: [] }): JsonA texture view, including optional mip/layer/aspect selection. Views share their texture's allocation.
Effects: fail, alloc.
constructor
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
bytes(): i64Bytes reserved by live resources.
Effects: fail, read.
Resources.available
available(): i64Unreserved bytes available for new declarations in this owner.
Effects: fail, read.
Resources.transaction
transaction<T>(work: () => T throws string): T throws stringApplies synchronous declaration edits atomically and returns what WORK made. Publication and recovery cannot occur inside an edit.
Resources.create
create(kind: string, descriptor: Json, bytes: i64 = 0): Handle throws stringCreates a declaration after validating its kind, dependencies and memory budget.
Effects: fail, read, write, alloc.
Resources.buffer
buffer(size: i64, usage: i64): Handle throws stringA buffer of SIZE bytes for USAGE (the BUFFER_ flags).
Effects: fail, read, write, alloc.
Resources.get
get(handle: Handle): Resource throws stringA live declaration. The presentation texture has no application-owned declaration.
Effects: fail, read.
Resources.release
release(handle: Handle): void throws stringReleases only a resource that no live declaration depends on. The host defers physical destruction.
Effects: fail, read, write, alloc.
Resources.recover
recover(): void throws stringMarks declarations for reconstruction after device loss. Buffer/texture content must be uploaded again.
Effects: fail, read, write, alloc.
Resources.initialized
initialized(handle: Handle): bool throws stringWhether data was written before this frame.
Effects: fail, read.
Resources.invalidate
invalidate(handle: Handle): void throws stringInvalidates 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
publish(written: Vec<Handle>, sent: Vec<{ handle: Handle; held: Held; }>, drawn: Vec<Handle>): void throws stringSENT 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
holds(handle: Handle, destination: i64, data: bytes): bool throws stringWhether the buffer of HANDLE holds DATA at DESTINATION already, so an upload of them changes nothing.
Effects: fail, read.
Resources.pending
pending(): Vec<Resource> throws stringUnpublished declarations in dependency order, including slots reused since the previous frame.
Effects: fail, read, write, console, io, alloc.
Resources.retiring
retiring(): Vec<Handle>Handles to retire after the submitted GPU work finishes.
Effects: fail, read.
Graph.transaction
transaction<T>(resources: Resources, work: () => T throws string): T throws stringStages resources and uploads together and returns what WORK made; a failed conversion leaves neither stale graph entries nor allocations.
Graph.add
add(pass: Pass): void throws stringAppends a pass. Clear ownership and names are checked before any GPU submission.
Effects: fail, read, write, alloc.
Graph.upload
upload(handle: Handle, data: bytes, destination: i64 = 0): void throws stringAdds one aligned buffer update to the frame's binary tail; no JSON/base64 copy of the data.
Effects: fail, read, write, alloc.
Graph.texture
texture(resources: Resources, format: string, width: i64, height: i64, depth: i64, layers: i64, levels: Vec<Level>): Handle throws stringA 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
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 stringUploads packed uncompressed or BC/ETC2/ASTC blocks without another decoder, transfer path or resource manager.
Effects: fail, read, write, alloc.
Graph.packet
packet(resources: Resources, measure: bool = false): bytes throws stringCompiles the graph and consumes its publication changes. Consume the returned packet exactly once.
Effects: fail, read, write, console, io, alloc.
Constants
FORMAT_SOURCE
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
const BUFFER_MAP_READ = 1The CPU maps it to read.
BUFFER_COPY_SRC
const BUFFER_COPY_SRC = 4A copy reads it.
BUFFER_COPY_DST
const BUFFER_COPY_DST = 8A copy or a write fills it.
BUFFER_INDEX
const BUFFER_INDEX = 16It holds indices.
BUFFER_VERTEX
const BUFFER_VERTEX = 32It holds vertices.
BUFFER_UNIFORM
const BUFFER_UNIFORM = 64A shader reads it as uniforms.
BUFFER_STORAGE
const BUFFER_STORAGE = 128A shader reads and writes it as storage.
BUFFER_QUERY_RESOLVE
const BUFFER_QUERY_RESOLVE = 512Queries resolve into it.
TEXTURE_COPY_DST
const TEXTURE_COPY_DST = 2A copy or a write fills it.
TEXTURE_BINDING
const TEXTURE_BINDING = 4A shader samples it.
TEXTURE_RENDER_ATTACHMENT
const TEXTURE_RENDER_ATTACHMENT = 16A pass renders into it.