or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

common.mdindex.mdmatrices.mdquaternions.mdvectors.md
tile.json

tessl/npm-gl-matrix

High-performance JavaScript library for vector and matrix mathematical operations optimized for WebGL applications and 3D graphics programming

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gl-matrix@3.4.x

To install, run

npx @tessl/cli install tessl/npm-gl-matrix@3.4.0

index.mddocs/

gl-matrix

gl-matrix is a high-performance JavaScript library providing comprehensive vector and matrix mathematical operations specifically optimized for WebGL applications and 3D graphics programming. It offers efficient implementations for 2D, 3D, and 4D vectors, 2x2, 3x3, and 4x4 matrices, quaternions, and dual quaternions with hand-tuned functions designed for maximum performance in browser JavaScript engines.

Package Information

  • Package Name: gl-matrix
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install gl-matrix

Core Imports

import { glMatrix, vec2, vec3, vec4, mat2, mat2d, mat3, mat4, quat, quat2 } from "gl-matrix";

Individual module imports:

import * as vec3 from "gl-matrix/vec3";
import * as mat4 from "gl-matrix/mat4";
import * as quat from "gl-matrix/quat";

CommonJS:

const { vec3, mat4, quat } = require("gl-matrix");

Basic Usage

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

// Create and manipulate 3D vectors
const position = vec3.fromValues(0, 0, -5);
const velocity = vec3.fromValues(1, 0, 0);
vec3.add(position, position, velocity);

// Create transformation matrices
const model = mat4.create();
mat4.translate(model, model, position);
mat4.rotateY(model, model, Math.PI / 4);

// Work with quaternions for rotations
const rotation = quat.create();
quat.fromEuler(rotation, 0, 45, 0); // 45 degrees around Y-axis

Architecture

gl-matrix is built around several key design principles:

  • Performance-First: All functions are hand-optimized for JavaScript engines with minimal memory allocation
  • Immutable Operations: Functions take separate output parameters to avoid creating new objects
  • Consistent API: All modules follow the same naming conventions and parameter patterns
  • Type Safety: Complete TypeScript definitions with generic types for IndexedCollection compatibility
  • WebGL Optimization: Matrix operations use column-major order matching WebGL conventions

The library uses Float32Array by default for optimal performance but can be configured to use regular JavaScript arrays.

Capabilities

Vector Operations

2D, 3D, and 4D vector mathematical operations including arithmetic, normalization, transformations, and interpolation.

// 2D Vector operations
const vec2: {
  create(): vec2;
  fromValues(x: number, y: number): vec2;
  add(out: vec2, a: ReadonlyVec2, b: ReadonlyVec2): vec2;
  normalize(out: vec2, a: ReadonlyVec2): vec2;
  dot(a: ReadonlyVec2, b: ReadonlyVec2): number;
};

// 3D Vector operations  
const vec3: {
  create(): vec3;
  fromValues(x: number, y: number, z: number): vec3;
  cross(out: vec3, a: ReadonlyVec3, b: ReadonlyVec3): vec3;
  transformMat4(out: vec3, a: ReadonlyVec3, m: ReadonlyMat4): vec3;
};

// 4D Vector operations
const vec4: {
  create(): vec4;
  fromValues(x: number, y: number, z: number, w: number): vec4;
  transformMat4(out: vec4, a: ReadonlyVec4, m: ReadonlyMat4): vec4;
};

Vector Operations

Matrix Operations

Comprehensive matrix operations for 2x2, 2D transformation (2x3), 3x3, and 4x4 matrices including creation, arithmetic, transformations, and decomposition.

// 4x4 Matrix operations
const mat4: {
  create(): mat4;
  identity(out: mat4): mat4;
  multiply(out: mat4, a: ReadonlyMat4, b: ReadonlyMat4): mat4;
  translate(out: mat4, a: ReadonlyMat4, v: ReadonlyVec3): mat4;
  rotate(out: mat4, a: ReadonlyMat4, rad: number, axis: ReadonlyVec3): mat4;
  scale(out: mat4, a: ReadonlyMat4, v: ReadonlyVec3): mat4;
  perspective(out: mat4, fovy: number, aspect: number, near: number, far: number): mat4;
  lookAt(out: mat4, eye: ReadonlyVec3, center: ReadonlyVec3, up: ReadonlyVec3): mat4;
};

// 3x3 Matrix operations
const mat3: {
  create(): mat3;
  fromMat4(out: mat3, a: ReadonlyMat4): mat3;
  normalFromMat4(out: mat3, a: ReadonlyMat4): mat3;
};

Matrix Operations

Quaternion Operations

Quaternion and dual quaternion operations for efficient 3D rotations and transformations.

// Quaternion operations
const quat: {
  create(): quat;
  identity(out: quat): quat;
  setAxisAngle(out: quat, axis: ReadonlyVec3, rad: number): quat;
  multiply(out: quat, a: ReadonlyQuat, b: ReadonlyQuat): quat;
  slerp(out: quat, a: ReadonlyQuat, b: ReadonlyQuat, t: number): quat;
  fromEuler(out: quat, x: number, y: number, z: number, order?: string): quat;
  fromMat3(out: quat, m: ReadonlyMat3): quat;
};

// Dual Quaternion operations
const quat2: {
  create(): quat2;
  fromRotationTranslation(out: quat2, q: ReadonlyQuat, t: ReadonlyVec3): quat2;
  normalize(out: quat2, a: ReadonlyQuat2): quat2;
};

Quaternion Operations

Common Utilities

Shared utilities and constants used across all modules.

const glMatrix: {
  EPSILON: number;
  ARRAY_TYPE: Float32ArrayConstructor | ArrayConstructor;
  RANDOM: () => number;
  ANGLE_ORDER: string;
  toRadian(a: number): number;
  toDegree(a: number): number;
  equals(a: number, b: number, tolerance?: number): boolean;
  setMatrixArrayType(type: Float32ArrayConstructor | ArrayConstructor): void;
};

Common Utilities

Types

// Core types
interface IndexedCollection extends Iterable<number> {
  readonly length: number;
  [index: number]: number;
}

// Vector types
type vec2 = [number, number] | IndexedCollection;
type vec3 = [number, number, number] | IndexedCollection;
type vec4 = [number, number, number, number] | IndexedCollection;

// Matrix types
type mat2 = [number, number, number, number] | IndexedCollection;
type mat2d = [number, number, number, number, number, number] | IndexedCollection;
type mat3 = [number, number, number, number, number, number, number, number, number] | IndexedCollection;
type mat4 = [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number] | IndexedCollection;

// Quaternion types
type quat = [number, number, number, number] | IndexedCollection;
type quat2 = [number, number, number, number, number, number, number, number] | IndexedCollection;

// Readonly variants
type ReadonlyVec2 = readonly [number, number] | IndexedCollection;
type ReadonlyVec3 = readonly [number, number, number] | IndexedCollection;
type ReadonlyVec4 = readonly [number, number, number, number] | IndexedCollection;
type ReadonlyMat2 = readonly [number, number, number, number] | IndexedCollection;
type ReadonlyMat2d = readonly [number, number, number, number, number, number] | IndexedCollection;
type ReadonlyMat3 = readonly [number, number, number, number, number, number, number, number, number] | IndexedCollection;
type ReadonlyMat4 = readonly [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number] | IndexedCollection;
type ReadonlyQuat = readonly [number, number, number, number] | IndexedCollection;
type ReadonlyQuat2 = readonly [number, number, number, number, number, number, number, number] | IndexedCollection;