Skip to content

Code-first video & image, rendered natively on WebGPU.

9.1 KB
Raw Blame
/**
 * Sampling a layer's animation at a frame exactly as the compositor draws
 * it: keyframe segments shaped by GSAP's eases (what the compiled GSAP
 * timeline plays), other sources (wiggle, spring, signals) by the program
 * evaluator. The compositor's draw-time tracks and anything that must agree
 * with the picture outside a render (physics following a layer) share it.
 */
import gsapModule from "gsap";
import type { NumberTrack, Vec3Track } from "./character-schema.js";
import { evaluateKeyframes, evaluateTrackAtFrame } from "./evaluator.js";
import type { AnimationTrack, EaseRef } from "./schema.js";

type EaseFn = (p: number) => number;
interface GsapEases {
	parseEase(ease: string): EaseFn | undefined;
}
const gsap = ((gsapModule as unknown as { default?: GsapEases }).default ??
	gsapModule) as unknown as GsapEases;

/**
 * Solves a cubic bezier curve defined by control points (x1, y1) and (x2, y2)
 * for a given progress parameter t in [0, 1].
 */
export function solveCubicBezier(
	x1: number,
	y1: number,
	x2: number,
	y2: number,
	t: number,
): number {
	if (t <= 0) return 0;
	if (t >= 1) return 1;

	// Check for linear edge case
	if (x1 === y1 && x2 === y2) return t;

	// Find u such that x(u) = t
	// x(u) = 3*(1-u)^2 * u * x1 + 3*(1-u) * u^2 * x2 + u^3
	// dx/du = 3*(1-u)^2 * x1 + 6*(1-u)*u * (x2 - x1) + 3*u^2 * (1 - x2)
	let u = t; // initial guess
	for (let i = 0; i < 8; i++) {
		const oneMinusU = 1 - u;
		const oneMinusU2 = oneMinusU * oneMinusU;
		const u2 = u * u;

		const currentX = 3 * oneMinusU2 * u * x1 + 3 * oneMinusU * u2 * x2 + u2 * u;
		const diff = currentX - t;
		if (Math.abs(diff) < 1e-6) break;

		const dx =
			3 * oneMinusU2 * x1 + 6 * oneMinusU * u * (x2 - x1) + 3 * u2 * (1 - x2);

		if (Math.abs(dx) < 1e-6) break;
		u -= diff / dx;
		u = Math.max(0, Math.min(1, u));
	}

	// Bisection fallback if Newton didn't converge within bounds
	const oneMinusU = 1 - u;
	const checkX =
		3 * oneMinusU * oneMinusU * u * x1 + 3 * oneMinusU * u * u * x2 + u * u * u;

	if (Math.abs(checkX - t) > 1e-3) {
		let low = 0;
		let high = 1;
		u = t;
		for (let i = 0; i < 16; i++) {
			const mid = (low + high) * 0.5;
			const oMid = 1 - mid;
			const xMid =
				3 * oMid * oMid * mid * x1 +
				3 * oMid * mid * mid * x2 +
				mid * mid * mid;
			if (Math.abs(xMid - t) < 1e-5) {
				u = mid;
				break;
			}
			if (xMid < t) low = mid;
			else high = mid;
			u = mid;
		}
	}

	// Evaluate y(u)
	const oU = 1 - u;
	return 3 * oU * oU * u * y1 + 3 * oU * u * u * y2 + u * u * u;
}

export function mappedEase(
	ease?: EaseRef,
	durationFrames?: number,
	fps = 24,
): string | ((p: number) => number) {
	if (!ease) return "none";
	const { name, dir, params } = ease;
	if (name === "none") return "none";

	// Custom closed-form Spring ease solver
	if ((name as string) === "spring") {
		const damping = Math.max(0.001, params?.[0] ?? 10);
		const stiffness = Math.max(0.001, params?.[1] ?? 100);
		const mass = Math.max(0.001, params?.[2] ?? 1);

		return (p: number) => {
			const safeFps = fps > 0 ? fps : 24;
			const durSec =
				durationFrames && durationFrames > 0 ? durationFrames / safeFps : 1.0;
			const t = p * durSec;

			const m = mass;
			const k = stiffness;
			const c = damping;

			const w0 = Math.sqrt(k / m);
			const zeta = c / (2 * Math.sqrt(k * m));

			let x = 0;
			if (zeta < 1) {
				const wd = w0 * Math.sqrt(1 - zeta * zeta);
				const A = -1;
				const B = (-zeta * w0) / wd;
				x =
					Math.exp(-zeta * w0 * t) *
					(A * Math.cos(wd * t) + B * Math.sin(wd * t));
			} else if (zeta === 1) {
				const A = -1;
				const B = -w0;
				x = Math.exp(-w0 * t) * (A + B * t);
			} else {
				const r1 = -w0 * (zeta - Math.sqrt(zeta * zeta - 1));
				const r2 = -w0 * (zeta + Math.sqrt(zeta * zeta - 1));
				const C1 = -1 / (1 - r1 / r2);
				const C2 = -1 - C1;
				x = C1 * Math.exp(r1 * t) + C2 * Math.exp(r2 * t);
			}
			return 1 + x;
		};
	}

	if ((name as string) === "cubic") {
		const x1 = params?.[0] ?? 0.25;
		const y1 = params?.[1] ?? 0.1;
		const x2 = params?.[2] ?? 0.25;
		const y2 = params?.[3] ?? 1.0;
		return (p: number) => solveCubicBezier(x1, y1, x2, y2, p);
	}

	if ((name as string) === "hold") {
		// GSAP rounds time to 1e-7 s, so on its own end frame a short segment's
		// progress can land ~1e-5 under 1; 1e-4 of a segment is safe slack for the
		// jump (it would only fire a frame early on segments over 10,000 frames).
		return (p: number) => (p >= 1 - 1e-4 ? 1 : 0);
	}

	const easeName = name as string;
	let suffix = "";
	if (params && params.length > 0) {
		suffix = `(${params.join(", ")})`;
	} else if (name === "back") {
		suffix = "(1.7)";
	} else if (name === "elastic") {
		suffix = "(1, 0.3)";
	}

	return `${easeName}.${dir}${suffix}`;
}

