docs(matrices): add docstrings for most fns

thi-ng · Jan 20, 2019 · 08f7bd1 · 08f7bd1
1 parent 2aceab9
commit 08f7bd1
Show file tree

Hide file tree

Showing 37 changed files with 422 additions and 37 deletions.
diff --git a/packages/matrices/src/add.ts b/packages/matrices/src/add.ts
@@ -2,6 +2,16 @@ import { add as _add, add4 } from "@thi.ng/vectors3";
 import { MatOpMM, MultiMatOpMM } from "./api";
 import { defMath } from "./internal/codegen";
 
+/**
+ * Componentwise matrix addition. If `out` is not given, writes result
+ * in `a`.
+ *
+ * out = a + b
+ *
+ * @param out
+ * @param a
+ * @param b
+ */
 export const add: MultiMatOpMM = _add;
 export const add22: MatOpMM = add4;
 export const [add23, add33, add44] = defMath(add, "+");
diff --git a/packages/matrices/src/addn.ts b/packages/matrices/src/addn.ts
@@ -2,6 +2,16 @@ import { addN as _addN, addN4 } from "@thi.ng/vectors3";
 import { MatOpMN, MultiMatOpMN } from "./api";
 import { defMathN } from "./internal/codegen";
 
+/**
+ * Adds single scalar componentwise to matrix. If `out` is not given,
+ * writes result in `mat`.
+ *
+ * out = mat + n
+ *
+ * @param out
+ * @param mat
+ * @param n
+ */
 export const addN: MultiMatOpMN = _addN;
 export const addN22: MatOpMN = addN4;
 export const [addN23, addN33, addN44] = defMathN(addN, "+");
diff --git a/packages/matrices/src/alignment-quat.ts b/packages/matrices/src/alignment-quat.ts
@@ -7,6 +7,15 @@ import {
 } from "@thi.ng/vectors3";
 import { quatFromAxisAngle } from "./quat-axis-angle";
 
