# The 3d-matrices Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The 3d-matrices Reference Manual

This is the 3d-matrices Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Nov 04 11:25:39 2020 GMT+0.

Next: , Previous: , Up: Top   [Contents][Index]

## 1 Introduction

This is a library implementing common matrix operations, mainly intended as the counterpiece to 3d-vectors and thus being aimed at operations in 3D space. Still, it also implements other common matrix tasks such as LU and QR factorisation, determinant computation, and sub-matrix selection. 2x2, 3x3, and 4x4 matrices are specially treated and often have specifically optimised or inlined variants in the operations to ensure as high a speed as possible. NxM matrices are also available, but will always use a general algorithm in the operations.

This library by no means attempts, nor comes in any way close to replacing or imitating things such as BLAS and LIN/LAPACK. The main purpose is to have a library that allows convenient matrix operations in conjunction with the 3d-vectors library. It should be sufficiently fast and accurate for most purposes, but should not be used for serious matrix based calculations. Please use industry-standard packages for that.

## How To

Load it through ASDF or Quicklisp and use the package.

``````(ql:quickload :3d-matrices)
(use-package :3d-matrices)
``````

All the functions are prefixed with an `m` or with `nm` for destructive ops. This should ensure that there are no clashes in names. Now let's look at creating matrices.

``````(mat 1 2 3 4)
(mat2 1)
(mat2 '(1 2 3 4))
(mcopy (mat3))
(matn 2 3)
(meye 5)
(muniform 2 3 1)
(mrand 10 10)
``````

In order to see the matrix in a more human-readable format, you can use `describe` or `write-matrix` directly:

``````(describe (meye 5))
(write-matrix (mat2) T)
(write-matrix (mat2) T :format :wolfram)
(write-matrix (mat2) T :format :array)
``````

Matrices always use `float`s. Where sensible, operations will accept `real`s as well however. Either `single-float`s or `double-float`s are used, depending on the presence of the `:3d-vectors-double-floats` keyword in `*features*`. This feature is taken over from the 3d-vectors library to ensure that both of them always agree on the float type.

The type `mat` includes all subtypes `mat2`, `mat3`, `mat4`, and `matn`. Each of them have their own specific accessors that are suffixed with the dimension number. Usually you should be fine with using the generic variants, but if you already know the type you should probably fall back to using the specific one, or use `with-fast-matref`.

``````(miref (meye 2) 3)
(mcref (meye 2) 1 1)
(with-fast-matref (e (mat 2) 2)
(e 1 1))
``````

Matrices are basically a struct that contains a simple-vector of floats. This means that every single reference must also dereference the array first. This is why, if you have many repeated accesses to an array, you should use `with-fast-matref` or do the same manually by first retrieving the backing array with `marr`.

If you're coming to this library with the intention of using it to do 3D math, you'll most likely be mostly looking for how to create translation, rotation, and scaling matrices. Specific functions exist for this that take care of it for you. They all operate on `mat4`s and take a `vec3` as argument.

``````(let ((mat (mtranslation (vec 1 2 3))))
(nmscale mat (vec 1 2 3))
(nmrotate mat +vx+ 90)
(m* mat (vec 1 2 3 4)))
``````

Aside from translations you'll probably also want to set up a projection and a camera. You can do this, too.

``````(mperspective 75 (/ w h) 0.001 10000)       ; Perspective projection
(mortho 0 w h 0 0.001 10000)                ; Orthographic projection
(nmlookat modelview camera-pos center +vy+) ; Look at the centre
``````

Aside from the basic comparison operators `m=` `m~=` `m/=` `m<` `m>` `m<=` `m>=`, and arithmetic operators `m+` `m-` `m*` `m/` `nm+` `nm-` `nm*` `n*m` `nm/`, 3d-matrices also includes LU decomposition `mlu`, determinant computation `mdet`, inversion `minv`, transposition `mtranspose`, trace calculation `mtrace`, minors `mminor`, cofactors `mcof` `mcofactor`, matrix adjugate `madj`, pivoting `mpivot`, norming `m1norm` `minorm` `m2norm`, QR decomposition `mqr` and eigenvalue calculation `meigen`. These should all work "as you expect" and I will thus refrain from showing them off in detail here. Refer to your standard linear algebra textbook to get an understanding of what they do if you don't know already.

Finally, There's also some basic operators to do sectioning or restructuring of a matrix.

``````(mcol (mat 1 2 3 4) 0)
(mrow (mat 1 2 3 4) 0)
(mdiag (mat 1 0 0 0 2 0 0 0 3))
(mtop (mat 1 2 3 4 5 6 7 8 9) 2)
(nmswap-row (mat 1 2 3 4) 0 1)
``````

And that's pretty much all she wrote. Note that some operations will only work on square or non-singular matrices, and all operations that take multiple operands require them to be of a compatible type. For example, you can only multiply matrices that are of agreeable rows and columns or multiply with a vector that is of the appropriate size.

## Also See

Next: , Previous: , Up: Top   [Contents][Index]

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 3d-matrices

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Source Control

(:git "https://github.com/shinmera/3d-matrices.git")

Bug Tracker

zlib

Description

A utility library implementing 2x2, 3x3, 4x4, and NxN matrix functionality.

Version

1.0.0

Dependencies
• documentation-utils
• 3d-vectors
Source

3d-matrices.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

## 3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 3.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.1 3d-matrices.asd

Location

3d-matrices.asd

Systems

3d-matrices (system)

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.2 3d-matrices/package.lisp

Parent

3d-matrices (system)

Location

package.lisp

Packages

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.3 3d-matrices/toolkit.lisp

Dependency

package.lisp (file)

Parent

3d-matrices (system)

Location

toolkit.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.4 3d-matrices/struct.lisp

Dependency

toolkit.lisp (file)

Parent

3d-matrices (system)

Location

struct.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.5 3d-matrices/iterate.lisp

Dependency

struct.lisp (file)

Parent

3d-matrices (system)

Location

iterate.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.6 3d-matrices/ops.lisp

Dependency

iterate.lisp (file)

Parent

3d-matrices (system)

Location

ops.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.7 3d-matrices/documentation.lisp

Dependency

ops.lisp (file)

Parent

3d-matrices (system)

Location

documentation.lisp

Next: , Previous: , Up: Top   [Contents][Index]

## 4 Packages

Packages are listed by definition order.

Previous: , Up: Packages   [Contents][Index]

### 4.1 3d-matrices

Source

package.lisp (file)

Nickname

org.shirakumo.flare.matrix

Use List
• 3d-vectors
• common-lisp
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

### 5.1 Exported definitions

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.1 Macros

Macro: with-fast-matcase (ACCESSOR MAT) &body BODY

Does an etypecase on MAT and an appropriate WITH-FAST-MATREF on each case.

The body should be an expression of (MAT-TYPE form*). For each
matrix type /except/ for MATN, the forms will be wrapped in an appropriate WITH-FAST-MATREF. This is not done for MATN, as often times a different approach to manipulating the matrix than by
direct reference is preferable for that case.

See WITH-FAST-MATREF

Package
Source

ops.lisp (file)

Macro: with-fast-matref (ACCESSOR MAT WIDTH) &body BODY

Allows efficient referencing to matrix elements.

ACCESSOR designates the name of the local macro that will allow you to both read and set the matrix element at the given position It will take either one or two arguments. If two, they are row and column of the cell to dereference, and if one, it is the row-major index of the element to dereference.

You must also designate the proper number of columns stored in the matrix. This is done because often times when you will want to use this macro, you’ll already know the number of columns anyway. Retrieving it again would be wasteful.

You should use this whenever you need to reference elements in a loop or need to do more than one reference overall.

Package
Source

ops.lisp (file)

Macro: with-fast-matrefs BINDINGS &body BODY

Allows efficient referencing of multiple matrices.

Each binding must be of the form that WITH-FAST-MATREF expects.

See WITH-FAST-MATREF

Package
Source

ops.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.2 Compiler macros

Compiler Macro: m* VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m+ VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m- VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m/ VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m/= VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m< VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m<= VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m= VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m> VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: m>= VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: mat &rest VALS
Package
Source

struct.lisp (file)

Compiler Macro: mat2 &optional ELEMENTS
Package
Source

struct.lisp (file)

Compiler Macro: mat3 &optional ELEMENTS
Package
Source

struct.lisp (file)

Compiler Macro: mat4 &optional ELEMENTS
Package
Source

struct.lisp (file)

Compiler Macro: matf MAT &rest VALS
Package
Source

struct.lisp (file)

Compiler Macro: matn R C &optional ELEMENTS
Package
Source

struct.lisp (file)

Compiler Macro: m~= VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: n*m VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: nm* VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: nm+ VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: nm- VAL &rest VALS
Package
Source

ops.lisp (file)

Compiler Macro: nm/ VAL &rest VALS
Package
Source

ops.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.3 Functions

Function: m* VAL &rest VALS

Computes a matrix multiplication.

If the other operand is a real, the matrix is multiplied with the real element-wise. If the other operand is a matrix, they are multiplied as per matrix multiplication. Note that the returned matrix may have different size than the input matrices as a result of this. The two matrices must agree on the size as per matrix multiplication.

Package
Source

ops.lisp (file)

Function: m+ VAL &rest VALS

Computes the element-wise addition of the matrices or reals. Returns a fresh matrix.

Package
Source

ops.lisp (file)

Function: m- VAL &rest VALS

Computes the element-wise subtraction of the matrices or reals. Returns a fresh matrix.

Package
Source

ops.lisp (file)

Function: m/ VAL &rest VALS

Computes an element-wise division of the matrix from a real. Returns a fresh matrix.

Package
Source

ops.lisp (file)

Function: m/= VAL &rest VALS

Compares matrices against each other or a real, returning T if they are element-wise equal by /=.

Package
Source

ops.lisp (file)

Function: m1norm M

Computes the 1 norm of the matrix, namely the maximum of the sums of the columns.

Package
Source

ops.lisp (file)

Function: m2norm M

Computes the 2 norm of the matrix, namely the square root of the sum of all squared elements.

Package
Source

ops.lisp (file)

Function: m< VAL &rest VALS

Compares matrices against each other or a real, returning T if they are element-wise ordered by <.

Package
Source

ops.lisp (file)

Function: m<= VAL &rest VALS

Compares matrices against each other or a real, returning T if they are element-wise ordered by <=.

Package
Source

ops.lisp (file)

Function: m= VAL &rest VALS

Compares matrices against each other or a real, returning T if they are element-wise equal by =.

Package
Source

ops.lisp (file)

Function: m> VAL &rest VALS

Compares matrices against each other or a real, returning T if they are element-wise ordered by >.

Package
Source

ops.lisp (file)

Function: m>= VAL &rest VALS

Compares matrices against each other or a real, returning T if they are element-wise ordered by >=.

Package
Source

ops.lisp (file)

Computes the adjugate of the matrix.

For MAT2 MAT3 MAT4, inlined variants exist. For MATN, an algorithm based on the cofactors is used.

Package
Source

ops.lisp (file)

Function: mapply MAT OP

Applies the function to each element of the matrix and maps the result of it to a new matrix.

Package
Source

ops.lisp (file)

Function: mapplyf MAT OP

Applies the function to each element of the matrix and maps the result of it back into the matrix.

Package
Source

ops.lisp (file)

Function: marr MAT

Returns the backing array used by the matrix.

This should be a SIMPLE-VECTOR with the elements of type FLOAT-TYPE.

See MARR2
See MARR3
See MARR4
See MARRN

Package
Source

struct.lisp (file)

Function: marr2 INSTANCE

Direct accessor to the backing array of the MAT2.

Package
Source

struct.lisp (file)

Writer

(setf marr2) (function)

Function: (setf marr2) VALUE INSTANCE
Package
Source

struct.lisp (file)

marr2 (function)

Function: marr3 INSTANCE

Direct accessor to the backing array of the MAT3o.

Package
Source

struct.lisp (file)

Writer

(setf marr3) (function)

Function: (setf marr3) VALUE INSTANCE
Package
Source

struct.lisp (file)

marr3 (function)

Function: marr4 INSTANCE

Direct accessor to the backing array of the MAT4.

Package
Source

struct.lisp (file)

Writer

(setf marr4) (function)

Function: (setf marr4) VALUE INSTANCE
Package
Source

struct.lisp (file)

marr4 (function)

Function: marrn INSTANCE

Direct accessor to the backing array of the MATN.

Package
Source

struct.lisp (file)

Writer

(setf marrn) (function)

Function: (setf marrn) VALUE INSTANCE
Package
Source

struct.lisp (file)

marrn (function)

Function: mat &rest VALS

Constructs a fitting matrix for the number of elements given.

This only works for square numbers of elements, as otherwise it is not possible to guess what dimensions the matrix should have. In the case of a non-square number, an error is signalled.

See MAT2
See MAT3
See MAT4
See MATN

Package
Source

struct.lisp (file)

Function: mat-p MAT

Returns T if the given object is of type MAT.

See MAT2-P
See MAT3-P
See MAT4-P
See MATN-P

Package
Source

struct.lisp (file)

Function: mat2 &optional ELEMENTS

Constructs a MAT2 from the given elements.

ELEMENTS can be
NULL — The matrix is initialised with zeroes. REAL — The matrix is initialised with this number. SEQUENCE — The sequence is mapped into the matrix and the rest are initialised to 0.

Package
Source

struct.lisp (file)

Function: mat2-p OBJECT

Returns T if the given object is of type MAT2.

Package
Source

struct.lisp (file)

Function: mat3 &optional ELEMENTS

Constructs a MAT3 from the given elements.

ELEMENTS can be
NULL — The matrix is initialised with zeroes. REAL — The matrix is initialised with this number. SEQUENCE — The sequence is mapped into the matrix and the rest are initialised to 0.

Package
Source

struct.lisp (file)

Function: mat3-p OBJECT

Returns T if the given object is of type MAT3.

Package
Source

struct.lisp (file)

Function: mat4 &optional ELEMENTS

Constructs a MAT4 from the given elements.

ELEMENTS can be
NULL — The matrix is initialised with zeroes. REAL — The matrix is initialised with this number. SEQUENCE — The sequence is mapped into the matrix and the rest are initialised to 0.

Package
Source

struct.lisp (file)

Function: mat4-p OBJECT

Returns T if the given object is of type MAT4.

Package
Source

struct.lisp (file)

Function: matf MAT &rest VALS

Maps the VALs into the matrix.

The values will be mapped in row-major order.

Package
Source

struct.lisp (file)

Function: matn R C &optional ELEMENTS

Constructs a MATN of the requested size from the given elements.

ELEMENTS can be
NULL — The matrix is initialised with zeroes.
REAL — The matrix is initialised with this number. SEQUENCE — The sequence is mapped into the matrix
and the rest are initialised to 0.

Note that if R and C are both...
2 - A MAT2 is constructed
3 - A MAT3 is constructed
4 - A MAT4 is constructed

Package
Source

struct.lisp (file)

Function: matn-p OBJECT

Returns T if the given object is of type MATN.

Package
Source

struct.lisp (file)

Function: mblock M Y1 X1 Y2 X2

Returns the designated sub-matrix as a new matrix. Y1, X1 are the upper left corner, inclusive Y2, X2 are the lower right corner, exclusive

Package
Source

ops.lisp (file)

Function: mbottom M N

Returns the lowermost N rows as a new matrix.

Package
Source

ops.lisp (file)

Function: mcof M

Computes the cofactor matrix.

See MCOFACTOR

Package
Source

ops.lisp (file)

Function: mcofactor M Y X

Computes the cofactor at the specified index of the matrix.

This is just the element at the position multiplied by the minor.

See MMINOR

Package
Source

ops.lisp (file)

Function: mcol MAT N

Accesses the requested column as a vector of the appropriate size.

This only works for MAT2, MAT3, MAT4.

Package
Source

ops.lisp (file)

Writer

(setf mcol) (function)

Function: (setf mcol) VEC MAT N
Package
Source

ops.lisp (file)

mcol (function)

Function: mcols MAT

Returns the number of columns the matrix stores.

Package
Source

struct.lisp (file)

Function: mcopy M

Creates a full copy of the matrix.

See MCOPY2
See MCOPY3
See MCOPY4
See MCOPYN

Package
Source

struct.lisp (file)

Function: mcopy2 M2

Creates a full copy of the MAT2.

Package
Source

struct.lisp (file)

Function: mcopy3 M3

Creates a full copy of the MAT3.

Package
Source

struct.lisp (file)

Function: mcopy4 M4

Creates a full copy of the MAT4.

Package
Source

struct.lisp (file)

Function: mcopyn MN

Creates a full copy of the MATN.

Package
Source

struct.lisp (file)

Function: mcref MAT Y X

Returns the element at the given cell in the matrix.

See MCREF2
See MCREF3
See MCREF4
See MCREFN

Package
Source

struct.lisp (file)

Setf Expander

(setf mcref) (setf expander)

Setf Expander: (setf mcref) MAT Y X
Package
Source

struct.lisp (file)

mcref (function)

Function: mcref2 MAT Y X

Returns the element at the given cell in the MAT2.

Package
Source

struct.lisp (file)

Setf Expander

(setf mcref2) (setf expander)

Setf Expander: (setf mcref2) MAT Y X
Package
Source

struct.lisp (file)

mcref2 (function)

Function: mcref3 MAT Y X

Returns the element at the given cell in the MAT3.

Package
Source

struct.lisp (file)

Setf Expander

(setf mcref3) (setf expander)

Setf Expander: (setf mcref3) MAT Y X
Package
Source

struct.lisp (file)

mcref3 (function)

Function: mcref4 MAT Y X

Returns the element at the given cell in the MAT4.

Package
Source

struct.lisp (file)

Setf Expander

(setf mcref4) (setf expander)

Setf Expander: (setf mcref4) MAT Y X
Package
Source

struct.lisp (file)

mcref4 (function)

Function: mcrefn MAT Y X

Returns the element at the given cell in the MATN.

Package
Source

struct.lisp (file)

Setf Expander

(setf mcrefn) (setf expander)

Setf Expander: (setf mcrefn) MAT Y X
Package
Source

struct.lisp (file)

mcrefn (function)

Function: mdet M

Computes the determinant of the matrix.

For MAT2 MAT3 MAT4, inlined variants exist. For MATN, an algorithm based on LU factorisation is used.

Package
Source

ops.lisp (file)

Function: mdiag M

Returns the diagonal values of the matrix as a list.

Package
Source

ops.lisp (file)

Function: meigen M &optional ITERATIONS

Computes an approximation of the eigenvalues of the matrix.

An approach based on QR factorisation is used. The number of iterations dictates how many times the factorisation is repeated to make the result more accurate. Usually something around 50 iterations should give somewhat accurate results, but due to floating point limitations that may be off more significantly.

Returns the eigenvalues as a list.

Package
Source

ops.lisp (file)

Function: meye N

Constructs a square identity matrix of the requested size.

Package
Source

ops.lisp (file)

Function: mfrustum LEFT RIGHT BOTTOM TOP NEAR FAR

Returns a 3D frustum projection view matrix.

See MPERSPECTIVE

Package
Source

ops.lisp (file)

Function: minorm M

Computes the infinity norm of the matrix, namely the maximum of the sums of the rows.

Package
Source

ops.lisp (file)

Function: minv M

Computes the inverses of the matrix.

This is only possible if the determinant is non-zero.

For MAT2 MAT3 MAT4, inlined variants exist. For MATN, an algorithm based on the adjugate is used.

Package
Source

ops.lisp (file)

Function: miref MAT I

Returns the element at the given index in the matrix.

Elements are stored in row-major format.

See MIREF2
See MIREF3
See MIREF4
See MIREFN

Package
Source

struct.lisp (file)

Setf Expander

(setf miref) (setf expander)

Setf Expander: (setf miref) MAT I
Package
Source

struct.lisp (file)

miref (function)

Function: miref2 MAT I

Returns the element at the given index in the MAT2.

Elements are stored in row-major format.

Package
Source

struct.lisp (file)

Setf Expander

(setf miref2) (setf expander)

Setf Expander: (setf miref2) MAT I
Package
Source

struct.lisp (file)

miref2 (function)

Function: miref3 MAT I

Returns the element at the given index in the MAT3.

Elements are stored in row-major format.

Package
Source

struct.lisp (file)

Setf Expander

(setf miref3) (setf expander)

Setf Expander: (setf miref3) MAT I
Package
Source

struct.lisp (file)

miref3 (function)

Function: miref4 MAT I

Returns the element at the given index in the MAT4.

Elements are stored in row-major format.

Package
Source

struct.lisp (file)

Setf Expander

(setf miref4) (setf expander)

Setf Expander: (setf miref4) MAT I
Package
Source

struct.lisp (file)

miref4 (function)

Function: mirefn MAT I

Returns the element at the given index in the MATN.

Elements are stored in row-major format.

Package
Source

struct.lisp (file)

Setf Expander

(setf mirefn) (setf expander)

Setf Expander: (setf mirefn) MAT I
Package
Source

struct.lisp (file)

mirefn (function)

Function: mleft M N

Returns the leftmost N columns as a new matrix.

Package
Source

ops.lisp (file)

Function: mlookat EYE TARGET UP

Returns a view translation matrix that should "look at" TARGET from EYE where UP is the up vector.

Package
Source

ops.lisp (file)

Function: mlu M &optional PIVOT

Computes an LU factorisation of the matrix.

An approach based on Crout is used with on-the-fly pivotisation if requested.

Returns the combined LU matrix, the permutation matrix, and the number of permutations that were done.

Package
Source

ops.lisp (file)

Function: mminor M Y X

Computes the minor at the specified index of the matrix.

This basically calculates the determinant of the matrix with the row and column of the specified index excluded.

Package
Source

ops.lisp (file)

Function: mortho LEFT RIGHT BOTTOM TOP NEAR FAR

Returns a 3D orthographic projection view matrix.

Package
Source

ops.lisp (file)

Function: mperspective FOVY ASPECT NEAR FAR

Returns a 3D perspective projection view matrix.

FOVY – The field of view (how "zoomy" it is) ASPECT – The aspect ratio of the screen NEAR / FAR – The Z near and far clipping planes

See MFRUSTUM

Package
Source

ops.lisp (file)

Function: mpivot M

Attempts to do a partial pivotisation.

Returns the pivotised matrix, the permutation matrix, and the number of permutations that were done.

Package
Source

ops.lisp (file)

Function: mqr MAT

Computes the QR factorisation of the matrix.

An approach based on givens rotations is used.

Returns the Q and R matrices, which are fresh.

Package
Source

ops.lisp (file)

Function: mrand R C &key MIN MAX

Constructs a matrix of the requested size where each element is randomized.

MIN and MAX return the inclusive bounds of the numbers in the matrix.

Package
Source

ops.lisp (file)

Function: mright M N

Returns the rightmost N columns as a new matrix.

Package
Source

ops.lisp (file)

Function: mrotation V ANGLE

Returns a 3D rotation matrix for the given vector as a MAT4.

Package
Source

ops.lisp (file)

Function: mrow MAT N

Accesses the requested row as a vector of the appropriate size.

This only works for MAT2, MAT3, MAT4.

Package
Source

ops.lisp (file)

Writer

(setf mrow) (function)

Function: (setf mrow) VEC MAT N
Package
Source

ops.lisp (file)

mrow (function)

Function: mrows MAT

Returns the number of rows the matrix stores.

Package
Source

struct.lisp (file)

Function: mscaling V

Returns a 3D scaling matrix for the given vector as a MAT4.

Package
Source

ops.lisp (file)

Function: mtop M N

Returns the topmost N rows as a new matrix.

Package
Source

ops.lisp (file)

Function: mtrace M

Computes the trace of the matrix.

For MAT2 MAT3 MAT4, inlined variants exist. For MATN, a generic sum is used.

Package
Source

ops.lisp (file)

Function: mtranslation V

Returns a 3D translation matrix for the given vector as a MAT4.

Package
Source

ops.lisp (file)

Function: mtranspose M

Computes the transpose of the matrix.

For MAT2 MAT3 MAT4, inlined variants exist. For MATN, a generic swap is used.

Package
Source

ops.lisp (file)

Function: muniform R C ELEMENT

Constructs a matrix of the requested size where each element is initialised to the requested element.

Package
Source

ops.lisp (file)

Function: m~= VAL &rest VALS

Compares matrices against each other or a real, returning T if they are element-wise equal by ~=.

See ~=

Package
Source

ops.lisp (file)

Function: n*m VAL &rest VALS

Computes a modifying matrix multiplication, but modifying the right-hand side.

See NM*

Package
Source

ops.lisp (file)

Function: nm* VAL &rest VALS

Computes a modifying matrix multiplication.

If the other operand is a real, the matrix is multiplied with the real element-wise. If the other operand is a matrix, they are multiplied as per matrix multiplication. Note that this only works for square matrix against square matrix, as otherwise a size change would occur, which is not possible to do in a modifying variant. The two matrices must agree on the size as per matrix multiplication.
If the other operand is a vector, the vector is modified.

See N*M

Package
Source

ops.lisp (file)

Function: nm+ VAL &rest VALS

Computes the element-wise addition of the matrices or reals. Returns the first matrix, modified.

Package
Source

ops.lisp (file)

Function: nm- VAL &rest VALS

Computes the element-wise subtraction of the matrices or reals. Returns the first matrix, modified.

Package
Source

ops.lisp (file)

Function: nm/ VAL &rest VALS

Computes an element-wise division of the matrix from a real. Returns the modified, first matrix.

Package
Source

ops.lisp (file)

Function: nmlookat M EYE TARGET UP

Modifies the matrix to look at TARGET from the EYE.

See MLOOKAT.

Package
Source

ops.lisp (file)

Function: nmrotate M V ANGLE

Rotates the given matrix around the vector by angle. Returns the modified matrix.

Package
Source

ops.lisp (file)

Function: nmscale M V

Scales the given matrix by the vector. Returns the modified matrix.

Package
Source

ops.lisp (file)

Function: nmswap-col M K L

Modifies the matrix by swapping the Kth column with the Lth column.

Package
Source

ops.lisp (file)

Function: nmswap-row M K L

Modifies the matrix by swapping the Kth row with the Lth row.

Package
Source

ops.lisp (file)

Function: nmtranslate M V

Translates the given matrix by the vector. Returns the modified matrix.

Package
Source

ops.lisp (file)

Function: write-matrix M STREAM &key FORMAT

Writes the matrix in a certain format, by default a human-readable one.

FORMAT can be one of
:NICE - Prints it in a nice representation intended for humans. :WOLFRAM - Prints it in the format for Wolfram Alpha, namely {{a,b..},..} :ARRAY - Prints it as a common lisp 2D array.

If the STREAM is NIL, a string of the output is returned. Otherwise the matrix itself is returned.

Package
Source

struct.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.4 Structures

Structure: mat2 ()

The 2x2 matrix type.

Package
Source

struct.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods
• describe-object (method)
• print-object (method)
Direct slots
Slot: marr2
Type

(simple-array 3d-vectors::float-type (4))

marr2 (function)

Writers

(setf marr2) (function)

Structure: mat3 ()

The 3x3 matrix type.

Package
Source

struct.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods
• describe-object (method)
• print-object (method)
Direct slots
Slot: marr3
Type

(simple-array 3d-vectors::float-type (9))

marr3 (function)

Writers

(setf marr3) (function)

Structure: mat4 ()

The 4x4 matrix type.

Package
Source

struct.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods
• describe-object (method)
• print-object (method)
Direct slots
Slot: marr4
Type

(simple-array 3d-vectors::float-type (16))

marr4 (function)

Writers

(setf marr4) (function)

Structure: matn ()

The NxM matrix type.

Package
Source

struct.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods
• describe-object (method)
• print-object (method)
Direct slots
Slot: %rows
Type

3d-matrices::mat-dim

%rows (function)

Writers

(setf %rows) (function)

Slot: %cols
Type

3d-matrices::mat-dim

%cols (function)

Writers

(setf %cols) (function)

Slot: marrn
Type

(simple-array 3d-vectors::float-type)

marrn (function)

Writers

(setf marrn) (function)

Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.5 Types

Type: mat ()

Supertype for all matrix types.

See MAT2
See MAT3
See MAT4
See MATN

Package
Source

struct.lisp (file)

Previous: , Up: Definitions   [Contents][Index]

### 5.2 Internal definitions

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.1 Special variables

Special Variable: *eps*

The allowed divergence for ~= and m~= to succeed.

Package
Source

toolkit.lisp (file)

Special Variable: *matrix-limit*

The maximum extent of a matrix dimension.

This is set to either the square root of ARRAY-DIMENSION-LIMIT or the square root of MOST-POSITIVE-FIXNUM, whichever is smaller.

Package
Source

toolkit.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.2 Macros

Macro: %2mat*-expansion A B

Inner expansion to compute a proper matrix multiplication, which is non element-wise.

Package
Source

ops.lisp (file)

Macro: %2mat-op A B C M2 M3 M4 MNMN MNR

Macro for the handling of an operation for two matrices.

A B — Variables for the two matrices.
C — The function that combines an element from each matrix. M2 M3 M4 — The aggregator for the respective matrix type that combines the result of the combinator for each element of the matrix into one.
MNMN — The form to use to calculate a MATN MATN op.
MNR — The form to use to calculate a MATN REAL op.

Package
Source

ops.lisp (file)

Macro: %2mat/-expansion A B

Inner expansion to compute an element-wise matrix division.

Package
Source

ops.lisp (file)

Macro: %2n*mat-expansion A B

Inner expansion to compute a proper, modifying matrix multiplication on the right side.

Package
Source

ops.lisp (file)

Macro: %2nmat*-expansion A B &optional U

Inner expansion to compute a proper, modifying matrix multiplication, which is non element-wise.

Package
Source

ops.lisp (file)

Macro: %2nmat/-expansion A B &optional MC MN

Inner expansion to compute an element-wise, modifying matrix division.

Package
Source

ops.lisp (file)

Macro: %mka SIZE &key ELEMENT CONTENTS COERCION

Proper array construction helper.

Emits a form that returns a useable array for a matrix.

Package
Source

struct.lisp (file)

Macro: %proper-array SIZE ELEMENTS

Proper array constructor.

ELEMENTS can be
NULL — The initial element is set to 0.
REAL — The initial element is set to this. SEQUENCE — The array is mapped into with this sequence and the initial element is set to 0.

Package
Source

struct.lisp (file)

Macro: define-describe-matrix TYPE

Shorthand macro to define a describe-object method.

Package
Source

struct.lisp (file)

Macro: define-mat-accessor MTYPE MIREF MCREF MARR SIZE
Package
Source

struct.lisp (file)

Macro: define-matcomp NAME OP &optional COMB

Defines a matrix comparison function of NAME, using OP as the element-wise comparator.

COMB defines how the elements are combined together, usually by AND.

Package
Source

ops.lisp (file)

Macro: define-matop NAME NNAME OP &optional BODY

Defines a non-mutating matrix operation of NAME that delegates to NNAME for secondary calculations, and uses OP to combine elements.

If BODY is given, it is used for the 2MAT-case in place of a standard %2MAT-OP based approach.
Body will be called with two arguments, the A and B matrix of the combination.

A MATOP like this always returns a fresh matrix.

Package
Source

ops.lisp (file)

Macro: define-nmatop NAME OP &optional BODY

Defines a mutating matrix operation of NAME that uses OP to combine elements.

If BODY is given, it is used for the 2MAT-case in place of standard %2MAT-OP based approach. Body will be called with two arguments, the A and B matrix of the combination.

A MATOP like this always returns the modified, first matrix.

Package
Source

ops.lisp (file)

Macro: do-mat-diag (I EL MAT &optional RESULT) &body BODY

Iterates over the diagonal of the matrix.

Binds the diagonal index to the variable of I and the element at that place to the variable of EL.

Package
Source

iterate.lisp (file)

Macro: do-mat-index (I EL MAT &optional RESULT) &body BODY

Iterates over the indexes of the matrix.

Binds the row-major index to the variable of I and the element at that place to the variable of EL.

Package
Source

iterate.lisp (file)

Macro: with-floats BINDINGS &body BODY

Like LET, except ensuring that each value is of the appropriate float type.

Package
Source

toolkit.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.3 Functions

Function: %cols INSTANCE

Direct accessor to the number of columns in the MATN.

Package
Source

struct.lisp (file)

Writer

(setf %cols) (function)

Function: (setf %cols) VALUE INSTANCE
Package
Source

struct.lisp (file)

%cols (function)

Function: %mat2 MARR2

Direct constructor for the 2x2 matrix struct.

Package
Source

struct.lisp (file)

Function: %mat3 MARR3

Direct constructor for the 3x3 matrix struct.

Package
Source

struct.lisp (file)

Function: %mat4 MARR4

Direct constructor for the 4x4 matrix struct.

Package
Source

struct.lisp (file)

Function: %matn %ROWS %COLS MARRN

Direct constructor for the NxM matrix struct.

Package
Source

struct.lisp (file)

Function: %proper-array-form SIZE ELEMENTS

Returns a form that should construct a proper array for the given compile-time args.

Package
Source

struct.lisp (file)

Function: %rows INSTANCE

Direct accessor to the number of rows in the MATN.

Package
Source

struct.lisp (file)

Writer

(setf %rows) (function)

Function: (setf %rows) VALUE INSTANCE
Package
Source

struct.lisp (file)

%rows (function)

Function: 2mat-m* A B
Package
Source

ops.lisp (file)

Function: 2mat-m+ A B
Package
Source

ops.lisp (file)

Function: 2mat-m- A B
Package
Source

ops.lisp (file)

Function: 2mat-m/ A B
Package
Source

ops.lisp (file)

Function: 2mat-m/= A B
Package
Source

ops.lisp (file)

Function: 2mat-m< A B
Package
Source

ops.lisp (file)

Function: 2mat-m<= A B
Package
Source

ops.lisp (file)

Function: 2mat-m= A B
Package
Source

ops.lisp (file)

Function: 2mat-m> A B
Package
Source

ops.lisp (file)

Function: 2mat-m>= A B
Package
Source

ops.lisp (file)

Function: 2mat-m~= A B
Package
Source

ops.lisp (file)

Function: 2mat-n*m A B
Package
Source

ops.lisp (file)

Function: 2mat-nm* A B
Package
Source

ops.lisp (file)

Function: 2mat-nm+ A B
Package
Source

ops.lisp (file)

Function: 2mat-nm- A B
Package
Source

ops.lisp (file)

Function: 2mat-nm/ A B
Package
Source

ops.lisp (file)

Function: ensure-function FUNCTIONISH

If the argument is a symbol, it resolves it to a function by FDEFINITION.

Otherwise it can only be a function in which case it is returned verbatim.

Package
Source

toolkit.lisp (file)

Function: intern* &rest PARTS
Package
Source

toolkit.lisp (file)

Function: map-mat-diag FUNCTION MAT

Maps the diagonal of the matrix to the function.

The function receives two arguments: the index in the diagonal, and the element at that position of the matrix.

Package
Source

iterate.lisp (file)

Function: map-mat-index FUNCTION MAT

Maps the matrix by index to the function.

The function receives two arguments: the row-major index in the matrix, and the element at that position of the matrix.

Package
Source

iterate.lisp (file)

Function: mswap-col M K L

Returns a copy of the matrix with the columns swapped.

Package
Source

ops.lisp (file)

Function: mswap-row M K L

Returns a copy of the matrix with the rows swapped.

Package
Source

ops.lisp (file)

Function: ~= A B

Does "approximate comparison" by testing whether the two numbers are within *EPS* from each other.

Package
Source

toolkit.lisp (file)

Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.4 Types

Type: mat-dim ()

Concrete type for the allowed matrix dimension size.

Package
Source

toolkit.lisp (file)

Previous: , Up: Top   [Contents][Index]

## Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.1 Concepts

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.2 Functions

Jump to: %   (   2   ~   C   D   E   F   I   M   N   S   W
Jump to: %   (   2   ~   C   D   E   F   I   M   N   S   W

Next: , Previous: , Up: Indexes   [Contents][Index]