6.6 - A Matrix Library - `GlMatrix4x4`¶

Fundamental to all 3D computer graphics is the 4x4 matrix transform. In the original OpenGL API, all basic transformations were implemented for you in the library’s code. All you had to do was call the correct function in the correct order. WebGL was implemented for low power mobile devices with limited CPU and GPU functionality. Transformation matrix functionality was not included in the WebGL API. Therefore, you have to implement your own matrix operations in JavaScript. But it doesn’t make sense for individual programmers to “re-invent the wheel”. This lesson presents you with a JavaScript matrix library and explains how to use it.

WebGL Transformation Matrices¶

A WebGL, 4x4, transformation matrix is a 1D array of type Float32Array which contains 16 floating point values. The values represent a 2D array that are stored in column-major order. (Back in the 1960’s, Fortran stored 2-dimensional data in column-major order. That convention has propagated to various system still in use today, including OpenGL. Most modern programming languages use row-major order.)

The 4x4 transformation matrix:

0
4
8
12
1
5
9
13
2
6
10
14
3
7
11
15
Eq1

would be created in JavaScript code like this:

var matrix = new Float32Array([0,4,8,12, 1,5,9,13, 2,6,10,14, 3,7,11,15]);
// Or
var m = new Float32Array(16);
m[0] =  0;  m[4] =  1;  m[ 8] =  2;  m[12] = 3;
m[1] =  4;  m[5] =  5;  m[ 9] =  6;  m[13] = 7;
m[2] =  8;  m[6] =  9;  m[10] = 10;  m[14] = 11;
m[3] = 12;  m[7] = 13;  m[11] = 14;  m[15] = 15;

In most cases the 2^nd example above is used because it is easier to debug the code if you can visualize the data values as a 2D array.

Note: If you re-format the matrix library code you will lose the “multiple statements per line” formatting which helps to visualize the 4x4 matrices. It is recommended that you do not re-format this code file.

Design Decisions for a Matrix Library¶

A typical class definition defines a set of data and a set of functions that act on that data. One of the important ideas behind classes is the encapsulation and protection of a set of data values inside an instance of the class. We don’t really need data protection for our matrix library. What we need is encapsulation of the functionality of matrix operations so that we can minimize the creation and deletion of scratch arrays that are needed for matrix processing. Consider that an animation requires the rendering of a scene at least 30 times per second. If you are constantly creating new object instances every time you render, you will be creating a lot of objects. JavaScript does dynamic memory garbage collection, so many programmers simply ignore memory issues. But if you can minimize the creation of new objects for each rendering, your animations have the potential to run more smoothly.

The `GlMatrix4x4` Class¶

A class called GlMatrix4x4 is defined in a file named glmatrix4x4.js. It encapsulates the matrix functionality we need to produce WebGL renderings. A GlMatrix4x4 object does not store a matrix. It encapsulates matrix functionality and the scratch arrays needed for that functionality. And, by separating matrix functionality from matrix data, the syntax of the code is simplified.

You can typically create one instance of the library and use it for your entire program. The library contains functions that:

create transforms,
set the values of a specific type of transform, and
perform matrix operations.

A matrix transform is stored as a Float32Array. Four functions in an GlMatrix4x4 object create and return new transforms and their names all start with create. These functions should not be called in your rendering code for every animation frame. They should be called once in your setup code to create any transforms you need during rendering. The four functions that create a new matrix transform are:

create(), which creates and returns a new 4x4 transformation matrix.
createOrthographic(), which creates a new orthographic projection transformation matrix.
createPerspective(), which creates a new perspective projection transformation matrix.
createFrustum(), which creates a new perspective projection transformation matrix.

Functions that set the values of a transformation matrix must send a transformation matrix as the first parameter. For example:

scale(M, sx, sy, sz) sets M to a scale transform.
translate(M, tx, ty, tz) sets M to a translation transform.
rotate(M, angle, x_axis, y_axis, z_axis) sets M to a rotation transform.

Functions that perform matrix calculations change the value of their first parameter, while leaving all of the other parameters unchanged. The parameters are ordered similar to assignment statements which always change their left-hand side variable, but leave all value on the right-hand-side of an assignment statement unchanged. For example:

multiply(R, A, B) sets R to the product of A times B. (R = A*B)

The function multiplySeries() will multiply any number of matrices together to produce a single transformation matrix. It uses variable arguments and will accept as many arguments as you send it. For example, m.multiplySeries(R,A,B,C,D,E) will calculate the matrix product of A*B*C*D*E and store the result in R. In equation format, it performs R = A*B*C*D*E;. The order of the multiplications is critical. If the transform R is applied to a set of vertices, the effect of R would be that

transform E was applied to a vertex,
then transform D was applied to the transformed vertex,
then transform C was applied to the transformed vertex,
then transform B was applied to the transformed vertex, and
finally transform A was applied to the transformed vertex.

When you create a single transform from multiple transforms, you must always order the transformations from right to left.

The GlMatrix4x4 Code¶

The WebGL program below displays the GlMatrix4x4 class code. Please study the GlMatrix4x4 class to get familiar with its matrix functionality. (Hide the canvas to better review the code.) The translate_scene.js code demonstrates how to use the matrix functionality in a WebGL program. Notice that the creation of all matrices is done once in the scene’s constructor. The matrices are then used repeatedly in the scene’s rendering function. Since there are no new objects created for each rendering, garage collection is minimized.

Show: Code Canvas Run Info

glmatrix4x4.js
translate_scene.js

