@pmndrs/klipp 0.0.0-stage → 0.14.0

package/dist/core/damping/Damper.js

@@ -0,0 +1,22 @@
+import { createState, damp, reset } from "./damping.js";
+//#region src/core/damping/Damper.ts
+/** Stateful wrapper over `damp`. */
+var Damper = class {
+	state = createState();
+	get velocity() {
+		return this.state.velocity;
+	}
+	set velocity(value) {
+		this.state.velocity = value;
+	}
+	update(current, target, dampingTime, dt, maxSpeed = Infinity, epsilon = 1e-4) {
+		this.state.value = current;
+		return damp(this.state, target, dampingTime, dt, maxSpeed, epsilon).value;
+	}
+	/** Reset the spring state so the next call snaps to the target again. */
+	reset() {
+		reset(this.state);
+	}
+};
+//#endregion
+export { Damper };

package/dist/core/damping/damping.d.ts

@@ -0,0 +1,30 @@
+import { type Quat, type Vec3 } from 'math';
+import { type Spring } from 'math/time';
+/** Damping time, optionally asymmetric for widening and narrowing gaps. */
+export type DampingConstant = number | {
+    into: number;
+    from: number;
+};
+/** Damper memory: a math `Spring<number>` plus asymmetric damping and snap state. */
+export type DamperState = Spring<number> & {
+    previousDistance: number;
+    hasUpdated: boolean;
+};
+export declare const createState: (value?: number) => DamperState;
+/** Reset the state so the next call snaps to the target. */
+export declare function reset(state: DamperState): void;
+/** Critically damped spring step with target snapping. Mutates and returns `state`. */
+export declare function damp(state: DamperState, target: number, damping: DampingConstant, dt: number, maxSpeed?: number, epsilon?: number): DamperState;
+/** One damper per Cartesian component. */
+export type Vector3DamperState = {
+    x: DamperState;
+    y: DamperState;
+    z: DamperState;
+};
+export declare const createVector3State: () => Vector3DamperState;
+/** Reset all three component dampers. */
+export declare function resetVector3(state: Vector3DamperState): void;
+/** Damps the components of `out` toward `target` independently. Mutates and returns `out`. */
+export declare function dampVector3(state: Vector3DamperState, out: Vec3, target: Vec3, damping: DampingConstant, dt: number, maxSpeed?: number): Vec3;
+/** Damps `out` toward `target` along the shortest angular delta. Mutates and returns `out`. */
+export declare function dampQuaternion(state: DamperState, out: Quat, target: Quat, damping: DampingConstant, dt: number, maxSpeed?: number): Quat;

package/dist/core/damping/damping.js

