s3m-three 0.3.6 → 0.3.8

package/src/anim/easing.ts

@@ -0,0 +1,195 @@
+/**
+ * 缓动曲线库
+ *
+ * 纯函数，不依赖 three / DOM，可以单独在 Worker 或 Node 里跑。
+ *
+ * 三类：
+ *   1. 命名曲线 —— CSS 那套 easeIn/Out/InOut × Quad…Bounce，覆盖 90% 场景
+ *   2. cubicBezier(x1,y1,x2,y2) —— 与 CSS `cubic-bezier()` 数值对齐，用来做产品级调校
+ *   3. steps(n, position) —— 离散跳变，做逐帧动画或「咔哒」感
+ *
+ * spring 不在这里：它没有「时长」概念，靠物理收敛，所以实现为 Animator 里的一种
+ * Track 类型，而不是 (t) => number 的曲线。
+ */
+
+export type EasingFn = (t: number) => number;
+
+/* ------------------------------------------------------------------ 基础 */
+
+const c1 = 1.70158;
+const c2 = c1 * 1.525;
+const c3 = c1 + 1;
+const c4 = (2 * Math.PI) / 3;
+const c5 = (2 * Math.PI) / 4.5;
+const n1 = 7.5625;
+const d1 = 2.75;
+
+function outBounce(t: number): number {
+  if (t < 1 / d1) return n1 * t * t;
+  if (t < 2 / d1) {
+    const x = t - 1.5 / d1;
+    return n1 * x * x + 0.75;
+  }
+  if (t < 2.5 / d1) {
+    const x = t - 2.25 / d1;
+    return n1 * x * x + 0.9375;
+  }
+  const x = t - 2.625 / d1;
+  return n1 * x * x + 0.984375;
+}
+
+function inBounce(t: number): number {
+  return 1 - outBounce(1 - t);
+}
+
+/* ------------------------------------------------------------------ 曲线表 */
+
+const CURVES = {
+  linear: (t) => t,
+
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => 1 - (1 - t) * (1 - t),
+  easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2),
+
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2),
+
+  easeInQuart: (t) => t * t * t * t,
+  easeOutQuart: (t) => 1 - Math.pow(1 - t, 4),
+  easeInOutQuart: (t) => (t < 0.5 ? 8 * t * t * t * t : 1 - Math.pow(-2 * t + 2, 4) / 2),
+
+  easeInQuint: (t) => t * t * t * t * t,
+  easeOutQuint: (t) => 1 - Math.pow(1 - t, 5),
+  easeInOutQuint: (t) => (t < 0.5 ? 16 * t * t * t * t * t : 1 - Math.pow(-2 * t + 2, 5) / 2),
+
+  easeInSine: (t) => 1 - Math.cos((t * Math.PI) / 2),
+  easeOutSine: (t) => Math.sin((t * Math.PI) / 2),
+  easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+
+  easeInExpo: (t) => (t === 0 ? 0 : Math.pow(2, 10 * t - 10)),
+  easeOutExpo: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+  easeInOutExpo: (t) =>
+    t === 0 ? 0 : t === 1 ? 1 : t < 0.5 ? Math.pow(2, 20 * t - 10) / 2 : (2 - Math.pow(2, -20 * t + 10)) / 2,
+
+  easeInCirc: (t) => 1 - Math.sqrt(1 - t * t),
+  easeOutCirc: (t) => Math.sqrt(1 - Math.pow(t - 1, 2)),
+  easeInOutCirc: (t) =>
+    t < 0.5
+      ? (1 - Math.sqrt(1 - Math.pow(2 * t, 2))) / 2
+      : (Math.sqrt(1 - Math.pow(-2 * t + 2, 2)) + 1) / 2,
+
+  easeInBack: (t) => c3 * t * t * t - c1 * t * t,
+  easeOutBack: (t) => 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2),
+  easeInOutBack: (t) =>
+    t < 0.5
+      ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+      : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2,
+
+  easeInElastic: (t) =>
+    t === 0 ? 0 : t === 1 ? 1 : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4),
+  easeOutElastic: (t) =>
+    t === 0 ? 0 : t === 1 ? 1 : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1,
+  easeInOutElastic: (t) =>
+    t === 0
+      ? 0
+      : t === 1
+        ? 1
+        : t < 0.5
+          ? -(Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * c5)) / 2
+          : (Math.pow(2, -20 * t + 10) * Math.sin((20 * t - 11.125) * c5)) / 2 + 1,
+
+  easeInBounce: inBounce,
+  easeOutBounce: outBounce,
+  easeInOutBounce: (t) => (t < 0.5 ? (1 - inBounce(1 - 2 * t)) / 2 : (1 + inBounce(2 * t - 1)) / 2),
+} satisfies Record<string, EasingFn>;
+
+/** 全部内置曲线名（顺序稳定，方便做下拉框 / 遍历自检） */
+export const EASING_NAMES = Object.keys(CURVES) as EasingName[];
+
+export type EasingName = keyof typeof CURVES;
+
+/** 按名字取曲线；名字不存在直接抛错，不做静默降级（拼错会变成「没动画」，很难查） */
+export function easing(name: EasingName | EasingFn): EasingFn {
+  if (typeof name === 'function') return name;
+  const fn = (CURVES as Record<string, EasingFn>)[name];
+  if (!fn) throw new Error(`[s3m] 未知的缓动曲线: ${String(name)}`);
+  return fn;
+}
+
+/* ------------------------------------------------------------------ 贝塞尔 */
+
+const NEWTON_ITERATIONS = 8;
+const NEWTON_MIN_SLOPE = 0.001;
+const SUBDIVISION_PRECISION = 1e-7;
+const SUBDIVISION_MAX_ITERATIONS = 12;
+
+const bezA = (a1: number, a2: number): number => 1 - 3 * a2 + 3 * a1;
+const bezB = (a1: number, a2: number): number => 3 * a2 - 6 * a1;
+const bezC = (a1: number): number => 3 * a1;
+
+/** 三次贝塞尔在参数 t 处的值（x 或 y 用同一组公式，只是控制点不同） */
+function bezierAt(t: number, a1: number, a2: number): number {
+  return ((bezA(a1, a2) * t + bezB(a1, a2)) * t + bezC(a1)) * t;
+}
+
+function bezierSlope(t: number, a1: number, a2: number): number {
+  return 3 * bezA(a1, a2) * t * t + 2 * bezB(a1, a2) * t + bezC(a1);
+}
+
+/**
+ * CSS `cubic-bezier(x1, y1, x2, y2)` 的等价实现。
+ *
+ * 与浏览器一致：先解 `x(t) = 输入进度` 得到参数 t，再取 `y(t)`。
+ * 用牛顿迭代，斜率过小时退化为二分——退化控制点（比如 (0,0,1,1)）也稳定。
+ */
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number): EasingFn {
+  // 线性特例：控制点落在对角线上时不必迭代
+  if (x1 === y1 && x2 === y2) return (t) => t;
+
+  const solveT = (x: number): number => {
+    let t = x;
+    for (let i = 0; i < NEWTON_ITERATIONS; i++) {
+      const slope = bezierSlope(t, x1, x2);
+      if (Math.abs(slope) < NEWTON_MIN_SLOPE) break;
+      const err = bezierAt(t, x1, x2) - x;
+      if (Math.abs(err) < SUBDIVISION_PRECISION) return t;
+      t -= err / slope;
+    }
+    // 牛顿不收敛：二分兜底
+    let lo = 0;
+    let hi = 1;
+    t = x;
+    for (let i = 0; i < SUBDIVISION_MAX_ITERATIONS; i++) {
+      const v = bezierAt(t, x1, x2);
+      if (Math.abs(v - x) < SUBDIVISION_PRECISION) return t;
+      if (v < x) lo = t;
+      else hi = t;
+      t = (lo + hi) / 2;
+    }
+    return t;
+  };
+
+  return (t: number): number => {
+    if (t <= 0) return 0;
+    if (t >= 1) return 1;
+    return bezierAt(solveT(t), y1, y2);
+  };
+}
+
+/* ------------------------------------------------------------------ 离散 */
+
+/**
+ * 阶梯曲线。
+ *
+ * @param count    档数
+ * @param position 'end' 表示「走完一档才跳」，'start' 表示「一进档就跳」
+ */
+export function steps(count: number, position: 'start' | 'end' = 'end'): EasingFn {
+  const n = Math.max(1, Math.floor(count));
+  return (t: number): number => {
+    const clamped = Math.min(1, Math.max(0, t));
+    if (position === 'start') return Math.min(1, (Math.floor(clamped * n) + 1) / n);
+    return Math.min(1, Math.floor(clamped * n) / n);
+  };
+}