/**
 * glmatrix4x4.js, By Wayne Brown, Fall 2017
 *
 * glmatrix4x4 is a set of functions that perform standard operations
 * on 4x4 transformation matrices.
 *
 * The 4x4 matrices are stored in column-major order using an array of 32-bit
 * floating point numbers, which is the format required by WebGL programs.
 *
 * The functions do not create new objects because in real-time graphics,
 * creating new objects slows things down.
 *
 * Function parameters are ordered in the same order an equivalent
 * assignment statements. For example, R = A*B, has parameters (R, A, B).
 * All matrix parameters use capital letters.
 *
 * The functions are defined inside an object to prevent pollution of
 * JavaScript's global address space. The functions contain no validation
 * of parameters, which makes them more efficient at run-time.
 */

/**
 * The MIT License (MIT)
 *
 * Copyright (c) 2017 C. Wayne Brown
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

// Do not perform code-formatting on this code. It destroys the matrix formatting.
//@formatter:off

"use strict";

/**
 * An object that contains matrix transformation functionality.
 * @constructor Create an instance of the GlMatrix4x4 class.
 */
window.GlMatrix4x4 = function () {

let self = this;

/** -----------------------------------------------------------------
   * Create a 4x4 transformation matrix.
   * @return {Float32Array} returns an uninitialized array of 16 floats.
   */
  self.create = function () {
    return new Float32Array(16);
  };

// Temporary matrices and vectors for calculations. They are reused to
  // prevent new objects from being constantly re-created and then garbage
  // collected.
  let T1, T2, V, v3, P, p4, axis_of_rotation, u, v, n, center, eye, up;

// Temporary matrices for matrix multiplications
  T1 = self.create();
  T2 = self.create();

// Temporary vectors
  V = new GlVector3();
  u = V.create();
  v = V.create();
  n = V.create();
  center = V.create();
  eye = V.create();
  up = V.create();
  v3 = V.create();
  axis_of_rotation = V.create();

// Temporary point
  P = new GlPoint4();
  p4 = P.create();

/** -----------------------------------------------------------------
   * M = I (identity Matrix)
   */
  self.setIdentity = function (M) {
    M[0] = 1;  M[4] = 0;  M[8]  = 0; M[12] = 0;
    M[1] = 0;  M[5] = 1;  M[9]  = 0; M[13] = 0;
    M[2] = 0;  M[6] = 0;  M[10] = 1; M[14] = 0;
    M[3] = 0;  M[7] = 0;  M[11] = 0; M[15] = 1;
  };

/** -----------------------------------------------------------------
   * @param angleInDegrees {number}
   * @return {number} Convert the input angle in degrees to radians
   */
  self.toRadians = function (angleInDegrees) {
    return angleInDegrees * 0.017453292519943295;  // Math.PI / 180
  };

/** -----------------------------------------------------------------
   * @param angleInRadians {number}
   * @return {number} Convert the input angle in radians to degrees
   */
  self.toDegrees = function (angleInRadians) {
    return angleInRadians * 57.29577951308232;  // 180 / Math.PI
  };

/** -----------------------------------------------------------------
   * To = From (an element-by-element copy)
   * @param To {Float32Array} destination matrix
   * @param From {Float32Array} source matrix
   * @return To {Float32Array} a 16 element Float32Array
   */
  self.copy = function (To, From) {
    for (let j = 0; j < 16; j += 1) {
      To[j] = From[j];
    }
    return To;
  };

/** -----------------------------------------------------------------
   * R = A * B (Matrix Multiplication); NOTE: order matters!
   * @param R {Float32Array} matrix which will contain the result
   * @param A {Float32Array} matrix
   * @param B {Float32Array} matrix
   */
  self.multiply = function (R, A, B) {
    // A and B can't change during the operation.
    // If R is the same as A and/or B, Make copies of A and B
    // The comparison must use ==, not ===. We are comparing for identical
    // objects, not if two objects might have the same values.
    if (A == R) {
      A = self.copy(T1, A);
    }
    if (B == R) {
      B = self.copy(T2, B);
    }

R[0]  = A[0] * B[0]  + A[4] * B[1]  + A[8]  * B[2]  + A[12] * B[3];
    R[1]  = A[1] * B[0]  + A[5] * B[1]  + A[9]  * B[2]  + A[13] * B[3];
    R[2]  = A[2] * B[0]  + A[6] * B[1]  + A[10] * B[2]  + A[14] * B[3];
    R[3]  = A[3] * B[0]  + A[7] * B[1]  + A[11] * B[2]  + A[15] * B[3];

R[4]  = A[0] * B[4]  + A[4] * B[5]  + A[8]  * B[6]  + A[12] * B[7];
    R[5]  = A[1] * B[4]  + A[5] * B[5]  + A[9]  * B[6]  + A[13] * B[7];
    R[6]  = A[2] * B[4]  + A[6] * B[5]  + A[10] * B[6]  + A[14] * B[7];
    R[7]  = A[3] * B[4]  + A[7] * B[5]  + A[11] * B[6]  + A[15] * B[7];

R[8]  = A[0] * B[8]  + A[4] * B[9]  + A[8]  * B[10] + A[12] * B[11];
    R[9]  = A[1] * B[8]  + A[5] * B[9]  + A[9]  * B[10] + A[13] * B[11];
    R[10] = A[2] * B[8]  + A[6] * B[9]  + A[10] * B[10] + A[14] * B[11];
    R[11] = A[3] * B[8]  + A[7] * B[9]  + A[11] * B[10] + A[15] * B[11];

R[12] = A[0] * B[12] + A[4] * B[13] + A[8]  * B[14] + A[12] * B[15];
    R[13] = A[1] * B[12] + A[5] * B[13] + A[9]  * B[14] + A[13] * B[15];
    R[14] = A[2] * B[12] + A[6] * B[13] + A[10] * B[14] + A[14] * B[15];
    R[15] = A[3] * B[12] + A[7] * B[13] + A[11] * B[14] + A[15] * B[15];
  };

/** -----------------------------------------------------------------
   * R = A * B * C * D ... (Matrix Multiplication); NOTE: order matters!
   */
  self.multiplySeries = function () {
    if (arguments.length >= 3) {
      self.multiply(arguments[0], arguments[1], arguments[2]);
      for (let j = 3; j < arguments.length; j += 1) {
        self.multiply(arguments[0], arguments[0], arguments[j]);
      }
    }
  };

/** -----------------------------------------------------------------
   * r = M * v (M is a 4x4 matrix, v is a 3-component vector)
   * @param r {Float32Array} a 3-component vector
   * @param M {Float32Array} a 4x4 matrix
   * @param v {Float32Array} a 3-component vector
   */
  self.multiplyV3 = function (r, M, v) {

// v can't change during the operation. If r and v are the same, make a copy of v
    if (r == v) {
      v = V.copy(v3, v);
    }

r[0] = M[0] * v[0] + M[4] * v[1] + M[8]  * v[2];
    r[1] = M[1] * v[0] + M[5] * v[1] + M[9]  * v[2];
    r[2] = M[2] * v[0] + M[6] * v[1] + M[10] * v[2];
  };

/** -----------------------------------------------------------------
   * r = M * p (M is a 4x4 matrix, p is a 4-component point)
   * @param r {Float32Array} a 4-component point
   * @param M {Float32Array} a 4x4 matrix
   * @param p {Float32Array} a 4-component point
   */
  self.multiplyP4 = function (r, M, p) {

// p can't change during the operation, so make a copy of p.
    P.copy(p4, p);

r[0] = M[0] * p4[0] + M[4] * p4[1] + M[8]  * p4[2] + M[12] * p4[3];
    r[1] = M[1] * p4[0] + M[5] * p4[1] + M[9]  * p4[2] + M[13] * p4[3];
    r[2] = M[2] * p4[0] + M[6] * p4[1] + M[10] * p4[2] + M[14] * p4[3];
    r[3] = M[3] * p4[0] + M[7] * p4[1] + M[11] * p4[2] + M[15] * p4[3];
  };

/** -----------------------------------------------------------------
   * Console.log(name, M)
   * @param name {string} a label for the output
   * @param M {Float32Array} a 4x4 matrix
   */
  self.print = function (name, M) {
    let fieldSize = 11;
    let numText;
    let rowText, number;
    console.log(name + ":");
    for (let row = 0; row < 4; row += 1) {
      rowText = "";
      for (let offset = 0; offset < 16; offset += 4) {
        number = Number(M[row + offset]);
        numText = number.toFixed(4);
        rowText += new Array(fieldSize - numText.length).join(" ") + numText;
      }
      console.log(rowText);
    }
  };

/** -----------------------------------------------------------------
   * M = M' (transpose the matrix)
   * @param M {Float32Array} a 4x4 matrix
   */
  self.transpose = function (M) {
    let t;

// The diagonal values don't move; 6 non-diagonal elements are swapped.
    t = M[1];  M[1]  = M[4];  M[4]  = t;
    t = M[2];  M[2]  = M[8];  M[8]  = t;
    t = M[3];  M[3]  = M[12]; M[12] = t;
    t = M[6];  M[6]  = M[9];  M[9]  = t;
    t = M[7];  M[7]  = M[13]; M[13] = t;
    t = M[11]; M[11] = M[14]; M[14] = t;
  };

/** -----------------------------------------------------------------
   * Inv = M(-1) (Inv is set to the inverse of M)
   * @param Inv {Float32Array} a 4x4 matrix, the results of the inverse.
   * @param M {Float32Array} a 4x4 matrix
   */
  self.inverse = function (Inv, M) {
    /* Structure of matrix

0   1   2   3
        ______________
     0 | 0   4   8  12
     1 | 1   5   9  13
     2 | 2   6  10  14
     3 | 3   7  11  15
    */

// Factored out common terms
    let t9_14_13_10 = M[9]  * M[14] - M[13] * M[10];
    let t13_6_5_14  = M[13] * M[6]  - M[5]  * M[14];
    let t5_10_9_6   = M[5]  * M[10] - M[9]  * M[6];
    let t12_10_8_14 = M[12] * M[10] - M[8]  * M[14];
    let t4_14_12_6  = M[4]  * M[14] - M[12] * M[6];
    let t8_6_4_10   = M[8]  * M[6]  - M[4]  * M[10];
    let t8_13_12_9  = M[8]  * M[13] - M[12] * M[9];
    let t12_5_4_13  = M[12] * M[5]  - M[4]  * M[13];
    let t4_9_8_5    = M[4]  * M[9]  - M[8]  * M[5];
    let t1_14_13_2  = M[1]  * M[14] - M[13] * M[2];
    let t9_2_1_10   = M[9]  * M[2]  - M[1]  * M[10];
    let t12_2_0_14  = M[12] * M[2]  - M[0]  * M[14];
    let t0_10_8_2   = M[0]  * M[10] - M[8]  * M[2];
    let t0_13_12_1  = M[0]  * M[13] - M[12] * M[1];
    let t8_1_0_9    = M[8]  * M[1]  - M[0]  * M[9];
    let t1_6_5_2    = M[1]  * M[6]  - M[5]  * M[2];
    let t4_2_0_6    = M[4]  * M[2]  - M[0]  * M[6];
    let t0_5_4_1    = M[0]  * M[5]  - M[4]  * M[1];

Inv[0]  = M[7] *  t9_14_13_10 + M[11] *  t13_6_5_14 + M[15] *  t5_10_9_6;
    Inv[4]  = M[7] *  t12_10_8_14 + M[11] *  t4_14_12_6 + M[15] *  t8_6_4_10;
    Inv[8]  = M[7] *  t8_13_12_9  + M[11] *  t12_5_4_13 + M[15] *  t4_9_8_5;
    Inv[12] = M[6] * -t8_13_12_9  + M[10] * -t12_5_4_13 + M[14] * -t4_9_8_5;
    Inv[1]  = M[3] * -t9_14_13_10 + M[11] *  t1_14_13_2 + M[15] *  t9_2_1_10;
    Inv[5]  = M[3] * -t12_10_8_14 + M[11] *  t12_2_0_14 + M[15] *  t0_10_8_2;
    Inv[9]  = M[3] * -t8_13_12_9  + M[11] *  t0_13_12_1 + M[15] *  t8_1_0_9;
    Inv[13] = M[2] *  t8_13_12_9  + M[10] * -t0_13_12_1 + M[14] * -t8_1_0_9;
    Inv[2]  = M[3] * -t13_6_5_14  + M[7]  * -t1_14_13_2 + M[15] *  t1_6_5_2;
    Inv[6]  = M[3] * -t4_14_12_6  + M[7]  * -t12_2_0_14 + M[15] *  t4_2_0_6;
    Inv[10] = M[3] * -t12_5_4_13  + M[7]  * -t0_13_12_1 + M[15] *  t0_5_4_1;
    Inv[14] = M[2] *  t12_5_4_13  + M[6]  *  t0_13_12_1 + M[14] * -t0_5_4_1;
    Inv[3]  = M[3] * -t5_10_9_6   + M[7]  * -t9_2_1_10  + M[11] * -t1_6_5_2;
    Inv[7]  = M[3] * -t8_6_4_10   + M[7]  * -t0_10_8_2  + M[11] * -t4_2_0_6;
    Inv[11] = M[3] * -t4_9_8_5    + M[7]  * -t8_1_0_9   + M[11] * -t0_5_4_1;
    Inv[15] = M[2] *  t4_9_8_5    + M[6]  *  t8_1_0_9   + M[10] *  t0_5_4_1;

let det;
    det =
        M[3]  * (M[6] * -t8_13_12_9 + M[10] * -t12_5_4_13 + M[14] * -t4_9_8_5) +
        M[7]  * (M[2] *  t8_13_12_9 + M[10] * -t0_13_12_1 + M[14] * -t8_1_0_9) +
        M[11] * (M[2] *  t12_5_4_13 + M[6]  *  t0_13_12_1 + M[14] * -t0_5_4_1) +
        M[15] * (M[2] *  t4_9_8_5   + M[6]  *  t8_1_0_9   + M[10] *  t0_5_4_1);

if (det !== 0) {
      let scale = 1 / det;
      for (let j = 0; j < 16; j += 1) {
        Inv[j] = Inv[j] * scale;
      }
    }
  };

/** -----------------------------------------------------------------
   * Create an orthographic projection matrix.
   * @param M {Float32Array} 4x4 transformation matrix
   * @param left   {Number} Farthest left on the x-axis
   * @param right  {Number} Farthest right on the x-axis
   * @param bottom {Number} Farthest down on the y-axis
   * @param top    {Number} Farthest up on the y-axis
   * @param near   {Number} Distance to the near clipping plane along the -Z axis
   * @param far    {Number} Distance to the far clipping plane along the -Z axis
   * @return {Float32Array} The orthographic transformation matrix
   */
  self.orthographic = function (M, left, right, bottom, top, near, far) {

// Make sure there is no division by zero
    if (left === right || bottom === top || near === far) {
      console.log("Invalid createOrthographic parameters");
      self.setIdentity(M);
    }

let widthRatio  = 1.0 / (right - left);
    let heightRatio = 1.0 / (top - bottom);
    let depthRatio  = 1.0 / (far - near);

let sx =  2 * widthRatio;
    let sy =  2 * heightRatio;
    let sz = -2 * depthRatio;

let tx = -(right + left) * widthRatio;
    let ty = -(top + bottom) * heightRatio;
    let tz = -(far + near)   * depthRatio;

M[0] = sx;  M[4] = 0;   M[8] = 0;   M[12] = tx;
    M[1] = 0;   M[5] = sy;  M[9] = 0;   M[13] = ty;
    M[2] = 0;   M[6] = 0;   M[10] = sz; M[14] = tz;
    M[3] = 0;   M[7] = 0;   M[11] = 0;  M[15] = 1;
  };

/** -----------------------------------------------------------------
   * Create an orthographic projection matrix.
   * @param left   {Number} Farthest left on the x-axis
   * @param right  {Number} Farthest right on the x-axis
   * @param bottom {Number} Farthest down on the y-axis
   * @param top    {Number} Farthest up on the y-axis
   * @param near   {Number} Distance to the near clipping plane along the -Z axis
   * @param far    {Number} Distance to the far clipping plane along the -Z axis
   * @return {Float32Array} The orthographic transformation matrix
   */
  self.createOrthographic = function (left, right, bottom, top, near, far) {

let M = self.create();
    self.orthographic(M, left, right, bottom, top, near, far);
    return M;
  };

/** -----------------------------------------------------------------
   * Create a perspective projection matrix based on the limits of a frustum.
   * @param M {Float32Array} 4x4 transformation matrix
   * @param left   {Number} Farthest left on the x-axis
   * @param right  {Number} Farthest right on the x-axis
   * @param bottom {Number} Farthest down on the y-axis
   * @param top    {Number} Farthest up on the y-axis
   * @param near   {Number} Distance to the near clipping plane along the -Z axis
   * @param far    {Number} Distance to the far clipping plane along the -Z axis
   * @return {Float32Array} A perspective transformation matrix
   */
  self.frustum = function (M, left, right, bottom, top, near, far) {

// Make sure there is no division by zero
    if (left === right || bottom === top || near === far) {
      console.log("Invalid createFrustum parameters");
      self.setIdentity(M);
    }
    if (near <= 0 || far <= 0) {
      console.log('For a perspective projection, the near and far distances must be positive');
      self.setIdentity(M);
    } else {

let sx = 2 * near / (right - left);
      let sy = 2 * near / (top - bottom);

let c1 = - (far + near) / (far - near);
      let c2 = 2 * near * far / (near - far);

let tx = -near * (left + right) / (right - left);
      let ty = -near * (bottom + top) / (top - bottom);

M[0] = sx; M[4] = 0;  M[8] = 0;    M[12] = tx;
      M[1] = 0;  M[5] = sy; M[9] = 0;    M[13] = ty;
      M[2] = 0;  M[6] = 0;  M[10] = c1;  M[14] = c2;
      M[3] = 0;  M[7] = 0;  M[11] = -1;  M[15] = 0;
    }
  };

/** -----------------------------------------------------------------
   * Create a perspective projection matrix based on the limits of a frustum.
   * @param left   {Number} Farthest left on the x-axis
   * @param right  {Number} Farthest right on the x-axis
   * @param bottom {Number} Farthest down on the y-axis
   * @param top    {Number} Farthest up on the y-axis
   * @param near   {Number} Distance to the near clipping plane along the -Z axis
   * @param far    {Number} Distance to the far clipping plane along the -Z axis
   * @return {Float32Array} A perspective transformation matrix
   */
  self.createFrustum = function (left, right, bottom, top, near, far) {

let M = self.create();
    self.frustum(M, left, right, bottom, top, near, far);
    return M;
  };

/** -----------------------------------------------------------------
   * Create a perspective projection matrix based on limits of a frustum.
   * @param left   {Number} Farthest left on the x-axis
   * @param right  {Number} Farthest right on the x-axis
   * @param bottom {Number} Farthest down on the y-axis
   * @param top    {Number} Farthest up on the y-axis
   * @param near   {Number} Distance to the near clipping plane along the -Z axis
   * @param far    {Number} Distance to the far clipping plane along the -Z axis
   * @return {Float32Array} A perspective transformation matrix
   */
  self.createFrustumTextbook = function (left, right, bottom, top, near, far) {

let M = self.create();

let sx = 2 * near / (right - left);
      let sy = 2 * near / (top - bottom);

let A = (right + left) / (right - left);
      let B = (top + bottom) / (top - bottom);

let c1 = -2 * near * far / (far - near);
      let c2 = - (far + near) / (far - near);

M[0] = sx; M[4] = 0;  M[8] = A;    M[12] = 0;
      M[1] = 0;  M[5] = sy; M[9] = B;    M[13] = 0;
      M[2] = 0;  M[6] = 0;  M[10] = c2;  M[14] = c1;
      M[3] = 0;  M[7] = 0;  M[11] = -1;  M[15] = 0;
    }

return M;
  };

