[gs-longan](../README.md) / Matrix4

# Class: Matrix4

4x4 单精度矩阵工具类

提供矩阵克隆、单位矩阵、相乘、逆、转置、投影、分解等常用操作。

## Table of contents

### Constructors

- [constructor](Matrix4.md#constructor)

### Properties

- [\_data](Matrix4.md#_data)

### Methods

- [Inverse](Matrix4.md#inverse)
- [InverseMatrix](Matrix4.md#inversematrix)
- [Transpose](Matrix4.md#transpose)
- [TransposeMatrix](Matrix4.md#transposematrix)
- [clone](Matrix4.md#clone)
- [compose](Matrix4.md#compose)
- [decompose](Matrix4.md#decompose)
- [determinant](Matrix4.md#determinant)
- [fromEulerVector](Matrix4.md#fromeulervector)
- [frustum](Matrix4.md#frustum)
- [getRotate](Matrix4.md#getrotate)
- [getScale](Matrix4.md#getscale)
- [getTranslate](Matrix4.md#gettranslate)
- [identity](Matrix4.md#identity)
- [isIdentity](Matrix4.md#isidentity)
- [lookat](Matrix4.md#lookat)
- [multiply](Matrix4.md#multiply)
- [multiplyBBProjection](Matrix4.md#multiplybbprojection)
- [multiplyBoundingBox](Matrix4.md#multiplyboundingbox)
- [multiplyPoint](Matrix4.md#multiplypoint)
- [multiplyPointProjection](Matrix4.md#multiplypointprojection)
- [multiplyPoints](Matrix4.md#multiplypoints)
- [multiplyReverse](Matrix4.md#multiplyreverse)
- [multiplyVector](Matrix4.md#multiplyvector)
- [multiplyWPoint](Matrix4.md#multiplywpoint)
- [ortho](Matrix4.md#ortho)
- [perspective](Matrix4.md#perspective)
- [rotate](Matrix4.md#rotate)
- [rotateByAxis](Matrix4.md#rotatebyaxis)
- [rotationX](Matrix4.md#rotationx)
- [rotationY](Matrix4.md#rotationy)
- [rotationZ](Matrix4.md#rotationz)
- [scale](Matrix4.md#scale)
- [scaleMatrix](Matrix4.md#scalematrix)
- [toEulerAngles](Matrix4.md#toeulerangles)
- [translate](Matrix4.md#translate)
- [translateMatrix](Matrix4.md#translatematrix)

## Constructors

### constructor

• **new Matrix4**(): [`Matrix4`](Matrix4.md)

#### Returns

[`Matrix4`](Matrix4.md)

## Properties

### \_data

• **\_data**: `Float32Array`

内部矩阵数据（长度为16 的 Float32Array）

## Methods

### Inverse

▸ **Inverse**(`m`): `void`

就地计算矩阵的逆，结果写回参数矩阵（若不可逆则返回 undefined）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 要求逆的矩阵（Float32Array，长度为16），函数会修改该矩阵以保存逆矩阵 |

#### Returns

`void`

___

### InverseMatrix

▸ **InverseMatrix**(`m`): `Float32Array`

返回矩阵的逆的副本（不修改原始矩阵）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 源矩阵（Float32Array，长度为16） |

#### Returns

`Float32Array`

逆矩阵的副本（Float32Array，长度为16）

___

### Transpose

▸ **Transpose**(`m`): `void`

就地转置矩阵（修改参数矩阵）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 待转置的矩阵（Float32Array，长度为16） |

#### Returns

`void`

___

### TransposeMatrix

▸ **TransposeMatrix**(`m`): `Float32Array`

返回转置矩阵的副本（不修改原始矩阵）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 源矩阵（Float32Array，长度为16） |

#### Returns

`Float32Array`

转置后的新矩阵（Float32Array，长度为16）

___

### clone

▸ **clone**(`m`, `mat?`): `Float32Array`

克隆矩阵数据到指定目标或返回新的矩阵副本

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 源矩阵（Float32Array，长度为16） |
| `mat?` | `Float32Array` | 可选的目标矩阵（Float32Array），若提供则写入并返回 void，否则返回新的副本 |

#### Returns

`Float32Array`

___

### compose

▸ **compose**(`scale`, `quaternion`, `translation`): `Float32Array`

根据缩放（Vector3）、旋转（四元数）和平移（Vector3）合成新的矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `scale` | `Float32Array` | 定义缩放向量（Float32Array，长度为3） |
| `quaternion` | `Float32Array` | 定义旋转四元数（Float32Array，长度为4） |
| `translation` | `Float32Array` | 定义平移向量（Float32Array，长度为3） |

#### Returns

`Float32Array`

新的 4x4 变换矩阵（Float32Array，长度为16）

___

### decompose

▸ **decompose**(`matrix`, `scale`, `quaternion`, `translation`, `preserveScalingNode?`, `useAbsoluteScaling?`): `boolean`

将当前矩阵分解为平移、旋转和缩放分量

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `matrix` | `Float32Array` | `undefined` | - |
| `scale` | `Float32Array` | `undefined` | 作为引用传入并更新的缩放向量（Vector3） |
| `quaternion` | `Float32Array` | `undefined` | 作为引用传入并更新的旋转四元数（Quaternion） |
| `translation` | `Float32Array` | `undefined` | 作为引用传入并更新的平移向量（Vector3） |
| `preserveScalingNode` | `any` | `null` | 可选。从该节点获取缩放符号以保留缩放方向，否则缩放符号可能会改变 |
| `useAbsoluteScaling` | `boolean` | `true` | 当为 true 时从 preserveScalingNode.absoluteScaling 获取符号，否则从 preserveScalingNode.scaling 获取 |

#### Returns

`boolean`

若分解成功则返回 true

___

### determinant

▸ **determinant**(`matrix`): `number`

获取矩阵的行列式
示例（Playground）
计算 4x4 矩阵的行列式使用拉普拉斯展开（Laplace expansion）：对某一行或列计算余子式并加权求和得到行列式。

#### Parameters

| Name | Type |
| :------ | :------ |
| `matrix` | `Float32Array` |

#### Returns

`number`

矩阵的行列式

___

### fromEulerVector

▸ **fromEulerVector**(`rotation`): `Float32Array`

从欧拉角向量创建四元数

#### Parameters

| Name | Type |
| :------ | :------ |
| `rotation` | `Float32Array` |

#### Returns

`Float32Array`

新的四元数（Float32Array，长度为4）

___

### frustum

▸ **frustum**(`left`, `right`, `bottom`, `top`, `fnear`, `ffar`): `Float32Array`

根据视锥体参数创建透视投影矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `left` | `number` | 左边界 |
| `right` | `number` | 右边界 |
| `bottom` | `number` | 底部 |
| `top` | `number` | 顶部 |
| `fnear` | `number` | 近裁剪面 |
| `ffar` | `number` | 远裁剪面 |

#### Returns

`Float32Array`

透视投影矩阵（Float32Array，长度为16）

___

### getRotate

▸ **getRotate**(`m`): `Float32Array`

从矩阵中提取旋转部分（移除平移与缩放），返回只包含旋转的矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 源矩阵（Float32Array，长度为16） |

#### Returns

`Float32Array`

只包含旋转分量的矩阵（Float32Array，长度为16）

___

### getScale

▸ **getScale**(`m`): `Float32Array`

从矩阵中提取缩放分量并返回对应的缩放矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 源矩阵（Float32Array，长度为16） |

#### Returns

`Float32Array`

包含缩放分量的矩阵（Float32Array，长度为16）

___

### getTranslate

▸ **getTranslate**(`m`): `Float32Array`

提取矩阵中的平移部分并返回平移矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 源矩阵（Float32Array，长度为16） |

#### Returns

`Float32Array`

只包含平移分量的矩阵（Float32Array，长度为16）

___

### identity

▸ **identity**(): `Float32Array`

返回 4x4 单位矩阵

#### Returns

`Float32Array`

单位矩阵（Float32Array，长度为16）

___

### isIdentity

▸ **isIdentity**(`m`): `boolean`

判断矩阵是否为近似单位矩阵（使用容差比较）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 矩阵（Float32Array，长度为16） |

#### Returns

`boolean`

若每个分量与单位矩阵相应分量在容差内，则返回 true

___

### lookat

▸ **lookat**(`eyeX`, `eyeY`, `eyeZ`, `centerX`, `centerY`, `centerZ`, `upX`, `upY`, `upZ`, `mat?`): `Float32Array`

创建观察矩阵（LookAt），将相机从 eye 看向 center，使用 up 指定上方向

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `eyeX` | `number` | 相机位置 X |
| `eyeY` | `number` | 相机位置 Y |
| `eyeZ` | `number` | 相机位置 Z |
| `centerX` | `number` | 目标点 X |
| `centerY` | `number` | 目标点 Y |
| `centerZ` | `number` | 目标点 Z |
| `upX` | `number` | up 向量 X 分量 |
| `upY` | `number` | up 向量 Y 分量 |
| `upZ` | `number` | up 向量 Z 分量 |
| `mat?` | `Float32Array` | 可选目标矩阵 |

#### Returns

`Float32Array`

观察矩阵（Float32Array，长度为16）

___

### multiply

▸ **multiply**(`m1`, `m2`, `mat?`): `Float32Array`

矩阵相乘

#### Parameters

| Name | Type |
| :------ | :------ |
| `m1` | `Float32Array` |
| `m2` | `Float32Array` |
| `mat?` | `Float32Array` |

#### Returns

`Float32Array`

___

### multiplyBBProjection

▸ **multiplyBBProjection**(`m`, `bb`): `Float32Array`

对包围盒进行投影变换并返回在投影空间中的包围盒

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 投影矩阵（Float32Array，长度为16） |
| `bb` | `Float32Array` | 包围盒 [minX,minY,minZ,maxX,maxY,maxZ]（Float32Array，长度为6） |

#### Returns

`Float32Array`

投影后的包围盒（Float32Array，长度为6）

___

### multiplyBoundingBox

▸ **multiplyBoundingBox**(`m`, `bb`): `Float32Array`

使用矩阵变换轴对齐包围盒（通过计算 8 个顶点并求 min/max）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 变换矩阵（Float32Array，长度为16） |
| `bb` | `Float32Array` | 包围盒 [minX,minY,minZ,maxX,maxY,maxZ]（Float32Array，长度为6） |

#### Returns

`Float32Array`

变换后的包围盒（Float32Array，长度为6）

___

### multiplyPoint

▸ **multiplyPoint**(`m`, `p`): `Float32Array`

点矩阵变换

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 矩阵 |
| `p` | `Float32Array` | 点 |

#### Returns

`Float32Array`

变换后的点

___

### multiplyPointProjection

▸ **multiplyPointProjection**(`m`, `point`): `Float32Array`

将点应用于投影矩阵并进行齐次除法，返回投影后的点（包含归一化）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 投影矩阵（Float32Array，长度为16） |
| `point` | `Float32Array` | 三维点（Float32Array，长度为3） |

#### Returns

`Float32Array`

投影并归一化后的四维点（Float32Array，长度为4）

___

### multiplyPoints

▸ **multiplyPoints**(`m`, `ps`): `Float32Array`

点数组矩阵变换

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 矩阵 |
| `ps` | `Float32Array` | - |

#### Returns

`Float32Array`

变换后的点数组

___

### multiplyReverse

▸ **multiplyReverse**(`m1`, `m2`, `mat?`): `Float32Array`

按列主序矩阵乘法（与 multiply 不同的索引顺序），支持写入目标矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m1` | `Float32Array` | 左矩阵（Float32Array，长度为16） |
| `m2` | `Float32Array` | 右矩阵（Float32Array，长度为16） |
| `mat?` | `Float32Array` | 可选的目标矩阵（Float32Array），若提供则填充并返回该矩阵 |

#### Returns

`Float32Array`

___

### multiplyVector

▸ **multiplyVector**(`m`, `v`): `Float32Array`

矩阵乘向量（用于变换方向向量，不包含平移分量）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 矩阵（Float32Array，长度为16） |
| `v` | `Float32Array` | 向量（Float32Array，长度为3） |

#### Returns

`Float32Array`

变换后的向量（Float32Array，长度为3）

___

### multiplyWPoint

▸ **multiplyWPoint**(`m`, `p`): `Float32Array`

点矩阵变换, 包含w维

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 矩阵 |
| `p` | `Float32Array` | 点 |

#### Returns

`Float32Array`

变换后的点

___

### ortho

▸ **ortho**(`left`, `right`, `bottom`, `top`, `near`, `far`, `mat?`): `Float32Array`

创建或写入正交投影矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `left` | `number` | 视体左边界 |
| `right` | `number` | 视体右边界 |
| `bottom` | `number` | 视体下边界 |
| `top` | `number` | 视体上边界 |
| `near` | `number` | 近裁剪面 |
| `far` | `number` | 远裁剪面 |
| `mat?` | `Float32Array` | 可选目标矩阵 |

#### Returns

`Float32Array`

正交投影矩阵（Float32Array，长度为16）

___

### perspective

▸ **perspective**(`fov`, `aspect`, `near`, `far`, `mat?`): `any`

创建透视投影矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `fov` | `number` | 垂直视野（弧度） |
| `aspect` | `number` | 纵横比（width/height） |
| `near` | `number` | 近裁剪面 |
| `far` | `number` | 远裁剪面 |
| `mat?` | `Float32Array` | 可选目标矩阵 |

#### Returns

`any`

透视投影矩阵（Float32Array，长度为16）

___

### rotate

▸ **rotate**(`axis`, `alpha`): `Float32Array`

绕任意轴旋转，返回 4x4 旋转矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `axis` | `Float32Array` | 旋转轴向量（Float32Array，长度为3，应为单位向量） |
| `alpha` | `number` | 旋转角度（弧度） |

#### Returns

`Float32Array`

旋转矩阵（Float32Array，长度为16）

___

### rotateByAxis

▸ **rotateByAxis**(`origin`, `axis`, `alpha`): `Float32Array`

指定点轴旋转

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `origin` | `Float32Array` | 点 |
| `axis` | `Float32Array` | 旋转轴 |
| `alpha` | `number` | 弧度 |

#### Returns

`Float32Array`

变换矩阵

___

### rotationX

▸ **rotationX**(`alpha`): `Float32Array`

绕 X 轴旋转并返回旋转矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `alpha` | `number` | 旋转角度（弧度） |

#### Returns

`Float32Array`

___

### rotationY

▸ **rotationY**(`alpha`): `Float32Array`

绕 Y 轴旋转并返回旋转矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `alpha` | `number` | 旋转角度（弧度） |

#### Returns

`Float32Array`

___

### rotationZ

▸ **rotationZ**(`alpha`): `Float32Array`

绕 Z 轴旋转并返回旋转矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `alpha` | `number` | 旋转角度（弧度） |

#### Returns

`Float32Array`

___

### scale

▸ **scale**(`m`, `x`, `y`, `z`): `void`

就地缩放矩阵（修改矩阵的缩放部分）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 要修改的矩阵（Float32Array，长度为16） |
| `x` | `number` | X 方向缩放因子 |
| `y` | `number` | Y 方向缩放因子 |
| `z` | `number` | Z 方向缩放因子 |

#### Returns

`void`

___

### scaleMatrix

▸ **scaleMatrix**(`x`, `y`, `z`): `Float32Array`

创建缩放矩阵

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `x` | `number` | X 方向缩放因子 |
| `y` | `number` | Y 方向缩放因子 |
| `z` | `number` | Z 方向缩放因子 |

#### Returns

`Float32Array`

缩放矩阵（Float32Array，长度为16）

___

### toEulerAngles

▸ **toEulerAngles**(`quaternion`): `Float32Array`

将四元数转换为欧拉角（以弧度表示）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `quaternion` | `Float32Array` | 要转换的四元数（Float32Array，长度为4） |

#### Returns

`Float32Array`

以弧度表示的欧拉角（Float32Array，长度为3）

___

### translate

▸ **translate**(`m`, `x`, `y`, `z`): `void`

将给定矩阵按指定平移量进行就地平移（修改矩阵）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `m` | `Float32Array` | 要应用平移的矩阵（Float32Array，长度为16） |
| `x` | `number` | X 方向平移量 |
| `y` | `number` | Y 方向平移量 |
| `z` | `number` | Z 方向平移量 |

#### Returns

`void`

___

### translateMatrix

▸ **translateMatrix**(`x`, `y`, `z`): `Float32Array`

创建一个平移矩阵（基于给定的 x,y,z 偏移）

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `x` | `number` | X 方向平移量 |
| `y` | `number` | Y 方向平移量 |
| `z` | `number` | Z 方向平移量 |

#### Returns

`Float32Array`

平移矩阵（Float32Array，长度为16）