vec4

vec4 是一个高性能的四维向量库，专为 3D 数学和图形计算设计。复制粘贴于 gl-matrix它提供了完整的四维向量操作函数，适用于游戏开发、3D 图形处理、物理模拟等场景。


功能特性

- 完整的向量操作：支持创建、加减乘除、归一化、插值等常见操作
- TypeScript 支持：完全类型安全，提供清晰的类型定义
- 高性能实现：基于 Float32Array，优化了内存使用和计算性能
- 多环境支持：支持 ESM、CommonJS 和浏览器环境
- 轻量无依赖：无多余依赖，体积小巧

安装

通过 npm 安装：

``bash
npm install vec4
`

使用方式

$3

`javascript
import { create, add, subtract, normalize } from 'vec4';

// 创建向量
const vecA = create();
const vecB = fromValues(1, 2, 3, 4);

// 向量运算
const result = create();
add(result, vecA, vecB);
subtract(result, vecB, vecA);
normalize(result, vecB);
`

$3

`javascript
const { create, add, scale } = require('vec4');

const vecA = create();
const vecB = fromValues(2, 3, 4, 5);

const result = create();
scale(result, vecB, 2.0);
`

$3

`html










`

使用示例

$3

`typescript
import { create, fromValues, add, subtract, multiply, divide } from 'vec4';

// 创建向量
const vecA = fromValues(1, 2, 3, 4);
const vecB = fromValues(2, 3, 4, 5);
const result = create();

// 基本运算
add(result, vecA, vecB); // result = vecA + vecB
subtract(result, vecA, vecB); // result = vecA - vecB
multiply(result, vecA, vecB); // result = vecA * vecB
divide(result, vecA, vecB); // result = vecA / vecB
`

$3

`typescript
import { fromValues, length, squaredLength, distance, dot } from 'vec4';

const vecA = fromValues(1, 2, 3, 4);
const vecB = fromValues(2, 3, 4, 5);

// 计算长度
const len = length(vecA);
const sqrLen = squaredLength(vecA);

// 计算距离
const dist = distance(vecA, vecB);

// 计算点积
const dotProduct = dot(vecA, vecB);
`

$3

`typescript
import { fromValues, normalize, scale, lerp } from 'vec4';

const vec = fromValues(3, 4, 0, 0);

// 归一化
const normalized = create();
normalize(normalized, vec); // normalized = [0.6, 0.8, 0, 0]

// 缩放
const scaled = create();
scale(scaled, vec, 2); // scaled = [6, 8, 0, 0]

// 线性插值
const start = fromValues(0, 0, 0, 0);
const end = fromValues(10, 10, 10, 10);
const interpolated = create();
lerp(interpolated, start, end, 0.5); // interpolated = [5, 5, 5, 5]
`

API 文档

$3

| 函数名 | 描述 |
|--------|------|
| create() | 创建一个新的空四维向量 [0, 0, 0, 0] |
| clone(a) | 从现有向量克隆一个新的向量 |
| fromValues(x, y, z, w) | 从给定值创建一个新的向量 |
| set(out, x, y, z, w) | 设置向量的分量值 |

$3

| 函数名 | 描述 |
|--------|------|
| add(out, a, b) | 向量加法 out = a + b |
| subtract(out, a, b) | 向量减法 out = a - b |
| multiply(out, a, b) | 向量乘法 out = a * b |
| divide(out, a, b) | 向量除法 out = a / b |
| scale(out, a, b) | 向量缩放 out = a * b |
| scaleAndAdd(out, a, b, scale) | 缩放后加法 out = a + b * scale |

$3

| 函数名 | 描述 |
|--------|------|
| ceil(out, a) | 向上取整 |
| floor(out, a) | 向下取整 |
| round(out, a) | 四舍五入 |
| min(out, a, b) | 取两个向量的最小值 |
| max(out, a, b) | 取两个向量的最大值 |

$3

| 函数名 | 描述 |
|--------|------|
| length(a) | 计算向量长度 |
| squaredLength(a) | 计算向量长度的平方 |
| distance(a, b) | 计算两个向量之间的距离 |
| squaredDistance(a, b) | 计算两个向量之间距离的平方 |
| dot(a, b) | 计算两个向量的点积 |

$3

| 函数名 | 描述 |
|--------|------|
| normalize(out, a) | 归一化向量 |
| negate(out, a) | 向量取反 |
| inverse(out, a) | 向量求倒数 |
| cross(out, u, v, w) | 计算四维空间中三个向量的叉积 |
| lerp(out, a, b, t) | 线性插值 |
| random(out, scale?) | 生成随机向量 |

$3

| 函数名 | 描述 |
|--------|------|
| transformMat4(out, a, m) | 使用 4x4 矩阵变换向量 |
| transformQuat(out, a, q) | 使用四元数变换向量 |

$3

| 函数名 | 描述 |
|--------|------|
| zero(out) | 将向量设置为零向量 |
| copy(out, a) | 复制向量 |
| exactEquals(a, b) | 精确比较两个向量是否相等 |
| equals(a, b) | 近似比较两个向量是否相等 |
| str(a) | 返回向量的字符串表示 |

$3

| 别名 | 原函数 |
|------|--------|
| sub | subtract |
| mul | multiply |
| div | divide |
| dist | distance |
| sqrDist | squaredDistance |
| len | length |
| sqrLen | squaredLength |

构建与测试

$3

1. 克隆仓库：
`bash
git clone https://gitee.com/cesiumjs/vec4.git
cd vec4
`

2. 安装依赖：
`bash
npm install
`

3. 构建库：
`bash
npm run build
`

编译后的文件将位于 dist 目录中，包含以下格式：
- index.js - CommonJS 格式
- index.mjs - ES Module 格式
- index.global.js - UMD 格式（适用于浏览器）

$3

`bash
npm test
`

性能特点

1. 基于 Float32Array：使用 Float32Array 以获得更好的性能和内存效率
2. 零内存分配：大部分函数通过修改输出向量来避免创建新对象
3. 内联优化：简单函数可以被 JavaScript 引擎内联优化
4. 缓存友好：连续内存布局有利于 CPU 缓存

浏览器兼容性

- Chrome 7+
- Firefox 4+
- Safari 5.1+
- Internet Explorer 10+
- Edge 所有版本

贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建新的分支用于开发功能或修复问题
3. 提交 Pull Request，并附上清晰的描述

确保代码符合现有的风格规范，并包含适当的单元测试。

许可证

本项目采用 MIT 许可证。
``