@@ -0,0 +1,119 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { clamp, quat, vec3, vec4 } from "math";
+import { spring } from "math/time";
+//#region src/core/damping/damping.ts
+var damping_exports = /* @__PURE__ */ __exportAll({
+	createState: () => createState,
+	createVector3State: () => createVector3State,
+	damp: () => damp,
+	dampQuaternion: () => dampQuaternion,
+	dampVector3: () => dampVector3,
+	reset: () => reset,
+	resetVector3: () => resetVector3
+});
+var createState = (value = 0) => ({
+	value,
+	velocity: 0,
+	previousDistance: 0,
+	hasUpdated: false
+});
+/** Reset the state so the next call snaps to the target. */
+function reset(state) {
+	state.velocity = 0;
+	state.previousDistance = 0;
+	state.hasUpdated = false;
+}
+/** Critically damped spring step with target snapping. Mutates and returns `state`. */
+function damp(state, target, damping, dt, maxSpeed = Infinity, epsilon = 1e-4) {
+	if (!state.hasUpdated) {
+		state.hasUpdated = true;
+		state.value = target;
+		return state;
+	}
+	dt = Math.max(0, dt);
+	const current = state.value;
+	const distance = Math.abs(target - current);
+	if (distance < epsilon) {
+		state.velocity = 0;
+		state.previousDistance = 0;
+		state.value = target;
+		return state;
+	}
+	const smoothTime = typeof damping === "number" ? damping : distance > state.previousDistance ? damping.into : damping.from;
+	state.previousDistance = distance;
+	const time = Math.max(1e-4, smoothTime);
+	const maxChange = maxSpeed * Math.max(time, dt);
+	const change = clamp(current - target, -maxChange, maxChange);
+	spring.damp(state, current - change, time, dt);
+	if (target - current > 0 === state.value > target) {
+		state.value = target;
+		state.velocity = 0;
+	}
+	return state;
+}
+var createVector3State = () => ({
+	x: createState(),
+	y: createState(),
+	z: createState()
+});
+/** Reset all three component dampers. */
+function resetVector3(state) {
+	reset(state.x);
+	reset(state.y);
+	reset(state.z);
+}
+/** Damps the components of `out` toward `target` independently. Mutates and returns `out`. */
+function dampVector3(state, out, target, damping, dt, maxSpeed = Infinity) {
+	if (typeof damping === "number" && damping <= 0) return vec3.copy(out, target);
+	state.x.value = out[0];
+	state.y.value = out[1];
+	state.z.value = out[2];
+	out[0] = damp(state.x, target[0], damping, dt, maxSpeed).value;
+	out[1] = damp(state.y, target[1], damping, dt, maxSpeed).value;
+	out[2] = damp(state.z, target[2], damping, dt, maxSpeed).value;
+	return out;
+}
+var scratchOutInverse = [
+	0,
+	0,
+	0,
+	1
+];
+var scratchDelta = [
+	0,
+	0,
+	0,
+	1
+];
+var scratchAxis = [
+	0,
+	0,
+	0
+];
+var scratchStep = [
+	0,
+	0,
+	0,
+	1
+];
+/** Damps `out` toward `target` along the shortest angular delta. Mutates and returns `out`. */
+function dampQuaternion(state, out, target, damping, dt, maxSpeed = Infinity) {
+	if (typeof damping === "number" && damping <= 0) return vec4.copy(out, target);
+	quat.conjugate(scratchOutInverse, out);
+	quat.multiply(scratchDelta, target, scratchOutInverse);
+	if (scratchDelta[3] < 0) vec4.negate(scratchDelta, scratchDelta);
+	const angle = 2 * Math.acos(clamp(scratchDelta[3], -1, 1));
+	if (angle < 1e-5) {
+		state.value = 0;
+		damp(state, 0, damping, dt);
+		state.velocity = 0;
+		return vec4.copy(out, target);
+	}
+	state.value = 0;
+	const dampedAngle = damp(state, angle, damping, dt, maxSpeed).value;
+	const halfSin = Math.sin(angle / 2);
+	vec3.set(scratchAxis, scratchDelta[0] / halfSin, scratchDelta[1] / halfSin, scratchDelta[2] / halfSin);
+	return quat.multiply(out, quat.setAxisAngle(scratchStep, scratchAxis, dampedAngle), out);
+}
+//#endregion
+export { createState, createVector3State, damp, dampQuaternion, dampVector3, damping_exports, reset, resetVector3 };

package/dist/core/damping/index.d.ts

@@ -0,0 +1,5 @@
+export { Damper } from './Damper.js';
+export * as damping from './damping.js';
+export type { DamperState, DampingConstant, Vector3DamperState } from './damping.js';
+export * as predictor from './predictor.js';
+export type { PredictorState } from './predictor.js';

package/dist/core/damping/predictor.d.ts

@@ -0,0 +1,16 @@
+import { type Vec3 } from 'math';
+import type { Vector3DamperState } from './damping.js';
+/** Velocity tracking state for position extrapolation. */
+export type PredictorState = {
+    velocity: Vec3;
+    previousPosition: Vec3;
+    velocityDamper: Vector3DamperState;
+    hasPosition: boolean;
+};
+export declare const create: () => PredictorState;
+/** Clear the tracked velocity and position history. */
+export declare function reset(state: PredictorState): void;
+/** Add a position sample and update the tracked velocity. */
+export declare function addPosition(state: PredictorState, position: Vec3, dt: number, smoothing: number): void;
+/** Write the predicted offset `time` seconds ahead into `out`. */
+export declare function predictDelta(out: Vec3, state: PredictorState, time: number): Vec3;

