CS 315 Lab 1: Getting Started With WebGL

This lab is an introduction to WebGL programming.

Assignment

After the lab seminar, you have one week to:

Seminar Notes

A. General OpenGL Architecture

General OpenGL Architecture

Block Diagram of Typical Application / OpenGL / OS interactions.

OpenGL is the definitive cross-platform 3D library. It has a long history. It inspired Microsoft's Direct3D (D3D) API, and both evolved together from supporting fixed function graphics accelerators to supporting modern programmable hardware. The modern OpenGL style, and the one most like recent versions of D3D, is known as Core Profile. A similar set of features is available for mobile devices as OpenGL ES. OpenGL ES 3.0 is used as the basis for WebGL 2, which we will be learning in this class.

By learning WebGL2, you will learn a low level graphics programming style that is common to all modern OpenGL flavours. Especially if you stick to the same programming language, switching between versions is not too hard, and porting code can be easy if you modularize properly.

Getting to the point where you can begin writing OpenGL code is a bit trickier as the process differs from operating system to operating system. Fortunately there are cross platform libraries that can make your code extremely simple to port. The above diagram shows the general case for getting a modern "Core" OpenGL environment. Regardless of how you choose to set up :

When you write a WebGL program, many of these details are hidden from you. In fact, your WebGL calls may not even be executed by an OpenGL driver. On Macs, where OpenGL support is built-in to the OS, WebGL calls are translated directly into their OpenGL equivalents. On Windows, DirectX/D3D 9 or better has been built-in to the OS since Vista, so a special layer called ANGLE — developed by Google — specifically for WebGL and used by Chrome, Firefox, IE11 and Edge — is used to translate WebGL API commands into equivalent D3D9 or D3D11 commands. On Linux, driver support is EXTREMELY important — most browsers only support nVidia's official drivers.

General WebGL Architecture

"Ideal" WebGL Application / OpenGL / OS interactions.
Windows WebGL Architecture

Windows WebGL Application / "OpenGL" / OS interactions.

ANGLE's translation from WebGL to D3D is good, but not perfect. If you want a "pure" OpenGL experience on Windows, and you think your graphics drivers are up to it, then:

Try one of the textbook's samples, or one of my experiments, to see if WebGL is working for you. If not, the lab has excellent Windows computers with very capable graphics cards installed. You may work there whenever a lab is not scheduled..

We will not go into detail on exactly how everything works in this week's lab. Instead we will focus on getting to the point where you can begin drawing, then use HTML UI elements to interact with the drawing.

B. Overview of an Interactive Program.

Model-View-Controller Architecture

Interactive program design entails breaking your program into three parts:

Object-oriented programming was developed, in part, to aid with modularising the components of Model-View-Architecture programs. Most user interface APIs are written in an Object Oriented language.

You will be structuring your programs to handle these three aspects of an interactive program. A 3D graphics: In your simplest programs your Model and View will be tightly coupled. You might have one or two variables set up that control a few things in your scene, and the scene itself may be described by hard coded calls made directly to WebGL with only a few dynamic elements. Eventually you will learn to store the scene in separate data structures.

The Main Events

All OpenGL programs should respond to at least two events:
There are other events you will frequently handle as well. If you place your program in a resizeable window it is very important to respond to size change events. If you don't, your rendered result will be distorted or incorrect when the window is resized. You may also wish to respond to mouse motions, clicks, key strokes, timers, network communications and HTML controls.

C. Setting up Your Lab Environment

With WebGL2 as the API of choice for this course, you will want to set up an environment to easily edit web pages. We will edit and view our code from Langs2 using Vite as a light web server. It will provide us with reload on save features. We will also use JavaScript modules based on the textbook's code and to make certain parts of the program easier to write. Follow these instructions to learn how to set up a textbook style WebGL program.

Before starting these instructions, make sure your browser is WebGL capable. I prefer Chrome for this lab, but Firefox will do. See the end of Section A for links to tests and instructions.

1. Download and Configure VS Code

You should be familiar with this process from CS 115 and CS 285. If not your instructor will guide you through these steps in lab:

2. Install and Run Vite

Vite is a web build tool that focuses on making your code lean. You develop in a custom server, then build to publish a highly optimised page with only the JavaScript you actually need for that page. For now, we'll be using it to provide a way to navigate your project tree and to reload your work on save.

