Getting Started With WebGL


Highlights of this lab:

This lab is an introduction to WebGL programming. You will see:

Exercise:

After the lab lecture, you have one week to: After the lab lecture, 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 simplified predecessor to OpenGL's Core Profile features inspired OpenGL ES 2.0 - by far the most popular low level 3D API for mobile devices. OpenGL ES 2.0 was, in turn used as the basis for WebGL, which you will be learning in this class.

By learning WebGL, 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, learn how to disable ANGLE at Geeks3D.

Try one of Dr. Angel's samples, or one of my experiments, to see if WebGL is working for you. If it isn't, then try following the advice in Learning WebGL Lesson 0.

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, and HTML controls.

C. Your First WebGL Program

Though WebGL is the API of choice for this course, you will always use textbook libraries 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. Also, make sure you are comfortable with an HTML and Javascript source editor on your computer. If you want to start simple, I suggest TextWrangler on Mac or Notepad++ on Windows. If you want to try something cool, then try Brackets

1. Set Up Your Folders

2. 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. -->
    <script id="vertex-shader" type="x-shader/x-vertex">
        // All vertex shaders require a position input or "attribute".
        // The name can be changed.
        // Other attributes can be added.
        attribute vec4 vPosition;

        void main()
        {
            // gl_Position is a built-in vertex shader output or "varying".
            // 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 fragment shader resource.
         Shaders can be linked from an external file as well. -->
    <script id="fragment-shader" type="x-shader/x-fragment">
        // Sets default precision for floats. 
        // Required, since fragment shaders have no default precision. 
        // Choices are lowp and mediump. 
        precision mediump float;

        void main()
        {
            // gl_FragColor is a built-in fragment shader output
            // In general it should be set, but this is not required.
            // The default gl_FragColor is undefined
            gl_FragColor = vec4(0,0,0,1);
        }
    </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="text/javascript" src="../Common/webgl-utils.js"></script>
    <script type="text/javascript" src="../Common/initShaders.js"></script>
    <script type="text/javascript" src="../Common/MVnew.js"></script>
    <script type="text/javascript" src="yourWebGLJavascript.js"></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 the Lab1 folder and paste the above code into it.

3. Create the Javascript File

The javascript 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 by defining an action for window.onload event. It can also draw if no animation is needed.

The following javascript defines a very minimalistic template WebGL program:

WebGL Template: javascript
// This variable will store the WebGL rendering context
var gl;

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

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

  //  Load shaders and initialize attribute buffers
  var 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
  //requestAnimFrame(render());
};


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

Using your favorite editor, create a new javascript file called Lab1Demo.js 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 .js 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.js
// This variable will store the WebGL rendering context
var gl;

window.onload = function init() {
  // Set up a WebGL Rendering Context in an HTML5 Canvas
  var canvas = document.getElementById("gl-canvas");
  gl = WebGLUtils.setupWebGL(canvas);
  if (!gl) {
    alert("WebGL 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 var 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.
  var vertices = [
            -0.5, -0.5, // point 1
             0.5, -0.5, // point 2
             0.0, 0.5   // point 2
        ];
  var colors = [
            1, 0, 0, // red
            0, 1, 0, // green
            0, 0, 1  // blue
        ];
// Load the data into GPU data buffers
  // The vertex array is copied into one buffer
  var vertex_buffer = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, vertex_buffer);
  gl.bufferData(gl.ARRAY_BUFFER, flatten(vertices), gl.STATIC_DRAW);

  // The colour array is copied into another
  var color_buffer = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, color_buffer);
  gl.bufferData(gl.ARRAY_BUFFER, flatten(colors), gl.STATIC_DRAW);
// Associate shader attributes with corresponding data buffers
  //Here we prepare the "vPosition" shader attribute entry point to
  //receive 2D float vertex positions from the vertex buffer
  var 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
  var 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 //requestAnimFrame(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
        // All vertex shaders require a position input or "attribute".
        // The name can be changed.
        // Other attributes can be added.
        attribute vec4 vPosition;
        attribute vec4 vColor;
        // This "varying" output is interpolated between the vertices in the 
        // primitive we are drawing before being sent to a varying with the 
        // same name in the fragment shader
        varying vec4 varColor;
void main() { // gl_Position is a built-in vertex shader output or "varying". // 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
        // Sets default precision for floats. 
        // Required, since fragment shaders have no default precision. 
        // Choices are lowp and mediump. 
        precision mediump float;
        
        varying vec4 varColor;
void main() { // gl_FragColor is a built-in fragment shader output // In general it should be set, but this is not required. // The default gl_FragColor is undefined
            gl_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.

D. 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.

E. A UI Event

Let's make the program a little more interactive.
Oops ... your browser doesn't support the HTML5 canvas element

If your result looks and works like this, congratulations!
You are now ready to begin the exercise.
Make sure you learn how to publish your work before proceeding.

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.

E. Publish Your Project

Part of submitting your work for these labs will be to publish everything to your Hercules homepage. If you haven't taken CS215 yet, you might not know what to do. Here's a quick summary:

Visit your Lab work modifying the underlined parts of this url as needed: http://www2.cs.uregina.ca/~your_username/WebGL_Labs/Lab#/web_gl_page.html

EXERCISE

To be completed and submitted to URCourses by the first midnight one week after the lab.

Play with WebGL

Try to make these changes to the RenderScene function. 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"
  4. Comment with URL to your published WebGL project on Hercules.