package/src/anim/index.ts

@@ -0,0 +1,10 @@
+export { Animator } from './Animator.js';
+export type { Channel, SpringSpec, TransitionOptions } from './Animator.js';
+export { Path } from './Path.js';
+export {
+  easing,
+  cubicBezier,
+  steps,
+  EASING_NAMES,
+} from './easing.js';
+export type { EasingFn, EasingName } from './easing.js';

package/src/core/TextureDecode.ts

@@ -26,10 +26,25 @@ export interface DecodedTextureData {
   /** WEBP 路径的解码结果（ImageBitmap 可 transfer，主线程直接 new THREE.Texture 包） */
   bitmap: ImageBitmap | null;
   hasAlpha: boolean;
+  /**
+   * 压缩直传模式（decodeTextureData 的 compressed 选项）：不解码，原样返回 DXT 块，
+   * 主线程用 CompressedTexture 硬件解压上传。与 rgba 互斥。
+   */
+  blocks?: Uint8Array;
+  blockFormat?: 'dxt1' | 'dxt5';
   /** CRN 转码失败时的原始错误（渲染层负责打 warn） */
   error?: string;
 }
 
+export interface DecodeOptions {
+  /**
+   * 压缩直传：dxt1/dxt5（含 CRN 转码产物）不解码，原样返回 DXT 块。
+   * 仅在宿主支持 WEBGL_compressed_texture_s3tc(+srgb) 时开启；
+   * flipY 纹理走不了压缩上传（WebGL 对压缩纹理忽略 UNPACK_FLIP_Y），自动回退解码。
+   */
+  compressed?: boolean;
+}
+
 /** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
 function flipRows(rgba: Uint8Array, width: number, height: number): void {
   const row = width * 4;
@@ -92,8 +107,23 @@ function rawRGBA(tex: S3MTexture): { rgba: Uint8Array; hasAlpha: boolean } {
   return { rgba: out, hasAlpha: hasAlphaChannel(pixelFormat) };
 }
 
+/**
+ * DXT 块数据的期望字节数：4×4 对齐块 × 每块字节（DXT1=8，DXT5=16）。
+ * S3M 纹理宽高不总是 4 的倍数，驱动按声明尺寸算期望大小——对不上就是
+ * GL_INVALID_VALUE: glCompressedTexSubImage2D: The <imageSize> does not match。
+ * 压缩直传前必须用这个函数把关，不匹配就回退 RGBA 解码。
+ */
+export function expectedDxtByteLength(width: number, height: number, format: 'dxt1' | 'dxt5'): number {
+  const bw = (width + 3) >> 2;
+  const bh = (height + 3) >> 2;
+  return bw * bh * (format === 'dxt1' ? 8 : 16);
+}
+
 /** 主线程 / Worker 共用的解码入口。不抛错：失败与不支持都体现在返回值里 */
