Matrix Operations

/**
 * Creates a new identity mat4
 * @returns New identity matrix
 */
function create(): mat4;

/**
 * Creates a new mat4 from an existing matrix
 * @param a - Matrix to clone
 * @returns New mat4 with copied values
 */
function clone(a: ReadonlyMat4): mat4;

/**
 * Copy values from one mat4 to another
 * @param out - Receiving matrix
 * @param a - Source matrix
 * @returns out parameter
 */
function copy(out: mat4, a: ReadonlyMat4): mat4;

/**
 * Creates a matrix from the given values (column-major order)
 * @param m00-m33 - Matrix components
 * @returns New mat4 with specified values
 */
function fromValues(
  m00: number, m01: number, m02: number, m03: number,
  m10: number, m11: number, m12: number, m13: number,
  m20: number, m21: number, m22: number, m23: number,
  m30: number, m31: number, m32: number, m33: number
): mat4;

/**
 * Set a mat4 to the identity matrix
 * @param out - Receiving matrix
 * @returns out parameter
 */
function identity(out: mat4): mat4;

/**
 * Set the components of a mat4 to the given values
 * @param out - Receiving matrix
 * @param m00-m33 - Matrix components
 * @returns out parameter
 */
function set(
  out: mat4,
  m00: number, m01: number, m02: number, m03: number,
  m10: number, m11: number, m12: number, m13: number,
  m20: number, m21: number, m22: number, m23: number,
  m30: number, m31: number, m32: number, m33: number
): mat4;

/**
 * Transpose the values of a mat4
 * @param out - Receiving matrix
 * @param a - Source matrix
 * @returns out parameter
 */
function transpose(out: mat4, a: ReadonlyMat4): mat4;

/**
 * Inverts a mat4
 * @param out - Receiving matrix
 * @param a - Source matrix
 * @returns out parameter or null if matrix is not invertible
 */
function invert(out: mat4, a: ReadonlyMat4): mat4 | null;

/**
 * Calculates the adjugate of a mat4
 * @param out - Receiving matrix
 * @param a - Source matrix
 * @returns out parameter
 */
function adjoint(out: mat4, a: ReadonlyMat4): mat4;

/**
 * Calculates the determinant of a mat4
 * @param a - Source matrix
 * @returns Determinant of a
 */
function determinant(a: ReadonlyMat4): number;

/**
 * Multiplies two mat4s
 * @param out - Receiving matrix
 * @param a - First operand
 * @param b - Second operand
 * @returns out parameter
 */
function multiply(out: mat4, a: ReadonlyMat4, b: ReadonlyMat4): mat4;

/**
 * Translate a mat4 by the given vector
 * @param out - Receiving matrix
 * @param a - Matrix to translate
 * @param v - Vector to translate by
 * @returns out parameter
 */
function translate(out: mat4, a: ReadonlyMat4, v: ReadonlyVec3): mat4;

/**
 * Scales the mat4 by the dimensions in the given vec3
 * @param out - Receiving matrix
 * @param a - Matrix to scale
 * @param v - Vector to scale by
 * @returns out parameter
 */
function scale(out: mat4, a: ReadonlyMat4, v: ReadonlyVec3): mat4;

/**
 * Rotates a mat4 by the given angle around the given axis
 * @param out - Receiving matrix
 * @param a - Matrix to rotate
 * @param rad - Angle to rotate by in radians
 * @param axis - Axis to rotate around
 * @returns out parameter
 */
function rotate(out: mat4, a: ReadonlyMat4, rad: number, axis: ReadonlyVec3): mat4;

/**
 * Rotates a matrix by the given angle around the X axis
 * @param out - Receiving matrix
 * @param a - Matrix to rotate
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function rotateX(out: mat4, a: ReadonlyMat4, rad: number): mat4;

/**
 * Rotates a matrix by the given angle around the Y axis
 * @param out - Receiving matrix
 * @param a - Matrix to rotate
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function rotateY(out: mat4, a: ReadonlyMat4, rad: number): mat4;

/**
 * Rotates a matrix by the given angle around the Z axis
 * @param out - Receiving matrix
 * @param a - Matrix to rotate
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function rotateZ(out: mat4, a: ReadonlyMat4, rad: number): mat4;

/**
 * Creates a matrix from a translation vector
 * @param out - Receiving matrix
 * @param v - Translation vector
 * @returns out parameter
 */