/** -----------------------------------------------------------------
   * Create a perspective projection matrix using a field-of-view and an aspect ratio.
   * @param M {Float32Array} 4x4 transformation matrix
   * @param fovy   {Number} The angle between the upper and lower sides of the viewing frustum.
   * @param aspect {Number} The aspect ratio of the view window. (width/height).
   * @param near   {Number} Distance to the near clipping plane along the -Z axis.
   * @param far    {Number} Distance to the far clipping plane along the -Z axis.
   * @return {Float32Array} The perspective transformation matrix.
   */
  self.perspective = function (M, fovy, aspect, near, far) {

if (fovy <= 0 || fovy >= 180 || aspect <= 0 || near >= far || near <= 0) {
      console.log('Invalid parameters to createPerspective');
      self.setIdentity(M);
    } else {
      let half_fovy = self.toRadians(fovy) / 2;

let top = near * Math.tan(half_fovy);
      let bottom = -top;
      let right = top * aspect;
      let left = -right;

self.frustum(M, left, right, bottom, top, near, far);
    }
  };

/** -----------------------------------------------------------------
   * Create a perspective projection matrix using a field-of-view and an aspect ratio.
   * @param fovy   {Number} The angle between the upper and lower sides of the viewing frustum.
   * @param aspect {Number} The aspect ratio of the view window. (width/height).
   * @param near   {Number} Distance to the near clipping plane along the -Z axis.
   * @param far    {Number} Distance to the far clipping plane along the -Z axis.
   * @return {Float32Array} The perspective transformation matrix.
   */
  self.createPerspective = function (fovy, aspect, near, far) {

let M = self.create();
    self.perspective(M, fovy, aspect, near, far);
    return M;
  };

