Code-first video & image, rendered natively on WebGPU.
/**
* @file packages/webgpu-renderers/src/text-animations/math.ts
* Mathematical formulations, closed-form physics, affine matrices, and evaluation algorithms.
*/
import { signalRegistry } from "../signals/signal-registry.js";
import type {
AudioSpectrumTypography,
ExpressionEvaluationContext,
KineticMarqueeConfig,
TextAnchorConfig,
VolumetricFormationConfig,
} from "./advanced-types.js";
/**
* Evaluates closed-form underdamped harmonic oscillator for spring physics:
*
* x(t) = target + (x0 - target) * exp(-zeta * omega_n * t) *
* [ cos(omega_d * t) + (zeta / sqrt(1 - zeta^2)) * sin(omega_d * t) ]
*
* @param t Time in seconds since excitation
* @param stiffness Spring stiffness (k)
* @param damping Damping coefficient (c)
* @param mass Mass of glyph (m)
* @param initialVelocity Initial velocity (v0)
* @returns Settled scalar progress in [0, 1] with overshoot
*/
export function evaluateSpringProgress(
t: number,
stiffness = 180,
damping = 12,
mass = 1.0,
initialVelocity = 0,
): number {
if (t <= 0) return 0;
const omega_n = Math.sqrt(Math.max(1e-4, stiffness) / Math.max(1e-4, mass)); // Natural frequency
const zeta = damping / (2 * Math.sqrt(Math.max(1e-4, stiffness * mass))); // Damping ratio
if (zeta < 1.0) {
// Underdamped (oscillates and overshoots target)
const omega_d = omega_n * Math.sqrt(1.0 - zeta * zeta); // Damped frequency
const decay = Math.exp(-zeta * omega_n * t);
const c1 = -1.0;
const c2 =
(initialVelocity - zeta * omega_n * -1.0) / Math.max(1e-6, omega_d);
const displacement =
decay * (c1 * Math.cos(omega_d * t) + c2 * Math.sin(omega_d * t));
return Math.min(2.0, Math.max(-1.0, 1.0 + displacement));
} else if (Math.abs(zeta - 1.0) < 1e-4) {
// Critically damped (fastest settle without overshoot)
const decay = Math.exp(-omega_n * t);
const displacement = (-1.0 + (initialVelocity - omega_n) * t) * decay;
return 1.0 + displacement;
} else {
// Overdamped
const s1 = -omega_n * (zeta - Math.sqrt(zeta * zeta - 1.0));
const s2 = -omega_n * (zeta + Math.sqrt(zeta * zeta - 1.0));
const c1 = (initialVelocity + s2) / Math.max(1e-6, s1 - s2);
const c2 = -1.0 - c1;
return 1.0 + (c1 * Math.exp(s1 * t) + c2 * Math.exp(s2 * t));
}
}
/**
* Evaluates 2D Directional Skew matrix components:
*
* S(theta, phi) = R(phi) * [ 1 tan(theta) ] * R(-phi)
* [ 0 1 ]
*
* @param skewDeg Skew angle in degrees
* @param skewAxisDeg Skew axis in degrees
* @returns 2x2 affine shear matrix components [m00, m01, m10, m11]
*/
export function evaluateSkewMatrix(
skewDeg: number,
skewAxisDeg = 0,
): [number, number, number, number] {
if (skewDeg === 0) return [1, 0, 0, 1];
const theta = (skewDeg * Math.PI) / 180;
const phi = (skewAxisDeg * Math.PI) / 180;
const cosPhi = Math.cos(phi);
const sinPhi = Math.sin(phi);
const tanTheta = Math.tan(theta);
// Multiplied rotation and shear matrices
const m00 = 1 - tanTheta * cosPhi * sinPhi;
const m01 = tanTheta * cosPhi * cosPhi;
const m10 = -tanTheta * sinPhi * sinPhi;
const m11 = 1 + tanTheta * sinPhi * cosPhi;
return [m00, m01, m10, m11];
}
/**
* Computes anchor pivot coordinates relative to glyph bounding box:
*
* @param bbox Glyph bounding box { width, height, ascender, descender }
* @param config Text anchor configuration
* @returns Pivot offset (px, py) relative to glyph quad center
*/
export function computeAnchorPivotOffset(
bbox: { width: number; height: number; ascender: number; descender: number },
config: TextAnchorConfig,
): { px: number; py: number } {
let normX = config.anchorX;
let normY = config.anchorY;
switch (config.preset) {
case "center":
normX = 0.5;
normY = 0.5;
break;
case "baseline":
normX = 0.5;
normY = bbox.height > 0 ? bbox.ascender / bbox.height : 0.8;
break;
case "bottom_left":
normX = 0.0;
normY = 1.0;
break;
case "bottom_center":
normX = 0.5;
normY = 1.0;
break;
case "bottom_right":
normX = 1.0;
normY = 1.0;
break;
case "top_left":
normX = 0.0;
normY = 0.0;
break;
case "top_center":
normX = 0.5;
normY = 0.0;
break;
case "top_right":
normX = 1.0;
normY = 0.0;
break;
default:
normX = 0.5;
normY = 0.5;
break;
}
// Offset relative to quad center (-0.5 to +0.5 of quad dimensions)
const px = (normX - 0.5) * bbox.width + config.offsetX;
const py = (normY - 0.5) * bbox.height + config.offsetY;
return { px, py };
}
/**
* Computes leading displacement per line based on lineAnchor:
*
* @param lineIndex 0-based index of current line
* @param lineCount Total lines in paragraph
* @param lineSpacing Additional leading in pixels
* @param lineAnchor Pivot line anchor in [0, 1]
* @returns Y displacement in pixels
*/
export function computeLineLeadingDisplacement(
lineIndex: number,
lineCount: number,
lineSpacing: number,
lineAnchor = 0,
): number {
if (lineSpacing === 0 || lineCount <= 1) return 0;
const pivotIndex = lineAnchor * (lineCount - 1);
return (lineIndex - pivotIndex) * lineSpacing;
}
/**
* Evaluates an Expression Selector formula safely in a sandboxed numeric scope.
*
* @param expression Formula string (e.g. "Math.sin(time * 4 + textIndex * 0.2)")
* @param ctx Glyph evaluation context
* @returns Numeric selector weight clamped to [-1, 1]
*/
export function evaluateExpressionSelector(
expression: string,
ctx: ExpressionEvaluationContext,
): number {
try {
const scope = {
textIndex: ctx.charIndex,
textTotal: Math.max(1, ctx.totalChars),
wordIndex: ctx.wordIndex,
wordTotal: Math.max(1, ctx.totalWords),
lineIndex: ctx.lineIndex,
lineTotal: Math.max(1, ctx.totalLines),
time: ctx.time,
frame: ctx.frame,
fps: ctx.fps,
sin: Math.sin,
cos: Math.cos,
tan: Math.tan,
exp: Math.exp,
log: Math.log,
abs: Math.abs,
min: Math.min,
max: Math.max,
sqrt: Math.sqrt,
pow: Math.pow,
floor: Math.floor,
ceil: Math.ceil,
round: Math.round,
PI: Math.PI,
clamp: (v: number, lo: number, hi: number) =>
Math.max(lo, Math.min(hi, v)),
noise: (seed: number) => {
const n = Math.sin(seed * 12.9898 + ctx.frame * 0.1) * 43758.5453;
return (n - Math.floor(n)) * 2 - 1;
},
signals: ctx.signals ?? {},
};
const keys = Object.keys(scope);
const values = Object.values(scope);
const fn = new Function(...keys, `return (${expression});`);
const result = Number(fn(...values));
return Number.isFinite(result) ? Math.max(-1, Math.min(1, result)) : 0;
} catch {
return 0;
}
}
/**
* 3D Volumetric arrangement transformation output.
*/
export interface Volumetric3DTransform {
x: number;
y: number;
z: number;
rotX: number;
rotY: number;
rotZ: number;
scaleMult: number;
depthOpacity?: number;
}
/**
* Evaluates 3D Volumetric Formation parametric coordinates.
*/
export function evaluateVolumetricFormation(
glyphIndex: number,
totalGlyphs: number,
config: VolumetricFormationConfig,
): Volumetric3DTransform {
const n = Math.max(1, totalGlyphs);
const norm = n > 1 ? glyphIndex / (n - 1) : 0;
const totalAngleRad = (config.totalAngle * Math.PI) / 180;
const phi = norm * totalAngleRad;
let x = 0;
let y = 0;
let z = 0;
let rotX = 0;
let rotY = 0;
let rotZ = 0;
let depthOpacity = 1.0;
switch (config.mode) {
case "cylinder": {
// Center arc around front-facing camera when totalAngle < 360; otherwise sweep full circle
const theta = config.totalAngle < 360 ? (norm - 0.5) * totalAngleRad : phi;
if (config.axis === "y") {
x = config.radius * Math.sin(theta);
z = config.radius * Math.cos(theta) - config.radius;
rotY = (theta * 180) / Math.PI;
} else if (config.axis === "x") {
y = config.radius * Math.sin(theta);
z = config.radius * Math.cos(theta) - config.radius;
rotX = (theta * 180) / Math.PI;
} else {
x = config.radius * Math.sin(theta);
y = config.radius * Math.cos(theta);
rotZ = (theta * 180) / Math.PI;
}
const facing = Math.cos(theta);
depthOpacity = Math.max(0.25, (facing + 1) * 0.5);
break;
}
case "vortex": {
const startAngleRad = -Math.PI / 2; // Start upright at 12 o'clock
const spiralPhi = startAngleRad + phi;
// Smooth radius decay from R down to 0.65 * R to keep inner characters cleanly separated
const r = config.radius * (1 - norm * 0.35);
x = r * Math.cos(spiralPhi);
y = r * Math.sin(spiralPhi);
z = -glyphIndex * config.pitch || 0;
// Exact analytical tangent orientation along spiral curve
const dr = (-0.35 * config.radius) / (totalAngleRad || 1);
const dx = dr * Math.cos(spiralPhi) - r * Math.sin(spiralPhi);
const dy = dr * Math.sin(spiralPhi) + r * Math.cos(spiralPhi);
rotZ = (Math.atan2(dy, dx) * 180) / Math.PI;
depthOpacity = Math.max(0.65, 1 - norm * 0.35);
break;
}
case "helix": {
if (config.axis === "x") {
// Horizontal DNA ribbon advancing along reading axis X
const pitchX = config.pitch > 10 ? config.pitch : 28;
x = (glyphIndex - (n - 1) / 2) * pitchX;
y = config.radius * Math.sin(phi);
z = config.radius * Math.cos(phi) - config.radius;
// Subtle 3D wave tilt (max 22°) along surface normal
rotX = Math.sin(phi) * 22;
const facing = Math.cos(phi);
depthOpacity = 0.75 + 0.25 * ((facing + 1) * 0.5);
} else {
// Vertical helix advancing along Y
const theta = (norm - 0.5) * totalAngleRad;
x = config.radius * Math.sin(theta);
y = (glyphIndex - (n - 1) / 2) * config.pitch;
z = config.radius * Math.cos(theta) - config.radius;
rotY = (theta * 180) / Math.PI;
const facing = Math.cos(theta);
depthOpacity = Math.max(0.65, (facing + 1) * 0.5);
}
break;
}
default: {
z = 0;
break;
}
}
const perspective = Math.max(100, config.perspective ?? 1200);
const depthDist = perspective - z;
const scaleMult = depthDist > 1 ? perspective / depthDist : 1;
return {
x: x * scaleMult,
y: y * scaleMult,
z,
rotX,
rotY,
rotZ,
scaleMult: Math.max(0.1, scaleMult),
depthOpacity,
};
}
/**
* Evaluates infinite kinetic marquee translation and snapping.
*/
export function evaluateMarqueeOffset(
baseX: number,
containerWidth: number,
contentWidth: number,
config: KineticMarqueeConfig,
elapsedSec: number,
): number {
const effectiveWidth =
containerWidth > 0 ? Math.max(containerWidth, contentWidth) : contentWidth;
const totalSpan = effectiveWidth + config.repeatGap;
if (totalSpan <= 0) return baseX;
let travel = config.velocity * elapsedSec;
if (config.snap?.enabled) {
const targetStop = config.snap.stopIndex ?? 0;
const snapUnit = config.snap.granularity === "character" ? 40 : 120;
const targetPos = targetStop * snapUnit;
// Decelerate towards snap stop
const decelFactor = Math.min(1.0, elapsedSec * 1.5);
travel = travel * (1.0 - decelFactor) + targetPos * decelFactor;
}
if (config.direction === "right" || config.direction === "down") {
travel = -travel;
}
if (config.loop) {
const wrapped = (baseX - travel) % totalSpan;
return wrapped < -contentWidth ? wrapped + totalSpan : wrapped;
}
return baseX - travel;
}
/**
* Samples audio FFT frequency bin and computes scale factor for Audio Spectrum Typography.
*/
export function sampleAudioSpectrumScale(
glyphIndex: number,
totalGlyphs: number,
config: AudioSpectrumTypography,
signals: Record<string, unknown> | undefined,
frame: number,
fps: number,
): number {
const n = Math.max(1, totalGlyphs);
const norm = n > 1 ? glyphIndex / (n - 1) : 0.5;
// Logarithmic frequency distribution
const minFreq = Math.max(20, config.minFreqHz);
const maxFreq = Math.max(minFreq + 100, config.maxFreqHz);
const targetFreq = minFreq * (maxFreq / minFreq) ** norm;
let magnitude = 0;
// Query from signal registry first
const regSamples = signalRegistry.getChannelSamples(
config.signalChannel,
"primary",
);
if (regSamples && regSamples.length > 0) {
const compFps = fps > 0 ? fps : 24;
const sampleIdx = Math.max(
0,
Math.min(regSamples.length - 1, Math.round((frame / compFps) * 24)),
);
magnitude = Number(regSamples[sampleIdx]) || 0;
} else if (signals) {
const sig = signals[config.signalChannel];
if (typeof sig === "number") {
magnitude = sig;
} else if (typeof sig === "function") {
magnitude = Number(sig(frame, fps, targetFreq)) || 0;
} else if (typeof sig === "object" && sig !== null) {
const sObj = sig as Record<string, unknown>;
if (typeof sObj.get === "function") {
magnitude =
Number(
(sObj.get as (ctx: unknown) => unknown)({
frame,
fps,
freq: targetFreq,
}),
) || 0;
} else if (
Array.isArray(sObj.samples) ||
ArrayBuffer.isView(sObj.samples)
) {
const arr = sObj.samples as ArrayLike<number>;
const binIdx = Math.floor(norm * (arr.length - 1));
magnitude = Number(arr[binIdx]) || 0;
}
}
}
// Clamp magnitude [0, 1]
const clampedMag = Math.max(0, Math.min(1, magnitude));
return config.minScale + clampedMag * (config.maxScale - config.minScale);
}