/** GSAP's shaping for a keyframe segment, so draw-time tracks ease like baked ones. */
export function gsapEase(
	fps: number,
): (ease: EaseRef | undefined, deltaFrames: number, t: number) => number {
	return (ease, deltaFrames, t) => {
		const e = mappedEase(ease, deltaFrames, fps);
		const fn = typeof e === "function" ? e : gsap.parseEase(e);
		return fn ? fn(t) : t;
	};
}

export interface TrackSampleContext {
	/** The layer's start frame: keyframes are relative to it. */
	startFrame?: number;
	/** Stepped timing ("on twos" = 2): the value holds for this many frames. */
	step?: number;
	/** The layer's own values, for sources that modulate them. */
	base?: Record<string, unknown>;
	signals?: Record<string, unknown>;
}

/** A track's value at composition frame `frame`. */
export function sampleTrack(
	track: AnimationTrack,
	frame: number,
	fps: number,
	ctx: TrackSampleContext = {},
): number | boolean | string {
	const startFrame = ctx.startFrame ?? 0;
	const step = ctx.step ?? 1;
	const f =
		step > 1
			? startFrame + Math.floor((frame - startFrame) / step) * step
			: frame;
	const source = track.source ?? { type: "keyframe" };
	if (source.type === "keyframe") {
		return evaluateKeyframes(track, f - startFrame, gsapEase(fps));
	}
	return evaluateTrackAtFrame(track, f, fps, {
		startFrame,
		baseValues: ctx.base,
		signals: ctx.signals,
	});
}

/** What `sampleLayerProp` reads from a layer. */
export interface AnimatedLayer {
	startFrame?: number;
	animation?: { tracks?: AnimationTrack[]; frameStep?: number };
	[prop: string]: unknown;
}

/**
 * A layer's numeric prop at composition frame `frame`: its own value, then
 * each of its tracks on that prop in order (a later track overrides).
 */
export function sampleLayerProp(
	layer: AnimatedLayer,
	prop: string,
	frame: number,
	fps: number,
	fallback = 0,
): number {
	const own = layer[prop];
	let value = typeof own === "number" && Number.isFinite(own) ? own : fallback;
	const animation = layer.animation;
	for (const track of animation?.tracks ?? []) {
		if (track.prop !== prop) continue;
		const v = sampleTrack(track, frame, fps, {
			startFrame: layer.startFrame ?? 0,
			step: animation?.frameStep,
			base: layer,
		});
		if (typeof v === "number" && Number.isFinite(v)) value = v;
	}
	return value;
}

// --- Character tracks (pose, IK and aim targets, weights) -------------------

/** What a track reads: the layer's frame, and the clock signals expect. */
export interface TrackClock {
	frame: number;
	fps: number;
}

const signalContext = (c: TrackClock) => ({
	frame: c.frame,
	fps: c.fps,
	time: c.frame / c.fps,
	duration: 0,
	durationMs: 0,
	progress: 0,
	deltaTime: 1 / c.fps,
});

/** A number track's value: constant, keys, function, or signal. */
export function numberAt(
	track: NumberTrack | undefined,
	clock: TrackClock,
	fallback: number,
): number {
	if (track === undefined) return fallback;
	if (typeof track === "number") return track;
	if (typeof track === "function") return track(clock.frame);
	if (Array.isArray(track)) return keyed(track, clock.frame, 1)[0] ?? fallback;
	const v = track.get(signalContext(clock));
	return Number.isFinite(v) ? v : fallback;
}

/** Whether a point track is `[[frame, x, y, z], …]` keys (not one track per axis). */
const isPointKeys = (track: unknown[]): track is number[][] =>
	Array.isArray(track[0]) && (track[0] as unknown[]).length === 4;

/** A point track's value: per-axis tracks, keys, or a function. */
export function vec3At(
	track: Vec3Track,
	clock: TrackClock,
): [number, number, number] {
	if (typeof track === "function") return track(clock.frame);
	if (isPointKeys(track))
		return keyed(track, clock.frame, 3) as [number, number, number];
	const axes = track as [NumberTrack, NumberTrack, NumberTrack];
	return [
		numberAt(axes[0], clock, 0),
		numberAt(axes[1], clock, 0),
		numberAt(axes[2], clock, 0),
	];
}

/** Linear interpolation over `[[frame, …values]]` keys, held past the ends. */
function keyed(keys: number[][], frame: number, size: number): number[] {
	const sorted = keys;
	const first = sorted[0]!;
	const last = sorted[sorted.length - 1]!;
	if (frame <= first[0]!) return first.slice(1, 1 + size);
	if (frame >= last[0]!) return last.slice(1, 1 + size);
	let k = 0;
	while (k + 1 < sorted.length && sorted[k + 1]![0]! <= frame) k++;
	const a = sorted[k]!;
	const b = sorted[k + 1]!;
	const u = (frame - a[0]!) / Math.max(1e-9, b[0]! - a[0]!);
	return a.slice(1, 1 + size).map((v, i) => v + (b[i + 1]! - v) * u);
}