@driftengine/core 3.61.0

package/dist/render/frame/schedule.js

@@ -0,0 +1,61 @@
+import { nodeCount, nodeReads, nodeWrites } from './arena.js';
+/**
+ * Group a frame's nodes into passes, and derive what happens to each attachment.
+ *
+ * **The order is the caller's and is never changed.** Blending and depth make *after*
+ * different from *before*, so an immediate-mode API's draw order carries meaning no
+ * dependency analysis may override. All this does is group adjacent compatible nodes and work
+ * out load and store from the reads that follow.
+ *
+ * **`liveOut` is what must survive this schedule**, and it is a parameter rather than a
+ * constant because the scheduler does not necessarily see the whole frame. During the
+ * migration a flush schedules only what has accumulated, so a resource written here may be
+ * read after the next flush — invisible from inside this call. The caller knows what is still
+ * live; this cannot work it out. The canvas belongs in it always, because nothing ever reads
+ * the canvas (it is presented, not sampled) and a purely read-driven rule would conclude it
+ * is safe to throw away.
+ *
+ * Allocates nothing: `out` is supplied by the caller and reused across frames, and the return
+ * value says how many of its entries were filled.
+ */
+export function schedule(arena, clearMask, liveOut, out) {
+    const total = nodeCount(arena);
+    if (total === 0)
+        return 0;
+    let passes = 0;
+    let at = 0;
+    let cleared = 0;
+    while (at < total) {
+        const writes = nodeWrites(arena, at);
+        let end = at + 1;
+        while (end < total && nodeWrites(arena, end) === writes)
+            end += 1;
+        /*
+         * Everything read between the end of this pass and the end of the frame. A resource in
+         * this set has to survive; one outside it does not, and that is the whole derivation.
+         *
+         * Recomputed per pass rather than kept as a suffix scan. This runs over tens of passes
+         * and hundreds of nodes, where the simple version is free and obviously correct. If a
+         * profile ever says otherwise, replace it with a suffix-OR computed once — and put the
+         * measurement in the commit, because this is the calculation the discard rests on.
+         */
+        let readLater = 0;
+        for (let i = end; i < total; i += 1)
+            readLater |= nodeReads(arena, i);
+        const unread = (writes & readLater) === 0 && (writes & liveOut) === 0;
+        if (!unread) {
+            const pass = out[passes];
+            if (pass === undefined)
+                return passes;
+            pass.writes = writes;
+            pass.first = at;
+            pass.count = end - at;
+            pass.clear = clearMask & writes & ~cleared;
+            pass.discard = writes & ~readLater & ~liveOut;
+            cleared |= writes;
+            passes += 1;
+        }
+        at = end;
+    }
+    return passes;
+}

package/dist/render/frameView.d.ts

@@ -0,0 +1,19 @@
+import type { Camera } from './camera.ts';
+/**
+ * What a drawing path needs from the camera, which is not the camera.
+ *
+ * **The seam reversed depth was waiting on.** WebGPU corrects a projection once a frame, in one
+ * place, at the last moment before drawing. WebGL2 had no such place: the camera's raw matrix was
+ * read directly by the main renderer and by the plume, water, caustics, wind-streak and flock
+ * renderers, each uploading it itself — so reversing depth meant remapping six call sites across
+ * five files and then finding a seventh, which is how three attempts at it went.
+ *
+ * Narrowing the parameter to the three fields those paths actually read is what lets the frame hand
+ * them a *corrected* matrix instead of the camera's own. A real `Camera` satisfies it structurally,
+ * so no caller outside changed, and the correction now lives in one place on this backend too.
+ *
+ * **Derived from `Camera` rather than restated.** Written out by hand, the day a field changes type
+ * this drifts and the mismatch shows up as geometry in the wrong place; picked off the class, it
+ * cannot.
+ */
+export type FrameView = Pick<Camera, 'position' | 'view' | 'viewProjection'>;

package/dist/render/frameView.js

@@ -0,0 +1 @@
+export {};

package/dist/render/gizmo.d.ts

