Avoid running untrusted scripts! They can compromise your system and data
For more info, read here

Matrix

4×4 transformation matrices for translation, rotation, scaling, and projection.

mat4 - 4×4 Matrix API

Constructor

Signature: mat4()

Description: Creates a new 4×4 identity matrix.

Parameters: None

Returns:

  • mat4: A new 4×4 identity matrix.

Example:

-- Create a new identity matrix
local matrix = mat4()
engine.log("Created a new 4×4 identity matrix", 255, 255, 255, 255)

Operators

The following operators are supported for mat4:

  • Multiplication: mat4 * mat4 - Multiplies two matrices (matrix composition).

  • Transformation: mat4 * vec4 - Transforms a vec4 using the matrix.

Example:

-- Create an identity matrix
local m1 = mat4()

-- Create a translation matrix
local translation = mat4()
translation:translate(vec3(10, 20, 30))

-- Multiply matrices
local result = m1 * translation

-- Transform a point
local point = vec4(1, 2, 3, 1)
local transformed = result * point
engine.log("Original point: (" .. point.x .. ", " .. point.y .. ", " .. point.z .. ")", 255, 255, 255, 255)
engine.log("Transformed point: (" .. transformed.x .. ", " .. transformed.y .. ", " .. transformed.z .. ")", 255, 255, 255, 255)

Access & Structure Methods

mat4:get

Signature: mat4:get(row, col)

Description: Gets the value at the specified row and column.

Parameters:

  • row (number): The row index (1-4).

  • col (number): The column index (1-4).

Returns:

  • number: The value at the specified position.

Example:

local m = mat4()
local value = m:get(1, 1)  -- Should be 1 for identity matrix
engine.log("Value at (1,1): " .. value, 255, 255, 255, 255)

mat4:set

Signature: mat4:set(row, col, value)

Description: Sets the value at the specified row and column.

Parameters:

  • row (number): The row index (1-4).

  • col (number): The column index (1-4).

  • value (number): The value to set.

Returns: None

Example:

local m = mat4()
m:set(1, 2, 5)  -- Set element at row 1, column 2 to 5
engine.log("Modified matrix element (1,2) to 5", 255, 255, 255, 255)

mat4:row

Signature: mat4:row(index)

Description: Returns a row of the matrix as a vec4.

Parameters:

  • index (number): The row index (1-4).

Returns:

  • vec4: The row vector.

Example:

local m = mat4()
local first_row = m:row(1)  -- Should be (1,0,0,0) for identity matrix
engine.log("First row: (" .. first_row.x .. ", " .. first_row.y .. ", " .. first_row.z .. ", " .. first_row.w .. ")", 255, 255, 255, 255)

mat4:column

Signature: mat4:column(index)

Description: Returns a column of the matrix as a vec4.

Parameters:

  • index (number): The column index (1-4).

Returns:

  • vec4: The column vector.

Example:

local m = mat4()
local first_column = m:column(1)  -- Should be (1,0,0,0) for identity matrix
engine.log("First column: (" .. first_column.x .. ", " .. first_column.y .. ", " .. first_column.z .. ", " .. first_column.w .. ")", 255, 255, 255, 255)

mat4:clone

Signature: mat4:clone()

Description: Creates a copy of the matrix.

Parameters: None

Returns:

  • mat4: A new matrix with the same values.

Example:

local original = mat4()
original:set(1, 1, 2)  -- Modify the original matrix

local copy = original:clone()
engine.log("Original (1,1): " .. original:get(1, 1), 255, 255, 255, 255)
engine.log("Copy (1,1): " .. copy:get(1, 1), 255, 255, 255, 255)

mat4:to_table

Signature: mat4:to_table()

Description: Converts the matrix to a nested Lua table.

Parameters: None

Returns:

  • table: A 4×4 nested table representing the matrix.

Example:

local m = mat4()
local table_form = m:to_table()
engine.log("Matrix converted to table", 255, 255, 255, 255)

mat4.from_table

Signature: mat4.from_table(table)

Description: Constructs a matrix from a nested Lua table.

Parameters:

  • table (table): A 4×4 nested table representing the matrix.

