《游戏引擎实现原理》9.3 曲线、样条与缓动

// file: src/core/curve.ts
// tier: L1
// verify: npx vitest run src/core/curve.test.ts
//
// helio 内核：贝塞尔、Catmull-Rom 样条与常用缓动函数（标量形式，向量按分量套用）。
// t 一律归一化到 [0, 1]。

function clamp01(t: number): number {
  return t < 0 ? 0 : t > 1 ? 1 : t;
}

/** 二次贝塞尔：只经过首尾两个控制点。 */
export function quadraticBezier(p0: number, p1: number, p2: number, t: number): number {
  const u = 1 - t;
  return u * u * p0 + 2 * u * t * p1 + t * t * p2;
}

/** 三次贝塞尔：不经过中间控制点 p1、p2。 */
export function cubicBezier(
  p0: number, p1: number, p2: number, p3: number, t: number,
): number {
  const u = 1 - t;
  return u * u * u * p0 + 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t * p3;
}

/**
 * Catmull-Rom 样条：t = 0 落在 p1、t = 1 落在 p2，
 * 即曲线精确穿过每一段的首尾控制点（与贝塞尔相反）。
 */
export function catmullRom(
  p0: number, p1: number, p2: number, p3: number, t: number,
): number {
  const t2 = t * t;
  const t3 = t2 * t;
  return 0.5 * (
    2 * p1 +
    (-p0 + p2) * t +
    (2 * p0 - 5 * p1 + 4 * p2 - p3) * t2 +
    (-p0 + 3 * p1 - 3 * p2 + p3) * t3
  );
}

// —— 缓动函数：输入 t ∈ [0, 1]，输出通常也在 [0, 1]，但不要求 ——

export function easeInQuad(t: number): number {
  return t * t;
}

export function easeOutQuad(t: number): number {
  return t * (2 - t);
}

export function easeInOutCubic(t: number): number {
  const x = clamp01(t);
  return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
}

/** Hermite 平滑阶跃：两端一阶导为 0，常用来做淡入淡出与权重过渡。 */
export function smoothstep(t: number): number {
  const x = clamp01(t);
  return x * x * (3 - 2 * x);
}

// file: src/core/curve-samples.ts
// tier: L1
// verify: node src/core/curve-samples.ts
//
// 打印曲线与缓动的采样点表，供正文直接引用。

import {
  catmullRom,
  cubicBezier,
  easeInOutCubic,
  easeInQuad,
  easeOutQuad,
  smoothstep,
} from './curve.ts';

const TS = [0, 0.25, 0.5, 0.75, 1];
const f3 = (x: number) => x.toFixed(3).padStart(6);

console.log('cubicBezier(0,0,1,1,t)  vs  catmullRom(0,0,1,1,t)');
console.log('   t   bezier  catmull');
for (const t of TS) {
  console.log(`${f3(t)}  ${f3(cubicBezier(0, 0, 1, 1, t))}  ${f3(catmullRom(0, 0, 1, 1, t))}`);
}

console.log('\ncatmullRom 过控制点：p=(0,1,2,3)');
console.log(`  t=0 -> ${catmullRom(0, 1, 2, 3, 0)}   t=1 -> ${catmullRom(0, 1, 2, 3, 1)}`);
console.log(`  冲过范围：catmullRom(0,0,0,1,0.5) = ${catmullRom(0, 0, 0, 1, 0.5)}`);

console.log('\n缓动函数采样');
console.log('   t   easeInQuad easeOutQuad easeInOutCubic smoothstep');
for (const t of TS) {
  console.log(
    `${f3(t)}  ${f3(easeInQuad(t))}  ${f3(easeOutQuad(t))}  ${f3(easeInOutCubic(t))}  ${f3(smoothstep(t))}`,
  );
}

// file: src/core/curve.test.ts
// tier: L1
// verify: npx vitest run src/core/curve.test.ts

import { describe, expect, it } from 'vitest';
import {
  catmullRom,
  cubicBezier,
  easeInOutCubic,
  easeInQuad,
  easeOutQuad,
  quadraticBezier,
  smoothstep,
} from './curve.ts';

const close = (a: number, b: number, eps = 1e-9) => Math.abs(a - b) < eps;

describe('贝塞尔曲线', () => {
  it('二次贝塞尔只经过首尾控制点', () => {
    expect(quadraticBezier(0, 1, 2, 0)).toBe(0);
    expect(quadraticBezier(0, 1, 2, 1)).toBe(2);
    expect(close(quadraticBezier(0, 1, 2, 0.5), 1)).toBe(true);
  });

  it('三次贝塞尔端点精确、中间控制点不经过', () => {
    expect(cubicBezier(0, 0, 1, 1, 0)).toBe(0);
    expect(cubicBezier(0, 0, 1, 1, 1)).toBe(1);
    // t = 0.5 只到 0.5，控制点 p1 = 0、p2 = 1 并未落在曲线上
    expect(close(cubicBezier(0, 0, 1, 1, 0.5), 0.5)).toBe(true);
  });
});

describe('Catmull-Rom 样条', () => {
  it('t = 0 落在 p1，t = 1 落在 p2（穿过控制点）', () => {
    expect(catmullRom(0, 1, 2, 3, 0)).toBe(1);
    expect(catmullRom(0, 1, 2, 3, 1)).toBe(2);
  });

  it('会冲过控制点范围（过冲）', () => {
    // 控制点都在 [0, 1]，但 t = 0.5 处冲到 -0.0625
    expect(catmullRom(0, 0, 0, 1, 0.5)).toBeLessThan(0);
    expect(close(catmullRom(0, 0, 0, 1, 0.5), -0.0625)).toBe(true);
  });
});

describe('缓动函数', () => {
  it('端点都是 0 与 1', () => {
    for (const e of [easeInQuad, easeOutQuad, easeInOutCubic, smoothstep]) {
      expect(e(0)).toBe(0);
      expect(e(1)).toBe(1);
    }
  });

  it('t = 0.5 的取值符合定义', () => {
    expect(close(easeInQuad(0.5), 0.25)).toBe(true);
    expect(close(easeOutQuad(0.5), 0.75)).toBe(true);
    expect(close(easeInOutCubic(0.5), 0.5)).toBe(true);
    expect(close(smoothstep(0.5), 0.5)).toBe(true);
  });

  it('全部单调不减', () => {
    for (const e of [easeInQuad, easeOutQuad, easeInOutCubic, smoothstep]) {
      let prev = -Infinity;
      for (let i = 0; i <= 100; i++) {
        const v = e(i / 100);
        expect(v).toBeGreaterThanOrEqual(prev);
        prev = v;
      }
    }
  });
});