if (fovy <= 0 || fovy >= 180 || aspect <= 0 || near >= far || near <= 0) {
      console.log('Invalid parameters to createPerspective');
      M = self.create();
      self.setIdentity(M);
    } else {
      let half_fovy = self.toRadians(fovy) / 2;

let top = near * Math.tan(half_fovy);
      let bottom = -top;
      let right = top * aspect;
      let left = -right;

self.frustum(M, left, right, bottom, top, near, far);
    }
  };

/** -----------------------------------------------------------------
   * Set the matrix M for scaling.
   * @param M {Float32Array} The matrix to set to a scaling matrix
   * @param sx {number} The scale factor along the x-axis
   * @param sy {number} The scale factor along the y-axis
   * @param sz {number} The scale factor along the z-axis
   */
  self.scale = function (M, sx, sy, sz) {
    M[0] = sx;  M[4] = 0;   M[8] = 0;   M[12] = 0;
    M[1] = 0;   M[5] = sy;  M[9] = 0;   M[13] = 0;
    M[2] = 0;   M[6] = 0;   M[10] = sz; M[14] = 0;
    M[3] = 0;   M[7] = 0;   M[11] = 0;  M[15] = 1;
  };

/** -----------------------------------------------------------------
   * Set the matrix M for translation.
   * @param M {Float32Array} The matrix to set to a translation matrix.
   * @param dx {number} The X value of a translation.
   * @param dy {number} The Y value of a translation.
   * @param dz {number} The Z value of a translation.
   */
  self.translate = function (M, dx, dy, dz) {
    M[0] = 1;  M[4] = 0;  M[8]  = 0;  M[12] = dx;
    M[1] = 0;  M[5] = 1;  M[9]  = 0;  M[13] = dy;
    M[2] = 0;  M[6] = 0;  M[10] = 1;  M[14] = dz;
    M[3] = 0;  M[7] = 0;  M[11] = 0;  M[15] = 1;
  };