Returns:

  • mat4: A new matrix with values from the table.

Example:

local table_data = {
    {1, 0, 0, 0},
    {0, 1, 0, 0},
    {0, 0, 1, 0},
    {0, 0, 0, 1}
}
local m = mat4.from_table(table_data)
engine.log("Matrix created from table", 255, 255, 255, 255)

Transformation Methods

mat4:transpose

Signature: mat4:transpose()

Description: Returns the transposed matrix (rows become columns).

Parameters: None

Returns:

  • mat4: The transposed matrix.

Example:

local m = mat4()
m:set(1, 2, 5)  -- Set element at row 1, column 2 to 5
local transposed = m:transpose()
engine.log("Original (1,2): " .. m:get(1, 2), 255, 255, 255, 255)
engine.log("Transposed (2,1): " .. transposed:get(2, 1), 255, 255, 255, 255)

mat4:inverse

Signature: mat4:inverse()

Description: Returns the inverse of the matrix.

Parameters: None

Returns:

  • mat4: The inverse matrix, or nil if the matrix is singular (non-invertible).

Example:

local m = mat4()
m:translate(vec3(10, 20, 30))  -- Create a translation matrix
local inv = m:inverse()

-- Test if m * inv = identity
local result = m * inv
engine.log("Result (1,1): " .. result:get(1, 1), 255, 255, 255, 255)  -- Should be close to 1
engine.log("Result (4,1): " .. result:get(4, 1), 255, 255, 255, 255)  -- Should be close to 0

mat4:determinant

Signature: mat4:determinant()

Description: Returns the determinant of the matrix.

Parameters: None

Returns:

  • number: The matrix determinant.

Example:

local m = mat4()
local det = m:determinant()  -- Should be 1 for identity matrix
engine.log("Determinant: " .. det, 255, 255, 255, 255)

mat4:scale

Signature: mat4:scale(vec3)

Description: Scales the matrix by a vec3.

Parameters:

  • vec3 (vec3): The scale factors for each axis.

Returns:

  • mat4: The scaled matrix.

Example:

local m = mat4()
m:scale(vec3(2, 3, 4))  -- Scale by 2 in X, 3 in Y, 4 in Z
engine.log("Matrix scaled", 255, 255, 255, 255)

-- Test the scaling
local point = vec4(1, 1, 1, 1)
local scaled = m * point
engine.log("Scaled point: (" .. scaled.x .. ", " .. scaled.y .. ", " .. scaled.z .. ")", 255, 255, 255, 255)

mat4:translate

Signature: mat4:translate(vec3)

Description: Applies translation to the matrix.

Parameters:

  • vec3 (vec3): The translation vector.

Returns:

  • mat4: The translated matrix.

Example:

local m = mat4()
m:translate(vec3(10, 20, 30))  -- Translate by (10, 20, 30)
engine.log("Matrix translated", 255, 255, 255, 255)

-- Test the translation
local point = vec4(0, 0, 0, 1)
local translated = m * point
engine.log("Translated point: (" .. translated.x .. ", " .. translated.y .. ", " .. translated.z .. ")", 255, 255, 255, 255)

mat4:rotate

Signature: mat4:rotate(angle, axis)

Description: Rotates the matrix around an axis by an angle in radians.

Parameters:

  • angle (number): The rotation angle in radians.

  • axis (vec3): The rotation axis (should be normalized).

Returns:

  • mat4: The rotated matrix.

Example:

local m = mat4()
m:rotate(math.pi / 2, vec3(0, 0, 1))  -- Rotate 90 degrees around Z axis
engine.log("Matrix rotated", 255, 255, 255, 255)

-- Test the rotation
local point = vec4(1, 0, 0, 1)
local rotated = m * point
engine.log("Rotated point: (" .. rotated.x .. ", " .. rotated.y .. ", " .. rotated.z .. ")", 255, 255, 255, 255)

mat4:apply_to_vec3

Signature: mat4:apply_to_vec3(vec3)

Description: Applies the matrix transformation to a vec3.

Parameters:

  • vec3 (vec3): The vector to transform.

Returns:

  • vec3: The transformed vector.