function fromTranslation(out: mat4, v: ReadonlyVec3): mat4;

/**
 * Creates a matrix from a scaling vector
 * @param out - Receiving matrix
 * @param v - Scaling vector
 * @returns out parameter
 */
function fromScaling(out: mat4, v: ReadonlyVec3): mat4;

/**
 * Creates a matrix from a given angle around a given axis
 * @param out - Receiving matrix
 * @param rad - Angle to rotate by in radians
 * @param axis - Axis to rotate around
 * @returns out parameter
 */
function fromRotation(out: mat4, rad: number, axis: ReadonlyVec3): mat4;

/**
 * Creates a matrix from the given angle around the X axis
 * @param out - Receiving matrix
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function fromXRotation(out: mat4, rad: number): mat4;

/**
 * Creates a matrix from the given angle around the Y axis
 * @param out - Receiving matrix
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function fromYRotation(out: mat4, rad: number): mat4;

/**
 * Creates a matrix from the given angle around the Z axis
 * @param out - Receiving matrix
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function fromZRotation(out: mat4, rad: number): mat4;

/**
 * Creates a matrix from a quaternion rotation and vector translation
 * @param out - Receiving matrix
 * @param q - Rotation quaternion
 * @param v - Translation vector
 * @returns out parameter
 */
function fromRotationTranslation(out: mat4, q: ReadonlyQuat, v: ReadonlyVec3): mat4;

/**
 * Creates a matrix from a quaternion rotation, vector translation and vector scale
 * @param out - Receiving matrix
 * @param q - Rotation quaternion
 * @param v - Translation vector
 * @param s - Scaling vector
 * @returns out parameter
 */
function fromRotationTranslationScale(out: mat4, q: ReadonlyQuat, v: ReadonlyVec3, s: ReadonlyVec3): mat4;

/**
 * Creates a matrix from a quaternion rotation, vector translation and vector scale with a separate origin
 * @param out - Receiving matrix
 * @param q - Rotation quaternion
 * @param v - Translation vector
 * @param s - Scaling vector
 * @param o - Origin vector
 * @returns out parameter
 */
function fromRotationTranslationScaleOrigin(out: mat4, q: ReadonlyQuat, v: ReadonlyVec3, s: ReadonlyVec3, o: ReadonlyVec3): mat4;

/**
 * Creates a matrix from a quaternion
 * @param out - Receiving matrix
 * @param q - Quaternion to create matrix from
 * @returns out parameter
 */
function fromQuat(out: mat4, q: ReadonlyQuat): mat4;

/**
 * Creates a matrix from a dual quaternion
 * @param out - Receiving matrix
 * @param a - Dual quaternion
 * @returns out parameter
 */
function fromQuat2(out: mat4, a: ReadonlyQuat2): mat4;

/**
 * Returns the translation vector component of a transformation matrix
 * @param out - Receiving vector
 * @param mat - Matrix to be decomposed
 * @returns out parameter
 */
function getTranslation(out: vec3, mat: ReadonlyMat4): vec3;

/**
 * Returns the scaling factor component of a transformation matrix
 * @param out - Receiving vector
 * @param mat - Matrix to be decomposed
 * @returns out parameter
 */
function getScaling(out: vec3, mat: ReadonlyMat4): vec3;

/**
 * Returns a quaternion representing the rotational component of a transformation matrix
 * @param out - Receiving quaternion
 * @param mat - Matrix to be decomposed
 * @returns out parameter
 */
function getRotation(out: quat, mat: ReadonlyMat4): quat;

