mat4

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


特性

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

安装

``bash
npm install mat4
`

快速开始

`typescript
// 导入默认的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 |

$3

`typescript
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

$3

| 函数 | 描述 | 简写 |
|------|------|------|
| 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） | - |

$3

| 函数 | 描述 | 简写 |
|------|------|------|
| 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 |

$3

| 函数 | 描述 |
|------|------|
| 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) | 创建视图矩阵（相机看向目标） |

$3

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

$3

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

常量

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

`typescript
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