Example:

local m = mat4()
m:translate(vec3(10, 20, 30))

local point = vec3(1, 2, 3)
local transformed = m:apply_to_vec3(point)
engine.log("Original: (" .. point.x .. ", " .. point.y .. ", " .. point.z .. ")", 255, 255, 255, 255)
engine.log("Transformed: (" .. transformed.x .. ", " .. transformed.y .. ", " .. transformed.z .. ")", 255, 255, 255, 255)

Decomposition & Comparison

mat4:decompose

Signature: mat4:decompose()

Description: Returns position, rotation, and scale components of the matrix.

Parameters: None

Returns:

  • position (vec3): The translation component.

  • rotation (vec4): The rotation as a quaternion.

  • scale (vec3): The scale component.

Example:

local m = mat4()
m:translate(vec3(10, 20, 30))
m:scale(vec3(2, 2, 2))

local position, rotation, scale = m:decompose()
engine.log("Position: (" .. position.x .. ", " .. position.y .. ", " .. position.z .. ")", 255, 255, 255, 255)
engine.log("Scale: (" .. scale.x .. ", " .. scale.y .. ", " .. scale.z .. ")", 255, 255, 255, 255)

mat4:equals

Signature: mat4:equals(other, tolerance?)

Description: Compares with another matrix for equality.

Parameters:

  • other (mat4): The matrix to compare with.

  • tolerance (number, optional): The comparison tolerance. Defaults to a small epsilon value.

Returns:

  • boolean: true if the matrices are equal within the tolerance, false otherwise.

Example:

local m1 = mat4()
local m2 = mat4()
local m3 = mat4():translate(vec3(0.0001, 0, 0))

engine.log("m1 equals m2: " .. tostring(m1:equals(m2)), 255, 255, 255, 255)  -- true
engine.log("m1 equals m3: " .. tostring(m1:equals(m3)), 255, 255, 255, 255)  -- false
engine.log("m1 equals m3 with tolerance: " .. tostring(m1:equals(m3, 0.001)), 255, 255, 255, 255)  -- true

mat4:is_identity

Signature: mat4:is_identity()

Description: Returns true if the matrix is an identity matrix.

Parameters: None

Returns:

  • boolean: true if the matrix is identity, false otherwise.

Example:

local m1 = mat4()
local m2 = mat4():translate(vec3(1, 0, 0))

engine.log("m1 is identity: " .. tostring(m1:is_identity()), 255, 255, 255, 255)  -- true
engine.log("m2 is identity: " .. tostring(m2:is_identity()), 255, 255, 255, 255)  -- false

Memory Access

mat4.read

Signature: mat4.read(address)

Description: Reads a mat4 from memory.

Parameters:

  • address (number): The memory address to read from.

Returns:

  • mat4: The matrix read from memory.

Example:

-- This example assumes we have valid memory operations
local buffer = m.alloc(16 * 4)  -- Allocate space for 16 floats
-- ... write matrix data to buffer ...
local matrix = mat4.read(buffer)
engine.log("Matrix read from memory", 255, 255, 255, 255)
m.free(buffer)

Special Matrix Constructors

mat4.perspective

Signature: mat4.perspective(fov_y, aspect, near, far)

Description: Creates a perspective projection matrix.

Parameters:

  • fov_y (number): The field of view angle in the Y direction, in radians.

  • aspect (number): The aspect ratio (width/height).

  • near (number): The distance to the near clipping plane.

  • far (number): The distance to the far clipping plane.

Returns:

  • mat4: A perspective projection matrix.

Example:

-- Create a perspective projection matrix
local fov = 60 * (math.pi / 180)  -- 60 degrees in radians
local aspect = 1280 / 720          -- 16:9 aspect ratio
local near = 0.1
local far = 1000.0
local proj = mat4.perspective(fov, aspect, near, far)
engine.log("Created perspective projection matrix", 255, 255, 255, 255)

mat4.orthographic

Signature: mat4.orthographic(left, right, bottom, top, near, far)

Description: Creates an orthographic projection matrix.