package/dist/core/damping/predictor.js

@@ -0,0 +1,56 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { createVector3State, dampVector3, resetVector3 } from "./damping.js";
+import { vec3 } from "math";
+//#region src/core/damping/predictor.ts
+var predictor_exports = /* @__PURE__ */ __exportAll({
+	addPosition: () => addPosition,
+	create: () => create,
+	predictDelta: () => predictDelta,
+	reset: () => reset
+});
+var create = () => ({
+	velocity: [
+		0,
+		0,
+		0
+	],
+	previousPosition: [
+		0,
+		0,
+		0
+	],
+	velocityDamper: createVector3State(),
+	hasPosition: false
+});
+/** Clear the tracked velocity and position history. */
+function reset(state) {
+	vec3.set(state.velocity, 0, 0, 0);
+	resetVector3(state.velocityDamper);
+	state.hasPosition = false;
+}
+var scratchRawVelocity = [
+	0,
+	0,
+	0
+];
+/** Add a position sample and update the tracked velocity. */
+function addPosition(state, position, dt, smoothing) {
+	if (!state.hasPosition) {
+		state.hasPosition = true;
+		vec3.copy(state.previousPosition, position);
+		return;
+	}
+	dt = Math.max(0, dt);
+	if (dt > 0) {
+		vec3.scale(scratchRawVelocity, vec3.subtract(scratchRawVelocity, position, state.previousPosition), 1 / dt);
+		const slowing = vec3.squaredLength(scratchRawVelocity) < vec3.squaredLength(state.velocity);
+		dampVector3(state.velocityDamper, state.velocity, scratchRawVelocity, smoothing / (slowing ? 30 : 10), dt);
+	}
+	vec3.copy(state.previousPosition, position);
+}
+/** Write the predicted offset `time` seconds ahead into `out`. */
+function predictDelta(out, state, time) {
+	return vec3.scale(out, state.velocity, time);
+}
+//#endregion
+export { addPosition, create, predictDelta, predictor_exports, reset };

package/dist/core/debug/debugZones.d.ts

@@ -0,0 +1,16 @@
+import type { GroupFramingMode } from '../extension/groupFraming.js';
+export type DebugZone = {
+    /** Zone center in normalized screen coordinates. */
+    screenPosition: [number, number];
+    /** Zone width and height. */
+    size: [number, number];
+    /** CSS class applied to the zone. */
+    className: string;
+};
+/** A composer's hard limit and dead zone as boxes. Both are half-extents around `screenPosition`. */
+export declare function composer(screenPosition: [number, number], deadZone: [number, number], hardLimit: [number, number]): DebugZone[];
+/**
+ * Size of group framing's padding boundary on screen, for a group `distance` away. An axis left out by
+ * `framingMode` spans the full frame.
+ */
+export declare function groupFramingPaddingBox(out: [number, number], fov: number, aspect: number, distance: number, padding: number, framingMode: GroupFramingMode): [number, number];

package/dist/core/debug/debugZones.js

