@zenfg/webgpu

@zenfg/webgpu is a lightweight WebGPU FrameGraph for declaring and executing per-frame GPU work. It orders graph nodes, validates resource access, culls unused work, derives WebGPU usage, tracks lifetimes, and reuses transient textures and buffers.

Build rendering features directly with WebGPU or compatible libraries, and combine them with existing renderers through explicit graph integration. See the composition model.

It is not a renderer abstraction. ZenFG owns graph-visible dependencies, execution order, retention, transient allocation, and optional diagnostics. The caller owns scenes, pipelines, bind groups, samplers, long-lived resources, surface presentation, device-loss policy, and concrete draw or dispatch work.

This is a public beta package. Pin the exact prerelease version while integrating. Import runtime APIs from the package root; the only supported diagnostic subpath is @zenfg/webgpu/snapshot.

Installation

npm install @zenfg/webgpu@0.1.0

Quick start

Run this in a browser module served from HTTPS or localhost, with native WebGPU enabled. The host supplies a GPUDevice and a configured canvas GPUCanvasContext. Call renderFrame() from the host animation loop; the canvas clears to dark blue. For a ready-to-run canvas host, open the minimal-frame recipe in the Examples.

Keep one FrameGraph for the lifetime of a GPUDevice. Create a fresh recording and import a fresh current surface texture for every presentation frame. This complete example needs no render pipeline because it only clears the surface attachment:

import { FrameGraph } from '@zenfg/webgpu';

// `device` and the configured `context` are caller-owned.
const graph = new FrameGraph(device);
let frameIndex = 0;

function renderFrame(): void {
	const recorder = graph.beginFrame();
	const backbuffer = recorder.importSwapchainTexture(
		context.getCurrentTexture(),
		{ label: 'backbuffer' },
	);

	recorder.render({
		label: 'clear-backbuffer',
		colorAttachments: [{
			target: backbuffer,
			loadOp: 'clear',
			storeOp: 'store',
			clearValue: { r: 0.04, g: 0.06, b: 0.1, a: 1 },
		}],
	});

	recorder.markPresent(backbuffer);
	recorder.compile().execute({ frameIndex: frameIndex++ });
}

// When the device-bound renderer stack is released:
// graph.destroy();

markPresent() makes the final surface value observable. Without a resource root or a side-effect node, work that contributes to no result is culled. Normal execution records and submits synchronously; only optional GPU timing returns an asynchronous readback result.

Lifecycle

FrameGraph runtime -> FrameGraphRecorder -> CompiledFrame
device lifetime       one recording        retained executable plan

• FrameGraph is permanently bound to one caller-owned GPUDevice and owns the transient pool and lazy profiler resources.
• beginFrame() creates an independent, single-use recording. A successful or failed compile() consumes it.
• Handles, views, and access tokens are local to one recording.
• A compiled frame can be re-executed only while all captured callbacks and imported GPU objects remain valid. Presentation recordings normally should not be re-executed.
• destroy() releases runtime-owned resources; it never destroys the device or imported resources.

Common tasks

Task	Public API
Create the device-bound runtime	new FrameGraph(device)
Start a recording	beginFrame()
Create transient storage	createTexture(), createBuffer()
Import caller-owned storage	importTexture(), importBuffer()
Import the current presentation target	importSwapchainTexture()
Select texture subresources	createTextureView()
Declare typed resource access	use() with TextureAccess or BufferAccess
Record structured work	render(), compute(), copy(), clearBuffer()
Encode custom graph-owned commands	command()
Call a renderer that submits itself	externalSubmission()
Retain observable values	markPresent(), markOutput(), markReadback(), markDebugCapture(), markPersistentState()
Compile a compact executable plan	compile()
Request full compilation diagnostics	compile({ report: true })
Execute and optionally request timing/debug groups	compiled.execute()
Inspect or clear retained allocations	getResourcePoolStats(), clearResourcePool()
Export portable diagnostics	createFrameGraphSnapshot() from @zenfg/webgpu/snapshot
Release runtime-owned resources	destroy()

Exact fields, overloads, defaults, return types, and failure conditions are documented by the TSDoc preserved in the packaged source and declarations.

Key pattern: declare, list, and unwrap access

use() creates an opaque typed token. A node must list that exact token in uses before its synchronous callback can resolve it with unwrap():

const sampledSceneColor = recorder.use(
	sceneColor,
	TextureAccess.Sampled,
);

