@driftengine/core 3.61.0

package/dist/render/gizmo.js

@@ -0,0 +1,727 @@
+/**
+ * A transform gizmo: what a ray is over, what a drag does to a transform, and the lines
+ * that draw it.
+ *
+ * **A generator and not a pass**, which is the argument `debugLines.ts` makes and which
+ * holds here with more force. `drawLines` has been on both backends since the polyline
+ * batch landed; what a gizmo adds is the arithmetic. Nothing in this file touches a
+ * context, so one implementation answers for WebGL2 and WebGPU alike and every test runs
+ * without either.
+ *
+ * **It says what, and dispatches nothing.** `registerPickable` settled this for picking
+ * and the same reasoning applies: enter, leave, capture and the difference between a click
+ * and a drag belong to the consumer, which already has that logic for anything with a drag
+ * in it. This is asked what a ray is over, and told when a drag begins, moves and ends.
+ *
+ * **It does not own the transform it edits.** `position`, `rotation` and `scale` are here
+ * because a drag has to put its answer somewhere; the caller copies them onto whatever it
+ * actually moves. A gizmo reaching into a `SceneNode` would be render code mutating scene
+ * state, which `ARCHITECTURE.md` forbids.
+ *
+ * **Nothing here throws and nothing allocates after construction**, for the reason
+ * `DebugLines` gives: a tool that threw would take the frame down at the moment somebody
+ * was trying to move something.
+ *
+ * A caller wires it in four lines:
+ *
+ * ```ts
+ * camera.rayThrough(origin, direction, cssX, cssY, cssWidth, cssHeight);
+ * gizmo.size = gizmoScaleFor(camera, gizmo.position, cssHeight, 90);
+ * if (down && !wasDown) gizmo.beginDrag(origin, direction);
+ * else if (down) gizmo.updateDrag(origin, direction);
+ * else { gizmo.endDrag(); gizmo.hover(origin, direction); }
+ * ```
+ */
+import { quat, vec3 } from 'gl-matrix';
+import { rayClosestOnLine, rayPlane, raySphere } from '../math/intersect.js';
+import { createLineSegments } from './linePoints.js';
+export const GIZMO_NONE = 0;
+export const GIZMO_TRANSLATE_X = 1;
+export const GIZMO_TRANSLATE_Y = 2;
+export const GIZMO_TRANSLATE_Z = 3;
+/** The plane handles are named for the axes they slide in, so `YZ` is normal to x. */
+export const GIZMO_TRANSLATE_YZ = 4;
+export const GIZMO_TRANSLATE_ZX = 5;
+export const GIZMO_TRANSLATE_XY = 6;
+export const GIZMO_ROTATE_X = 7;
+export const GIZMO_ROTATE_Y = 8;
+export const GIZMO_ROTATE_Z = 9;
+export const GIZMO_SCALE_X = 10;
+export const GIZMO_SCALE_Y = 11;
+export const GIZMO_SCALE_Z = 12;
+export const GIZMO_SCALE_UNIFORM = 13;
+/** Buffer indices. Three axes, one neutral, one for whatever is highlighted. */
+export const GIZMO_GROUP_X = 0;
+export const GIZMO_GROUP_Y = 1;
+export const GIZMO_GROUP_Z = 2;
+export const GIZMO_GROUP_NEUTRAL = 3;
+export const GIZMO_GROUP_ACTIVE = 4;
+export 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 const GIZMO_GROUP_COLORS = [
+    [0.9, 0.25, 0.25],
+    [0.35, 0.85, 0.3],
+    [0.3, 0.5, 0.95],
+    [0.75, 0.75, 0.78],
+    [1.0, 0.85, 0.2],
+];
+/* Every length below is a fraction of `size`, so the whole gizmo scales as one thing. */
+const ARM_START = 0.15;
+const ARM_END = 1.0;
+const ARM_PICK_RADIUS = 0.08;
+const HEAD_LENGTH = 0.2;
+const HEAD_RADIUS = 0.06;
+const PLANE_INNER = 0.28;
+const PLANE_OUTER = 0.58;
+const RING_RADIUS = 1.0;
+const RING_PICK_HALF_WIDTH = 0.07;
+/** Inside this radius a ring drag's angle is noise, so the drag holds what it had. */
+const RING_MIN_GRAB = 0.2;
+const CENTRE_RADIUS = 0.13;
+const TIP_RADIUS = 0.07;
+/** A scale can be driven small but never to zero, which is not invertible, or negative. */
+const MIN_SCALE = 0.01;
+const TWO_PI = Math.PI * 2;
+const BASIS = [
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1],
+];
+/**
+ * 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 function gizmoScaleFor(camera, target, cssHeight, pixels) {
+    const dx = target[0] - camera.position[0];
+    const dy = target[1] - camera.position[1];
+    const dz = target[2] - camera.position[2];
+    const distance = Math.hypot(dx, dy, dz);
+    const halfFov = (camera.fovYDeg * Math.PI) / 360;
+    const worldPerPixel = (2 * distance * Math.tan(halfFov)) / Math.max(cssHeight, 1);
+    return worldPerPixel * pixels;
+}
+export class Gizmo {
+    mode = 'translate';
+    space = 'world';
+    /** The gizmo's own world size. See `gizmoScaleFor`. Non-positive draws and picks nothing. */
+    size = 1;
+    /** The transform being edited. Written by a drag; the caller copies it where it belongs. */
+    position = new Float32Array(3);
+    /** A quaternion, `xyzw`, identity at construction. */
+    rotation = new Float32Array([0, 0, 0, 1]);
+    scale = new Float32Array([1, 1, 1]);
+    groups = [];
+    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.
+     */
+    axes = [new Float32Array(3), new Float32Array(3), new Float32Array(3)];
+    dragAxes = [new Float32Array(3), new Float32Array(3), new Float32Array(3)];
+    hoveredHandle = GIZMO_NONE;
+    activeHandle = GIZMO_NONE;
+    /* Anchors, all captured by `beginDrag` and read by `updateDrag`. */
+    grabPosition = new Float32Array(3);
+    grabRotation = new Float32Array(4);
+    grabScale = new Float32Array(3);
+    grabPoint = new Float32Array(3);
+    grabViewNormal = new Float32Array(3);
+    grabParam = 0;
+    grabRadius = 0;
+    previousAngle = 0;
+    accumulated = 0;
+    /* Scratch, so a pointer move allocates nothing. */
+    closest = new Float32Array(3);
+    point = new Float32Array(3);
+    offset = new Float32Array(3);
+    turn = new Float32Array(4);
+    corners = new Float32Array(18);
+    /**
+     * `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 = 48) {
+        if (!(ringSegments >= 8))
+            throw new Error(`Gizmo: ringSegments must be at least 8, got ${ringSegments}`);
+        this.ringSegments = Math.floor(ringSegments);
+        const capacity = this.ringSegments + 16;
+        for (let group = 0; group < GIZMO_GROUP_COUNT; group++)
+            this.groups.push(createLineSegments(capacity));
+    }
+    /** What a `hover` last found, or `GIZMO_NONE`. */
+    get hovered() {
+        return this.hoveredHandle;
+    }
+    /** The handle a drag is on, or `GIZMO_NONE`. */
+    get active() {
+        return this.activeHandle;
+    }
+    get dragging() {
+        return this.activeHandle !== GIZMO_NONE;
+    }
+    /**
+     * 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() {
+        return this.activeHandle >= GIZMO_ROTATE_X && this.activeHandle <= GIZMO_ROTATE_Z
+            ? this.accumulated
+            : 0;
+    }
+    /** One group's geometry, filled by the last `build`. Draw it with `GIZMO_GROUP_COLORS[group]`. */
+    segments(group) {
+        const at = this.groups[group];
+        if (at === undefined)
+            throw new Error(`Gizmo: no group ${group}`);
+        return at;
+    }
+    /**
+     * 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, direction) {
+        if (!(this.size > 0))
+            return GIZMO_NONE;
+        this.refreshAxes(this.axes);
+        if (this.mode === 'scale') {
+            const centre = raySphere(origin, direction, this.position, this.size * CENTRE_RADIUS);
+            if (centre >= 0)
+                return GIZMO_SCALE_UNIFORM;
+        }
+        let best = Infinity;
+        let handle = GIZMO_NONE;
+        for (let axis = 0; axis < 3; axis++) {
+            if (this.mode === 'rotate') {
+                const t = this.pickRing(origin, direction, axis, this.axes);
+                if (t >= 0 && t < best) {
+                    best = t;
+                    handle = GIZMO_ROTATE_X + axis;
+                }
+                continue;
+            }
+            const arm = this.pickArm(origin, direction, axis, this.axes);
+            if (arm >= 0 && arm < best) {
+                best = arm;
+                handle = (this.mode === 'translate' ? GIZMO_TRANSLATE_X : GIZMO_SCALE_X) + axis;
+            }
+            if (this.mode === 'translate') {
+                const plane = this.pickPlane(origin, direction, axis, this.axes);
+                if (plane >= 0 && plane < best) {
+                    best = plane;
+                    handle = GIZMO_TRANSLATE_YZ + axis;
+                }
+            }
+        }
+        return handle;
+    }
+    /** `pick`, remembered. Returns what it found. Ignored while a drag is running. */
+    hover(origin, direction) {
+        if (this.dragging)
+            return this.activeHandle;
+        this.hoveredHandle = this.pick(origin, direction);
+        return this.hoveredHandle;
+    }
+    /**
+     * 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, direction) {
+        const handle = this.pick(origin, direction);
+        if (handle === GIZMO_NONE)
+            return false;
+        for (let axis = 0; axis < 3; axis++)
+            this.dragAxes[axis].set(this.axes[axis]);
+        this.grabPosition.set(this.position);
+        this.grabRotation.set(this.rotation);
+        this.grabScale.set(this.scale);
+        this.accumulated = 0;
+        if (!this.anchor(handle, origin, direction))
+            return false;
+        this.activeHandle = handle;
+        this.hoveredHandle = handle;
+        return true;
+    }
+    /**
+     * 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, direction) {
+        const handle = this.activeHandle;
+        if (handle === GIZMO_NONE)
+            return false;
+        if (handle >= GIZMO_TRANSLATE_X && handle <= GIZMO_TRANSLATE_Z) {
+            return this.dragAlongArm(origin, direction, handle - GIZMO_TRANSLATE_X, true);
+        }
+        if (handle >= GIZMO_TRANSLATE_YZ && handle <= GIZMO_TRANSLATE_XY) {
+            return this.dragInPlane(origin, direction, handle - GIZMO_TRANSLATE_YZ);
+        }
+        if (handle >= GIZMO_ROTATE_X && handle <= GIZMO_ROTATE_Z) {
+            return this.dragRing(origin, direction, handle - GIZMO_ROTATE_X);
+        }
+        if (handle >= GIZMO_SCALE_X && handle <= GIZMO_SCALE_Z) {
+            return this.dragAlongArm(origin, direction, handle - GIZMO_SCALE_X, false);
+        }
+        return this.dragUniform(origin, direction);
+    }
+    /** Let go. Safe to call on a frame with no drag running. */
+    endDrag() {
+        this.activeHandle = GIZMO_NONE;
+    }
+    /**
+     * 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() {
+        for (const group of this.groups)
+            group.count = 0;
+        if (!(this.size > 0))
+            return;
+        /* A running drag draws against the basis it grabbed. Refreshing it here would undo the
+         * freeze `beginDrag` took, and a local-space ring would chase its own rotation. */
+        if (!this.dragging)
+            this.refreshAxes(this.axes);
+        const axes = this.dragging ? this.dragAxes : this.axes;
+        const lit = this.dragging ? this.activeHandle : this.hoveredHandle;
+        if (this.mode === 'translate') {
+            for (let axis = 0; axis < 3; axis++) {
+                this.buildArm(axis, axes, this.groupFor(GIZMO_TRANSLATE_X + axis, axis, lit), true);
+                this.buildPlane(axis, axes, this.groupFor(GIZMO_TRANSLATE_YZ + axis, axis, lit));
+            }
+            return;
+        }
+        if (this.mode === 'rotate') {
+            for (let axis = 0; axis < 3; axis++) {
+                this.buildRing(axis, axes, this.groupFor(GIZMO_ROTATE_X + axis, axis, lit));
+            }
+            return;
+        }
+        for (let axis = 0; axis < 3; axis++) {
+            this.buildArm(axis, axes, this.groupFor(GIZMO_SCALE_X + axis, axis, lit), false);
+        }
+        this.buildOctahedron(this.position[0], this.position[1], this.position[2], this.size * CENTRE_RADIUS, axes, lit === GIZMO_SCALE_UNIFORM ? GIZMO_GROUP_ACTIVE : GIZMO_GROUP_NEUTRAL);
+    }
+    /** A handle's own colour group, unless it is the one lit. */
+    groupFor(handle, axis, lit) {
+        return handle === lit ? GIZMO_GROUP_ACTIVE : axis;
+    }
+    /**
+     * 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.
+     */
+    refreshAxes(into) {
+        const local = this.space === 'local' || this.mode === 'scale';
+        for (let axis = 0; axis < 3; axis++) {
+            const source = BASIS[axis];
+            const target = into[axis];
+            if (local)
+                vec3.transformQuat(target, source, this.rotation);
+            else
+                target.set(source);
+        }
+    }
+    /**
+     * 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.
+     */
+    pickArm(origin, direction, axis, axes) {
+        const ray = this.closest;
+        if (!rayClosestOnLine(origin, direction, this.position, axes[axis], ray)) {
+            return -1;
+        }
+        const along = ray[1];
+        if (along < this.size * ARM_START || along > this.size * ARM_END)
+            return -1;
+        if (ray[2] > this.size * ARM_PICK_RADIUS)
+            return -1;
+        const distance = ray[0];
+        return distance >= 0 ? distance : -1;
+    }
+    /**
+     * 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.
+     */
+    pickPlane(origin, direction, normalAxis, axes) {
+        const normal = axes[normalAxis];
+        const distance = rayPlane(origin, direction, this.position, normal);
+        if (distance < 0)
+            return -1;
+        this.offsetAt(origin, direction, distance);
+        const first = (normalAxis + 1) % 3;
+        const second = (normalAxis + 2) % 3;
+        const a = this.along(first, axes);
+        const b = this.along(second, axes);
+        const inner = this.size * PLANE_INNER;
+        const outer = this.size * PLANE_OUTER;
+        if (a < inner || a > outer || b < inner || b > outer)
+            return -1;
+        return distance;
+    }
+    /** Where a ray meets a rotation ring's annulus, or `-1`. */
+    pickRing(origin, direction, axis, axes) {
+        const normal = axes[axis];
+        const distance = rayPlane(origin, direction, this.position, normal);
+        if (distance < 0)
+            return -1;
+        this.offsetAt(origin, direction, distance);
+        const radius = Math.hypot(this.offset[0], this.offset[1], this.offset[2]);
+        if (Math.abs(radius - this.size * RING_RADIUS) > this.size * RING_PICK_HALF_WIDTH)
+            return -1;
+        return distance;
+    }
+    /** Capture whatever the handle being grabbed needs. `false` refuses the drag. */
+    anchor(handle, origin, direction) {
+        if (handle >= GIZMO_TRANSLATE_X && handle <= GIZMO_TRANSLATE_Z) {
+            return this.anchorArm(origin, direction, handle - GIZMO_TRANSLATE_X);
+        }
+        if (handle >= GIZMO_TRANSLATE_YZ && handle <= GIZMO_TRANSLATE_XY) {
+            return this.anchorPlane(origin, direction, handle - GIZMO_TRANSLATE_YZ);
+        }
+        if (handle >= GIZMO_ROTATE_X && handle <= GIZMO_ROTATE_Z) {
+            return this.anchorRing(origin, direction, handle - GIZMO_ROTATE_X);
+        }
+        if (handle >= GIZMO_SCALE_X && handle <= GIZMO_SCALE_Z) {
+            return this.anchorArm(origin, direction, handle - GIZMO_SCALE_X);
+        }
+        return this.anchorUniform(origin, direction);
+    }
+    anchorArm(origin, direction, axis) {
+        const ray = this.closest;
+        const line = this.dragAxes[axis];
+        if (!rayClosestOnLine(origin, direction, this.grabPosition, line, ray))
+            return false;
+        this.grabParam = ray[1];
+        return true;
+    }
+    anchorPlane(origin, direction, normalAxis) {
+        const normal = this.dragAxes[normalAxis];
+        const distance = rayPlane(origin, direction, this.grabPosition, normal);
+        if (distance < 0)
+            return false;
+        this.grabPoint[0] = origin[0] + direction[0] * distance;
+        this.grabPoint[1] = origin[1] + direction[1] * distance;
+        this.grabPoint[2] = origin[2] + direction[2] * distance;
+        return true;
+    }
+    anchorRing(origin, direction, axis) {
+        const angle = this.ringAngle(origin, direction, axis);
+        if (angle === null)
+            return false;
+        this.previousAngle = angle;
+        return true;
+    }
+    anchorUniform(origin, direction) {
+        /* The view plane at the moment of grabbing: the pointer's own direction is its normal,
+         * which is the view direction at that point and asks nothing of a camera. */
+        this.grabViewNormal[0] = direction[0];
+        this.grabViewNormal[1] = direction[1];
+        this.grabViewNormal[2] = direction[2];
+        const distance = rayPlane(origin, direction, this.grabPosition, this.grabViewNormal);
+        if (distance < 0)
+            return false;
+        this.offsetAt(origin, direction, distance);
+        this.grabRadius = Math.hypot(this.offset[0], this.offset[1], this.offset[2]);
+        return true;
+    }
+    /** Translate along an arm, or scale along it. One intersection answers both. */
+    dragAlongArm(origin, direction, axis, translate) {
+        const ray = this.closest;
+        const line = this.dragAxes[axis];
+        if (!rayClosestOnLine(origin, direction, this.grabPosition, line, ray))
+            return false;
+        const moved = ray[1] - this.grabParam;
+        if (translate) {
+            for (let component = 0; component < 3; component++) {
+                this.position[component] =
+                    this.grabPosition[component] + line[component] * moved;
+            }
+            return true;
+        }
+        this.scale[axis] = Math.max(this.grabScale[axis] * (1 + moved / this.size), MIN_SCALE);
+        return true;
+    }
+    dragInPlane(origin, direction, normalAxis) {
+        const normal = this.dragAxes[normalAxis];
+        const distance = rayPlane(origin, direction, this.grabPosition, normal);
+        if (distance < 0)
+            return false;
+        for (let component = 0; component < 3; component++) {
+            const hit = origin[component] + direction[component] * distance;
+            this.position[component] =
+                this.grabPosition[component] + (hit - this.grabPoint[component]);
+        }
+        return true;
+    }
+    /**
+     * 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.
+     */
+    dragRing(origin, direction, axis) {
+        const angle = this.ringAngle(origin, direction, axis);
+        if (angle === null)
+            return false;
+        let delta = angle - this.previousAngle;
+        if (delta > Math.PI)
+            delta -= TWO_PI;
+        else if (delta < -Math.PI)
+            delta += TWO_PI;
+        this.previousAngle = angle;
+        this.accumulated += delta;
+        quat.setAxisAngle(this.turn, this.dragAxes[axis], this.accumulated);
+        quat.multiply(this.rotation, this.turn, this.grabRotation);
+        return true;
+    }
+    dragUniform(origin, direction) {
+        const distance = rayPlane(origin, direction, this.grabPosition, this.grabViewNormal);
+        if (distance < 0)
+            return false;
+        this.offsetAt(origin, direction, distance);
+        const radius = Math.hypot(this.offset[0], this.offset[1], this.offset[2]);
+        const factor = 1 + (radius - this.grabRadius) / this.size;
+        for (let component = 0; component < 3; component++) {
+            this.scale[component] = Math.max(this.grabScale[component] * factor, MIN_SCALE);
+        }
+        return true;
+    }
+    /**
+     * 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.
+     */
+    ringAngle(origin, direction, axis) {
+        const normal = this.dragAxes[axis];
+        const distance = rayPlane(origin, direction, this.grabPosition, normal);
+        if (distance < 0)
+            return null;
+        for (let component = 0; component < 3; component++) {
+            this.offset[component] =
+                origin[component] +
+                    direction[component] * distance -
+                    this.grabPosition[component];
+        }
+        const radius = Math.hypot(this.offset[0], this.offset[1], this.offset[2]);
+        if (radius < this.size * RING_MIN_GRAB)
+            return null;
+        const first = (axis + 1) % 3;
+        const second = (axis + 2) % 3;
+        return Math.atan2(this.along(second, this.dragAxes), this.along(first, this.dragAxes));
+    }
+    /** `offset` becomes the vector from the gizmo to the ray's point at `distance`. */
+    offsetAt(origin, direction, distance) {
+        for (let component = 0; component < 3; component++) {
+            this.offset[component] =
+                origin[component] +
+                    direction[component] * distance -
+                    this.position[component];
+        }
+    }
+    /** How far `offset` reaches along one of the axes. */
+    along(axis, axes) {
+        const vector = axes[axis];
+        return (this.offset[0] * vector[0] +
+            this.offset[1] * vector[1] +
+            this.offset[2] * vector[2]);
+    }
+    emit(group, ax, ay, az, bx, by, bz) {
+        const target = this.groups[group];
+        if (target === undefined)
+            return;
+        const at = target.count;
+        /* Discarded rather than thrown, for the reason `DebugLines.dropped` exists. */
+        if (at >= target.capacity)
+            return;
+        target.from[at * 3] = ax;
+        target.from[at * 3 + 1] = ay;
+        target.from[at * 3 + 2] = az;
+        target.to[at * 3] = bx;
+        target.to[at * 3 + 1] = by;
+        target.to[at * 3 + 2] = bz;
+        target.count = at + 1;
+    }
+    /** `point` becomes the gizmo origin plus a combination of the three axes. */
+    at(axes, a, u, b, v, c, w) {
+        const first = axes[a];
+        const second = axes[b];
+        const third = axes[c];
+        for (let component = 0; component < 3; component++) {
+            this.point[component] =
+                this.position[component] +
+                    first[component] * u +
+                    second[component] * v +
+                    third[component] * w;
+        }
+    }
+    buildArm(axis, axes, group, arrow) {
+        const first = (axis + 1) % 3;
+        const second = (axis + 2) % 3;
+        const tip = this.size * ARM_END;
+        const base = arrow ? tip - this.size * HEAD_LENGTH : tip - this.size * TIP_RADIUS;
+        this.at(axes, axis, this.size * ARM_START, first, 0, second, 0);
+        const sx = this.point[0], sy = this.point[1], sz = this.point[2];
+        this.at(axes, axis, base, first, 0, second, 0);
+        this.emit(group, sx, sy, sz, this.point[0], this.point[1], this.point[2]);
+        if (!arrow) {
+            this.at(axes, axis, tip, first, 0, second, 0);
+            this.buildOctahedron(this.point[0], this.point[1], this.point[2], this.size * TIP_RADIUS, axes, group);
+            return;
+        }
+        /* A four-spoke cone: the tip to four points around the base, and the base square. */
+        this.at(axes, axis, tip, first, 0, second, 0);
+        const tx = this.point[0], ty = this.point[1], tz = this.point[2];
+        const radius = this.size * HEAD_RADIUS;
+        let px = 0, py = 0, pz = 0;
+        for (let corner = 0; corner < 4; corner++) {
+            const angle = (corner / 4) * TWO_PI;
+            this.at(axes, axis, base, first, Math.cos(angle) * radius, second, Math.sin(angle) * radius);
+            const cx = this.point[0], cy = this.point[1], cz = this.point[2];
+            this.emit(group, tx, ty, tz, cx, cy, cz);
+            if (corner > 0)
+                this.emit(group, px, py, pz, cx, cy, cz);
+            if (corner === 3) {
+                this.at(axes, axis, base, first, radius, second, 0);
+                this.emit(group, cx, cy, cz, this.point[0], this.point[1], this.point[2]);
+            }
+            px = cx;
+            py = cy;
+            pz = cz;
+        }
+    }
+    buildPlane(normalAxis, axes, group) {
+        const first = (normalAxis + 1) % 3;
+        const second = (normalAxis + 2) % 3;
+        const inner = this.size * PLANE_INNER;
+        const outer = this.size * PLANE_OUTER;
+        let px = 0, py = 0, pz = 0;
+        let fx = 0, fy = 0, fz = 0;
+        for (let corner = 0; corner < 4; corner++) {
+            const u = corner === 1 || corner === 2 ? outer : inner;
+            const v = corner >= 2 ? outer : inner;
+            this.at(axes, first, u, second, v, normalAxis, 0);
+            const cx = this.point[0], cy = this.point[1], cz = this.point[2];
+            if (corner === 0) {
+                fx = cx;
+                fy = cy;
+                fz = cz;
+            }
+            else {
+                this.emit(group, px, py, pz, cx, cy, cz);
+            }
+            if (corner === 3)
+                this.emit(group, cx, cy, cz, fx, fy, fz);
+            px = cx;
+            py = cy;
+            pz = cz;
+        }
+    }
+    buildRing(axis, axes, group) {
+        const first = (axis + 1) % 3;
+        const second = (axis + 2) % 3;
+        const radius = this.size * RING_RADIUS;
+        let px = 0, py = 0, pz = 0;
+        for (let step = 0; step <= this.ringSegments; step++) {
+            const angle = (step / this.ringSegments) * TWO_PI;
+            this.at(axes, first, Math.cos(angle) * radius, second, Math.sin(angle) * radius, axis, 0);
+            const cx = this.point[0], cy = this.point[1], cz = this.point[2];
+            if (step > 0)
+                this.emit(group, px, py, pz, cx, cy, cz);
+            px = cx;
+            py = cy;
+            pz = cz;
+        }
+    }
+    /**
+     * 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.
+     */
+    buildOctahedron(cx, cy, cz, radius, axes, group) {
+        const vertices = this.corners;
+        for (let axis = 0; axis < 3; axis++) {
+            const vector = axes[axis];
+            for (let component = 0; component < 3; component++) {
+                const offset = vector[component] * radius;
+                const centre = component === 0 ? cx : component === 1 ? cy : cz;
+                vertices[axis * 6 + component] = centre + offset;
+                vertices[axis * 6 + 3 + component] = centre - offset;
+            }
+        }
+        /* Every +/- vertex of one axis joins every +/- vertex of the next: four edges a pair. */
+        for (let axis = 0; axis < 3; axis++) {
+            const next = (axis + 1) % 3;
+            for (let a = 0; a < 2; a++) {
+                for (let b = 0; b < 2; b++) {
+                    this.emit(group, vertices[axis * 6 + a * 3], vertices[axis * 6 + a * 3 + 1], vertices[axis * 6 + a * 3 + 2], vertices[next * 6 + b * 3], vertices[next * 6 + b * 3 + 1], vertices[next * 6 + b * 3 + 2]);
+                }
+            }
+        }
+    }
+}