compute

The compute namespace — 46 functions.

compute/compile

compute.compile(nameOrHandle, opts)

Compile + register a zero-scaffolding .computeShader. The author writes ONLY @compute fn main (no @group/@binding); the engine generates the entire group(0) interface from the declared schema and registers it via the mixed-binding Ex path. opts: { source, entryPoint = "main", bindings = { { name, kind, access?, element?, format? }, ... }, params = { { name, type, default }, ... } }. kind ∈ buffer|texture3d|texture2d|storage3d|storage2d|sampler. Internal — driven by the .computeShader assetType.

compute/createSampler

compute.createSampler(name, opts?)

Create a named sampler. opts: { filter = true, clamp = true }. The volume manager always provides 'linear_clamp', 'linear_repeat', 'nearest_clamp' by default.

compute/createStorageTexture2D

compute.createStorageTexture2D(name, opts)

Create a 2D storage texture used as a volume-shader output (raymarch target). opts: { width, height, format = "rgba16f" }.

compute/createTexture3D

compute.createTexture3D(name, opts)

Create a 3D texture. opts: { width, height, depth, format = "rgba16f", storage = true }. format is one of r8/r16f/r32f/rgba8/rgba16f/rgba32f. storage = true (default) lets compute shaders write to it.

compute/createTextureHistory

compute.createTextureHistory(name, opts)

Create a double-buffered 2D storage texture pair for temporal accumulation. Bind kind = "history_prev" to read the previous frame, kind = "history_curr" to write the current frame; the renderer flips them once per frame. opts: { width, height, format = "rgba16f" }.

compute/destroyShaderEx

compute.destroyShaderEx(name)

Destroy a registered volume shader.

compute/destroyStorageTexture2D

compute.destroyStorageTexture2D(name)

Destroy a named volume render target.

compute/destroyTexture3D

compute.destroyTexture3D(name)

Destroy a named 3D volume and free its GPU memory.

compute/destroyTextureHistory

compute.destroyTextureHistory(name)

Destroy a named texture-history pair.

compute/dispatchEx

compute.dispatchEx(shaderNameOrHandle, opts)

Dispatch a volume shader. Accepts a shader name string or an asset handle from asset.resolve(...). opts: { resources = { {kind, name}, ... }, workgroups = {x,y,z} }. Resource kinds: 'volume', 'render_target', 'sampler', 'buffer', 'texture_2d', 'history_prev', 'history_curr', 'scene_depth'. 'scene_depth' needs no name: it binds the engine's per-frame scene-depth blit (R32Float, depth in .r, 1.0 = far/sky) to a texture_2d slot — read it with textureLoad to depth-clamp a raymarch against opaque geometry.

compute/readTexture3D

compute.readTexture3D(name)

Start a GPU→CPU readback of a named 3D volume. Returns a result key — poll with compute.getReadbackResult() (the readback channel is shared).

compute/registerShaderEx

compute.registerShaderEx(nameOrHandle, opts?)

Register a volume compute shader. Accepts an asset handle from asset.resolve(...) (preferred — the engine reuses the cached source) or (name, opts) with inline WGSL. opts: { source?, entry = "main", bindings = {...} }. Each binding is { kind = "texture_3d|texture_2d|storage_3d|storage_2d|sampler|storage_buffer|uniform_buffer", format = "rgba16f"?, readOnly = false? }.

compute/setParam

compute.setParam(name, prop, value)

Write one scalar field of a compiled .computeShader's params uniform. No-op (logged warning) if the shader or param is unknown.

compute/textureFormatBytes

compute.textureFormatBytes(format)

Bytes per voxel for a format name. Returns 0 for unknown formats.

compute/writeFloatsTexture3D

compute.writeFloatsTexture3D(name, floats, formatOrOpts?)

Upload float values into a named 3D volume. Values are packed into bytes using the supplied format string (or opts.format), defaulting to rgba16f. Pass the same format the volume was created with.

compute/writeTexture3D

compute.writeTexture3D(name, data)

Upload raw bytes (interpreted as u8) into a named 3D volume. Byte count must match the volume's dimensions * format bytes-per-voxel.

globals/compute/compile

globals/compute/compile(nameOrHandle: string | { [string]: any } | AssetRef, opts: { [string]: any }?) -> boolean

Compile a compute shader from inline WGSL + a declarative binding schema — the same codegen a .computeShader asset uses. The engine generates the @group/@binding declarations from bindings/params, so the source writes only @compute fn main. Symmetric with registerShader, but with zero-scaffolding bindings (incl. textures, samplers, storage textures and a params uniform). For asset-backed shaders prefer authoring a .computeShader (compiled automatically); use this for dynamic/generated compute shaders.

globals/compute/compileByName

globals/compute/compileByName(ref: string | { [string]: any } | AssetRef)

Optional explicit pre-warm for a .computeShader asset (idempotent — fingerprint-guarded). NORMALLY UNNECESSARY: compute.dispatch / dispatchEx auto-compile a .computeShader on first use. Reach for this only to avoid the one-frame first-dispatch warm-up in a latency-critical spot. Accepts an identity/guid string or a resolved asset handle (its .identity is used).

globals/compute/createBuffer

globals/compute/createBuffer(name: string, opts: BufferOpts) -> boolean

Create a named GPU storage buffer.

globals/compute/createSampler

globals/compute/createSampler(name: string, opts: { [string]: any }?) -> boolean

Create a named GPU sampler. opts: filter/wrap settings.

globals/compute/createStorageTexture2D

globals/compute/createStorageTexture2D(name: string, opts: { [string]: any }) -> boolean

