1.1 - Introduction¶

Welcome to this “Learn WebGL” Web Site¶

This web site will help you learn how to display and manipulate real-time 3D computer graphics inside a web page. 3D computer graphics has the potential to create visualizations of anything your mind can imagine. But it’s not simple or easy to implement. So take your time and work methodically through the tutorials in this website.

Learning philosophy¶

Mastery learning is key to this set of tutorials. Mastery learning has been used with great success by the Kahn Academy and it is one of the main reasons why this set of tutorials was developed. Today’s students are ingrained in a system that conditions them to learn a little about a topic and then move on – regardless of how much they still don’t understand. As a student you need to re-think what it means to learn, and break your old habits of just ignoring things you don’t understand.

This site is designed on the principle that complex topics should be learned “top-down”. It is important that you understand the “big picture” before you dig into the details. As you learn the details you will have a framework that allows you to understand how the details accomplish a small part of a larger problem.

These tutorials are designed to be self-directed and self-paced. You are encouraged to stay with a topic until you understand it at more than a surface level. If you “master” each topic before going to the next topic, you will be prepared for the more detailed topics that follow. Please follow the flow of lessons as they are organized on the table-of-contents page. This will provide you with a firm foundation on which to understand the new topics.

What is WebGL?¶

WebGL is a JavaScript application programmer interface (API) that allows a programmer to use the graphics processing unit (GPU) of a computing device in a web browser window to render real-time 3D computer graphics. It is the only cross platform development environment for producing 3D computer graphics that the software industry has today. Learning WebGL is the best way to understand the basics of computer graphics while ending up with a “toolbox” that you can use to produce your own computer graphics.

What is a WebGL Program?¶

A typical web page that contains 3D computer graphics generated by a WebGL program is made up of these basic parts:

A HTML (Hypertext Markup Language) description of the web page.
A CSS (Cascading Style Sheet) that decribes how each element of the HTML description is formatted.
A HTML canvas element in the web page that provides a rectangular area in which 3D computer graphics can be rendered.
Graphical data that defines the 3D objects to be rendered.
JavaScript programs that load your graphical data, configure your graphical data, render your graphical data, and code that responds to user events.
OpenGL Shader programs that perform critical parts of the graphical rendering.

All of these basic parts initially reside on a web server. When a user (a client) requests a web page that contains 3D graphics, the data described above has to be transferred to the client’s computer, stored in correct places, and then processed by appropriate processors. Modern computing devices have multiple processors of different types.

CPU’s – central processing units – are the “brains” of the device. CPU’s perform the general processing and run the operating system (OS) that controls the overall functioning of the device.
GPU’s – graphics processing units – are specially designed to render 3D graphics.

Modern computing devices also have many types of memory designed for different purposes.

RAM – random access memory – stores program data and program instructions.
Graphics memory - a separate memory system for video and graphics processing. GPU’s have dedicated memory specifically designed for 3D graphics.

A simplified diagram of these ideas is shown below.

Major hardware pieces in a computing device

When a client requests a web page from a web server, the following sequence of events happen:

The server sends the HTML description of the web page to the client and the client stores the web page in RAM.
The client’s web browser (e.g., Chrome, Safari, Internet Explorer) reads the HTML page description and requests any other documents that are referenced in the HTML code, including images, JavaScript code, CSS (cascading style sheets), data files, etc. All of these files are stored in the client’s RAM.
If there is JavaScript code associated with the page, it is executed. For a page that contains 3D graphics, the JavaScript code will perform the following tasks:
- It might request that other data files be downloaded from the server (for example, the data that describes the 3D graphic objects to be rendered).
- It will get and initialize the WebGL graphics context associated with the HTML canvas element where the graphics will be rendered.
- It will configure and copy the model data to the GPU’s memory. (Technically the data is copied to GPU’s vertex object buffers).
- It will establish “event handlers” that associate HTML events with JavaScript code that will execute when an event happens.
Finally, the web page is rendered to a window in the browser and the web page waits for user events. Timer events can be set up to automatically generate events on a regular schedule, which can create animations of the 3D graphics.