+/**
+ * Returns quaternion describing the rotation from direction vector
+ * `from` -> `to`. If `normalize` is true (default), first normalizes
+ * the vectors (not modifying original).
+ *
+ * @param from
+ * @param to
+ * @param normalize
+ */
 export const alignmentQuat =
     (from: ReadonlyVec, to: ReadonlyVec, normalize = true) => {
         if (normalize) {

diff --git a/packages/matrices/src/column.ts b/packages/matrices/src/column.ts
@@ -6,6 +6,14 @@ import {
 } from "@thi.ng/vectors3";
 import { MultiVecOpMN, VecOpMN } from "./api";
 
+/**
+ * Extracts column vector from given matrix and writes result to `out`.
+ * If `out` is null, creates new vector.
+ *
+ * @param out
+ * @param mat
+ * @param column
+ */
 export const column: MultiVecOpMN = vop(1);
 
 export const column22: VecOpMN =

diff --git a/packages/matrices/src/concat.ts b/packages/matrices/src/concat.ts
@@ -1,6 +1,16 @@
 import { Mat, ReadonlyMat } from "./api";
 import { mulM } from "./mulm";
 
+/**
+ * Concatenates / multiplies given matrices in left-to-right order. A
+ * minimum of 2 input matrices must be given. If `out` is null, writes
+ * result into `a`.
+ *
+ * @param out
+ * @param a
+ * @param b
+ * @param xs
+ */
 export const concat =
     (out: Mat, a: ReadonlyMat, b: ReadonlyMat, ...xs: ReadonlyMat[]) =>
         xs.reduce(

diff --git a/packages/matrices/src/conjugate.ts b/packages/matrices/src/conjugate.ts
@@ -9,5 +9,3 @@ export const conjugateQ =
             -a[2],
             a[3]
         );
-
-
diff --git a/packages/matrices/src/diag.ts b/packages/matrices/src/diag.ts
@@ -1,6 +1,12 @@
 import { vop, setS2, setS3, setS4 } from "@thi.ng/vectors3";
 import { MultiVecOpM } from "./api";
 
+/**
+ * Extracts matrix diagonal into `out`.
+ *
+ * @param out
+ * @param mat
+ */
 export const diag: MultiVecOpM = vop(1);
 
 export const diag22 =

diff --git a/packages/matrices/src/div.ts b/packages/matrices/src/div.ts
@@ -2,6 +2,16 @@ import { div as _div, div4 } from "@thi.ng/vectors3";
 import { MatOpMM, MultiMatOpMM } from "./api";
 import { defMath } from "./internal/codegen";
 
+/**
+ * Componentwise matrix division. If `out` is not given, writes result
+ * in `a`.
+ *
+ * out = a / b
+ *
+ * @param out
+ * @param a
+ * @param b
+ */
 export const div: MultiMatOpMM = _div;
 export const div22: MatOpMM = div4;
 export const [div23, div33, div44] = defMath(div, "/");
diff --git a/packages/matrices/src/divn.ts b/packages/matrices/src/divn.ts
@@ -2,6 +2,16 @@ import { divN as _divN, divN4 } from "@thi.ng/vectors3";
 import { MatOpMN, MultiMatOpMN } from "./api";
 import { defMathN } from "./internal/codegen";
 
+/**
+ * Componentwise matrix division by single scalar. If `out` is not
+ * given, writes result in `mat`.
+ *
+ * out = mat / n
+ *
+ * @param out
+ * @param mat
+ * @param n
+ */
 export const divN: MultiMatOpMN = _divN;
 export const divN22: MatOpMN = divN4;
 export const [divN23, divN33, divN44] = defMathN(divN, "/");
diff --git a/packages/matrices/src/frustum.ts b/packages/matrices/src/frustum.ts
@@ -2,6 +2,17 @@ import { DEG2RAD } from "@thi.ng/math";
 import { setC } from "@thi.ng/vectors3";
 import { Mat } from "./api";
 
+/**
+ * Constructs a M44 representing the given view frustum.
+ *
+ * @param out
+ * @param left
+ * @param right
+ * @param bottom
+ * @param top
+ * @param near
+ * @param far
+ */
 export const frustum = (
     out: Mat,
     left: number,

diff --git a/packages/matrices/src/identity.ts b/packages/matrices/src/identity.ts
@@ -8,6 +8,9 @@ import {
 } from "./api";
 import { set } from "./set";
 
+/**
+ * Writes identity matrix into given matrix.
+ */
 export const identity: MultiMatOp1 = vop();
 
 export const identity22 =

diff --git a/packages/matrices/src/index.ts b/packages/matrices/src/index.ts
@@ -15,6 +15,9 @@ export * from "./frustum";
 export * from "./identity";
 export * from "./invert";
 export * from "./lookat";
+export * from "./m22-m23";
+export * from "./m23-m22";
+export * from "./m23-m44";
 export * from "./m33-m44";
 export * from "./m44-m33";
 export * from "./mixq";

diff --git a/packages/matrices/src/invert.ts b/packages/matrices/src/invert.ts
@@ -15,6 +15,9 @@ import { det44FromCoeffs, detCoeffs44 } from "./determinant";
 const dp4 = dotC4;
 const dp6 = dotC6;
 
+/**
+ * Matrix inversion.
+ */
 export const invert: MultiMatOpM = vop(1);
 
 export const invert22: MatOpM =

diff --git a/packages/matrices/src/lookat.ts b/packages/matrices/src/lookat.ts
@@ -8,6 +8,15 @@ import {
 } from "@thi.ng/vectors3";
 import { Mat } from "./api";
 
+/**
+ * Constructs a M44 camera matrix for given `eye` position, look-at `target`
+ * (both in world space) and `up` vector.
+ *
+ * @param out
+ * @param eye
+ * @param target
+ * @param up
+ */
 export const lookAt = (
     out: Mat,
     eye: ReadonlyVec,

diff --git a/packages/matrices/src/m33-m44.ts b/packages/matrices/src/m33-m44.ts
@@ -1,12 +1,18 @@
 import { setS3, setS4, ZERO4 } from "@thi.ng/vectors3";
 import { MatOpM } from "./api";
 
+/**
+ * Converts M33 to M44 and writes result to `out`.
+ *
+ * @param out
+ * @param m33
+ */
 export const mat33to44: MatOpM =
-    (m44, m33) => (
-        !m44 && (m44 = []),
-        setS3(m44, m33, 0, 0),
-        setS3(m44, m33, 4, 3),
-        setS3(m44, m33, 8, 6),
-        setS3(m44, ZERO4, 12),
-        setS4(m44, [0, 0, 0, 1], 3, 0, 4)
+    (out, m33) => (
+        !out && (out = []),
+        setS3(out, m33, 0, 0),
+        setS3(out, m33, 4, 3),
+        setS3(out, m33, 8, 6),
+        setS3(out, ZERO4, 12),
+        setS4(out, [0, 0, 0, 1], 3, 0, 4)
     );
diff --git a/packages/matrices/src/m44-m33.ts b/packages/matrices/src/m44-m33.ts
@@ -1,10 +1,16 @@
 import { setS3 } from "@thi.ng/vectors3";
 import { MatOpM } from "./api";
 
+/**
+ * Converts M44 to M33 and writes result to `out`.
+ *
+ * @param out
+ * @param m44
+ */
 export const mat44to33: MatOpM =
-    (m33, m44) => (
-        !m33 && (m33 = []),
-        setS3(m33, m44),
-        setS3(m33, m44, 3, 4),
-        setS3(m33, m44, 6, 8)
+    (out, m44) => (
+        !out && (out = []),
+        setS3(out, m44),
+        setS3(out, m44, 3, 4),
+        setS3(out, m44, 6, 8)
     );
diff --git a/packages/matrices/src/mixq.ts b/packages/matrices/src/mixq.ts
@@ -7,6 +7,18 @@ import {
     Vec
 } from "@thi.ng/vectors3";
 
+/**
+ * Interpolates quaternion `a` to `b` by given amount `t`, using SLERP.
+ * Writes result to `out`. The optional `eps` (default 1e-3) is used to
+ * switch to linear interpolation if the angular difference is very
+ * small.
+ *
+ * @param out
+ * @param a
+ * @param b
+ * @param t
+ * @param eps
+ */
 export const mixQ =
     (out: Vec, a: ReadonlyVec, b: ReadonlyVec, t: number, eps = 1e-3) => {
         const d = dot4(a, b);

diff --git a/packages/matrices/src/mul.ts b/packages/matrices/src/mul.ts
@@ -2,6 +2,16 @@ import { mul as _mul, mul4 } from "@thi.ng/vectors3";
 import { MatOpMM, MultiMatOpMM } from "./api";
 import { defMath } from "./internal/codegen";
 
+/**
+ * Componentwise matrix addition. Use `mulM` for actual matrix-matrix
+ * multiplication. If `out` is not given, writes result in `a`.
+ *
+ * out = a * b
+ *
+ * @param out
+ * @param a
+ * @param b
+ */
 export const mul: MultiMatOpMM = _mul;
 export const mul22: MatOpMM = mul4;
 export const [mul23, mul33, mul44] = defMath(mul, "*");
diff --git a/packages/matrices/src/mulm.ts b/packages/matrices/src/mulm.ts
@@ -9,6 +9,14 @@ import {
 } from "@thi.ng/vectors3";
 import { MultiMatOpMM } from "./api";
 
+/**
+ * Performs matrix-matrix multiplication. If `out` is not given, writes
+ * result in `a`.
+ *
+ * @param out
+ * @param a
+ * @param b
+ */
 export const mulM: MultiMatOpMM = vop(1);
 
 export const mulM22 =

diff --git a/packages/matrices/src/muln.ts b/packages/matrices/src/muln.ts
@@ -2,6 +2,16 @@ import { mulN as _mulN, mulN4 } from "@thi.ng/vectors3";
 import { MatOpMN, MultiMatOpMN } from "./api";
 import { defMathN } from "./internal/codegen";
 
+/**
+ * Multiplies matrix componentwise with single scalar. If `out` is not
+ * given, writes result in `mat`.
+ *
+ * out = mat * n
+ *
+ * @param out
+ * @param mat
+ * @param n
+ */
 export const mulN: MultiMatOpMN = _mulN;
 export const mulN22: MatOpMN = mulN4;
 export const [mulN23, mulN33, mulN44] = defMathN(mulN, "*");
diff --git a/packages/matrices/src/mulq.ts b/packages/matrices/src/mulq.ts
@@ -1,5 +1,13 @@
 import { ReadonlyVec, setC4, Vec } from "@thi.ng/vectors3";
 
+/**
+ * Performs quaternion multiplication of `a` and `b` and writes result
+ * to `out`. If `out` is null, writes result into `a`.
+ *
+ * @param out
+ * @param a
+ * @param b
+ */
 export const mulQ =
     (out: Vec, a: ReadonlyVec, b: ReadonlyVec) => {
         const { 0: ax, 1: ay, 2: az, 3: aw } = a;

diff --git a/packages/matrices/src/mulv.ts b/packages/matrices/src/mulv.ts
@@ -117,13 +117,13 @@ export const mulV344: MatOpMV =
  * vector or modifies in-place if `out` is null or `v`.
  *
  * @param out
- * @param quat
+ * @param q
  * @param v
  */
 export const mulVQ =
-    (out: Vec, quat: ReadonlyVec, v: ReadonlyVec) => {
+    (out: Vec, q: ReadonlyVec, v: ReadonlyVec) => {
         const { 0: px, 1: py, 2: pz } = v;
-        const { 0: qx, 1: qy, 2: qz, 3: qw } = quat;
+        const { 0: qx, 1: qy, 2: qz, 3: qw } = q;
         const ix = qw * px + qy * pz - qz * py;
         const iy = qw * py + qz * px - qx * pz;
         const iz = qw * pz + qx * py - qy * px;

diff --git a/packages/matrices/src/ortho.ts b/packages/matrices/src/ortho.ts
@@ -1,6 +1,18 @@
 import { setC } from "@thi.ng/vectors3";
 import { Mat } from "./api";
 
+/**
+ * Computes a M44 orthographic projection matrix and writes result to
+ * `out`.
+ *
+ * @param out
+ * @param left
+ * @param right
+ * @param bottom
+ * @param top
+ * @param near
+ * @param far
+ */
 export const ortho = (
     out: Mat,
     left: number,

diff --git a/packages/matrices/src/perspective.ts b/packages/matrices/src/perspective.ts
@@ -1,6 +1,16 @@
 import { Mat } from "./api";
 import { frustum, frustumBounds } from "./frustum";
 
+/**
+ * Computes a M44 perspective projection matrix and writes result to
+ * `out`.
+ *
+ * @param out
+ * @param fov
+ * @param aspect
+ * @param near
+ * @param far
+ */
 export const perspective = (
     out: Mat,
     fov: number,
Original file line number	Diff line number	Diff line change
Expand Up		@@ -9,5 +9,3 @@ export const conjugateQ =
		-a[2],
		a[3]
		);