Create a 2D storage texture (compute-writable render target). opts: { width, height, format? }.

globals/compute/createTexture3D

globals/compute/createTexture3D(name: string, opts: { [string]: any }) -> boolean

Create a 3D texture volume. opts: { width, height, depth, format?, storage? }.

globals/compute/createTextureHistory

globals/compute/createTextureHistory(name: string, opts: { [string]: any }) -> boolean

Create a temporal history buffer (ping-pong textures) for a target. opts: { width, height, format? }.

globals/compute/destroyBuffer

globals/compute/destroyBuffer(name: string) -> boolean

Destroy a named GPU compute buffer and free its memory.

globals/compute/destroyShader

globals/compute/destroyShader(name: string) -> boolean

Destroy a named compute shader pipeline.

globals/compute/destroyShaderEx

globals/compute/destroyShaderEx(name: string) -> boolean

Destroy a shader registered via registerShaderEx.

globals/compute/destroyStorageTexture2D

globals/compute/destroyStorageTexture2D(name: string) -> boolean

Destroy a named 2D storage texture.

globals/compute/destroyTexture3D

globals/compute/destroyTexture3D(name: string) -> boolean

Destroy a named 3D volume and free its GPU memory.

globals/compute/destroyTextureHistory

globals/compute/destroyTextureHistory(name: string) -> boolean

Destroy a named texture-history buffer.

globals/compute/dispatch

globals/compute/dispatch(shaderNameOrHandle: string | { [string]: any } | AssetRef, opts: DispatchOpts) -> boolean

Dispatch a compute shader with bound buffers. Accepts a shader name string or an asset handle from asset.load().

globals/compute/dispatchEx

globals/compute/dispatchEx(shaderNameOrHandle: string | { [string]: any } | AssetRef, opts: { [string]: any }) -> boolean

Dispatch a compute shader with extended texture/storage/sampler bindings. Asset-backed .computeShaders resolve to their stable guid (collision-safe, lazily compiled on first dispatch); raw registerShaderEx names pass through.

globals/compute/dispatchOnVertices

globals/compute/dispatchOnVertices(shaderNameOrHandle: string | { [string]: any } | AssetRef, opts: DispatchOnVerticesOpts) -> boolean

Dispatch a compute shader with a model's vertex buffer bound at binding 0 (read_write). Use to mutate vertex positions directly.

globals/compute/getReadbackResult

globals/compute/getReadbackResult(resultKey: string) -> { number }?

Poll for a completed read-back. Returns array of f32 values if ready, nil if pending. Result is consumed on retrieval.

globals/compute/getReadbackResultU32

globals/compute/getReadbackResultU32(resultKey: string) -> { number }?

Poll for a completed read-back interpreting bytes as u32. Returns array of integer values if ready, nil if pending.

globals/compute/isReadbackReady

globals/compute/isReadbackReady(resultKey: string) -> boolean

Check if a readback result is available without consuming it.

globals/compute/readBuffer

globals/compute/readBuffer(bufferName: string) -> string

Start an async GPU→CPU read-back of a named buffer. The buffer must have been created with readback = true. Returns a result key to poll with getReadbackResult().

globals/compute/readTexture3D

globals/compute/readTexture3D(name: string) -> string

Start a GPU→CPU readback of a named 3D volume. Returns a result key to poll.

globals/compute/registerShader

globals/compute/registerShader(nameOrHandle: string | { [string]: any } | AssetRef, opts: ShaderOpts?) -> boolean

Register a compute shader. Accepts an asset handle from asset.load(), or (name, opts) with inline WGSL source.

globals/compute/registerShaderEx

globals/compute/registerShaderEx(nameOrHandle: string | { [string]: any } | AssetRef, opts: { [string]: any }?) -> boolean

Register a compute shader with extended texture/sampler bindings. Accepts a name + opts or an asset handle.

globals/compute/setParam

globals/compute/setParam(name: string, prop: string, value: number) -> boolean

Set a named scalar parameter on a .computeShader (a params: entry in its bindings.yaml). Updates the shader's params uniform in place; the next dispatch sees the new value. No effect on raw registerShader shaders, which have no params block.

globals/compute/textureFormatBytes

globals/compute/textureFormatBytes(format: string) -> number

Bytes-per-voxel for a texture format string (rgba16f, r8, ...).

globals/compute/writeBuffer

globals/compute/writeBuffer(name: string, data: { number }, offset: number?) -> boolean

Write an array of floats to a named GPU buffer (little- endian f32 bytes).

globals/compute/writeBufferBytes

globals/compute/writeBufferBytes(name: string, bytes: string, offset: number?) -> boolean

Write the raw bytes of a binary string to a named GPU buffer, verbatim. For packed binary that already matches a GPU layout (decoded vertex / index / record pools, file bytes, a network message) — no number-array round trip, unlike writeBuffer / writeBufferU32 which reinterpret each element as one f32 / u32.

globals/compute/writeBufferU32

globals/compute/writeBufferU32(name: string, data: { number }, offset: number?) -> boolean

Write an array of unsigned integers to a named GPU buffer (little-endian u32 bytes).

globals/compute/writeFloatsTexture3D

globals/compute/writeFloatsTexture3D(name: string, floats: { number }, formatOrOpts: (string | { [string]: any })?) -> boolean

Upload float values into a named 3D volume, packed via the given format (default rgba16f).

globals/compute/writeTexture3D

globals/compute/writeTexture3D(name: string, data: { number }) -> boolean

Upload raw bytes (u8) into a named 3D volume.