Math library for Max Engine
npm install @maxellabs/mathMaxellabs 3D Engine 的高性能数学库,提供3D图形和游戏开发所需的核心数学运算和数据结构。
``bash`
npm install @maxellabs/math或
yarn add @maxellabs/math或
pnpm add @maxellabs/math
`typescript
import { Vector3, Matrix4, Quaternion } from '@maxellabs/math';
// 创建向量(使用对象池)
const v1 = Vector3.create(1, 2, 3);
const v2 = Vector3.create(4, 5, 6);
// 向量运算
const result = v1.add(v2).normalize();
// 释放到对象池
Vector3.release(v1);
Vector3.release(v2);
Vector3.release(result);
`
`typescript
import { Matrix4, Vector3, Quaternion } from '@maxellabs/math';
// 创建变换矩阵
const transform = Matrix4.create();
const position = Vector3.create(10, 0, 0);
const rotation = Quaternion.create().setFromEuler(0, Math.PI / 2, 0);
const scale = Vector3.create(2, 2, 2);
// 组合变换
transform.compose(position, rotation, scale);
// 应用变换
const point = Vector3.create(1, 1, 1);
transform.transformPoint(point);
`
`typescript
import { Vector3Batch, Matrix4 } from '@maxellabs/math';
// 批量向量运算
const positions = new Float32Array([
1, 2, 3,
4, 5, 6,
7, 8, 9
]);
const transform = Matrix4.create().makeRotationY(Math.PI / 4);
// 批量变换(SIMD优化)
Vector3Batch.transformArray(positions, transform);
`
`typescript
import { Ray, Box3, Sphere } from '@maxellabs/math';
// 射线与包围盒相交
const ray = new Ray(Vector3.ZERO, Vector3.X);
const box = new Box3(Vector3.create(-1, -1, -1), Vector3.create(1, 1, 1));
const intersection = ray.intersectBox(box);
if (intersection) {
console.log('相交点:', intersection);
}
// 球体碰撞检测
const sphere1 = new Sphere(Vector3.ZERO, 1);
const sphere2 = new Sphere(Vector3.create(1.5, 0, 0), 1);
if (sphere1.intersectsSphere(sphere2)) {
console.log('球体相交');
}
`
#### Vector3
`typescript`
class Vector3 {
// 构造函数
constructor(x?: number, y?: number, z?: number);
// 静态方法(对象池)
static create(x?: number, y?: number, z?: number): Vector3;
static release(vector: Vector3): void;
// 基础运算
add(v: Vector3 | number): this;
subtract(v: Vector3 | number): this;
multiply(v: Vector3 | number): this;
divide(v: Vector3 | number): this;
// 向量运算
dot(v: Vector3): number;
cross(v: Vector3): this;
normalize(): this;
length(): number;
// 变换
applyMatrix4(m: Matrix4): this;
applyQuaternion(q: Quaternion): this;
}
#### Matrix4
`typescript`
class Matrix4 {
// 构造函数
constructor();
// 静态方法(对象池)
static create(): Matrix4;
static release(matrix: Matrix4): void;
// 矩阵运算
multiply(m: Matrix4): this;
invert(): this;
transpose(): this;
// 变换构建
makeTranslation(v: Vector3): this;
makeRotationFromQuaternion(q: Quaternion): this;
makeScale(v: Vector3): this;
compose(position: Vector3, rotation: Quaternion, scale: Vector3): this;
// 投影矩阵
makePerspective(fov: number, aspect: number, near: number, far: number): this;
makeOrthographic(left: number, right: number, bottom: number, top: number, near: number, far: number): this;
}
#### Quaternion
`typescript`
class Quaternion {
// 构造函数
constructor(x?: number, y?: number, z?: number, w?: number);
// 静态方法(对象池)
static create(x?: number, y?: number, z?: number, w?: number): Quaternion;
static release(quaternion: Quaternion): void;
// 旋转构建
setFromEuler(x: number, y: number, z: number, order?: string): this;
setFromAxisAngle(axis: Vector3, angle: number): this;
setFromRotationMatrix(m: Matrix4): this;
// 四元数运算
multiply(q: Quaternion): this;
slerp(q: Quaternion, t: number): this;
conjugate(): this;
normalize(): this;
}
#### Vector3Batch
`typescript`
class Vector3Batch {
// 批量变换(SIMD优化)
static transformArray(vectors: Float32Array, matrix: Matrix4): void;
static normalizeArray(vectors: Float32Array): void;
static addArrays(a: Float32Array, b: Float32Array, result: Float32Array): void;
// 批量计算
static computeBounds(vectors: Float32Array): Box3;
static computeCenter(vectors: Float32Array): Vector3;
}
#### Ray
`typescript`
class Ray {
constructor(origin: Vector3, direction: Vector3);
// 相交检测
intersectBox(box: Box3): Vector3 | null;
intersectSphere(sphere: Sphere): Vector3 | null;
intersectPlane(plane: Plane): Vector3 | null;
// 距离计算
distanceToPoint(point: Vector3): number;
closestPointToPoint(point: Vector3): Vector3;
}
#### Box3
`typescript`
class Box3 {
constructor(min?: Vector3, max?: Vector3);
// 包围盒运算
expandByPoint(point: Vector3): this;
expandByBox(box: Box3): this;
intersectsBox(box: Box3): boolean;
containsPoint(point: Vector3): boolean;
// 属性计算
getCenter(): Vector3;
getSize(): Vector3;
getVolume(): number;
}
`typescript
// 推荐:使用对象池
const v1 = Vector3.create(1, 2, 3);
const v2 = Vector3.create(4, 5, 6);
const result = v1.add(v2);
// 使用完毕后释放
Vector3.release(v1);
Vector3.release(v2);
Vector3.release(result);
// 不推荐:频繁创建新对象
const v1 = new Vector3(1, 2, 3); // 会产生GC压力
`
`typescript`
// 自动检测SIMD支持
if (Vector3.hasSIMDSupport()) {
// 使用SIMD优化的批量运算
Vector3Batch.transformArray(positions, transform);
} else {
// 回退到标准实现
for (let i = 0; i < positions.length; i += 3) {
const v = Vector3.create(positions[i], positions[i + 1], positions[i + 2]);
v.applyMatrix4(transform);
positions[i] = v.x;
positions[i + 1] = v.y;
positions[i + 2] = v.z;
Vector3.release(v);
}
}
`typescript
// 使用TypedArray提高性能
const positions = new Float32Array(vertexCount * 3);
const normals = new Float32Array(vertexCount * 3);
// 批量处理,减少函数调用开销
Vector3Batch.normalizeArray(normals);
`
`typescript
import { MathConfig } from '@maxellabs/math';
// 配置对象池大小
MathConfig.setPoolSize({
Vector3: 2000,
Matrix4: 100,
Quaternion: 500
});
// 启用SIMD优化
MathConfig.enableSIMD(true);
// 设置精度
MathConfig.setEpsilon(1e-6);
`
`bash运行单元测试
npm test
| 操作 | 标准实现 | 优化实现 | 提升 |
|------|----------|----------|------|
| Vector3.add | 100ns | 45ns | 2.2x |
| Matrix4.multiply | 500ns | 180ns | 2.8x |
| 批量变换(1000个点) | 50ms | 12ms | 4.2x |
| Quaternion.slerp | 200ns | 85ns | 2.4x |
欢迎提交 Issue 和 Pull Request!
MIT
---
详细的开发计划请参考 DEVELOPMENT_PLAN.md