/** -----------------------------------------------------------------
   * Set the matrix M to a rotation matrix. The axis of rotation axis may not be normalized.
   * @param M {Float32Array} The matrix to set to a rotation matrix.
   * @param angle {number} The angle of rotation (degrees)
   * @param x_axis {number} The X coordinate of axis vector for rotation.
   * @param y_axis {number} The Y coordinate of axis vector for rotation.
   * @param z_axis {number} The Z coordinate of axis vector for rotation.
   */
  self.rotate = function (M, angle, x_axis, y_axis, z_axis) {
    let s, c, c1, ux, uy, uz;

angle = self.toRadians(angle);

s = Math.sin(angle);
    c = Math.cos(angle);

if (x_axis !== 0 && y_axis === 0 && z_axis === 0) {
      // Rotation around the X axis
      if (x_axis < 0) {
        s = -s;
      }

M[0] = 1;  M[4] = 0;  M[8]  = 0;  M[12] = 0;
      M[1] = 0;  M[5] = c;  M[9]  = -s; M[13] = 0;
      M[2] = 0;  M[6] = s;  M[10] = c;  M[14] = 0;
      M[3] = 0;  M[7] = 0;  M[11] = 0;  M[15] = 1;

} else if (x_axis === 0 && y_axis !== 0 && z_axis === 0) {
      // Rotation around Y axis
      if (y_axis < 0) {
        s = -s;
      }

M[0] = c;  M[4] = 0;  M[8]  = s;  M[12] = 0;
      M[1] = 0;  M[5] = 1;  M[9]  = 0;  M[13] = 0;
      M[2] = -s; M[6] = 0;  M[10] = c;  M[14] = 0;
      M[3] = 0;  M[7] = 0;  M[11] = 0;  M[15] = 1;

} else if (x_axis === 0 && y_axis === 0 && z_axis !== 0) {
      // Rotation around Z axis
      if (z_axis < 0) {
        s = -s;
      }

M[0] = c;  M[4] = -s;  M[8]  = 0;  M[12] = 0;
      M[1] = s;  M[5] = c;   M[9]  = 0;  M[13] = 0;
      M[2] = 0;  M[6] = 0;   M[10] = 1;  M[14] = 0;
      M[3] = 0;  M[7] = 0;   M[11] = 0;  M[15] = 1;

} else {
      // Rotation around any arbitrary axis
      axis_of_rotation[0] = x_axis;
      axis_of_rotation[1] = y_axis;
      axis_of_rotation[2] = z_axis;
      V.normalize(axis_of_rotation);
      ux = axis_of_rotation[0];
      uy = axis_of_rotation[1];
      uz = axis_of_rotation[2];

c1 = 1 - c;

M[0] = c + ux * ux * c1;
      M[1] = uy * ux * c1 + uz * s;
      M[2] = uz * ux * c1 - uy * s;
      M[3] = 0;

M[4] = ux * uy * c1 - uz * s;
      M[5] = c + uy * uy * c1;
      M[6] = uz * uy * c1 + ux * s;
      M[7] = 0;

M[8] = ux * uz * c1 + uy * s;
      M[9] = uy * uz * c1 - ux * s;
      M[10] = c + uz * uz * c1;
      M[11] = 0;

M[12] = 0;
      M[13] = 0;
      M[14] = 0;
      M[15] = 1;
    }
  };