@@ -0,0 +1,38 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { horizontalHalfFov } from "../extension/groupFraming.js";
+import { clamp, degreesToRadians } from "math";
+//#region src/core/debug/debugZones.ts
+var debugZones_exports = /* @__PURE__ */ __exportAll({
+	composer: () => composer,
+	groupFramingPaddingBox: () => groupFramingPaddingBox
+});
+/** A composer's hard limit and dead zone as boxes. Both are half-extents around `screenPosition`. */
+function composer(screenPosition, deadZone, hardLimit) {
+	const zones = [];
+	if (hardLimit[0] > 0 || hardLimit[1] > 0) zones.push({
+		screenPosition,
+		size: [hardLimit[0] * 2, hardLimit[1] * 2],
+		className: "klipp-debug-hardlimit"
+	});
+	if (deadZone[0] > 0 || deadZone[1] > 0) zones.push({
+		screenPosition,
+		size: [deadZone[0] * 2, deadZone[1] * 2],
+		className: "klipp-debug-deadzone"
+	});
+	return zones;
+}
+function paddingEdgeFraction(halfFov, distance, padding) {
+	return clamp(1 - padding / (distance * Math.sin(halfFov)), 0, 1);
+}
+/**
+* Size of group framing's padding boundary on screen, for a group `distance` away. An axis left out by
+* `framingMode` spans the full frame.
+*/
+function groupFramingPaddingBox(out, fov, aspect, distance, padding, framingMode) {
+	const verticalHalfFov = degreesToRadians(fov) / 2;
+	out[0] = framingMode === "vertical" ? 2 : paddingEdgeFraction(horizontalHalfFov(verticalHalfFov, aspect), distance, padding) * 2;
+	out[1] = framingMode === "horizontal" ? 2 : paddingEdgeFraction(verticalHalfFov, distance, padding) * 2;
+	return out;
+}
+//#endregion
+export { composer, debugZones_exports, groupFramingPaddingBox };

package/dist/core/debug/index.d.ts

@@ -0,0 +1,2 @@
+export * as debugZones from './debugZones.js';
+export type { DebugZone } from './debugZones.js';

package/dist/core/extension/GroupFramingExtension.d.ts

@@ -0,0 +1,26 @@
+import type { CameraState } from '../CameraState.js';
+import type { DampingConstant } from '../damping/damping.js';
+import * as groupFraming from './groupFraming.js';
+import type { GroupFramingFitMode, GroupFramingMode, GroupFramingParams, GroupMember, GroupPositionMode } from './groupFraming.js';
+export type GroupFramingOptions = Partial<GroupFramingParams>;
+/** Keeps a group of members in frame by adjusting distance and view offset. Layers override `readMembers`. */
+export declare class GroupFramingExtension implements GroupFramingParams {
+    /** The members, updated by the caller every frame. */
+    members: readonly GroupMember[];
+    positionMode: GroupPositionMode;
+    padding: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    damping: DampingConstant;
+    maxSpeed: number;
+    screenPosition: [number, number];
+    fitMode: GroupFramingFitMode;
+    minDistance: number;
+    maxDistance: number;
+    framingMode: GroupFramingMode;
+    readonly state: groupFraming.GroupFramingState;
+    constructor(members?: readonly GroupMember[], positionMode?: GroupPositionMode, options?: GroupFramingOptions);
+    update: (out: CameraState, dt: number, justActivated: boolean) => boolean;
+    /** This frame's members. */
+    protected readMembers(): readonly GroupMember[];
+}

package/dist/core/extension/GroupFramingExtension.js

@@ -0,0 +1,24 @@
+import { createParams, createState, update } from "./groupFraming.js";
+//#region src/core/extension/GroupFramingExtension.ts
+/** Keeps a group of members in frame by adjusting distance and view offset. Layers override `readMembers`. */
+var GroupFramingExtension = class {
+	/** The members, updated by the caller every frame. */
+	members;
+	positionMode;
+	state = createState();
+	constructor(members = [], positionMode = "groupCenter", options) {
+		this.members = members;
+		this.positionMode = positionMode;
+		Object.assign(this, createParams(options));
+	}
+	update = (out, dt, justActivated) => {
+		const members = this.readMembers();
+		return update(out, this.state, this, members, this.positionMode, dt, justActivated);
+	};
+	/** This frame's members. */
+	readMembers() {
+		return this.members;
+	}
+};
+//#endregion
+export { GroupFramingExtension };

package/dist/core/extension/LensExtension.d.ts

@@ -0,0 +1,20 @@
+import type { CameraState } from '../CameraState.js';
+import type { DampingConstant } from '../damping/damping.js';
+import * as lens from './lens.js';
+import type { LensParams } from './lens.js';
+export type LensOptions = Partial<LensParams>;
+/** Overrides lens fields with independent damping. */
+export declare class LensExtension implements LensParams {
+    fov?: number;
+    near?: number;
+    far?: number;
+    fovDamping: DampingConstant;
+    nearDamping: DampingConstant;
+    farDamping: DampingConstant;
+    fovMaxSpeed: number;
+    nearMaxSpeed: number;
+    farMaxSpeed: number;
+    readonly state: lens.LensState;
+    constructor(options?: LensOptions);
+    update: (out: CameraState, dt: number, justActivated: boolean) => boolean;
+}