/**
 * Decomposes a transformation matrix into its rotation, translation and scale components
 * @param out_r - Receiving rotation quaternion
 * @param out_t - Receiving translation vector
 * @param out_s - Receiving scaling vector
 * @param mat - Matrix to be decomposed
 * @returns out_r parameter
 */
function decompose(out_r: quat, out_t: vec3, out_s: vec3, mat: ReadonlyMat4): quat;

/**
 * Creates a frustum matrix
 * @param out - Receiving matrix
 * @param left - Left bound of the frustum
 * @param right - Right bound of the frustum
 * @param bottom - Bottom bound of the frustum
 * @param top - Top bound of the frustum
 * @param near - Near bound of the frustum
 * @param far - Far bound of the frustum
 * @returns out parameter
 */
function frustum(out: mat4, left: number, right: number, bottom: number, top: number, near: number, far: number): mat4;

/**
 * Creates a perspective projection matrix with the given bounds (near plane at z=0)
 * @param out - Receiving matrix
 * @param fovy - Vertical field of view in radians
 * @param aspect - Aspect ratio (width/height)
 * @param near - Near bound of the frustum
 * @param far - Far bound of the frustum
 * @returns out parameter
 */
function perspectiveNO(out: mat4, fovy: number, aspect: number, near: number, far: number): mat4;

/**
 * Creates a perspective projection matrix with the given bounds (z range 0 to 1)
 * @param out - Receiving matrix
 * @param fovy - Vertical field of view in radians
 * @param aspect - Aspect ratio (width/height)
 * @param near - Near bound of the frustum
 * @param far - Far bound of the frustum
 * @returns out parameter
 */
function perspectiveZO(out: mat4, fovy: number, aspect: number, near: number, far: number): mat4;

/**
 * Creates a perspective projection matrix from the given field of view object
 * @param out - Receiving matrix
 * @param fov - Object containing field of view parameters
 * @param near - Near bound of the frustum
 * @param far - Far bound of the frustum
 * @returns out parameter
 */
function perspectiveFromFieldOfView(out: mat4, fov: any, near: number, far: number): mat4;

/**
 * Creates an orthogonal projection matrix with the given bounds (near plane at z=0)
 * @param out - Receiving matrix
 * @param left - Left bound of the frustum
 * @param right - Right bound of the frustum
 * @param bottom - Bottom bound of the frustum
 * @param top - Top bound of the frustum
 * @param near - Near bound of the frustum
 * @param far - Far bound of the frustum
 * @returns out parameter
 */
function orthoNO(out: mat4, left: number, right: number, bottom: number, top: number, near: number, far: number): mat4;

/**
 * Creates an orthogonal projection matrix with the given bounds (z range 0 to 1)
 * @param out - Receiving matrix
 * @param left - Left bound of the frustum
 * @param right - Right bound of the frustum
 * @param bottom - Bottom bound of the frustum
 * @param top - Top bound of the frustum
 * @param near - Near bound of the frustum
 * @param far - Far bound of the frustum
 * @returns out parameter
 */
function orthoZO(out: mat4, left: number, right: number, bottom: number, top: number, near: number, far: number): mat4;

/**
 * Generates a look-at matrix with the given eye position, focal point, and up axis
 * @param out - Receiving matrix
 * @param eye - Position of the viewer
 * @param center - Point the viewer is looking at
 * @param up - Up direction
 * @returns out parameter
 */
function lookAt(out: mat4, eye: ReadonlyVec3, center: ReadonlyVec3, up: ReadonlyVec3): mat4;

/**
 * Generates a matrix that makes something look at something else
 * @param out - Receiving matrix
 * @param eye - Position of the viewer
 * @param target - Point the viewer is looking at
 * @param up - Up direction
 * @returns out parameter
 */
function targetTo(out: mat4, eye: ReadonlyVec3, target: ReadonlyVec3, up: ReadonlyVec3): mat4;

/**
 * Adds two mat4s
 * @param out - Receiving matrix
 * @param a - First operand
 * @param b - Second operand
 * @returns out parameter
 */
function add(out: mat4, a: ReadonlyMat4, b: ReadonlyMat4): mat4;