/** -----------------------------------------------------------------
   * Set a camera matrix.
   * @param M {Float32Array} The matrix to contain the camera transformation.
   * @param eye_x {number} The x component of the eye point.
   * @param eye_y {number} The y component of the eye point.
   * @param eye_z {number} The z component of the eye point.
   * @param center_x {number} The x component of a point being looked at.
   * @param center_y {number} The y component of a point being looked at.
   * @param center_z {number} The z component of a point being looked at.
   * @param up_dx {number} The x component of a vector in the up direction.
   * @param up_dy {number} The y component of a vector in the up direction.
   * @param up_dz {number} The z component of a vector in the up direction.
   */
  self.lookAt = function (M, eye_x, eye_y, eye_z, center_x, center_y, center_z, up_dx, up_dy, up_dz) {

// Local coordinate system for the camera:
    //   u maps to the x-axis
    //   v maps to the y-axis
    //   n maps to the z-axis

V.set(center, center_x, center_y, center_z);
    V.set(eye, eye_x, eye_y, eye_z);
    V.set(up, up_dx, up_dy, up_dz);

V.subtract(n, eye, center);  // n = eye - center
    V.normalize(n);

V.crossProduct(u, up, n);
    V.normalize(u);

V.crossProduct(v, n, u);
    V.normalize(v);

let tx = - V.dotProduct(u,eye);
    let ty = - V.dotProduct(v,eye);
    let tz = - V.dotProduct(n,eye);

// Set the camera matrix
    M[0] = u[0];  M[4] = u[1];  M[8]  = u[2];  M[12] = tx;
    M[1] = v[0];  M[5] = v[1];  M[9]  = v[2];  M[13] = ty;
    M[2] = n[0];  M[6] = n[1];  M[10] = n[2];  M[14] = tz;
    M[3] = 0;     M[7] = 0;     M[11] = 0;     M[15] = 1;
  };
};