package/dist/core/extension/LensExtension.js

@@ -0,0 +1,12 @@
+import { createParams, createState, update } from "./lens.js";
+//#region src/core/extension/LensExtension.ts
+/** Overrides lens fields with independent damping. */
+var LensExtension = class {
+	state = createState();
+	constructor(options) {
+		Object.assign(this, createParams(options));
+	}
+	update = (out, dt, justActivated) => update(out, this.state, this, dt, justActivated);
+};
+//#endregion
+export { LensExtension };

package/dist/core/extension/groupFraming.d.ts

@@ -0,0 +1,62 @@
+import { type Vec3 } from 'math';
+import type { CameraState } from '../CameraState.js';
+import type { TargetExtent } from '../TargetExtent.js';
+import type { DamperState, DampingConstant } from '../damping/damping.js';
+/** A group member. Set `resolved` to `false` to skip it, for example while it isn't loaded yet. */
+export type GroupMember = {
+    position: Vec3;
+    extent: TargetExtent;
+    weight: number;
+    resolved: boolean;
+};
+export declare const createMember: () => GroupMember;
+/** Strategy used to compute the group's position. */
+export type GroupPositionMode = 'groupCenter' | 'groupAverage';
+/** Fit mode controlling whether the extension can dolly the camera closer. */
+export type GroupFramingFitMode = 'ceiling' | 'rigid';
+/** Which screen dimensions the fit distance has to satisfy. */
+export type GroupFramingMode = 'horizontal' | 'vertical' | 'horizontalAndVertical';
+export type GroupFramingParams = {
+    /** Margin kept clear around the group's members, in world units. */
+    padding: number;
+    /** Viewport width in pixels. */
+    viewportWidth: number;
+    /** Viewport height in pixels. */
+    viewportHeight: number;
+    /** Response time for distance and screen composition. */
+    damping: DampingConstant;
+    /** Maximum damping speed, in world units/sec. */
+    maxSpeed: number;
+    /** Frustum offset used to compose the group on screen. */
+    screenPosition: [number, number];
+    /** `'ceiling'` never dollies closer than the Body placed the camera, `'rigid'` always sits at the fit distance. */
+    fitMode: GroupFramingFitMode;
+    /** Minimum fit distance. */
+    minDistance: number;
+    /** Maximum fit distance. */
+    maxDistance: number;
+    /** Which screen dimensions the fit distance has to satisfy. */
+    framingMode: GroupFramingMode;
+};
+/** Every setting from `settings`, or its default. */
+export declare const createParams: (settings?: Partial<GroupFramingParams>) => GroupFramingParams;
+export type GroupFramingState = {
+    distanceDamper: DamperState;
+    screenPositionXDamper: DamperState;
+    screenPositionYDamper: DamperState;
+    currentDistance: number;
+    currentScreenPosition: [number, number];
+};
+export declare const createState: () => GroupFramingState;
+/**
+ * Writes the group position to `outPosition` and returns a conservative enclosing radius, or -1 (leaving
+ * `outPosition` untouched) when no member is resolved.
+ */
+export declare function computeBounds(outPosition: Vec3, members: readonly GroupMember[], mode: GroupPositionMode): number;
+/** Half the horizontal field of view, in radians, for a vertical half-FOV and aspect ratio. */
+export declare const horizontalHalfFov: (verticalHalfFov: number, aspect: number) => number;
+/**
+ * Keeps the group inside the frame by moving `out` along its own view axis and easing `viewOffset` to
+ * `screenPosition`. Returns true while still moving.
+ */
+export declare function update(out: CameraState, state: GroupFramingState, params: GroupFramingParams, members: readonly GroupMember[], positionMode: GroupPositionMode, dt: number, justActivated: boolean): boolean;