/**
 * Subtracts matrix b from matrix a
 * @param out - Receiving matrix
 * @param a - First operand
 * @param b - Second operand
 * @returns out parameter
 */
function subtract(out: mat4, a: ReadonlyMat4, b: ReadonlyMat4): mat4;

/**
 * Multiply each element of a matrix by a scalar
 * @param out - Receiving matrix
 * @param a - Source matrix
 * @param b - Amount to scale the matrix's elements by
 * @returns out parameter
 */
function multiplyScalar(out: mat4, a: ReadonlyMat4, b: number): mat4;

/**
 * Adds two mat4s after multiplying each element of the second operand by a scalar
 * @param out - Receiving matrix
 * @param a - First operand
 * @param b - Second operand
 * @param scale - Amount to scale b's elements by before adding
 * @returns out parameter
 */
function multiplyScalarAndAdd(out: mat4, a: ReadonlyMat4, b: ReadonlyMat4, scale: number): mat4;

/**
 * Returns a string representation of a mat4
 * @param a - Matrix to represent as string
 * @returns String representation of the matrix
 */
function str(a: ReadonlyMat4): string;

/**
 * Returns Frobenius norm of a mat4
 * @param a - Matrix to calculate Frobenius norm of
 * @returns Frobenius norm
 */
function frob(a: ReadonlyMat4): number;

/**
 * Returns whether or not the matrices have exactly the same elements in the same position
 * @param a - First matrix
 * @param b - Second matrix
 * @returns True if the matrices are equal, false otherwise
 */
function exactEquals(a: ReadonlyMat4, b: ReadonlyMat4): boolean;

/**
 * Returns whether or not the matrices have approximately the same elements in the same position
 * @param a - First matrix
 * @param b - Second matrix
 * @returns True if the matrices are equal, false otherwise
 */
function equals(a: ReadonlyMat4, b: ReadonlyMat4): boolean;

/**
 * Alias for multiply
 */
const mul: typeof multiply;

/**
 * Alias for subtract
 */
const sub: typeof subtract;

/**
 * Alias for perspectiveNO
 */
const perspective: typeof perspectiveNO;

/**
 * Alias for orthoNO
 */
const ortho: typeof orthoNO;

/**
 * Creates a new identity mat3
 * @returns New identity matrix
 */
function create(): mat3;

/**
 * Creates a new mat3 from a mat4
 * @param out - Receiving matrix
 * @param a - Source mat4
 * @returns out parameter
 */
function fromMat4(out: mat3, a: ReadonlyMat4): mat3;

/**
 * Creates a matrix from the given values (column-major order)
 * @param m00-m22 - Matrix components
 * @returns New mat3 with specified values
 */
function fromValues(
  m00: number, m01: number, m02: number,
  m10: number, m11: number, m12: number,
  m20: number, m21: number, m22: number
): mat3;

/**
 * Set a mat3 to the identity matrix
 * @param out - Receiving matrix
 * @returns out parameter
 */
function identity(out: mat3): mat3;

/**
 * Translate a mat3 by the given vector
 * @param out - Receiving matrix
 * @param a - Matrix to translate
 * @param v - Vector to translate by
 * @returns out parameter
 */
function translate(out: mat3, a: ReadonlyMat3, v: ReadonlyVec2): mat3;

/**
 * Rotates a mat3 by the given angle
 * @param out - Receiving matrix
 * @param a - Matrix to rotate
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function rotate(out: mat3, a: ReadonlyMat3, rad: number): mat3;

/**
 * Scales the mat3 by the dimensions in the given vec2
 * @param out - Receiving matrix
 * @param a - Matrix to scale
 * @param v - Vector to scale by
 * @returns out parameter
 */
function scale(out: mat3, a: ReadonlyMat3, v: ReadonlyVec2): mat3;

/**
 * Creates a matrix from a translation vector
 * @param out - Receiving matrix
 * @param v - Translation vector
 * @returns out parameter
 */
function fromTranslation(out: mat3, v: ReadonlyVec2): mat3;