/**--------------------------------------------------------------------
 * @constructor Create an instance of the GlMatrixStack class
 */
window.GlMatrixStack = function () {

let self = this;
  let stack = [];

self.push = function (M) {
    stack.push(M);
  };

self.pop = function () {
    return stack.pop();
  };

self.clear = function () {
    stack = [];
  };

self.size = function () {
    return stack.length;
  };

};

//@formatter:on

/**
 * translate_scene.js, By Wayne Brown, Fall 2017
 */

/**
 * The MIT License (MIT)
 *
 * Copyright (c) 2015 C. Wayne Brown
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.

"use strict";

/** -----------------------------------------------------------------------
 * Create a WebGL 3D scene, store its state, and render its models.
 *
 * @param id {string} The id of the webglinteractive directive
 * @param download {SceneDownload} An instance of the SceneDownload class
 * @param vshaders_dictionary {object} A dictionary of vertex shaders.
 * @param fshaders_dictionary {object} A dictionary of fragment shaders.
 * @param models {object} A dictionary of models.
 * @constructor
 */
window.TranslateScene = function (id, download, vshaders_dictionary,
                                fshaders_dictionary, models) {

// Private variables
  let self = this;
  let my_canvas = null;

let gl = null;
  let program = null;
  let textx, texty, textz, cubex, cubey, cubez, cube_center;
  let textx_gpu, texty_gpu, textz_gpu, cubex_gpu, cubey_gpu,
      cubez_gpu, cube_center_gpu;

let x_axis_gpu, y_axis_gpu, z_axis_gpu;
  let x_axis, y_axis, z_axis;

let matrix = new window.GlMatrix4x4();
  let translate = matrix.create();
  let transform = matrix.create();
  let projection;
  let camera = matrix.create();
  let rotate_x_matrix = matrix.create();
  let rotate_y_matrix = matrix.create();
  let scale_matrix = matrix.create();
  let scale_axes = matrix.create();

// Public variables that will possibly be used or changed by event handlers.
  self.angle_x = 0.0;
  self.angle_y = 0.0;
  self.tx = 0.0;
  self.ty = 0.0;
  self.tz = 0.0;
  self.animate_active = false;
  self.out = download.out;

//-----------------------------------------------------------------------
  function _renderCubes(transform) {
    textx.render(transform);
    texty.render(transform);
    textz.render(transform);
    cubex.render(transform);
    cubey.render(transform);
    cubez.render(transform);
    cube_center.render(transform);
  }

//-----------------------------------------------------------------------
  self.render = function () {

// Build individual transforms
    matrix.setIdentity(transform);
    matrix.rotate(rotate_x_matrix, self.angle_x, 1, 0, 0);
    matrix.rotate(rotate_y_matrix, self.angle_y, 0, 1, 0);
    matrix.translate(translate, self.tx, self.ty, self.tz);

// Render the cubes models
    matrix.multiplySeries(transform, projection, camera, rotate_x_matrix, rotate_y_matrix, translate);
    _renderCubes(transform);

// Render the global axes
    matrix.multiplySeries(transform, projection, camera, rotate_x_matrix, rotate_y_matrix, scale_axes);
    x_axis.render(transform);
    y_axis.render(transform);
    z_axis.render(transform);
  };

//-----------------------------------------------------------------------
  self.delete = function () {

// Clean up shader programs
    gl.deleteShader(program.vShader);
    gl.deleteShader(program.fShader);
    gl.deleteProgram(program);

// Delete each model's VOB
    textx.delete(gl);
    texty.delete(gl);
    textz.delete(gl);
    cubex.delete(gl);
    cubey.delete(gl);
    cubez.delete(gl);
    cube_center.delete(gl);
    x_axis.delete(gl);
    y_axis.delete(gl);
    z_axis.delete(gl);

events.removeAllEventHandlers();

// Disable any animation
    self.animate_active = false;
  };

//-----------------------------------------------------------------------
  // Object constructor. One-time initialization of the scene.

// Get the rendering context for the canvas
  my_canvas = download.getCanvas(id + "_canvas");  // by convention
  if (my_canvas) {
    gl = download.getWebglContext(my_canvas);
  }
  if (!gl) {
    return;
  }

// Set up the rendering program and set the state of webgl
  program = download.createProgram(gl, vshaders_dictionary["color_per_vertex"], fshaders_dictionary["color_per_vertex"]);

gl.useProgram(program);

gl.enable(gl.DEPTH_TEST);

gl.clearColor(0.98, 0.98, 0.98, 1.0);

projection = matrix.createPerspective(45.0, 1.0, 1.0, 100.0);
  matrix.lookAt(camera, 0, 0, 12, 0, 0, 0, 0, 1, 0);

// Create Vertex Object Buffers for the cubes models and
  // pre-processing for rendering.
  textx_gpu = new ModelArraysGPU(gl, models.textx, self.out);
  textx = new RenderColorPerVertex(gl, program, textx_gpu, self.out);

texty_gpu = new ModelArraysGPU(gl, models.texty, self.out);
  texty = new RenderColorPerVertex(gl, program, texty_gpu, self.out);

textz_gpu = new ModelArraysGPU(gl, models.textz, self.out);
  textz = new RenderColorPerVertex(gl, program, textz_gpu, self.out);

cubex_gpu = new ModelArraysGPU(gl, models.cubex, self.out);
  cubex = new RenderColorPerVertex(gl, program, cubex_gpu, self.out);

cubey_gpu = new ModelArraysGPU(gl, models.cubey, self.out);
  cubey = new RenderColorPerVertex(gl, program, cubey_gpu, self.out);

cubez_gpu = new ModelArraysGPU(gl, models.cubez, self.out);
  cubez = new RenderColorPerVertex(gl, program, cubez_gpu, self.out);

cube_center_gpu = new ModelArraysGPU(gl, models.cube_center, self.out);
  cube_center = new RenderColorPerVertex(gl, program, cube_center_gpu, self.out);

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  // Setup of models to render the global axes
  x_axis_gpu = new ModelArraysGPU(gl, models.x_axis, self.out);
  y_axis_gpu = new ModelArraysGPU(gl, models.y_axis, self.out);
  z_axis_gpu = new ModelArraysGPU(gl, models.z_axis, self.out);

x_axis = new RenderColorPerVertex(gl, program, x_axis_gpu, self.out);
  y_axis = new RenderColorPerVertex(gl, program, y_axis_gpu, self.out);
  z_axis = new RenderColorPerVertex(gl, program, z_axis_gpu, self.out);

// Set the scaling for the global axes.
  matrix.scale(scale_axes, 0.2, 0.2, 0.2);

// Set up callbacks for user and timer events
  let events;
  events = new TranslateEvents(id, self);
  events.animate();
};

