跳到主要内容
中文系列课

Mat4

表示一个 4x4 列主序变换矩阵，适用于 3D 变换，并可直接上传到 GPU uniform buffer。

-- Construct an MVP matrix
local proj = Mat4.perspective(math.rad(60), 16 / 9, 0.1, 100)
local view = Mat4.fromTranslation(0, 0, -3) -- camera 3 units back
local model = Mat4.fromRotationY(angle)
local mvp = proj * view * model

-- Upload to a uniform buffer (64 bytes, column-major)
mvp:writeToBuffer(uboBytes, 0)

字段​

m11​

位于行 R、列 C 的元素（从 1 开始索引）。例如 m.m12 是第 1 行第 2 列的元素。

local m = Mat4.identity()
m.m11 = 2 -- scale x
m.m22 = 3 -- scale y
m.m14 = 50 -- translate x

m12​

m13​

m14​

m21​

m22​

m23​

m24​

m31​

m32​

m33​

m34​

m41​

m42​

m43​

m44​

构造函数​

identity​

identity() -> Mat4

返回 4x4 单位矩阵。

values​

values(c0x: number, c0y: number, c0z: number, c0w: number, c1x: number, c1y: number, c1z: number, c1w: number, c2x: number, c2y: number, c2z: number, c2w: number, c3x: number, c3y: number, c3z: number, c3w: number) -> Mat4

使用 16 个分量创建矩阵，分量按列主序提供（先是第 0 列：c0x、c0y、c0z、c0w、c1x，依此类推）。

fromTranslation​

fromTranslation(x: number, y: number, z: number) -> Mat4

创建平移矩阵。

local t = Mat4.fromTranslation(10, 20, 30)

fromScale​

fromScale(x: number, y: number?, z: number?) -> Mat4

创建缩放矩阵。如果省略 y 和 z，则对所有轴应用由 x 指定的统一缩放。

local s1 = Mat4.fromScale(2)        -- uniform 2x
local s2 = Mat4.fromScale(1, 2, 1)  -- 2x in Y only

fromRotationX​

fromRotationX(radians: number) -> Mat4

创建绕 X 轴旋转的矩阵（弧度）。

fromRotationY​

fromRotationY(radians: number) -> Mat4

创建绕 Y 轴旋转的矩阵（弧度）。

fromRotationZ​

fromRotationZ(radians: number) -> Mat4

创建绕 Z 轴旋转的矩阵（弧度）。

perspective​

perspective(fovY: number, aspect: number, near: number, far: number) -> Mat4

创建右手坐标系透视投影矩阵，将 z 映射到 [0, 1] 的 NDC 深度范围。fovY 使用弧度；near 和 far 为正距离。

local proj = Mat4.perspective(math.rad(60), 16 / 9, 0.1, 100)

perspectiveReverseZ​

perspectiveReverseZ(fovY: number, aspect: number, near: number) -> Mat4

右手坐标系透视投影，使用 reverse-Z（near -> 1，far -> 0）和无限远平面。结合浮点深度缓冲区时，可在整个视锥体范围内获得近似均匀的 1/z 深度分布——这是任意场景能达到的最佳精度。深度缓冲区必须清除为 0（而不是 1），并且深度测试需要切换为 GREATER。

local proj = Mat4.perspectiveReverseZ(math.rad(60), 16 / 9, 0.1)

lookAt​

lookAt(eye: Vector, center: Vector, up: Vector) -> Mat4

创建右手坐标系视图矩阵，从 eye 看向 center（GLM 约定）。up 不需要归一化。

local view = Mat4.lookAt(Vector.xyz(0, 2, 5), Vector.origin(), Vector.xyz(0, 1, 0))

ortho​

ortho(left: number, right: number, bottom: number, top: number, near: number, far: number) -> Mat4

创建右手坐标系正交投影矩阵，将 z 映射到 [0, 1] 的 NDC 深度范围（与 Mat4.perspective 匹配），例如用于阴影贴图级联或 2D 叠加层。

local proj = Mat4.ortho(-10, 10, -10, 10, 0.1, 100)

multiply​

multiply(output: Mat4, a: Mat4, b: Mat4) -> Mat4

