mat4

高性能4x4矩阵运算库，专为3D图形开发设计，提供多精度版本满足不同场景需求，接口统一且易用。

特性

• 多精度支持：提供三种实现版本，按需选择
  • Float32版本：性能最优，适合大多数3D场景
  • Float64版本：高精度计算，适合科学运算
  • 普通数组版本：兼容性最佳，支持老旧环境
• 统一接口：所有版本API完全一致，切换成本为零
• 轻量高效：核心代码仅3KB，无外部依赖
• 性能优化：内置内存池减少GC压力，运算速度媲美主流矩阵库
• 类型安全：完整TypeScript类型定义，开发更可靠

安装

npm install mat4

快速开始

// 导入默认的Float32版本（性能最优）
import { create, rotateX, multiply, translate } from 'mat4';

// 创建矩阵
const m = create();

// 应用变换
rotateX(m, m, Math.PI / 4); // 绕X轴旋转45度
translate(m, m, [10, 20, 30]); // 平移变换

// 矩阵乘法
const a = create();
const b = create();
const result = create();
multiply(result, a, b);

版本区分

库通过函数后缀区分不同精度版本，接口完全一致：

| 版本类型 | 特点 | 函数命名 | 类型定义 | |---------|------|---------|---------| | Float32Array | 性能最优，内存高效 | 无后缀（默认） | mat4, vec3 | | Float64Array | 高精度计算 | 带64后缀 | mat464, vec364 | | 普通数组 | 兼容性最好 | 带Array后缀 | mat4Array, vec3Array |

多版本使用示例

import { 
  create,          // Float32版本
  create64,        // Float64版本
  createArray,     // 普通数组版本
  mat4,            // Float32类型
  mat464,          // Float64类型
  mat4Array        // 数组类型
} from 'mat4';

// Float32版本（默认）
const m32: mat4 = create();

// Float64版本（高精度）
const m64: mat464 = create64();

// 普通数组版本（兼容性）
const mArr: mat4Array = createArray();

核心API

矩阵基础操作

| 函数 | 描述 | 简写 | |------|------|------| | create() | 创建新矩阵（初始为单位矩阵） | - | | identity(out: mat4) | 设置为单位矩阵 | - | | copy(out: mat4, a: mat4) | 复制矩阵 | - | | multiply(out: mat4, a: mat4, b: mat4) | 矩阵乘法 (out = a × b) | mul | | transpose(out: mat4, a: mat4) | 矩阵转置 | trans | | invert(out: mat4, a: mat4) | 矩阵求逆（失败返回null） | - |

几何变换

| 函数 | 描述 | 简写 | |------|------|------| | translate(out: mat4, a: mat4, v: vec3) | 平移变换 | - | | scale(out: mat4, a: mat4, v: vec3) | 缩放变换 | - | | rotateX(out: mat4, a: mat4, rad: number) | 绕X轴旋转 | rotX | | rotateY(out: mat4, a: mat4, rad: number) | 绕Y轴旋转 | rotY | | rotateZ(out: mat4, a: mat4, rad: number) | 绕Z轴旋转 | rotZ |

投影矩阵

| 函数 | 描述 | |------|------| | perspective(out: mat4, fovy: number, aspect: number, near: number, far: number) | 创建透视投影矩阵 | | ortho(out: mat4, left: number, right: number, bottom: number, top: number, near: number, far: number) | 创建正交投影矩阵 | | lookAt(out: mat4, eye: vec3, center: vec3, up: vec3) | 创建视图矩阵（相机看向目标） |

向量变换

| 函数 | 描述 | |------|------| | transformPoint(out: vec3, m: mat4, v: vec3) | 变换3D点（考虑平移） | | transformVector(out: vec3, m: mat4, v: vec3) | 变换3D向量（不考虑平移） |

批量操作与内存管理

| 函数 | 描述 | 简写 | |------|------|------| | tempMat4() | 获取临时矩阵（从内存池） | - | | tempMat4Bulk(count: number) | 批量获取临时矩阵 | - | | multiplyBulk(out: mat4[], a: mat4[], b: mat4[], count: number) | 批量矩阵乘法 | mulBulk | | resetPoolArray() | 重置数组版本的内存池 | - |

常量

库提供常用数学常量，同样遵循版本后缀规则：

import { PI, PI64, PIArray } from 'mat4';

// PI常量（不同版本）
console.log(PI);       // Float32版本的π
console.log(PI64);     // Float64版本的π
console.log(PIArray);  // 数组版本的π

可用常量包括：EPSILON（极小值）、PI（π）、PI_2（2π）、PI_HALF（π/2）

性能对比

| 操作 | Float32 vs 数组版本 | Float32 vs Float64 | |------|-------------------|-------------------| | 矩阵乘法 | 快3.37倍 | 快12% | | 旋转变换 | 快2.75倍 | 快10% | | 矩阵求逆 | 快3.23倍 | 快15% | | 批量操作 | 快3.43倍 | 快13% |

适用场景

• WebGL/Three.js等3D渲染框架辅助计算
• 3D游戏开发中的坐标变换
• 计算机图形学算法实现
• AR/VR应用中的姿态计算
• 需要高精度计算的科学应用
• 兼容性要求高的老旧环境

许可证

MIT