-export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTextureData> {
+export async function decodeTextureData(
+  tex: S3MTexture,
+  options: DecodeOptions = {}
+): Promise<DecodedTextureData> {
   const empty: DecodedTextureData = {
     kind: 'unsupported(0/0)',
     width: 0,
@@ -106,13 +136,35 @@ export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTexture
 
   const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
 
+  // 压缩直传的公共前提：不是 GL 翻行图集（压缩上传无法 flipY）
+  const canCompress = options.compressed === true && !tex.flipY;
+
+  /** 块数据字节数与 4×4 对齐公式一致才允许直传，否则回退解码 */
+  const compressible = (data: Uint8Array, w: number, h: number, format: 'dxt1' | 'dxt5'): boolean =>
+    data.byteLength === expectedDxtByteLength(w, h, format);
+
   if (kind === 'crn') {
     try {
       const crn = await transcodeCRN(tex.data);
+      const pf = crn.dxtFormat === 1 ? PixelFormat.DXT1 : PixelFormat.DXT5;
+      const fmt = crn.dxtFormat === 1 ? 'dxt1' : 'dxt5';
+      if (canCompress && compressible(crn.data, crn.width, crn.height, fmt)) {
+        // CRN→DXT 的转码免不了（wasm），但后续的 DXT→RGBA 解块省掉，块数据直传 GPU
+        return {
+          kind: `crn->dxt${crn.dxtFormat}(c)`,
+          width: crn.width,
+          height: crn.height,
+          rgba: null,
+          bitmap: null,
+          hasAlpha: pf === PixelFormat.DXT5,
+          blocks: crn.data,
+          blockFormat: fmt,
+        };
+      }
       const decoded = decodeDXT({
         width: crn.width,
         height: crn.height,
-        pixelFormat: crn.dxtFormat === 1 ? PixelFormat.DXT1 : PixelFormat.DXT5,
+        pixelFormat: pf,
         data: crn.data,
       });
       return {
@@ -138,7 +190,21 @@ export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTexture
   }
 
   if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
-    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
+    const pf = dxtPixelFormatOf(kind);
+    // dxt3/dxt4 少见，不进直传白名单；块长与 4×4 对齐公式不符的也回退解码
+    if (canCompress && (kind === 'dxt1' || kind === 'dxt5') && compressible(tex.data, tex.width, tex.height, kind)) {
+      return {
+        kind: `${kind}(c)`,
+        width: tex.width,
+        height: tex.height,
+        rgba: null,
+        bitmap: null,
+        hasAlpha: kind === 'dxt5',
+        blocks: tex.data,
+        blockFormat: kind,
+      };
+    }
+    const decoded = decodeDXT({ ...tex, pixelFormat: pf });
     return { kind, width: tex.width, height: tex.height, rgba: decoded.rgba, bitmap: null, hasAlpha: decoded.hasAlpha };
   }