将 a * b 写入 output，复用其存储空间。返回 output。在紧密循环中使用它可以避免每次乘法都分配新的 Mat4。output 可以与 a 或 b 为同一对象。

local out = Mat4.identity()
for i = 1, 1000 do Mat4.multiply(out, view, model) end

multiplyAffine​

multiplyAffine(output: Mat4, a: Mat4, b: Mat4) -> Mat4

类似于 Mat4.multiply，但假定两个输入都是仿射矩阵（底行 [0, 0, 0, 1]——任何平移/缩放/旋转矩阵的组合都满足条件）。它会跳过底行计算，每次乘法大约减少 25% 的 FLOP。结果始终为仿射矩阵。调用者必须确保两个输入都是仿射矩阵；传入非仿射输入会得到不正确的结果。

local world = Mat4.identity()
for _, bone in ipairs(bones) do
    Mat4.multiplyAffine(world, parent, bone.local)
end

静态函数​

invert​

invert(output: Mat4, input: Mat4) -> boolean

将 input 的逆矩阵写入 output，成功时返回 true；如果 input 为奇异矩阵，则返回 false。

local inv = Mat4.identity()
local ok = Mat4.invert(inv, m)

invertAffine​

invertAffine(output: Mat4, input: Mat4) -> boolean

将 input 的仿射逆矩阵写入 output。契约请参见 Mat4:invertAffine；它比 Mat4.invert 更快。

方法​

invert​

invert() -> Mat4?

线性列主序访问。索引 1..4 是第 0 列，5..8 是第 1 列，9..12 是第 2 列，13..16 是第 3 列（平移）。

local m = Mat4.identity()
m[13] = 50 -- translate x
m[14] = 100 -- translate y
m[15] = 25 -- translate z

返回矩阵的逆矩阵；如果矩阵为奇异矩阵，则返回 nil。

local m = Mat4.fromTranslation(50, 100, 25)
local inv = m:invert()

transpose​

transpose() -> Mat4

返回矩阵的转置。

local m = Mat4.fromRotationY(math.rad(45))
local t = m:transpose()

transformPoint​

transformPoint(x: number, y: number, z: number) -> Vector

使用矩阵变换给定的 3D 点（将 w 视为 1），并将结果作为 Vector 返回。如果结果的齐次 w 不是 1（例如经过透视矩阵之后），返回的点会进行透视除法。

local m = Mat4.fromTranslation(10, 20, 30)
local p = m:transformPoint(1, 2, 3)
print(p.x, p.y, p.z) -- 11, 22, 33

transformVec4​

transformVec4(x: number, y: number, z: number, w: number) -> (number, number, number, number)

使用矩阵变换给定的齐次 4D 向量，并以多个返回值的形式返回四个分量，不进行透视除法。当调用者需要检查或保留齐次 w（例如裁剪空间坐标）时使用它。

local mvp = proj * view * model
local x, y, z, w = mvp:transformVec4(px, py, pz, 1)

writeToBuffer​

writeToBuffer(buf: buffer, byteOffset: number) -> ()

将矩阵以 64 字节（列主序，16 个 float32 条目）写入给定 buffer 的 byteOffset 位置。从该偏移开始，buffer 必须至少有 64 字节可用。

local mvp = Mat4.identity()
local ubo = buffer.create(64)
mvp:writeToBuffer(ubo, 0)

__eq​

__eq(rhs: Mat4) -> boolean

如果两个矩阵的全部 16 个分量都相等，则返回 true。

__mul​

__mul(rhs: Mat4) -> Mat4

返回两个矩阵的矩阵乘积。适用于组合变换，例如 proj * view * model。会分配新的 Mat4；在紧密循环中，建议使用 Mat4.multiply(out, a, b) 来复用存储空间。

invertAffine​

invertAffine() -> Mat4?

仿射矩阵的闭式逆（底行 [0, 0, 0, 1]——任何 fromTranslation/fromScale/fromRotationX/Y/Z 的组合都满足条件）。如果线性部分为奇异矩阵，则返回 nil。它比 :invert() 更快，并且避免完整的 4x4 余子式计算。

local m = Mat4.fromTranslation(3, -4, 5) * Mat4.fromRotationY(0.4)
local inv = m:invertAffine()