@@ -0,0 +1,236 @@
+import type { LineSegments } from './linePoints.ts';
+import type { Camera } from './camera.ts';
+import type { Vec3 } from '../math/color.ts';
+export declare const GIZMO_NONE = 0;
+export declare const GIZMO_TRANSLATE_X = 1;
+export declare const GIZMO_TRANSLATE_Y = 2;
+export declare const GIZMO_TRANSLATE_Z = 3;
+/** The plane handles are named for the axes they slide in, so `YZ` is normal to x. */
+export declare const GIZMO_TRANSLATE_YZ = 4;
+export declare const GIZMO_TRANSLATE_ZX = 5;
+export declare const GIZMO_TRANSLATE_XY = 6;
+export declare const GIZMO_ROTATE_X = 7;
+export declare const GIZMO_ROTATE_Y = 8;
+export declare const GIZMO_ROTATE_Z = 9;
+export declare const GIZMO_SCALE_X = 10;
+export declare const GIZMO_SCALE_Y = 11;
+export declare const GIZMO_SCALE_Z = 12;
+export declare const GIZMO_SCALE_UNIFORM = 13;
+export type GizmoMode = 'translate' | 'rotate' | 'scale';
+export type GizmoSpace = 'world' | 'local';
+/** Buffer indices. Three axes, one neutral, one for whatever is highlighted. */
+export declare const GIZMO_GROUP_X = 0;
+export declare const GIZMO_GROUP_Y = 1;
+export declare const GIZMO_GROUP_Z = 2;
+export declare const GIZMO_GROUP_NEUTRAL = 3;
+export declare const GIZMO_GROUP_ACTIVE = 4;
+export declare const GIZMO_GROUP_COUNT = 5;
+/**
+ * A colour per group, in the order the groups are indexed.
+ *
+ * Exported as data rather than baked into a draw call because this file draws nothing.
+ * A consumer with its own palette overrides them and nothing here notices.
+ */
+export declare const GIZMO_GROUP_COLORS: readonly Vec3[];
+/**
+ * The world size that covers `pixels` screen pixels at the target's distance.
+ *
+ * A separate function rather than a method, which is what keeps every intersection and
+ * every drag in this file testable against a bare ray: the gizmo never learns what a
+ * camera is. A caller assigns the result to `size` once a frame.
+ *
+ * Perspective only, because `Camera` is. An orthographic camera's answer does not depend
+ * on distance at all, and the day one exists this grows a branch rather than a caller.
+ */
+export declare function gizmoScaleFor(camera: Camera, target: ArrayLike<number>, cssHeight: number, pixels: number): number;
+export declare class Gizmo {
+    mode: GizmoMode;
+    space: GizmoSpace;
+    /** The gizmo's own world size. See `gizmoScaleFor`. Non-positive draws and picks nothing. */
+    size: number;
+    /** The transform being edited. Written by a drag; the caller copies it where it belongs. */
+    readonly position: Float32Array<ArrayBuffer>;
+    /** A quaternion, `xyzw`, identity at construction. */
+    readonly rotation: Float32Array<ArrayBuffer>;
+    readonly scale: Float32Array<ArrayBuffer>;
+    private readonly groups;
+    private readonly ringSegments;
+    /**
+     * The basis the handles point along, rebuilt on every pick and frozen for a drag.
+     *
+     * Three standing `Float32Array`s rather than one of nine with a `subarray` per read:
+     * `subarray` allocates a view object, and these are read several times per handle per
+     * pointer move.
+     */
+    private readonly axes;
+    private readonly dragAxes;
+    private hoveredHandle;
+    private activeHandle;
+    private readonly grabPosition;
+    private readonly grabRotation;
+    private readonly grabScale;
+    private readonly grabPoint;
+    private readonly grabViewNormal;
+    private grabParam;
+    private grabRadius;
+    private previousAngle;
+    private accumulated;
+    private readonly closest;
+    private readonly point;
+    private readonly offset;
+    private readonly turn;
+    private readonly corners;
+    /**
+     * `ringSegments` is the resolution of a rotation ring, and it also sets every buffer's
+     * capacity because a ring is the largest thing any one of them holds.
+     */
+    constructor(ringSegments?: number);
+    /** What a `hover` last found, or `GIZMO_NONE`. */
+    get hovered(): number;
+    /** The handle a drag is on, or `GIZMO_NONE`. */
+    get active(): number;
+    get dragging(): boolean;
+    /**
+     * How far the current rotation drag has turned, in radians, signed and unbounded.
+     *
+     * **This is the only place the unwrap in `dragRing` is observable, and that is not
+     * obvious.** The orientation is not: `quat.setAxisAngle` is 2π-periodic and a quaternion
+     * double-covers the rotations, so an accumulated angle that is wrong by a whole turn
+     * produces the same orientation, negated — which is the same rotation. What the unwrap
+     * buys is a continuous *number*: a readout that says 270° rather than −90°, and a caller
+     * that wants to snap to fifteen degrees or stop at a limit, both of which need the turn
+     * and not the pose. Zero when no rotation drag is running.
+     */
+    get dragAngle(): number;
+    /** One group's geometry, filled by the last `build`. Draw it with `GIZMO_GROUP_COLORS[group]`. */
+    segments(group: number): LineSegments;
+    /**
+     * The handle a ray is over, or `GIZMO_NONE`. No side effects; `hover` is the one that
+     * remembers.
+     *
+     * **Nearest along the ray wins, except that the centre handle wins outright**, which is
+     * one documented exception rather than a priority table: a priority table would let a
+     * plane handle behind the camera beat an arm in front of it, which a user sees as a
+     * click landing on the wrong thing.
+     *
+     * **As the radii stand the exception decides nothing**, and that is worth saying rather
+     * than implying otherwise: an arm's pick cylinder starts at `ARM_START` of the size and
+     * the centre's sphere ends at `CENTRE_RADIUS`, which is smaller, so the two regions do
+     * not meet. The ordering is what keeps a later change to either radius from quietly
+     * producing a centre nobody can click, which is the failure it is here to prevent.
+     *
+     * `direction` must be unit length. `camera.rayThrough` gives one.
+     */
+    pick(origin: ArrayLike<number>, direction: ArrayLike<number>): number;
+    /** `pick`, remembered. Returns what it found. Ignored while a drag is running. */
+    hover(origin: ArrayLike<number>, direction: ArrayLike<number>): number;
+    /**
+     * Grab whatever the ray is over. Returns whether a drag started.
+     *
+     * **The transform and the axes are both captured here and neither is re-read until the
+     * drag ends.** Recomputing the basis from a rotation the drag is changing feeds the
+     * answer back into its own input, and what that looks like is a ring that accelerates
+     * away from the pointer.
+     *
+     * A grab whose anchor cannot be computed — a ray parallel to the axis it is grabbing —
+     * refuses rather than starting a drag with an arbitrary origin.
+     */
+    beginDrag(origin: ArrayLike<number>, direction: ArrayLike<number>): boolean;
+    /**
+     * Move the drag. Returns whether the transform changed.
+     *
+     * **Every answer is absolute, computed from the anchor rather than accumulated from the
+     * last call**, so a drag cannot drift however many frames it runs for. Rotation is the
+     * one exception and §5 of the design says why: an angle has to be unwrapped against the
+     * previous one to survive the seam at ±π, so the total is accumulated and the *total* is
+     * what the transform is built from.
+     *
+     * **A degenerate ray keeps the previous value rather than producing one.** The
+     * alternative is the object teleporting at the moment the pointer crosses the plane it
+     * is dragging in, which is the single most annoying thing a gizmo can do.
+     */
+    updateDrag(origin: ArrayLike<number>, direction: ArrayLike<number>): boolean;
+    /** Let go. Safe to call on a frame with no drag running. */
+    endDrag(): void;
+    /**
+     * Fill the five buffers for this frame's mode, transform and highlight.
+     *
+     * Cheap enough to call every frame — a rotation ring at the default resolution is 48
+     * segments of arithmetic — and it has to be, because the highlight changes with the
+     * pointer.
+     */
+    build(): void;
+    /** A handle's own colour group, unless it is the one lit. */
+    private groupFor;
+    /**
+     * The basis the handles point along.
+     *
+     * **Scale is always local whatever `space` says.** A non-uniform scale along a world
+     * axis is not representable in a translation-rotation-scale transform, so a gizmo
+     * offering it would shear the object and call it scaling.
+     */
+    private refreshAxes;
+    /**
+     * Where a ray meets an arm's cylinder, or `-1`.
+     *
+     * The region is a cylinder without caps: a closest point past either end of the segment
+     * is a miss rather than being clamped to the cap. It costs a sliver of pickable area at
+     * the two ends of a handle a user aims at the middle of, and it keeps this to one
+     * intersection.
+     */
+    private pickArm;
+    /**
+     * Where a ray meets a plane handle's quad, or `-1`.
+     *
+     * The quad sits in the positive quadrant of its two axes and stays there. Following the
+     * camera into whichever quadrant faces it is what a mature editor does and it is a
+     * second thing to get right; a fixed quadrant is honest and is visible from where it is.
+     */
+    private pickPlane;
+    /** Where a ray meets a rotation ring's annulus, or `-1`. */
+    private pickRing;
+    /** Capture whatever the handle being grabbed needs. `false` refuses the drag. */
+    private anchor;
+    private anchorArm;
+    private anchorPlane;
+    private anchorRing;
+    private anchorUniform;
+    /** Translate along an arm, or scale along it. One intersection answers both. */
+    private dragAlongArm;
+    private dragInPlane;
+    /**
+     * Turn about a ring.
+     *
+     * **`atan2` answers in `(−π, π]`, so a drag crossing the seam reads as a jump of nearly
+     * a full turn.** Each update is unwrapped against the previous angle and the total
+     * accumulates, which is what makes a three-quarter turn a three-quarter turn instead of
+     * a quarter the other way — in the number. See `dragAngle` for why the orientation
+     * cannot show the difference, and why the unwrap is still not dead code.
+     */
+    private dragRing;
+    private dragUniform;
+    /**
+     * The angle a ray makes in a ring's plane, or `null` when there is none to speak of.
+     *
+     * Near the centre the hit is a point whose angle is dominated by whatever the last
+     * floating-point bit did, so a drag there would spin. Refusing keeps what the drag had.
+     */
+    private ringAngle;
+    /** `offset` becomes the vector from the gizmo to the ray's point at `distance`. */
+    private offsetAt;
+    /** How far `offset` reaches along one of the axes. */
+    private along;
+    private emit;
+    /** `point` becomes the gizmo origin plus a combination of the three axes. */
+    private at;
+    private buildArm;
+    private buildPlane;
+    private buildRing;
+    /**
+     * Six vertices on the axes and the twelve edges between them.
+     *
+     * Drawn as an octahedron and picked as a sphere of the same radius, so the region that
+     * responds is slightly larger than the shape — which errs toward being easy to grab.
+     */
+    private buildOctahedron;
+}