Parameters:

  • left (number): The left coordinate of the viewing volume.

  • right (number): The right coordinate of the viewing volume.

  • bottom (number): The bottom coordinate of the viewing volume.

  • top (number): The top coordinate of the viewing volume.

  • near (number): The near depth clipping plane.

  • far (number): The far depth clipping plane.

Returns:

  • mat4: An orthographic projection matrix.

Example:

-- Create an orthographic projection matrix
local left = -5
local right = 5
local bottom = -5
local top = 5
local near = 0.1
local far = 100.0
local ortho = mat4.orthographic(left, right, bottom, top, near, far)
engine.log("Created orthographic projection matrix", 255, 255, 255, 255)

mat4.trs

Signature: mat4.trs(position, rotation_quat, scale)

Description: Creates a matrix from translation, rotation (quaternion), and scale.

Parameters:

  • position (vec3): The translation vector.

  • rotation_quat (vec4): The rotation as a quaternion.

  • scale (vec3): The scale vector.

Returns:

  • mat4: A transformation matrix.

Example:

-- Create a transformation matrix with translation, rotation and scale
local position = vec3(10, 0, 0)
local rotation = vec4(0, 0, 0, 1)  -- Identity quaternion
local scale = vec3(2, 1, 1)
local matrix = mat4.trs(position, rotation, scale)
engine.log("Created TRS matrix", 255, 255, 255, 255)

mat4.look_at

Signature: mat4.look_at(eye, target, up)

Description: Creates a view matrix looking at a target from a position.

Parameters:

  • eye (vec3): The camera position.

  • target (vec3): The point to look at.

  • up (vec3): The up vector.

Returns:

  • mat4: A view matrix.

Example:

-- Create a view matrix for a camera
local eye = vec3(0, 0, 5)     -- Camera position
local target = vec3(0, 0, 0)  -- Looking at the origin
local up = vec3(0, 1, 0)      -- Y-axis is up
local view = mat4.look_at(eye, target, up)
engine.log("Created view matrix", 255, 255, 255, 255)

Matrix Transformations Workflow

Creating and Composing Transformations

Example:

-- Create individual transformation matrices
local translate = mat4()
translate:translate(vec3(10, 0, 0))  -- Translate 10 units along X

local rotate = mat4()
rotate:rotate(math.pi/4, vec3(0, 0, 1))  -- Rotate 45 degrees around Z axis

local scale = mat4()
scale:scale(vec3(2, 2, 2))  -- Scale by 2 in all directions

-- Combine transformations (applied right-to-left: scale, then rotate, then translate)
local transform = translate * rotate * scale

-- Apply to a point
local point = vec4(1, 0, 0, 1)
local transformed = transform * point

engine.log("Original point: (" .. point.x .. ", " .. point.y .. ", " .. point.z .. ")", 255, 255, 255, 255)
engine.log("Transformed point: (" .. transformed.x .. ", " .. transformed.y .. ", " .. transformed.z .. ")", 255, 255, 255, 255)

Creating a Camera Matrix

Example:

-- Set up camera parameters
local eye = vec3(0, 0, 5)     -- Camera position
local target = vec3(0, 0, 0)  -- Looking at the origin
local up = vec3(0, 1, 0)      -- Y-axis is up

-- Create view matrix
local view = mat4.look_at(eye, target, up)

-- Create projection matrix (perspective)
local fov = 60 * (math.pi / 180)  -- 60 degrees in radians
local aspect = 16 / 9              -- 16:9 aspect ratio
local near = 0.1
local far = 100.0
local projection = mat4.perspective(fov, aspect, near, far)

-- Combine view and projection matrices
local view_projection = projection * view

-- Apply to a world-space point
local world_point = vec4(10, 0, 0, 1)
local clip_space = view_projection * world_point

engine.log("World point: (" .. world_point.x .. ", " .. world_point.y .. ", " .. world_point.z .. ")", 255, 255, 255, 255)
engine.log("Clip space: (" .. clip_space.x .. ", " .. clip_space.y .. ", " .. clip_space.z .. ", " .. clip_space.w .. ")", 255, 255, 255, 255)
PreviousVector Types (vec2, vec3, vec4)NextWindows

Last updated

Was this helpful?