@adobe/ecs-gpu 0.0.0-stage → 0.0.1

package/src/surface/surface.ts

@@ -0,0 +1,140 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type Entity, Finalizer, System, type Vec2, type World } from "@adobe/ecs";
+import * as Target from "../target/public.js";
+
+/** How a surface presents: how its alpha composites with the page, its color space, and its tone mapping. */
+export type Options = {
+    readonly alphaMode: GPUCanvasAlphaMode;
+    readonly colorSpace: PredefinedColorSpace;
+    readonly toneMapping: GPUCanvasToneMappingMode;
+};
+
+export const Options = {
+    default: { alphaMode: "opaque", colorSpace: "srgb", toneMapping: "standard" },
+} as const;
+
+/** A surface's canvas, configured for the world's device in its target's format. */
+export type State = {
+    readonly entity: Entity;
+    readonly canvas: OffscreenCanvas;
+    readonly context: GPUCanvasContext;
+    readonly device: GPUDevice;
+    readonly format: GPUTextureFormat;
+    readonly options: Options;
+};
+
+/**
+ * A render target with these presents to a canvas: the canvas, on the world's thread, and how it presents. The
+ * canvas's size follows the target's.
+ */
+export const canvas = Symbol("Surface.canvas");
+export const options = Symbol("Surface.options");
+/** Each surface's configured canvas, by its entity: null until surfaces are first updated. */
+export const states = Symbol("Surface.states");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [canvas]: { type: OffscreenCanvas; transfer: true };
+        [options]: { type: Options };
+    }
+    interface Resources {
+        [states]: { type: ReadonlyMap<Entity, State> | null };
+    }
+}
+
+/**
+ * A surface presenting to `canvas`, moved to the world's thread, of `width` by `height` pixels: a canvas's
+ * `transferControlToOffscreen()`, or an `OffscreenCanvas` of its own. Resolves to its entity.
+ */
+export const attach = System.create({}, ({ commands }, input: {
+    readonly canvas: OffscreenCanvas;
+    readonly width: number;
+    readonly height: number;
+    readonly target?: Target.Options;
+    readonly surface?: Options;
+}) => commands.spawn([Target.options, Target.size, canvas, options])({
+    [Target.options]: input.target ?? Target.Options.default,
+    [Target.size]: [Math.max(1, Math.floor(input.width)), Math.max(1, Math.floor(input.height))],
+    [canvas]: input.canvas,
+    [options]: input.surface ?? Options.default,
+}));
+
+const sameOptions = (a: Options, b: Options): boolean => a.alphaMode === b.alphaMode && a.colorSpace === b.colorSpace && a.toneMapping === b.toneMapping;
+
+/** A surface as an index lists it: its entity, canvas, options and its target's size. */
+export type Listed = { readonly entity: Entity; readonly [canvas]: OffscreenCanvas; readonly [options]: Options; readonly [Target.size]: Vec2.U32 };
+
+/**
+ * Each surface's canvas sized to its target and configured for `device` in its target's format, again where either
+ * changed; with no device, or no target state, unconfigured. Gives `previous` itself when nothing changed.
+ */
+export const updated = (device: GPUDevice | null, targets: ReadonlyMap<Entity, Target.State>, previous: ReadonlyMap<Entity, State> | null, surfaces: { readonly length: number; at(index: number): Listed }): ReadonlyMap<Entity, State> => {
+    const held = previous ?? new Map<Entity, State>();
+    let next: Map<Entity, State> | null = null;
+    for (let i = 0; i < surfaces.length; i++) {
+        const surface = surfaces.at(i);
+        const presented = surface[canvas];
+        const [width, height] = surface[Target.size];
+        if (presented.width !== width) presented.width = width;
+        if (presented.height !== height) presented.height = height;
+        const target = targets.get(surface.entity);
+        const old = held.get(surface.entity);
+        if (device === null || target === undefined) {
+            if (old === undefined) continue;
+            old.context.unconfigure();
+            next ??= new Map(held);
+            next.delete(surface.entity);
+            continue;
+        }
+        const declared = surface[options];
+        if (old !== undefined && old.device === device && old.format === target.format && old.canvas === presented && sameOptions(old.options, declared)) continue;
+        const context = presented.getContext("webgpu");
+        if (context === null) continue;
+        context.configure({
+            device, format: target.format, usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_DST,
+            alphaMode: declared.alphaMode, colorSpace: declared.colorSpace, toneMapping: { mode: declared.toneMapping },
+        });
+        next ??= new Map(held);
+        next.set(surface.entity, { entity: surface.entity, canvas: presented, context, device, format: target.format, options: declared });
+    }
+    return next ?? held;
+};
+
+/** Unconfigures a surface's canvas when it stops being one. */
+export const release = Finalizer.create({ components: { with: [canvas] } }, (surface, { resources }) => {
+    const current = resources[states];
+    const state = current?.get(surface.entity);
+    if (current === null || state === undefined) return;
+    state.context.unconfigure();
+    const next = new Map(current);
+    next.delete(surface.entity);
+    resources[states] = next;
+});
+
+/** A canvas's size in device pixels, from what a `ResizeObserver` saw of it. */
+const pixelsOf = (entry: ResizeObserverEntry): readonly [number, number] => {
+    const [device] = entry.devicePixelContentBoxSize ?? [];
+    if (device !== undefined) return [device.inlineSize, device.blockSize];
+    const [box] = entry.contentBoxSize;
+    const scale = globalThis.devicePixelRatio ?? 1;
+    return box === undefined ? [entry.contentRect.width * scale, entry.contentRect.height * scale] : [box.inlineSize * scale, box.blockSize * scale];
+};
+
+/**
+ * Keeps a surface's size the size of `element` on the page, in device pixels, on the thread the page is on: the world
+ * may be here or on a worker that joined it. Returns a function that stops.
+ */
+export const observe = (element: Element, world: Pick<World, "run">, surface: Entity): (() => void) => {
+    const observer = new ResizeObserver(entries => {
+        const entry = entries.at(-1);
+        if (entry === undefined) return;
+        const [width, height] = pixelsOf(entry);
+        world.run(Target.resize, { target: surface, width, height }).catch(reportError);
+    });
+    try {
+        observer.observe(element, { box: "device-pixel-content-box" });
+    } catch {
+        observer.observe(element);
+    }
+    return () => observer.disconnect();
+};

