mat4.js/README.md

High-performance 4x4 matrix library with multi-precision support for 3D graphics development

# mat4

A high-performance 4x4 matrix library designed for 3D graphics development, offering multiple precision versions to meet diverse scenario needs with a unified, easy-to-use interface.

[![npm version](https://badge.fury.io/js/mat4.svg)](https://badge.fury.io/js/mat4)
[![minified size](https://badgen.net/bundlephobia/min/mat4)](https://bundlephobia.com/package/mat4)
[![license](https://badgen.net/npm/license/mat4)](https://github.com/yourusername/mat4/blob/main/LICENSE)

## Features

- **Multi-Precision Support**: Three implementations to choose from:
  - Float32Array: Performance-optimized (ideal for most 3D scenarios)
  - Float64Array: High-precision (suitable for scientific computing)
  - Regular Array: Maximum compatibility (supports legacy environments)
- **Unified Interface**: Consistent API across all versions for seamless switching
- **Lightweight & Dependency-Free**: Core code is only 3KB minified with zero external dependencies
- **Performance Optimized**: Built-in memory pool reduces GC pressure; speed comparable to mainstream matrix libraries
- **Type Safety**: Full TypeScript type definitions for reliable development

## Installation

```bash
npm install mat4
```

## Quick Start

```typescript
// Import the default Float32 version (performance-optimized)
import { create, rotateX, multiply, translate } from 'mat4';

// Create a new matrix (initialized as identity matrix)
const m = create();

// Apply transformations
rotateX(m, m, Math.PI / 4); // Rotate 45 degrees around X-axis
translate(m, m, [10, 20, 30]); // Translate along [x, y, z]

// Matrix multiplication
const a = create();
const b = create();
const result = create();
multiply(result, a, b); // result = a × b
```

## Version Differentiation

Versions are distinguished by **function suffixes**, with identical interfaces across all variants:

| Version Type       | Key Features          | Function Naming       | Type Definitions      |
|--------------------|-----------------------|-----------------------|-----------------------|
| Float32Array       | Best performance      | No suffix (default)   | `mat4`, `vec3`        |
| Float64Array       | High precision        | Suffix with `64`      | `mat464`, `vec364`    |
| Regular Array      | Maximum compatibility | Suffix with `Array`   | `mat4Array`, `vec3Array` |

### Multi-Version Usage Example

```typescript
import { 
  create,          // Float32 version (default)
  create64,        // Float64 version (high-precision)
  createArray,     // Regular Array version (compatibility)
  mat4,            // Float32 type
  mat464,          // Float64 type
  mat4Array        // Regular Array type
} from 'mat4';

// Float32 version (default)
const m32: mat4 = create();

// Float64 version (high-precision)
const m64: mat464 = create64();

// Regular Array version (compatibility)
const mArr: mat4Array = createArray();
```

## Core API

### Basic Matrix Operations

| Function | Description | Shortcut |
|----------|-------------|----------|
| `create()` | Creates a new matrix (initialized as identity) | - |
| `identity(out: mat4)` | Sets a matrix to the identity matrix | - |
| `copy(out: mat4, a: mat4)` | Copies matrix `a` to `out` | - |
| `multiply(out: mat4, a: mat4, b: mat4)` | Performs matrix multiplication (out = a × b) | `mul` |
| `transpose(out: mat4, a: mat4)` | Transposes matrix `a` to `out` | `trans` |
| `invert(out: mat4, a: mat4)` | Inverts matrix `a` to `out` (returns `null` if singular) | - |

### Geometric Transformations

| Function | Description | Shortcut |
|----------|-------------|----------|
| `translate(out: mat4, a: mat4, v: vec3)` | Applies translation to matrix `a` | - |
| `scale(out: mat4, a: mat4, v: vec3)` | Applies scaling to matrix `a` | - |
| `rotateX(out: mat4, a: mat4, rad: number)` | Rotates matrix `a` around X-axis (in radians) | `rotX` |
| `rotateY(out: mat4, a: mat4, rad: number)` | Rotates matrix `a` around Y-axis (in radians) | `rotY` |
| `rotateZ(out: mat4, a: mat4, rad: number)` | Rotates matrix `a` around Z-axis (in radians) | `rotZ` |

### Projection Matrices

| Function | Description |
|----------|-------------|
| `perspective(out: mat4, fovy: number, aspect: number, near: number, far: number)` | Creates a perspective projection matrix |
| `ortho(out: mat4, left: number, right: number, bottom: number, top: number, near: number, far: number)` | Creates an orthographic projection matrix |
| `lookAt(out: mat4, eye: vec3, center: vec3, up: vec3)` | Creates a view matrix (camera looking at target) |

### Vector Transformations

| Function | Description |
|----------|-------------|
| `transformPoint(out: vec3, m: mat4, v: vec3)` | Transforms a 3D point (includes translation) |
| `transformVector(out: vec3, m: mat4, v: vec3)` | Transforms a 3D vector (excludes translation) |

### Batch Operations & Memory Management

| Function | Description | Shortcut |
|----------|-------------|----------|
| `tempMat4()` | Retrieves a temporary matrix from the memory pool | - |
| `tempMat4Bulk(count: number)` | Retrieves multiple temporary matrices in bulk | - |
| `multiplyBulk(out: mat4[], a: mat4[], b: mat4[], count: number)` | Performs batch matrix multiplication | `mulBulk` |
| `resetPoolArray()` | Resets the memory pool for the Regular Array version | - |

## Constants

Common mathematical constants are provided with version-specific suffixes:

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

// π constants for different versions
console.log(PI);       // π for Float32 version
console.log(PI64);     // π for Float64 version
console.log(PIArray);  // π for Regular Array version
```

Available constants:
- `EPSILON`: Small epsilon value for precision comparisons
- `PI`: π (pi)
- `PI_2`: 2π (two pi)
- `PI_HALF`: π/2 (half pi)

## Performance Comparison

| Operation          | Float32 vs Regular Array | Float32 vs Float64 |
|--------------------|--------------------------|--------------------|
| Matrix Multiplication | 3.37x faster            | 12% faster         |
| Rotation Transformation | 2.75x faster          | 10% faster         |
| Matrix Inversion   | 3.23x faster            | 15% faster         |
| Batch Operations   | 3.43x faster            | 13% faster         |

## Use Cases

- WebGL/Three.js and other 3D rendering framework辅助计算
- Coordinate transformations in 3D game development
- Computer graphics algorithm implementation
- Pose calculation in AR/VR applications
- Scientific computing requiring high precision
- Legacy environments with no TypedArray support

## License

MIT