/**
 * Creates a matrix from a given angle
 * @param out - Receiving matrix
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function fromRotation(out: mat3, rad: number): mat3;

/**
 * Creates a matrix from a scaling vector
 * @param out - Receiving matrix
 * @param v - Scaling vector
 * @returns out parameter
 */
function fromScaling(out: mat3, v: ReadonlyVec2): mat3;

/**
 * Creates a mat3 from a mat2d
 * @param out - Receiving matrix
 * @param a - Source mat2d
 * @returns out parameter
 */
function fromMat2d(out: mat3, a: ReadonlyMat2d): mat3;

/**
 * Creates a mat3 from a quaternion
 * @param out - Receiving matrix
 * @param q - Quaternion to create matrix from
 * @returns out parameter
 */
function fromQuat(out: mat3, q: ReadonlyQuat): mat3;

/**
 * Calculates a 3x3 normal matrix (transpose inverse) from the 4x4 matrix
 * @param out - Receiving matrix
 * @param a - Source mat4
 * @returns out parameter
 */
function normalFromMat4(out: mat3, a: ReadonlyMat4): mat3;

/**
 * Creates a 2D projection matrix
 * @param out - Receiving matrix
 * @param width - Width of the projection
 * @param height - Height of the projection
 * @returns out parameter
 */
function projection(out: mat3, width: number, height: number): mat3;

/**
 * Creates a new identity mat2d
 * @returns New identity matrix
 */
function create(): mat2d;

/**
 * Creates a new mat2d with the given values
 * @param a - Component A (index 0)
 * @param b - Component B (index 1)
 * @param c - Component C (index 2)
 * @param d - Component D (index 3)
 * @param tx - Component TX (index 4)
 * @param ty - Component TY (index 5)
 * @returns New mat2d with specified values
 */
function fromValues(a: number, b: number, c: number, d: number, tx: number, ty: number): mat2d;

/**
 * Set a mat2d to the identity matrix
 * @param out - Receiving matrix
 * @returns out parameter
 */
function identity(out: mat2d): mat2d;

/**
 * Rotates a mat2d by the given angle
 * @param out - Receiving matrix
 * @param a - Matrix to rotate
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function rotate(out: mat2d, a: ReadonlyMat2d, rad: number): mat2d;

/**
 * Scales the mat2d by the dimensions in the given vec2
 * @param out - Receiving matrix
 * @param a - Matrix to scale
 * @param v - Vector to scale by
 * @returns out parameter
 */
function scale(out: mat2d, a: ReadonlyMat2d, v: ReadonlyVec2): mat2d;

/**
 * Translates the mat2d by the dimensions in the given vec2
 * @param out - Receiving matrix
 * @param a - Matrix to translate
 * @param v - Vector to translate by
 * @returns out parameter
 */
function translate(out: mat2d, a: ReadonlyMat2d, v: ReadonlyVec2): mat2d;

/**
 * Creates a matrix from a given angle
 * @param out - Receiving matrix
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function fromRotation(out: mat2d, rad: number): mat2d;

/**
 * Creates a matrix from a scaling vector
 * @param out - Receiving matrix
 * @param v - Scaling vector
 * @returns out parameter
 */
function fromScaling(out: mat2d, v: ReadonlyVec2): mat2d;

/**
 * Creates a matrix from a translation vector
 * @param out - Receiving matrix
 * @param v - Translation vector
 * @returns out parameter
 */
function fromTranslation(out: mat2d, v: ReadonlyVec2): mat2d;

/**
 * Creates a new identity mat2
 * @returns New identity matrix
 */
function create(): mat2;

/**
 * Creates a new mat2 with the given values
 * @param m00 - Component in column 0, row 0 position
 * @param m01 - Component in column 0, row 1 position
 * @param m10 - Component in column 1, row 0 position
 * @param m11 - Component in column 1, row 1 position
 * @returns New mat2 with specified values
 */
function fromValues(m00: number, m01: number, m10: number, m11: number): mat2;