When a JavaScript event handler initiates the rendering of graphics into a HTML canvas element, it tells the GPU which object buffer(s) contain the data it wants to render and then issues the WebGL “draw” command. Notice that the data to be rendered is usually already in the GPU memory. In a typical graphics program, the model data is copied to the GPU’s memory only once. This saves time and makes the graphics rendering efficient and fast. When we use the term “real-time graphics” we mean that rendering can be done in less than 1/30 of a second and the user can view smooth graphical animations. Such fast rendering is only possible if the transfer of data between the GPU’s memory and RAM is minimized.

The idea that expensive operations are only done once is a basic principle of all computer graphics. Throughout these tutorial you will continually see the phrases “preprocessing step” and “rendering step”. The goal is to perform the “preprocessing step” only once. Therefore the JavaScript code that performs graphics rendering is typically divided into two separate parts: 1) a setup (or preprocessing) part that is done once and 2) a rendering part that is performed each time an object is drawn. Each tutorial lesson will make a clear distinction between preprocessing code and rendering code.

To re-emphasize the “big picture,” the diagram below summarizes the above discussion. Note that the JavaScript code runs on the CPU(s) and the graphics rendering is done by the GPU(s). The JavaScript code is the “master”. It “runs the show” and tells the GPU(s) when and what to render.

Where the different parts of a WebGL program are stored and executed

Tutorial Examples¶

A web page interface that allows you to view WebGL code, data, and the results of a WebGL rendering has been developed and an example is shown below. The interface will help you experiment with a WebGL program interactively. Remember, personal experimentation is critical to your learning! Pause when you come to the interactive examples and experiment!

The interface includes commands across the top of the interactive example that allow for the following options:

Re-start - If you edit the code displayed in the left window panes, you can click the “re-start” button to reload the WebGL program using your modified code and/or data. If you introduce errors in the code or data the WebGL program will not execute properly, but you should see error messages displayed in the output window pane below the canvas. In some cases the errors will only be visible in the JavaScript console window. Some editor panes have editing disabled to prevent unintentional changes. All three edit panes below have editing disabled because you are not ready to experiment with the code yet.
Show checkboxes - Allows you to hide any of the three display panels in the interactive example. Typically only one or two files will be presented in the edit windows. This will help you focus on a single piece of a WebGL program at one time.
Download All - Downloads all of the files that make up this WebGL program to your computer’s default download folder. The number of files can be large, depending on the complexity of the example. To use the code in a stand-alone program the files will have to be organized appropriately in sub-folders. (More on this later.) It is recommended that you empty your download folder before downloading a WebGL program so you don’t miss any important files.

The interactive example below is shown here for you to familiarize yourself with the interface. All of the edit windows are read-only for this example. Simply examine the HTML, JavaScript, and model data to see what it looks like. You can interact with the graphics in this specific example by clicking and dragging your mouse in the canvas window. You can also enable or disable the automatic animation using the checkbox below the canvas window. If you would like to see the results of the WebGL program as a separate, independent page, use the hyperlink at the bottom of the interactive example. Depending on your default browser settings, the WebGL program will open in a new window or a new tab.

Show: Code Canvas Run Info

example.html
learn_webgl_vector3.js
model_cone4.obj

<!doctype html>

<html lang="en-US">

<head>
  <meta charset="UTF-8">
  <meta name="keywords" content="Learn, WebGL, tutorial, example">
  <meta name="description" content="WebGL tutorials - an example">
  <meta name="author" content="Wayne Brown">
  <title>WebGL Example</title>
  <script src="../../lib/jquery.js"></script>
  <link rel="stylesheet" href="../../lib/webglcode.css" />
</head>

<body>
<p>An example of using WebGL to render a 3D animated object.</p>

<canvas id="W1_canvas" class="canvas3D">
  Please use a browser that supports "canvas"
</canvas>
<br>

<input type="checkbox" id="my_pause" checked> Animate<br>