An example of translating a model.

Animate
X translation 0.00 : -2.0 2.0
Y translation 0.00 : -2.0 2.0
Z translation 0.00 : -2.0 2.0

Show: Process information Warnings Errors

Open this webgl program in a new tab or window

HTML Code To Use GlMatrix4x4¶

The GlMatrix4x4 class uses code from two other classes:

glpoint4.js, which defines a class for (x,y,z,w) points.
glvector3.js, which defines a class for <dx,dy,dz> vectors.

These files must be loaded into your browser along with the matrix library. To use the matrix library include <script> directives in your HTML file that look something like this:

<script src="../learn_webgl/glpoint4.js"></script>
<script src="../learn_webgl/glvector3.js"></script>
<script src="../learn_webgl/glmatrix4x4.js"></script>

Change the file paths based on the relative location of your JavaScript code files to your HTML file. If the HTML and JavaScript files are in the same folder on the server, you can omit a file path.

Glossary¶

code library: a set of common functionality gathered into a single place. It is standard practice to put the functionality into a single class, or a group of classes.
column-major order: values in a 2-dimensional array are store in a 1D array and organized by columns. (All computer memory is 1-dimensional; multi-dimensional arrays are always stored in computer memory as 1D arrays in some agreed upon order.)

Self Assessment¶

For all of these questions, assume that m is an instance of the GlMatrix4x4 class.

GlMatrix4x4

One
Correct.
Four
Incorrect. Where did four come from?
One for each 4x4 transform you need in a program.
Incorrect. No, a GlMatrix4x4 contains functionality, not matrices.
Two for each 4x4 transform you need in a program.
Incorrect. No, a GlMatrix4x4 contains functionality, not matrices.

Q-139: You have created an instance of the GlMatrix4x4 class called m and you want to use it to create a 4x4 transformation matrix called sam. Which of the following code examples accomplish this?

sam = m.create();
Correct.
sam = new GlMatrix4x4().create();
Incorrect. (While this will work in theory, it creates an unnecessary GlMatrix4x4 object.)
sam = new GlMatrix4x4();
Incorrect. This creates an instance of the GlMatrix4x4 class.
m.create();
Incorrect. It creates a new 4x4 transformation matrix but does not assign it to a variable so it can be used.

Q-140: You need to multiple 3 matrices together, a times b times c, and store the results in matrix q. You can do this using the multiplySeries() function like this:

m.multiplySeries(q,a,b,c);

Which of the parameters to the multiplySeries() function are modified by the function call? (Select all that apply.)

matrix q
Correct. Only the first parameter is modified and contains the results of the matrix multiplications.
matrix a
Incorrect.
matrix b
Incorrect.
matrix c
Incorrect.

mary

m.scale(mary, 2, 1, 1);
Correct. The x scale factor is 2, while the scale factors of 1 for the y and z components leaves them unchanged.
m.scale(mary, 2, 2, 2);
Incorrect. This doubles the x, y and z components of all vertices.
m.scale(mary, 2);
Incorrect. This does not provide the 3 scaling parameters required by the function call.
m.scale(mary, 1, 1, 2);
Incorrect. This doubles the z components, leaving the x and y components unchanged.

nice

m.rotate(nice, 30, 0, 1, 0);
Correct. The angle is 30 degrees and the axis of rotation is the y axis, <0,1,0>.
m.rotate(nice, 30, 1, 0, 0)
Incorrect. This rotates about the x axis, <1,0,0>.
m.rotate(nice, 30, 0, 0, 1);
Incorrect. This rotates about the z axis, <0,0,1>.
m.rotate(nice, 30);
Incorrect. This is missing the 3 parameters that define the axis of rotation.

Next Section - 6.7 - Using GlMatrix4x4 - A Robot Arm

6.6 - A Matrix Library - GlMatrix4x4¶