Vite requires Node.js, so we'll start there.

3. Install WebGL Folders

The textbook provides many WebGL2 samples and a set of library files to make writing 3D programs easier for you. Most importantly, the textbook provides simple shader loaders and a Vector/Matrix math library. The CS 315 team has modernized and added to these by modularizing the textbook's libraries and providing the uofrGraphics.mjs module that can draw various simple shapes. We will now download these adapted files, plus a new Vite homepage, and explore a bit.

D. Your First WebGL Program

1. Create the HTML File

The HTML file for a WebGL application will link in necessary javascript files and resources. Some resources, such as shaders, can be defined in-line. The following is a commented minimal HTML file for a textbook style WebGL application:

WebGL Template: HTML
         
<!DOCTYPE html>
<html>
<head>
   <title>WebGL Template</title>

   <!-- This in-line script is a vertex shader resource
      Shaders can be linked from an external file as well. 
      First line must be shader language version, no spaces before.
      (Actually textbook's shader loader strips leading spaces...) 
      -->
   <script id="vertex-shader" type="x-shader/x-vertex">
      #version 300 es

      // All vertex shaders require a position input.
      // The name can be changed.
      // Other inputs can be added as desired for colors and other features.
      in vec4 vPosition;

      void main()
      {
         // gl_Position is a built-in vertex shader output.
         // Its value should always be set by the vertex shader.
         // The simplest shaders just copy the position attribute straight to 
         // gl_Position
         gl_Position = vPosition;
      }
   </script>

   <!-- This in-line script is a vertex shader resource
      Shaders can be linked from an external file as well. 
      First line must be shader language version, no spaces before.
      (Actually textbook's shader loader strips the spaces...) -->
   <script id="fragment-shader" type="x-shader/x-fragment">
      #version 300 es

      // Sets default precision for floats. 
      // Since fragment shaders have no default precision, you must either:
      //   - set a default before declaring types that use floating point OR
      //   - specify the precision before each floating point declaration
      // Choices are lowp, mediump, and highp. 
      precision mediump float;

      // The output of a fragment shader is sent to draw buffers, 
      // which might be an array or the screen. The default is 
      out vec4 fragColor;

      void main()
      {
         // In general, the fragment shader output should be set, 
         //     but this is not required.
         // If an output is not set, 
         //    there will be no output to the corresponding draw buffer.
         fragColor = vec4(0.0, 0.0, 0.0, 1.0);
      }
   </script>

   <!-- These are external javascript files. 
      The first three are the textbook libraries.
      The last one is your own javascript code. Make sure to change the name 
      to match your javascript file. -->
   <script type="module" src="yourWebGLJavascript.mjs"></script>
</head>

<body>
   <!-- This is the canvas - the only HTML element that can render WebGL 
      graphics. You can have more than one WebGL canvas on a web page, but
      that gets tricky. Stick to one per page for now. -->
   <canvas id="gl-canvas" width="512" height="512">
      Oops ... your browser doesn't support the HTML5 canvas element
   </canvas>
</body>
</html>

Using your favorite editor, create a new HTML file called Lab1Demo.html in your Lab1 folder and paste the above code into it.

2. Create the Javascript Module File

The JavaScript module file will breathe life into your WebGL application. It sets up the WebGL rendering context, does the drawing and defines responses to various events. The simplest WebGL javascript program will set up the rendering context after the HTML has been loaded. This type of code has been placed in the init() function which is called at the end of the file. It can also draw, but we'll separate that into a render() function that can be called once when initialization is done for simple drawings or repeatedly with requestAnimationFrame() if animation is desired.

The following JavaScript defines a very minimalistic template WebGL program:

WebGL Template: javascript
            
import * as MV from '/Common/MV.mjs';
import { uofrGraphics, flatten4x4 } from "/Common/uofrGraphics.mjs";
import { initShaders } from "/Common/initShadersHTML.mjs";

// This variable will store the WebGL rendering context
let gl;

// This variable will store UofR Graphics object
let urgl;

function init() {
   // Set up a WebGL Rendering Context in an HTML5 Canvas
   let canvas = document.getElementById("gl-canvas");
   gl = canvas.getContext('webgl2');
   if (!gl) {
     throw new Error("WebGL 2.0 isn't available");;
   }

   //  Configure WebGL
   //  eg. - set a clear color
   //      - turn on depth testing

   //  Load shaders and initialize attribute buffers
   let program = initShaders(gl, "vertex-shader", "fragment-shader");
   gl.useProgram(program);

   // Set up data to draw

   // Load the data into GPU data buffers

   // Associate shader attributes with corresponding data buffers

   // Get addresses of shader uniforms

   // Either draw as part of initialization
   //render();

   // Or draw just before the next repaint event
   //requestAnimationFrame(render);
};


function render() {
   // clear the screen
   // draw
}

init();

Using your favorite editor, create a new javascript file called Lab1Demo.mjs in the Lab1 folder and paste the above code into it. Don't forget to edit the .html file so it knows about your new .mjs file!

4. Add More Code to Draw a Coloured Triangle

Load the HTML file in your WebGL capable web browser. You will see nothing. This is the correct behaviour. Let's add the code to draw a blended colour triangle, starting with the necessary javascript, then moving to the shaders.

In this part, add or change the highlighted code in the template code.

Changes to Lab1Demo.mjs
         
import * as MV from '/Common/MV.mjs';
import { uofrGraphics, flatten4x4 } from "/Common/uofrGraphics.mjs";
import { initShaders } from "/Common/initShadersHTML.mjs";

// This variable will store the WebGL rendering context
let gl;

// This variable will store UofR Graphics object
let urgl;

window.onload = function init() {
   // Set up a WebGL Rendering Context in an HTML5 Canvas
   let canvas = document.getElementById("gl-canvas");
   gl = canvas.getContext('webgl2');
   if (!gl) alert("WebGL 2.0 isn't available");

   //  Configure WebGL
   //  eg. - set a clear color
   //      - turn on depth testing
   // This light gray clear colour will help you see your canvas
   gl.clearColor(0.9, 0.9, 0.9, 1.0);

   //  Load shaders and initialize attribute buffers
   let program = initShaders(gl, "vertex-shader", "fragment-shader");
   gl.useProgram(program);

   // Set up data to draw
   // Here, 2D vertex positions and RGB colours are loaded into arrays.
   let positions = [
         -0.5, -0.5, // point 1
         0.5, -0.5, // point 2
         0.0,  0.5   // point 2
      ];
   let colors = [
         1, 0, 0, // red
         0, 1, 0, // green
         0, 0, 1  // blue
      ];

   // Load the data into GPU data buffers
   // The vertex positions are copied into one buffer
   let vertex_buffer = gl.createBuffer();
   gl.bindBuffer(gl.ARRAY_BUFFER, vertex_buffer);
   gl.bufferData(gl.ARRAY_BUFFER, MV.flatten(positions), gl.STATIC_DRAW);

   // The colours are copied into another buffer
   let color_buffer = gl.createBuffer();
   gl.bindBuffer(gl.ARRAY_BUFFER, color_buffer);
   gl.bufferData(gl.ARRAY_BUFFER, MV.flatten(colors), gl.STATIC_DRAW);

   // Associate shader attributes with corresponding data buffers
   // Create a connection manager for the data, a Vertex Array Object
   // These are typically made global so you can swap what you draw in the 
   //    render function.
   let triangleVAO = gl.createVertexArray();
   gl.bindVertexArray(triangleVAO);

   //Here we prepare the "vPosition" shader attribute entry point to
   //receive 2D float vertex positions from the vertex buffer
   let vPosition = gl.getAttribLocation(program, "vPosition");
   gl.bindBuffer(gl.ARRAY_BUFFER, vertex_buffer);
   gl.vertexAttribPointer(vPosition, 2, gl.FLOAT, false, 0, 0);
   gl.enableVertexAttribArray(vPosition);

   //Here we prepare the "vColor" shader attribute entry point to
   //receive RGB float colours from the colour buffer
   let vColor = gl.getAttribLocation(program, "vColor");
   gl.bindBuffer(gl.ARRAY_BUFFER, color_buffer);
   gl.vertexAttribPointer(vColor, 3, gl.FLOAT, false, 0, 0);
   gl.enableVertexAttribArray(vColor);

  
   // Get addresses of shader uniforms
   // None in this program...

   //Either draw once as part of initialization
  render();

   //Or schedule a draw just before the next repaint event
   //requestAnimationFrame(render);
};


function render() {
   // clear the screen
   // Actually, the  WebGL automatically clears the screen before drawing.
   // This command will clear the screen to the clear color instead of white.
   gl.clear(gl.COLOR_BUFFER_BIT);
 
   // draw
   // Draw the data from the buffers currently associated with shader variables
   // Our triangle has three vertices that start at the beginning of the buffer.
   gl.drawArrays(gl.TRIANGLES, 0, 3);
}

Reload the HTML page. The result should look like this:

Intermediate Result

What your project should look like. If you see nothing and you are sure you copy/pasted everything correctly, make sure your HTML is referencing your javascript file instead of the template's dummy one.

Now we're getting somewhere. The reason the triangle is black is that the shaders in the HTML file are hardcoded to paint everything black. Check your web browser's error console. Your WebGL object may have reported errors when you called vertexAttribPointer() and enableVertexAttribArray() with the invalid vColor returned by getAttribLocation(). We need to modify the shaders to make them aware of the colour buffer. Make the following changes to the vertex and fragment shaders:

Lab1Demo.html: vertex-shader changes
      
      #version 300 es

      // All vertex shaders require a position input.
      // The name can be changed.
      // Other inputs can be added as desired for colors and other features.
      in vec4 vPosition;
      in vec4 vColor;

      // This varying output is interpolated between the vertices in the 
      // primitive we are drawing before being sent to an input with  
      // matching name and type in the fragment shader
      out vec4 varColor;

      void main()
      {
         // gl_Position is a built-in vertex shader output.
         // Its value should always be set by the vertex shader.
         // The simplest shaders just copy the position attribute straight to 
         // gl_Position
         gl_Position = vPosition;
         varColor = vColor;
      }
Lab1Demo.html: fragment-shader changes
         
         #version 300 es

         // Sets default precision for floats. 
         // Since fragment shaders have no default precision, you must either:
         //   - set a default before declaring types that use floating point OR
         //   - specify the precision before each floating point declaration
         // Choices are lowp, mediump, and highp. 
         precision mediump float;
        
         in vec4 varColor;
         // The output of a fragment shader is sent to draw buffers, 
         // which might be an array or the screen. The default is 
         out vec4 fragColor;

         void main()
         {
            // In general, the fragment shader output should be set, 
            //     but this is not required.
            // If an output is not set, 
            //    there will be no output to the corresponding draw buffer.
            fragColor = varColor;
        }
When you reload your HTML page, you should see this:
Final Result

Much more colourful. Yay!

Click here to see a page with the working WebGL result instead of a picture.

E. A More Complex Scene

The triangle is OK, but you probably want Real 3D Graphcs. Let's do that. I do not expect you to understand everything that's going on here, but you should be able to understand enough to use this as the basis for your exercise this week.


F. A UI Event

Let's make the program a little more interactive.

If your result looks and works like this, congratulations!
You are now ready to begin the exercise.

Good luck!

If your program runs correctly, you might be wondering how exactly the picture is drawn. That is, you might want to understand how each function works. Well, you do not have to worry too much about this in the first lab. Over the rest of the semester we will go through these subjects one-by-one in detail. Of course, we will learn some even more advanced functions and features too.

G. Assignment

To be completed and submitted to URCourses by the start of your next lab seminar.

Play with WebGL

Try to make to the RenderScene function by following the TODOs in the comments. This is a taste of things to come. For help with the function calls read the comments carefully and consult with your lab instructor.

Your result should look like this... you may add other objects to the scene if you wish, but please keep the blue cube and red sphere visible.

Think About Event Programming

Learn About the CS315 Libraries

You have seen a lot of stuff so far and you may be confused about all the libraries used in this lab's program. Take a moment to learn about them.

Deliverables

Package all your exercise files into one zip file. Submit the .zip file to URCourses. Include the following:
  1. Working WebGL folder structure including Lab1 and Common folders with all code with modified box/sphere position and your new event handler/UI element.
  2. Shown on Lab1Exercise.html page: answers to the "Think About Event Programming" questions.
  3. Shown on Lab1Exercise.html page: answers to "Learn About the CS315 Libraries"