package/src/target/public.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { Options, options, release, resize, size, states, type State } from "./target.js";

package/src/target/target.ts

@@ -0,0 +1,133 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type Entity, Finalizer, System, type Vec2, type Vec4 } from "@adobe/ecs";
+
+/**
+ * What a render target draws into: its color format, null for the platform's preferred canvas format; its samples per
+ * pixel, more than one drawing multisampled and resolving into its color; its depth format, null for none; and the
+ * color it's cleared to each frame, null to keep what it holds.
+ */
+export type Options = {
+    readonly format: GPUTextureFormat | null;
+    readonly sampleCount: 1 | 4;
+    readonly depthFormat: GPUTextureFormat | null;
+    readonly clear: Vec4 | null;
+};
+
+export const Options = {
+    default: { format: null, sampleCount: 1, depthFormat: "depth24plus", clear: [0, 0, 0, 1] },
+} as const;
+
+/**
+ * A target's textures on the world's device. `color` holds what's drawn, single-sampled, for reading and presenting;
+ * with more than one sample, passes draw into `multisampled` and resolve into `color`. `size` is in pixels.
+ */
+export type State = {
+    readonly entity: Entity;
+    readonly device: GPUDevice;
+    readonly options: Options;
+    readonly format: GPUTextureFormat;
+    readonly size: Vec2.U32;
+    readonly color: GPUTexture;
+    readonly multisampled: GPUTexture | null;
+    readonly depth: GPUTexture | null;
+};
+
+/** An entity with these is a render target: what its textures are, and their size in pixels. */
+export const options = Symbol("Target.options");
+export const size = Symbol("Target.size");
+/** Each render target's textures on the world's device, by its entity: null until targets are first updated. */
+export const states = Symbol("Target.states");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [options]: { type: Options };
+        [size]: { type: Vec2.U32 };
+    }
+    interface Resources {
+        [states]: { type: ReadonlyMap<Entity, State> | null };
+    }
+}
+
+const sameOptions = (a: Options, b: Options): boolean =>
+    a.format === b.format && a.sampleCount === b.sampleCount && a.depthFormat === b.depthFormat
+    && (a.clear === b.clear || (a.clear !== null && b.clear !== null && a.clear.every((value, index) => value === b.clear?.[index])));
+
+const destroyTextures = (state: State): void => {
+    state.color.destroy();
+    state.multisampled?.destroy();
+    state.depth?.destroy();
+};
+
+const created = (device: GPUDevice, entity: Entity, declared: Options, [width, height]: Vec2.U32): State => {
+    const format = declared.format ?? navigator.gpu.getPreferredCanvasFormat();
+    const extent = [width, height];
+    const color = device.createTexture({
+        label: `target ${entity} color`, size: extent, format,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC | GPUTextureUsage.COPY_DST,
+    });
+    const multisampled = declared.sampleCount === 1 ? null : device.createTexture({
+        label: `target ${entity} multisampled`, size: extent, format, sampleCount: declared.sampleCount, usage: GPUTextureUsage.RENDER_ATTACHMENT,
+    });
+    const depth = declared.depthFormat === null ? null : device.createTexture({
+        label: `target ${entity} depth`, size: extent, format: declared.depthFormat, sampleCount: declared.sampleCount,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+    });
+    return { entity, device, options: declared, format, size: [width, height], color, multisampled, depth };
+};
+
+/** A render target as an index lists it: its entity, options and size. */
+export type Listed = { readonly entity: Entity; readonly [options]: Options; readonly [size]: Vec2.U32 };
+
+/**
+ * Each render target's textures on `device`, made again where its options, its size or the device changed, destroying
+ * those they replace; with no device, none. Gives `previous` itself when nothing changed.
+ */
+export const updated = (device: GPUDevice | null, previous: ReadonlyMap<Entity, State> | null, targets: { readonly length: number; at(index: number): Listed }): ReadonlyMap<Entity, State> => {
+    const held = previous ?? new Map<Entity, State>();
+    let next: Map<Entity, State> | null = null;
+    for (let i = 0; i < targets.length; i++) {
+        const target = targets.at(i);
+        const old = held.get(target.entity);
+        const [width, height] = target[size];
+        if (device !== null && old !== undefined && old.device === device && old.size[0] === width && old.size[1] === height && sameOptions(old.options, target[options])) continue;
+        if (device === null && old === undefined) continue;
+        next ??= new Map(held);
+        if (old !== undefined) destroyTextures(old);
+        if (device === null) next.delete(target.entity);
+        else next.set(target.entity, created(device, target.entity, target[options], target[size]));
+    }
+    return next ?? held;
+};
+
+/** Records clearing each target that declares a clear color: its color to that color, and its depth to 1. */
+export const recordClears = (encoder: GPUCommandEncoder, targets: ReadonlyMap<Entity, State>): void => {
+    for (const target of targets.values()) {
+        const color = target.options.clear;
+        if (color === null) continue;
+        const [r, g, b, a] = color;
+        encoder.beginRenderPass({
+            label: `clear target ${target.entity}`,
+            colorAttachments: [{
+                view: (target.multisampled ?? target.color).createView(), resolveTarget: target.multisampled === null ? undefined : target.color.createView(),
+                clearValue: { r, g, b, a }, loadOp: "clear", storeOp: "store",
+            }],
+            depthStencilAttachment: target.depth === null ? undefined : { view: target.depth.createView(), depthClearValue: 1, depthLoadOp: "clear", depthStoreOp: "store" },
+        }).end();
+    }
+};
+
+/** Destroys a render target's textures when it stops being one. */
+export const release = Finalizer.create({ components: { with: [options, size] } }, (target, { resources }) => {
+    const current = resources[states];
+    const state = current?.get(target.entity);
+    if (current === null || state === undefined) return;
+    destroyTextures(state);
+    const next = new Map(current);
+    next.delete(target.entity);
+    resources[states] = next;
+});
+
+/** Sets a render target's size in pixels, at least one by one. */
+export const resize = System.create({ components: { with: [size] }, target: "target" }, (row, _context, input: { readonly target: Entity; readonly width: number; readonly height: number }) => {
+    row[size] = [Math.max(1, Math.floor(input.width)), Math.max(1, Math.floor(input.height))];
+});