<script src="../../lib/learn_webgl.js"></script>
<script src="../../lib/learn_webgl_console_messages.js"></script>
<script src="../../lib/learn_webgl_point4.js"></script>
<script src="../../lib/learn_webgl_vector3.js"></script>
<script src="../../lib/learn_webgl_matrix.js"></script>
<script src="../../lib/learn_webgl_model_01.js"></script>
<script src="../../lib/learn_webgl_vob_model_01.js"></script>
<script src="./example_render_01.js"></script>
<script src="./example_events_01.js"></script>

<script>
  var models = ["../../lib/models/model_cone4.obj"];
  var shaders = ["../../lib/shaders/shader05.vert", "../../lib/shaders/shader05.frag"];
  var controls = ["my_pause"];
  var my_program = new Learn_webgl("W1_canvas", "Scene_example_render", models, shaders, controls);
</script>

</body>
</html>

/**
 * Learn_webgl_vector3.js, By Wayne Brown, Spring 2015
 *
 * Learn_webgl_vector3 is a set of functions that perform standard
 * operations on 3-component vectors - (dx, dy, dz), which are stored as
 * 3-element arrays. The data type, Float32Array, was added to JavaScript
 * specifically for GPU programming. It stores 32 bit, floating-
 * point numbers in the format required by the GPU.
 *
 * The functions do not create new objects because in real-time graphics,
 * creating new objects slows things down.
 *
 * The functions are defined inside an object to prevent pollution of
 * JavaScript's global address space.
 */

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

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

"use strict";
/*globals Float32Array, console */

