6.7 - Using `GlMatrix4x4` - A Robot Arm¶

This lesson introduces an example WebGL program that uses the GlMatrix4x4 JavaScript class to create and manipulate transformation matrices. Before the example program is explained, let’s review how the graphics pipeline works.

The Graphics Pipeline

A Review of the Graphics Pipeline¶

In the first stage of the graphics pipeline, vertices are passed through a vertex shader program to position and orient models in a scene. Notice that the second stage clips away everything that is outside the view of the scene’s virtual camera. Therefore, a vertex shader program needs to accomplish the following tasks:

Model Transform: Transform a model into it’s correct size, location, and orientation for the current scene.
View Transform: Transform a model into the correct location and orientation in front of the scene’s virtual camera.
Projection Transform: Transform a model into normalized device coordinates to facilitate clipping, which discards anything outside the view frame of the scene’s camera. (The projection also “projects” a 3D world into a 2D view.)

It is important that you understand the following “big ideas”:

Each of these transformation operations can be performed by multiplying the vertices of a model by a 4-by-4 matrix.
You must always include all of these transformations. They are not optional!
There are too many details to discuss all of these transforms at the same time. This lesson concentrates on the model transform. The other transforms will be fully explained in later lessons.

It is common practice to combine the model, view, and projection transformations into a single 4-by-4 transformation matrix which minimizes the calculations a vertex shader program must execute. The example WebGL program below creates such a combined transform. Remember that transformations must be ordered from right to left. Every WebGL program you ever develop will create a vertex transformation matrix like this:

VertexTransform
=ProjectionMatrix
*ViewMatrix
*ModelMatrix
Eq1

To create this VertexTransform 4x4 matrix there are pre-processing commands that need to be executed only once and separate commands that need to executed every time an individual frame of an animation is rendered. Let’s walk through the details of these separate sets of commands.

WebGL Program Example¶

The RobotBaseScene class used in the WebGL program below places its initialization code in its class constructor and the rendering commands for a single frame in a class function called render. The constructor code is all statements that are not inside a sub-function of the class. Because we use the JavaScript "use strict"; mode, all variables and functions must be defined before they can be used. This causes the constructor code to be spread throughout the class definition. The public and private variable declarations are at the top of the class definition, while the constructor commands are at the bottom of the definition.

This WebGL program renders of a single model which is the base of a robotic arm.

Show: Code Canvas Run Info

robot_base_scene.js

/**
 * robot_base_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.

* 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.
 */

"use strict";

