vgpu-render 0.0.0-stage → 0.2.0

package/dist/gpu-debug-draw-2d.js

@@ -0,0 +1,450 @@
+/**
+ * GPU renderer for the 2D debug-draw layer.
+ *
+ * The 2D primitives are the 3D ones under a different projection. `camera-2d.ts` produces a clip
+ * matrix that lands `world2d`/`screen` pixels on the near plane, and the line, point and joint
+ * shaders already do everything after the projection in screen space — pixel widths, dash phase,
+ * joint wedges, the near-plane clip. So this renderer reuses that WGSL verbatim (injected as
+ * `shaders`, because the 3D renderer owns the source and must not be imported back) and only
+ * supplies its own instance buffers, indirect draws and camera uniforms.
+ *
+ * `world2d` and `screen` commands need different matrices, and one draw binds one uniform, so each
+ * space gets its own bucket of primitives. The layer draws after every 3D primitive with depth
+ * write off, which is what makes the 2D overlay unconditionally cover the 3D world.
+ */
+import { compute, draw, geometry, storage } from "vgpu";
+import { prepareShader } from "@vgpu/wgsl/prepare";
+import { instanceGeometry } from "vgpu/scene/gpu";
+import { instances } from "vgpu/scene";
+import { DEFAULT_CAMERA_2D, projection2D } from "./camera-2d.js";
+import { identity, indirectArgs, INDIRECT_SHADER, trim, world, zeroGeometry } from "./gpu-instancing.js";
+import { shape2dShader } from "./shape2d-shader.js";
+/** Must match the `SHAPE_*` constants in `shape2d-shader.ts`. */
+const SHAPE2D_CODES = {
+    "rect": 0,
+    "rounded-rect": 1,
+    "circle": 2,
+    "ellipse": 3,
+    "arc": 4,
+    "annulus": 5,
+    "capsule": 6,
+    "polygon": 7,
+    "triangle": 8,
+    "rhombus": 9,
+    "sector": 10,
+    "segment": 11,
+};
+/** One view matrix, shared by every 2D draw: the layer never applies the back-face normal fade. */
+const IDENTITY_VIEW = identity();
+const ZERO_NORMAL = [0, 0, 0];
+function sameVec2(a, b) {
+    return a[0] === b[0] && a[1] === b[1];
+}
+function sameColor(a, b) {
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2] && a[3] === b[3];
+}
+function samePoint2D(a, b) {
+    return sameVec2(a.position, b.position) && sameColor(a.color, b.color) && a.size === b.size && a.sizeMode === b.sizeMode && a.round === b.round;
+}
+function sameLine2D(a, b) {
+    return (sameVec2(a.start, b.start) &&
+        sameVec2(a.end, b.end) &&
+        sameColor(a.color, b.color) &&
+        sameColor(a.colorEnd, b.colorEnd) &&
+        a.width === b.width &&
+        a.widthMode === b.widthMode &&
+        a.dash?.[0] === b.dash?.[0] &&
+        a.dash?.[1] === b.dash?.[1] &&
+        a.dash?.[2] === b.dash?.[2] &&
+        a.joint === b.joint);
+}
+function sameJoint2D(a, b) {
+    return (sameVec2(a.previous, b.previous) &&
+        sameVec2(a.center, b.center) &&
+        sameVec2(a.next, b.next) &&
+        sameColor(a.color, b.color) &&
+        a.width === b.width &&
+        a.widthMode === b.widthMode &&
+        a.joint === b.joint &&
+        a.dash?.[0] === b.dash?.[0] &&
+        a.dash?.[1] === b.dash?.[1] &&
+        a.dash?.[2] === b.dash?.[2]);
+}
+function sameShape2D(a, b) {
+    return (a.shape === b.shape &&
+        sameVec2(a.center, b.center) &&
+        sameVec2(a.size, b.size) &&
+        sameVec2(a.vertexB, b.vertexB) &&
+        sameVec2(a.vertexC, b.vertexC) &&
+        a.cornerRadius === b.cornerRadius &&
+        a.thickness === b.thickness &&
+        a.filled === b.filled &&
+        a.rotation === b.rotation &&
+        a.startAngle === b.startAngle &&
+        a.sweep === b.sweep &&
+        a.sides === b.sides &&
+        sameColor(a.color, b.color));
+}
+/** Two-dimensional point lifted onto the near plane the projection matrix maps to. */
+function lift2D(point) {
+    return [point[0], point[1], 0];
+}
+/** Circle that bounds the shape at any rotation: the instanced quad's extent in shape space. */
+function boundingRadius(command) {
+    const [x, y] = command.size;
+    switch (command.shape) {
+        case "rect":
+        case "rounded-rect":
+        case "rhombus":
+            return Math.hypot(x, y);
+        case "ellipse":
+            return Math.max(x, y);
+        case "capsule":
+            return y + x;
+        case "triangle": {
+            const corners = [command.size, command.vertexB, command.vertexC];
+            return Math.max(...corners.map((corner) => Math.hypot(corner[0], corner[1])));
+        }
+        default:
+            // circle, arc, annulus (x is the outer radius), polygon, sector and segment.
+            return x;
+    }
+}
+function jointGeometry(gpu, vertexCount) {
+    return geometry(gpu, {
+        buffers: [{ attributes: { position: "float32x3" }, data: new Float32Array(vertexCount * 3) }],
+        vertexCount,
+        topology: "triangle-list",
+    });
+}
+/**
+ * The primitives of one 2D space. Separate instance collections from the 3D layer, because one
+ * draw binds one camera uniform and both layers can be visible in the same frame.
+ */
+class SpaceBucket2D {
+    space;
+    #points;
+    #lines;
+    #joints;
+    #shapes;
+    #pointIds = [];
+    #lineIds = [];
+    #jointIds = [];
+    #shapeIds = [];
+    #pointCache = [];
+    #lineCache = [];
+    #jointCache = [];
+    #shapeCache = [];
+    #pointBridge;
+    #lineBridge;
+    #jointBridge;
+    #shapeBridge;
+    #pointDraw;
+    #lineDraw;
+    #jointDraw;
+    #shapeDraw;
+    #pointIndirect;
+    #lineIndirect;
+    #jointIndirect;
+    #shapeIndirect;
+    #indirectCompute;
+    #jointVertexCount;
+    #pointCount = 0;
+    #lineCount = 0;
+    #jointCount = 0;
+    #shapeCount = 0;
+    #pointDirty = true;
+    #lineDirty = true;
+    #jointDirty = true;
+    #shapeDirty = true;
+    constructor(gpu, space, options, capacities) {
+        this.space = space;
+        this.#jointVertexCount = options.jointVertexCount;
+        this.#points = instances({ capacity: capacities.points, attributes: { point: "float32x3", color: "float32x4", size: "float32", flags: "uint32" } });
+        this.#lines = instances({ capacity: capacities.lines, attributes: { start: "float32x3", end: "float32x3", color: "float32x4", colorEnd: "float32x4", width: "float32", flags: "uint32", dash: "float32x3", normal: "float32x3", joint: "uint32" } });
+        this.#joints = instances({ capacity: capacities.joints, attributes: { previous: "float32x3", center: "float32x3", next: "float32x3", color: "float32x4", width: "float32", flags: "uint32", dash: "float32x3", joint: "uint32", previousNormal: "float32x3", nextNormal: "float32x3" } });
+        this.#shapes = instances({ capacity: capacities.shapes, attributes: { shape: "uint32", center: "float32x3", size: "float32x2", vertexB: "float32x2", vertexC: "float32x2", params: "float32x4", rotationRadius: "float32x2", color: "float32x4", flags: "uint32" } });
+        this.#pointBridge = instanceGeometry(gpu, this.#points, { mesh: zeroGeometry(gpu) });
+        this.#lineBridge = instanceGeometry(gpu, this.#lines, { mesh: zeroGeometry(gpu) });
+        this.#jointBridge = instanceGeometry(gpu, this.#joints, { mesh: jointGeometry(gpu, options.jointVertexCount) });
+        this.#shapeBridge = instanceGeometry(gpu, this.#shapes, { mesh: zeroGeometry(gpu) });
+        // No depth write: the 2D layer is an overlay, and the projection puts it on the near plane
+        // where a "less-equal" test against anything the 3D layer drew succeeds.
+        const depth = { write: false, compare: "less-equal" };
+        this.#pointDraw = draw(gpu, { shader: prepareShader(options.shaders.point), geometry: this.#pointBridge.geometry, instances: 0, blend: "alpha", cull: "none", depth });
+        this.#lineDraw = draw(gpu, { shader: prepareShader(options.shaders.line), geometry: this.#lineBridge.geometry, instances: 0, blend: "alpha", cull: "none", depth });
+        this.#jointDraw = draw(gpu, { shader: prepareShader(options.shaders.joint), geometry: this.#jointBridge.geometry, instances: 0, blend: "alpha", cull: "none", depth });
+        this.#shapeDraw = draw(gpu, { shader: prepareShader(shape2dShader()), geometry: this.#shapeBridge.geometry, instances: 0, blend: "alpha", cull: "none", depth });
+        this.#pointIndirect = storage(gpu, 16, { access: "read-write", indirect: true });
+        this.#lineIndirect = storage(gpu, 16, { access: "read-write", indirect: true });
+        this.#jointIndirect = storage(gpu, 16, { access: "read-write", indirect: true });
+        this.#shapeIndirect = storage(gpu, 16, { access: "read-write", indirect: true });
+        this.#indirectCompute = compute(gpu, INDIRECT_SHADER);
+        indirectArgs(this.#pointIndirect, 6, 0);
+        indirectArgs(this.#lineIndirect, 6, 0);
+        indirectArgs(this.#jointIndirect, options.jointVertexCount, 0);
+        indirectArgs(this.#shapeIndirect, 6, 0);
+    }
+    prepare(points, lines, joints, shapes) {
+        this.#pointDirty = false;
+        this.#lineDirty = false;
+        this.#jointDirty = false;
+        this.#shapeDirty = false;
+        for (let index = 0; index < points.length; index++)
+            this.#addPoint(points[index], index);
+        for (let index = 0; index < lines.length; index++)
+            this.#addLine(lines[index], index);
+        for (let index = 0; index < joints.length; index++)
+            this.#addJoint(joints[index], index);
+        for (let index = 0; index < shapes.length; index++)
+            this.#addShape(shapes[index], index);
+        if (trim(this.#points, this.#pointIds, points.length))
+            this.#pointDirty = true;
+        if (trim(this.#lines, this.#lineIds, lines.length))
+            this.#lineDirty = true;
+        if (trim(this.#joints, this.#jointIds, joints.length))
+            this.#jointDirty = true;
+        if (trim(this.#shapes, this.#shapeIds, shapes.length))
+            this.#shapeDirty = true;
+        if (this.#pointCache.length !== points.length)
+            this.#pointDirty = true;
+        if (this.#lineCache.length !== lines.length)
+            this.#lineDirty = true;
+        if (this.#jointCache.length !== joints.length)
+            this.#jointDirty = true;
+        if (this.#shapeCache.length !== shapes.length)
+            this.#shapeDirty = true;
+        this.#pointCache.length = points.length;
+        this.#lineCache.length = lines.length;
+        this.#jointCache.length = joints.length;
+        this.#shapeCache.length = shapes.length;
+        if (this.#pointDirty) {
+            this.#pointCount = this.#pointBridge.publish();
+            indirectArgs(this.#pointIndirect, 6, this.#pointCount);
+        }
+        if (this.#lineDirty) {
+            this.#lineCount = this.#lineBridge.publish();
+            indirectArgs(this.#lineIndirect, 6, this.#lineCount);
+        }
+        if (this.#jointDirty) {
+            this.#jointCount = this.#jointBridge.publish();
+            indirectArgs(this.#jointIndirect, this.#jointVertexCount, this.#jointCount);
+        }
+        if (this.#shapeDirty) {
+            this.#shapeCount = this.#shapeBridge.publish();
+            indirectArgs(this.#shapeIndirect, 6, this.#shapeCount);
+        }
+    }
+    dispatchIndirect(pass) {
+        this.#indirectCompute.set({ params: { vertexCount: 6, instanceCount: this.#pointCount }, args: this.#pointIndirect });
+        pass.dispatch(this.#indirectCompute, 1);
+        this.#indirectCompute.set({ params: { vertexCount: 6, instanceCount: this.#lineCount }, args: this.#lineIndirect });
+        pass.dispatch(this.#indirectCompute, 1);
+        this.#indirectCompute.set({ params: { vertexCount: this.#jointVertexCount, instanceCount: this.#jointCount }, args: this.#jointIndirect });
+        pass.dispatch(this.#indirectCompute, 1);
+        this.#indirectCompute.set({ params: { vertexCount: 6, instanceCount: this.#shapeCount }, args: this.#shapeIndirect });
+        pass.dispatch(this.#indirectCompute, 1);
+    }
+    draw(pass, camera) {
+        if (this.#pointCount === 0 && this.#lineCount === 0 && this.#jointCount === 0 && this.#shapeCount === 0)
+            return;
+        const viewportSize = pass.target.size;
+        const viewProjection = projection2D(this.space, camera, viewportSize);
+        // Filled shapes first, then strokes, then points and joints: the layer reads as a filled
+        // backdrop with its outlines and markers drawn over it.
+        if (this.#shapeCount > 0) {
+            this.#shapeDraw.set({
+                camera: {
+                    viewProjection,
+                    viewportSize,
+                    yFlip: this.space === "screen" ? 1 : -1,
+                    pixelsPerUnit: this.space === "screen" ? 1 : camera.zoom,
+                },
+            });
+            pass.draw(this.#shapeDraw, { indirect: this.#shapeIndirect });
+        }
+        if (this.#pointCount > 0) {
+            this.#pointDraw.set({ camera: { viewProjection, viewportSize } });
+            pass.draw(this.#pointDraw, { indirect: this.#pointIndirect });
+        }
+        if (this.#lineCount > 0) {
+            this.#lineDraw.set({ camera: { viewProjection, view: IDENTITY_VIEW, viewportSize } });
+            pass.draw(this.#lineDraw, { indirect: this.#lineIndirect });
+        }
+        if (this.#jointCount > 0) {
+            this.#jointDraw.set({ camera: { viewProjection, view: IDENTITY_VIEW, viewportSize } });
+            pass.draw(this.#jointDraw, { indirect: this.#jointIndirect });
+        }
+    }
+    destroy() {
+        this.#pointDraw.dispose();
+        this.#lineDraw.dispose();
+        this.#jointDraw.dispose();
+        this.#shapeDraw.dispose();
+        this.#indirectCompute.dispose();
+        this.#pointBridge.destroy();
+        this.#lineBridge.destroy();
+        this.#jointBridge.destroy();
+        this.#shapeBridge.destroy();
+    }
+    get count() {
+        return this.#pointCount + this.#lineCount + this.#jointCount + this.#shapeCount;
+    }
+    #addPoint(command, index) {
+        const previous = this.#pointCache[index];
+        this.#pointCache[index] = command;
+        if (previous !== undefined && samePoint2D(previous, command))
+            return;
+        this.#pointDirty = true;
+        const id = this.#pointIds[index] ?? this.#addPointId(index);
+        this.#points.set(id, {
+            point: lift2D(command.position),
+            color: command.color,
+            size: command.size,
+            flags: (command.sizeMode === "world" ? 1 : 0) | (command.round ? 2 : 0),
+        });
+    }
+    #addPointId(index) {
+        const id = this.#points.add({ point: [0, 0, 0], color: [0, 0, 0, 0], size: 0, flags: 0 });
+        world(this.#points, id);
+        this.#pointIds[index] = id;
+        return id;
+    }
+    #addLine(command, index) {
+        const previous = this.#lineCache[index];
+        this.#lineCache[index] = command;
+        if (previous !== undefined && sameLine2D(previous, command))
+            return;
+        this.#lineDirty = true;
+        const id = this.#lineIds[index] ?? this.#addLineId(index);
+        const dash = command.dash ?? [0, 0, 0];
+        const joint = command.joint === "round" ? 1 : command.joint === "bevel" ? 2 : command.joint === "miter" ? 3 : 0;
+        this.#lines.set(id, {
+            start: lift2D(command.start),
+            end: lift2D(command.end),
+            color: command.color,
+            colorEnd: command.colorEnd,
+            width: command.width,
+            flags: command.widthMode === "world" ? 1 : 0,
+            dash,
+            normal: ZERO_NORMAL,
+            joint,
+        });
+    }
+    #addLineId(index) {
+        const id = this.#lines.add({ start: [0, 0, 0], end: [0, 0, 0], color: [0, 0, 0, 0], colorEnd: [0, 0, 0, 0], width: 0, flags: 0, dash: [0, 0, 0], normal: [0, 0, 0], joint: 0 });
+        world(this.#lines, id);
+        this.#lineIds[index] = id;
+        return id;
+    }
+    #addJoint(command, index) {
+        const previous = this.#jointCache[index];
+        this.#jointCache[index] = command;
+        if (previous !== undefined && sameJoint2D(previous, command))
+            return;
+        this.#jointDirty = true;
+        const id = this.#jointIds[index] ?? this.#addJointId(index);
+        this.#joints.set(id, {
+            previous: lift2D(command.previous),
+            center: lift2D(command.center),
+            next: lift2D(command.next),
+            color: command.color,
+            width: command.width,
+            flags: command.widthMode === "world" ? 1 : 0,
+            dash: command.dash ?? [0, 0, 0],
+            joint: command.joint === "round" ? 1 : command.joint === "bevel" ? 2 : 3,
+            previousNormal: ZERO_NORMAL,
+            nextNormal: ZERO_NORMAL,
+        });
+    }
+    #addJointId(index) {
+        const id = this.#joints.add({ previous: [0, 0, 0], center: [0, 0, 0], next: [0, 0, 0], color: [0, 0, 0, 0], width: 0, flags: 0, dash: [0, 0, 0], joint: 0, previousNormal: [0, 0, 0], nextNormal: [0, 0, 0] });
+        world(this.#joints, id);
+        this.#jointIds[index] = id;
+        return id;
+    }
+    #addShape(command, index) {
+        const previous = this.#shapeCache[index];
+        this.#shapeCache[index] = command;
+        if (previous !== undefined && sameShape2D(previous, command))
+            return;
+        this.#shapeDirty = true;
+        const id = this.#shapeIds[index] ?? this.#addShapeId(index);
+        this.#shapes.set(id, {
+            shape: SHAPE2D_CODES[command.shape],
+            center: lift2D(command.center),
+            size: command.size,
+            vertexB: command.vertexB,
+            vertexC: command.vertexC,
+            params: [command.cornerRadius, command.thickness, command.startAngle, command.sweep],
+            rotationRadius: [command.rotation, boundingRadius(command)],
+            color: command.color,
+            flags: (command.filled ? 1 : 0) | (command.sides << 8),
+        });
+    }
+    #addShapeId(index) {
+        const id = this.#shapes.add({ shape: 0, center: [0, 0, 0], size: [0, 0], vertexB: [0, 0], vertexC: [0, 0], params: [0, 0, 0, 0], rotationRadius: [0, 0], color: [0, 0, 0, 0], flags: 0 });
+        world(this.#shapes, id);
+        this.#shapeIds[index] = id;
+        return id;
+    }
+}
+export class GpuDebugDraw2D {
+    #buckets;
+    #camera = DEFAULT_CAMERA_2D;
+    constructor(gpu, options) {
+        const capacities = {
+            points: options.points ?? 4096,
+            lines: options.lines ?? 16384,
+            joints: options.joints ?? 8192,
+            shapes: options.shapes ?? 8192,
+        };
+        this.#buckets = {
+            world2d: new SpaceBucket2D(gpu, "world2d", options, capacities),
+            screen: new SpaceBucket2D(gpu, "screen", options, capacities),
+        };
+    }
+    /** Camera the `world2d` bucket projects through. `screen` commands ignore it. */
+    setCamera(camera) {
+        this.#camera = { pan: [camera.pan[0], camera.pan[1]], zoom: camera.zoom };
+    }
+    get camera() {
+        return this.#camera;
+    }
+    prepare(commands) {
+        const points = { world2d: [], screen: [] };
+        const lines = { world2d: [], screen: [] };
+        const joints = { world2d: [], screen: [] };
+        const shapes = { world2d: [], screen: [] };
+        for (const command of commands) {
+            if (command.kind === "point2d")
+                points[command.space].push(command);
+            else if (command.kind === "line2d")
+                lines[command.space].push(command);
+            else if (command.kind === "shape2d")
+                shapes[command.space].push(command);
+            else
+                joints[command.space].push(command);
+        }
+        // Both buckets are refreshed every frame, empty or not: that is what drops the previous
+        // frame's primitives instead of leaving them on screen.
+        this.#buckets.world2d.prepare(points.world2d, lines.world2d, joints.world2d, shapes.world2d);
+        this.#buckets.screen.prepare(points.screen, lines.screen, joints.screen, shapes.screen);
+    }
+    dispatchIndirect(pass) {
+        this.#buckets.world2d.dispatchIndirect(pass);
+        this.#buckets.screen.dispatchIndirect(pass);
+    }
+    draw(pass) {
+        this.#buckets.world2d.draw(pass, this.#camera);
+        this.#buckets.screen.draw(pass, this.#camera);
+    }
+    destroy() {
+        this.#buckets.world2d.destroy();
+        this.#buckets.screen.destroy();
+    }
+    /** Instances the last `prepare` left in both buckets, for tests and status readouts. */
+    get primitiveCount() {
+        return this.#buckets.world2d.count + this.#buckets.screen.count;
+    }
+}

package/dist/gpu-debug-draw-3d.d.ts

@@ -0,0 +1,52 @@
+import { type Frame, type FramePass, type Gpu } from "vgpu";
+import type { Camera2D } from "./camera-2d.js";
+import type { FrameCommand } from "./frame-draw-list.js";
+import { type GpuText3DOptions } from "./gpu-text-3d.js";
+/**
+ * Named glyph sources. A text command picks one by name through `TextOptions.source`; commands that
+ * name nothing use the first one registered.
+ *
+ * More than one source is what lets a single frame mix quality levels — a sharp pass for the block
+ * the user is reading and a cheap one for the rest — or put two encodings side by side.
+ */
+export type TextSources = Readonly<Record<string, GpuText3DOptions["font"]>>;
+export type GpuTextOptions = {
+    readonly sources: TextSources;
+    readonly capacity?: number;
+    readonly atlasSize?: number;
+    readonly mipLevels?: number;
+    /** Atlas pages per source. See `GpuText3DOptions.pages`. */
+    readonly pages?: number;
+    /** What a glyph that no page can hold costs. See `GpuText3DOptions.onFull`. Defaults to `"skip"`. */
+    readonly onFull?: "throw" | "skip";
+};
+/**
+ * Reference scenes set `depth_bias = -0.001` on the reference before drawing. Keeping it as an
+ * option (and baking it into the WGSL) means the shader can match the reference exactly
+ * without adding a fourth uniform field that would break the shared camera layout.
+ */
+export declare const DEFAULT_DEPTH_BIAS = -0.001;
+type Camera = {
+    viewProjection: ArrayLike<number>;
+    view: ArrayLike<number>;
+};
+export declare class GpuDebugDraw3D {
+    #private;
+    constructor(gpu: Gpu, capacities?: {
+        points?: number;
+        lines?: number;
+        triangles?: number;
+        joints?: number;
+        depthBias?: number;
+        text?: GpuTextOptions;
+    });
+    prepare(commands: readonly FrameCommand[], camera: Camera, camera2d?: Camera2D): void;
+    updateIndirect(frame: Frame): void;
+    draw(pass: FramePass): void;
+    destroy(): void;
+    private addTriangle;
+    private addPoint;
+    private addLine;
+    private addJoint;
+}
+export {};