recorder.render({
	label: 'present',
	uses: [sampledSceneColor],
	colorAttachments: [{
		target: backbuffer,
		loadOp: 'clear',
		storeOp: 'store',
	}],
	encode({ pass, unwrap }) {
		const sceneColorView = unwrap(sampledSceneColor);
		pass.setPipeline(presentPipeline);
		pass.setBindGroup(0, createPresentBindGroup(sceneColorView));
		pass.draw(3);
	},
});

Resolved transient objects are callback-scoped. Do not cache them across callbacks or frames. The complete transient-to-present.ts recipe shows the pipeline and bind-group setup without placeholder helpers.

Resource and integration choices

Declaration granularity is optional: complex workloads can keep private weights, parameters, and scratch internally bound, while teaching or diagnostic use can expose more resources. Graph-visible dependencies and access correctness still apply. See Choosing resource declaration granularity.

For resources exposed to the graph:

• Create a transient resource when native storage is needed only for the compiled frame. Import a resource when the caller owns its native storage or it must survive execution.
• Transient and surface contents begin undefined. The first write to a transient range must fully overwrite it. Use preserve for partial, conditional, sparse, or atomic writes.
• Use structured render, compute, copy, and clear nodes whenever possible. Use command() for custom work on a FrameGraph-owned encoder.
• Use externalSubmission() when a third-party renderer owns and submits its encoders. The node orders queue submissions but is not a GPU-completion fence.
• Acquire, import, compile, execute, and present a fresh surface texture on each presentation frame.

See Core concepts for the complete ownership, content, dependency, lifetime, and integration model.

Diagnostics and Snapshot

Compilation reports, CPU/GPU timing, and pool statistics are opt-in and independent. Requesting them does not change the execution plan. Convert matching reports to the portable protocol through @zenfg/webgpu/snapshot; ordinary compile and execute paths do not create Snapshot data.

Snapshot export produces an in-memory value only. Capture naming, filesystem storage, transport, and retention policy remain caller-owned. The language- neutral wire contract is defined by the @zenfg/snapshot specification.

Use compiled.executeWithTiming({ frameIndex, timing: 'cpu' }), choosing 'cpu', 'gpu' or 'both'. The returned cpu report is immediately available; consume gpu as a Promise only when requested. Ordinary execute() remains synchronous and does not collect timing. CPU duration is elapsed time, not thread CPU usage, and covers every executed node kind. Keep compilation, frame identity and pool counters from the same execution when exporting.

Common mistakes

Symptom	Fix
A node disappears from execution	Retain its final value with the correct root, or mark only genuine side effects as such.
A read or preserving write reports undefined contents	Clear or fully overwrite the selected range first, or declare imported initial contents correctly.
The first transient write is rejected	Use overwrite only when the complete declared range is written.
unwrap() rejects a token	List the same token in the active node's uses; never cross a recording boundary.
The same native object is imported twice	Import it once at the composition boundary and share the logical handle.
A later presentation frame fails	Do not reuse an old current texture or compiled presentation frame.
Work after an external node starts too early	Queue all declared external work on the shared device queue before the callback returns.
Timing is unavailable	Treat unsupported, busy, and readback-failed as non-fatal results.

Complete recipes

The following files are published with the package and type-checked as consumers of supported public entrypoints:

Workflow	Recipe
Minimal presentation lifecycle	minimal-frame.ts
Transient render target to presentation	transient-to-present.ts
Caller-owned imported resource	imported-resource.ts
Cross-frame persistent state	persistent-state.ts
Opaque third-party submission	external-submission.ts
Portable Snapshot export	snapshot-export.ts
Asynchronous GPU timing	gpu-timing.ts
Compute storage output	compute-output.ts

GPU-dependent recipes are compile-checked. CPU-only workflows also execute in CI. See the examples index for their input contracts.

Further reading

• ZenFG documentation index
• Core concepts
• @zenfg/snapshot
• @zenfg/inspector
• Compatibility

Documentation and versions

This README describes @zenfg/webgpu 0.1.0. Registry badges show the current published channel, not your installed version.

• Exact installed APIs: follow package.json → exports → dist/*.d.ts; declaration maps point to the included src/. Only declared export paths are public.
• Online guide (development branch). The site may describe changes newer than this package.
• TypeScript API (development branch).
• Source and documentation for this release.
• Shared concepts for this release and compatibility.
• Plain Markdown documentation index (development branch).
• Local complete recipes: examples.