//-------------------------------------------------------------------------
/**
 * Initialize and render a scene.
 * @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.RobotBaseScene = function (id, download, vshaders_dictionary,
                                  fshaders_dictionary, models) {

// Private variables
  let self = this; // Store a local reference to the new object.

let out = download.out;
  let events;
  let my_canvas;

let gl = null;
  let program = null;
  let base_model;
  let base_gpu;

let matrix = new GlMatrix4x4();
  let transform = matrix.create();
  let camera = matrix.create();
  let projection;
  let base_y_rotate = matrix.create();

// Public variables that will be changed by event handlers or that
  // the event handlers need access to.
  self.base_y_angle = 0.0;
  self.animate_active = true;
  self.out = out;

//-----------------------------------------------------------------------
  // Public function to render the scene.
  self.render = function () {

// The base is being rotated by the animation callback so the rotation
    // about the y axis must be calculated on every frame.
    matrix.rotate(base_y_rotate, self.base_y_angle, 0, 1, 0);

// Combine the transforms into a single transformation
    matrix.multiplySeries(transform, projection, camera, base_y_rotate);

// Draw the models
    base_model.render(transform);
  };

//-----------------------------------------------------------------------
  // Public function to delete and reclaim all rendering objects.
  self.delete = function () {
    // Clean up shader programs
    gl.deleteShader(program.vShader);
    gl.deleteShader(program.fShader);
    gl.deleteProgram(program);
    program = null;

// Delete each model's buffer objects
    base_model.delete();

// Disable any animation
    self.animate_active = false;

// Remove all event handlers
    events.removeAllEventHandlers();
    events = null;

// Release the GL graphics context
    gl = null;
  };

//-----------------------------------------------------------------------
  // 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;
  }

// Enable hidden-surface removal
  gl.enable(gl.DEPTH_TEST);

projection = matrix.createOrthographic(-8, 8, -8, 8, -8, 20);
  matrix.lookAt(camera, 0, 4, 8, 0, 0, 0, 0, 1, 0);

// Set up the rendering shader program and make it the active shader program
  program = download.createProgram(gl, vshaders_dictionary["color_per_vertex"], fshaders_dictionary["color_per_vertex"]);
  gl.useProgram(program);

// Create the Buffer Objects needed for this model and copy
  // the model data to the GPU.
  base_gpu = new ModelArraysGPU(gl, models.Base, out);
  base_model = new RenderColorPerVertex(gl, program, base_gpu, out);

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

The base of a robot arm.

Animate

Show: Process information Warnings Errors

Open this webgl program in a new tab or window

Please study these detailed notes about the RobotBaseScene class definition above.

Line(s)	Description
Line(s)	Description
33-42	The class function header. The `download` object has downloaded all of the required files and creates an instance of this class. The object receives the shader programs ( `vshaders_dictionary` and `fshaders_dictionary`), and the models that will be used in the scene.





44-67, 110-139	The class constructor. This code is executed once when the object is created. It initializes all data needed to render the scene.


56	One instance of the `GlMatrix4x4` object is created. This gives you access to all of the matrix functionality we discussed in the previous lesson.



57-60	The required transformation matrices are created.
57-60	The required transformation matrices are created.
64-66	The variables that events can modify are made public variables.
64-66
114-120	The GL context for the canvas window is retrieved.
114-120	The GL context for the canvas window is retrieved.
129	A shader program is created using a vertex shader and a fragment shader.


130	The shader program is made the active graphics pipeline program.
130
134	Buffer objects in the GPU are created and the model data is copied to the GPU.


135	Shader program variables are retrieved.
135	Shader program variables are retrieved.
138	Callbacks for user events are initialized.
138	Callbacks for user events are initialized.

Each time the scene needs to rendered, the render function in lines 70-85 is called. It takes the following major actions:

Line(s)	Description
Line(s)	Description
74	The color buffer that holds the rendered image is cleared to a background color, and the depth buffer that determines which pixels are visible is cleared.



78	The rotation transform that is causing the base model to rotate is calculated because the angle of rotation changes on every frame.


81	A single vertex transform is calculated, which includes the projection, camera, and model transforms. The transforms are ordered from right to left. Conceptually, the model transform happens first, then the view transform, and finally the projection transform.





84	The model is rendered using the calculated transform.
84	The model is rendered using the calculated transform.

Notes:¶

The delete function in lines 89-108 is used by the interactive textbook background processes when you “restart” a demo. The running program must be “cleared” from memory so that a modified version of the demo code can be executed. In a game environment, a function like delete might be used when you change the game level and want to clear memory for an entirely new scene.

This example will be enhanced in the next several lessons, so please make sure you understand this example before proceeding to the next lesson.

Glossary¶

model transform: A 4-by-4 transformation matrix that changes the vertices of a model to set its desired size, location, and orientation.
view (or camera) transform: A 4-by-4 transformation matrix that moves a model into the correct location and orientation in front of the scene’s virtual camera.
model-view transform: A 4-by-4 transformation matrix that contains both the model transform and the view transform.
projection transform: A 4-by-4 transformation matrix that projects a 3-dimensional world into normalize device coordinates in preparation for clipping. It also “projects” the 3D world to a 2D view.

Self Assessment¶

RobotBaseScene

When using the JavaScript "use strict" mode, variables and functions must be defined before they can be used.
Correct.
It separates declarations from commands.
Incorrect. While the code is basically separated in this way, the organization is for logical reasons instead of necessity.
JavaScript syntax requires it this way.
Incorrect. All code not in a sub-function is part of a class constructor.
It makes the code easier to read and maintain.
Incorrect. Having all the constructor code contiguous in one place would be a better organization.

matrix

To access all of the functionality in a "GlMatrix4x4" object.
Correct.
To perform matrix multiplication.
Incorrect. It allows access to the "multiplySeries()" function, but much more.
To create a 4x4 transformation matrix.
Incorrect. It allows access to the "create()" function, but much more.
To setup a rotation transformation matrix.
Incorrect. It allows access to the "rotate()" function, but much more.

projection, camera, model
Correct.
model, camera, projection
Incorrect.
camera, projection, model
Incorrect.
model, projection, camera
Incorrect.

Next Section - 6.8 - Chaining Transformations - Adding a Forearm

6.7 - Using GlMatrix4x4 - A Robot Arm¶