var Learn_webgl_vector3 = function () {

var self = this;

/** ---------------------------------------------------------------------
   * Create a new 3-component vector.
   * @param dx Number The change in x of the vector.
   * @param dy Number The change in y of the vector.
   * @param dz Number The change in z of the vector.
   * @return Float32Array A new 3-component vector
   */
  self.create = function (dx, dy, dz) {
    var v = new Float32Array(3);
    v[0] = 0;
    v[1] = 0;
    v[2] = 0;
    if (arguments.length >= 1) { v[0] = dx; }
    if (arguments.length >= 2) { v[1] = dy; }
    if (arguments.length >= 3) { v[2] = dz; }
    return v;
  };

/** ---------------------------------------------------------------------
   * Create a new 3-component vector and set its components equal to an existing vector.
   * @param from Float32Array An existing vector.
   * @return Float32Array A new 3-component vector with the same values as "from"
   */
  self.createFrom = function (from) {
    var v = new Float32Array(3);
    v[0] = from[0];
    v[1] = from[1];
    v[2] = from[2];
    return v;
  };

/** ---------------------------------------------------------------------
   * Create a vector using two existing points.
   * @param tail Float32Array A 3-component point.
   * @param head Float32Array A 3-component point.
   * @return Float32Array A new 3-component vector defined by 2 points
   */
  self.createFrom2Points = function (tail, head) {
    var v = new Float32Array(3);
    self.subtract(v, head, tail);
    return v;
  };

/** ---------------------------------------------------------------------
   * Copy a 3-component vector into another 3-component vector
   * @param to Float32Array A 3-component vector that you want changed.
   * @param from Float32Array A 3-component vector that is the source of data
   * @returns Float32Array The "to" 3-component vector
   */
  self.copy = function (to, from) {
    to[0] = from[0];
    to[1] = from[1];
    to[2] = from[2];
    return to;
  };

/** ---------------------------------------------------------------------
   * Set the components of a 3-component vector.
   * @param v Float32Array The vector to change.
   * @param dx Number The change in x of the vector.
   * @param dy Number The change in y of the vector.
   * @param dz Number The change in z of the vector.
   */
  self.set = function (v, dx, dy, dz) {
    v[0] = dx;
    v[1] = dy;
    v[2] = dz;
  };

/** ---------------------------------------------------------------------
   * Calculate the length of a vector.
   * @param v Float32Array A 3-component vector.
   * @return Number The length of a vector
   */
  self.length = function (v) {
    return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
  };

/** ---------------------------------------------------------------------
   * Make a vector have a length of 1.
   * @param v Float32Array A 3-component vector.
   * @return Float32Array The input vector normalized to unit length. Or null if the vector is zero length.
   */
  self.normalize = function (v) {
    var length, percent;

length = self.length(v);
    if (Math.abs(length) < 0.0000001) {
      return null; // Invalid vector
    }

percent = 1.0 / length;
    v[0] = v[0] * percent;
    v[1] = v[1] * percent;
    v[2] = v[2] * percent;
    return v;
  };

/** ---------------------------------------------------------------------
   * Add two vectors:  result = V0 + v1
   * @param result Float32Array A 3-component vector.
   * @param v0 Float32Array A 3-component vector.
   * @param v1 Float32Array A 3-component vector.
   */
  self.add = function (result, v0, v1) {
    result[0] = v0[0] + v1[0];
    result[1] = v0[1] + v1[1];
    result[2] = v0[2] + v1[2];
  };

/** ---------------------------------------------------------------------
   * Subtract two vectors:  result = v0 - v1
   * @param result Float32Array A 3-component vector.
   * @param v0 Float32Array A 3-component vector.
   * @param v1 Float32Array A 3-component vector.
   */
  self.subtract = function (result, v0, v1) {
    result[0] = v0[0] - v1[0];
    result[1] = v0[1] - v1[1];
    result[2] = v0[2] - v1[2];
  };

/** ---------------------------------------------------------------------
   * Calculate the cross product of 2 vectors: result = v0 x v1 (order matters)
   * @param result Float32Array A 3-component vector.
   * @param v0 Float32Array A 3-component vector.
   * @param v1 Float32Array A 3-component vector.
   */
  self.crossProduct = function (result, v0, v1) {
    result[0] = v0[1] * v1[2] - v0[2] * v1[1];
    result[1] = v0[2] * v1[0] - v0[0] * v1[2];
    result[2] = v0[0] * v1[1] - v0[1] * v1[0];
  };

/** ---------------------------------------------------------------------
   * Calculate the dot product of 2 vectors
   * @param v0 Float32Array A 3-component vector.
   * @param v1 Float32Array A 3-component vector.
   * @return Number Float32Array The dot product of v0 and v1
   */
  self.dotProduct = function (v0, v1) {
    return v0[0] * v1[0] + v0[1] * v1[1] + v0[2] * v1[2];
  };

/** ---------------------------------------------------------------------
   * Print a vector on the console.
   * @param name String A description of the vector to be printed.
   * @param v Float32Array A 3-component vector.
   */
  self.print = function (name, v) {
    var maximum, order, digits;

maximum = Math.max(v[0], v[1], v[2]);
    order = Math.floor(Math.log(maximum) / Math.LN10 + 0.000000001);
    digits = (order <= 0) ? 5 : (order > 5) ? 0 : (5 - order);

console.log("Vector3: " + name + ": " + v[0].toFixed(digits) + " "
                                          + v[1].toFixed(digits) + " "
                                          + v[2].toFixed(digits));
  };
};

An example of using WebGL to render a 3D animated object.

Animate

Shader errors, Shader warnings, Javascript info

Open this webgl program in a new tab or window

Download the files for the example above and then look in you computer’s download folder at the files that were created. This will give you a feel for what is required for a WebGL program.

Summary¶

As you start learning WebGL, please remember to refer back to these “Big Picture” lessons to put the details into their proper place. The following lessons cover these “big picture” topics:

What is 3D computer graphics and how does it work?
Where did WebGL come from?
How can the complexity of WebGL programs be managed?

Glossary¶

mastery learning: learn a foundational topic completely before moving on to harder more advanced topics.
web server: a program that runs on a server computer and stores web pages and related files. When a client computer requests a web page, the web server sends the requested files to the client.
web browser: a program that runs on a client computer which allows a user to download, view, and interact with web pages. Commonly used web browsers are Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Internet Explorer.
CPU: central processing unit - the hardware that controls a computing device and performs all of its calculations.
GPU: graphic processing unit - the hardware that is optimized to produce 3D computer graphics.
RAM: random access memory - where data and programs are stored for CPU access and manipulation.
GPU memory: where data and programs are stored for GPU access and manipulation.
preprocessing step: manipulation of data that happens once.

Next Section - 1.2 - 3D Computer Graphics - What and How