package/src/view/public.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { begin, layout, projection, release, states, target, viewport, wgsl, type State } from "./view.js";

package/src/view/view.ts

@@ -0,0 +1,125 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type Entity, Finalizer, type Mat4x4, type Vec4 } from "@adobe/ecs";
+import { perDevice } from "../cache/cache.js";
+import * as Target from "../target/public.js";
+
+/**
+ * A view's place on its target's device: the target, its rectangle in the target in pixels (`x`, `y`, `width`,
+ * `height`), and the uniform buffer and bind group holding its projection and size, for `wgsl`'s declarations.
+ */
+export type State = {
+    readonly entity: Entity;
+    readonly target: Target.State;
+    readonly rectangle: readonly [number, number, number, number];
+    readonly projection: Mat4x4;
+    readonly buffer: GPUBuffer;
+    readonly bindGroup: GPUBindGroup;
+};
+
+/**
+ * An entity with these is a view: the render target it draws into, which owns it; its rectangle in that target as
+ * fractions of its size (`x`, `y`, `width`, `height`); and the matrix taking its scene to clip space.
+ */
+export const target = Symbol("View.target");
+export const viewport = Symbol("View.viewport");
+export const projection = Symbol("View.projection");
+/** Each view's state on the world's device, by its entity: null until views are first updated. */
+export const states = Symbol("View.states");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [target]: { type: Entity; reference: "owner" };
+        [viewport]: { type: Vec4; default: [0, 0, 1, 1] };
+        [projection]: { type: Mat4x4 };
+    }
+    interface Resources {
+        [states]: { type: ReadonlyMap<Entity, State> | null };
+    }
+}
+
+/** The uniform each view binds: its projection, then its size in pixels. */
+const uniformBytes = 80;
+
+const layouts = perDevice((device: GPUDevice, _key: null) => device.createBindGroupLayout({
+    label: "view",
+    entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT | GPUShaderStage.COMPUTE, buffer: { type: "uniform" } }],
+}), () => "");
+
+/** The bind group layout of a view's uniform, one per device: a pipeline's layout takes it at the group `wgsl` names. */
+export const layout = (device: GPUDevice): GPUBindGroupLayout => layouts(device, null);
+
+/** The WGSL declarations of a view's uniform at bind group `group`: `view.projection` and `view.size`, in pixels. */
+export const wgsl = (group: number): string =>
+    `struct View { projection: mat4x4f, size: vec2f }\n@group(${group}) @binding(0) var<uniform> view: View;\n`;
+
+const rectangleOf = ([x, y, width, height]: Vec4, [targetWidth, targetHeight]: readonly [number, number]): readonly [number, number, number, number] => {
+    const left = Math.min(targetWidth - 1, Math.max(0, Math.round(x * targetWidth)));
+    const top = Math.min(targetHeight - 1, Math.max(0, Math.round(y * targetHeight)));
+    return [left, top, Math.max(1, Math.min(targetWidth - left, Math.round(width * targetWidth))), Math.max(1, Math.min(targetHeight - top, Math.round(height * targetHeight)))];
+};
+
+const sameRectangle = (a: readonly number[], b: readonly number[]): boolean => a.every((value, index) => value === b[index]);
+const sameMatrix = (a: Mat4x4, b: Mat4x4): boolean => a.every((value, index) => value === b[index]);
+
+/** A view as an index lists it: its entity, target, viewport and projection. */
+export type Listed = { readonly entity: Entity; readonly [target]: Entity; readonly [viewport]: Vec4; readonly [projection]: Mat4x4 };
+
+/**
+ * Each view placed in its target, its uniform written where its projection or rectangle changed; a view whose target
+ * has no textures, as without a device, has no state. Gives `previous` itself when nothing changed.
+ */
+export const updated = (device: GPUDevice | null, targets: ReadonlyMap<Entity, Target.State>, previous: ReadonlyMap<Entity, State> | null, views: { readonly length: number; at(index: number): Listed }): ReadonlyMap<Entity, State> => {
+    const held = previous ?? new Map<Entity, State>();
+    let next: Map<Entity, State> | null = null;
+    for (let i = 0; i < views.length; i++) {
+        const view = views.at(i);
+        const old = held.get(view.entity);
+        const drawn = device === null ? undefined : targets.get(view[target]);
+        if (device === null || drawn === undefined) {
+            if (old === undefined) continue;
+            old.buffer.destroy();
+            next ??= new Map(held);
+            next.delete(view.entity);
+            continue;
+        }
+        const rectangle = rectangleOf(view[viewport], drawn.size);
+        const matrix = view[projection];
+        if (old !== undefined && old.target === drawn && sameRectangle(old.rectangle, rectangle) && sameMatrix(old.projection, matrix)) continue;
+        const kept = old !== undefined && old.target.device === device;
+        if (old !== undefined && !kept) old.buffer.destroy();
+        const buffer = kept ? old.buffer : device.createBuffer({ label: `view ${view.entity}`, size: uniformBytes, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        const bindGroup = kept ? old.bindGroup : device.createBindGroup({ layout: layout(device), entries: [{ binding: 0, resource: { buffer } }] });
+        device.queue.writeBuffer(buffer, 0, new Float32Array([...matrix, rectangle[2], rectangle[3], 0, 0]));
+        next ??= new Map(held);
+        next.set(view.entity, { entity: view.entity, target: drawn, rectangle, projection: matrix, buffer, bindGroup });
+    }
+    return next ?? held;
+};
+
+/** Destroys a view's uniform buffer when it stops being one. */
+export const release = Finalizer.create({ components: { with: [target, viewport, projection] } }, (view, { resources }) => {
+    const current = resources[states];
+    const state = current?.get(view.entity);
+    if (current === null || state === undefined) return;
+    state.buffer.destroy();
+    const next = new Map(current);
+    next.delete(view.entity);
+    resources[states] = next;
+});
+
+/**
+ * Begins a render pass drawing into a view: its target's textures, loading what they hold, limited to its rectangle,
+ * multisampled passes resolving into the target's color.
+ */
+export const begin = (encoder: GPUCommandEncoder, view: State, label?: string): GPURenderPassEncoder => {
+    const { color, multisampled, depth } = view.target;
+    const pass = encoder.beginRenderPass({
+        label,
+        colorAttachments: [{ view: (multisampled ?? color).createView(), resolveTarget: multisampled === null ? undefined : color.createView(), loadOp: "load", storeOp: "store" }],
+        depthStencilAttachment: depth === null ? undefined : { view: depth.createView(), depthLoadOp: "load", depthStoreOp: "store" },
+    });
+    const [x, y, width, height] = view.rectangle;
+    pass.setViewport(x, y, width, height, 0, 1);
+    pass.setScissorRect(x, y, width, height);
+    return pass;
+};