/**
 * Set a mat2 to the identity matrix
 * @param out - Receiving matrix
 * @returns out parameter
 */
function identity(out: mat2): mat2;

/**
 * Rotates a mat2 by the given angle
 * @param out - Receiving matrix
 * @param a - Matrix to rotate
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function rotate(out: mat2, a: ReadonlyMat2, rad: number): mat2;

/**
 * Scales the mat2 by the dimensions in the given vec2
 * @param out - Receiving matrix
 * @param a - Matrix to scale
 * @param v - Vector to scale by
 * @returns out parameter
 */
function scale(out: mat2, a: ReadonlyMat2, v: ReadonlyVec2): mat2;

/**
 * Creates a matrix from a given angle
 * @param out - Receiving matrix
 * @param rad - Angle to rotate by in radians
 * @returns out parameter
 */
function fromRotation(out: mat2, rad: number): mat2;

/**
 * Creates a matrix from a scaling vector
 * @param out - Receiving matrix
 * @param v - Scaling vector
 * @returns out parameter
 */
function fromScaling(out: mat2, v: ReadonlyVec2): mat2;

/**
 * Calculates LDU decomposition of a mat2
 * @param L - Receiving lower triangular matrix
 * @param D - Receiving diagonal matrix
 * @param U - Receiving upper triangular matrix
 * @param a - Source matrix
 * @returns Array containing the decomposition matrices
 */
function LDU(L: mat2, D: mat2, U: mat2, a: ReadonlyMat2): Array<mat2>;

/**
 * Math operations available for all matrix types
 */
function transpose(out: mat, a: ReadonlyMat): mat;
function invert(out: mat, a: ReadonlyMat): mat | null;
function adjoint(out: mat, a: ReadonlyMat): mat;
function determinant(a: ReadonlyMat): number;
function multiply(out: mat, a: ReadonlyMat, b: ReadonlyMat): mat;

/**
 * Arithmetic operations available for all matrix types
 */
function add(out: mat, a: ReadonlyMat, b: ReadonlyMat): mat;
function subtract(out: mat, a: ReadonlyMat, b: ReadonlyMat): mat;
function multiplyScalar(out: mat, a: ReadonlyMat, b: number): mat;
function multiplyScalarAndAdd(out: mat, a: ReadonlyMat, b: ReadonlyMat, scale: number): mat;

/**
 * Utility functions available for all matrix types
 */
function str(a: ReadonlyMat): string;
function frob(a: ReadonlyMat): number;
function exactEquals(a: ReadonlyMat, b: ReadonlyMat): boolean;
function equals(a: ReadonlyMat, b: ReadonlyMat): boolean;

import { mat4, mat3, mat2d, vec3 } from "gl-matrix";

// Create transformation matrices
const model = mat4.create();
const view = mat4.create();
const projection = mat4.create();

// Model transformations
const position = vec3.fromValues(0, 0, -5);
const rotation = vec3.fromValues(0, Math.PI / 4, 0);
const scale = vec3.fromValues(1, 1, 1);

mat4.translate(model, model, position);
mat4.rotateY(model, model, rotation[1]);
mat4.scale(model, model, scale);

// View matrix (camera)
const eye = vec3.fromValues(0, 0, 5);
const center = vec3.fromValues(0, 0, 0);
const up = vec3.fromValues(0, 1, 0);
mat4.lookAt(view, eye, center, up);

// Projection matrix
mat4.perspective(projection, Math.PI / 4, 16/9, 0.1, 100.0);

// Combine matrices
const mvp = mat4.create();
mat4.multiply(mvp, projection, view);
mat4.multiply(mvp, mvp, model);

// 2D transformations
const transform2d = mat2d.create();
mat2d.translate(transform2d, transform2d, [100, 50]);
mat2d.rotate(transform2d, transform2d, Math.PI / 6);
mat2d.scale(transform2d, transform2d, [2, 2]);

// Normal matrix for lighting calculations
const normalMatrix = mat3.create();
mat3.normalFromMat4(normalMatrix, model);