# WebGL Essentials: Part I

This post is part of a series called WebGL Essentials.
WebGL Essentials: Part II

WebGL is an in-browser 3D renderer based on OpenGL, which lets you display your 3D content directly into an HTML5 page. In this tutorial I will cover all the essentials you need to get started using this framework.

## Introduction

There are a couple things you should know before we get started. WebGL is a JavaScript API that renders 3D content to an HTML5 canvas. It does this by using two scripts that are known in the "3D world" as Shaders. The two shaders are:

Now don't get too nervous when you hear these names; it's just a fancy way of saying, "position calculator" and "color chooser" respectively. The fragment shader is the easier one to understand; it simply tells WebGL what color a given point on your model should be. The vertex shader is a little more technical, but basically it converts the points in your 3D models into 2D coordinates. Because all computer monitors are flat 2D surfaces, and when you see 3D objects on your screen, they are merely an illusion of perspective.

If you want to know exactly how this calculation works, you'd need to ask a mathematician, because it uses advanced 4 x 4 matrix multiplications, which are a bit beyond the 'Essentials' tutorial. Luckily, you don't have to know how it works because WebGL will take care of most of it. So let's get started.

## Step 1: Setting Up WebGL

WebGL has a lot of small settings that you have to setup nearly every time you draw something to the screen. In order to save time and make your code neat, I am going to make a JavaScript object that will contain all the 'behind the scene' things in a separate file. To get started, create a new file called 'WebGL.js' and place the following code inside it:

 1 function WebGL(CID, FSID, VSID){  2  var canvas = document.getElementById(CID);  3  if(!canvas.getContext("webgl") && !canvas.getContext("experimental-webgl"))  4  alert("Your Browser Doesn't Support WebGL");  5  else  6  {  7  this.GL = (canvas.getContext("webgl")) ? canvas.getContext("webgl") : canvas.getContext("experimental-webgl");  8   9  this.GL.clearColor(1.0, 1.0, 1.0, 1.0); // this is the color  10  this.GL.enable(this.GL.DEPTH_TEST); //Enable Depth Testing  11  this.GL.depthFunc(this.GL.LEQUAL); //Set Perspective View  12  this.AspectRatio = canvas.width / canvas.height;  13   14  //Load Shaders Here  15  }  16 } 

This constructor function takes in the IDs of the canvas and the two shader objects. First, we get the canvas element and make sure it supports WebGL. If it does, then we assign the WebGL context to a local variable called "GL". The clear color is simply the background color, and it is worth noting that in WebGL most of the parameters go from 0.0 to 1.0 so you would have to divide your rgb values by 255. So in our example 1.0, 1.0, 1.0, 1.0 means a white background with 100% visibility (no transparency). The next two lines tell WebGL to calculate depth and perspective so that an object closer to you will block objects behind it. Finally, we set the aspect ratio which is calculated by dividing the canvas's width by it's height.

Before we continue and load the two shaders, let's write them. I am going to write these in the HTML file where we are going to put the actual canvas element. Create an HTML file, and place the following two script elements just before the closing body tag:

 1   17 18  

The vertex shader is created first, and we define two attributes:

• the vertex position, which is the location in x,y and z coordinates of the current vertex (Point in your Model)
• the texture coordinate; the location in the texture image that should be assigned to this point

Next, we create variables for the transformation and perspective matrices. These are used to convert the 3D model into a 2D image. The next line creates a shared variable to the fragment shader, and in the main function we calculate the gl_Position (the final 2D position). We then assign the 'current texture coordinate' to the shared variable.

In the fragment shader we just take the coordinates we defined in the vertex shader and we 'sample' the texture at that coordinate. Basically we are just getting the color in the texture that corresponds to the current point on our geometry.

Now that we have written the shaders, we can go back to loading them in our JS file. So replace the "//Load Shaders Here" with the following code:

 1 var FShader = document.getElementById(FSID);  2 var VShader = document.getElementById(VSID);  3 4 if(!FShader || !VShader)  5  alert("Error, Could Not Find Shaders");  6 else  7 {  8  //Load and Compile Fragment Shader  9  var Code = LoadShader(FShader);  10  FShader = this.GL.createShader(this.GL.FRAGMENT_SHADER);  11  this.GL.shaderSource(FShader, Code);  12  this.GL.compileShader(FShader);  13   14  //Load and Compile Vertex Shader  15  Code = LoadShader(VShader);  16  VShader = this.GL.createShader(this.GL.VERTEX_SHADER);  17  this.GL.shaderSource(VShader, Code);  18  this.GL.compileShader(VShader);  19   20  //Create The Shader Program  21  this.ShaderProgram = this.GL.createProgram();  22  this.GL.attachShader(this.ShaderProgram, FShader);  23  this.GL.attachShader(this.ShaderProgram, VShader);  24  this.GL.linkProgram(this.ShaderProgram);  25  this.GL.useProgram(this.ShaderProgram);  26   27  //Link Vertex Position Attribute from Shader  28  this.VertexPosition = this.GL.getAttribLocation(this.ShaderProgram, "VertexPosition");  29  this.GL.enableVertexAttribArray(this.VertexPosition);  30   31  //Link Texture Coordinate Attribute from Shader  32  this.VertexTexture = this.GL.getAttribLocation(this.ShaderProgram, "TextureCoord");  33  this.GL.enableVertexAttribArray(this.VertexTexture);  34 } 

Your textures have to be in even byte sizes or you will get an error...like 2x2, 4x4, 16x16, 32x32...

Now let's look at the LoadShader function, You should put this outside of the WebGL function:

 1 function LoadShader(Script){  2  var Code = "";  3  var CurrentChild = Script.firstChild;  4  while(CurrentChild)  5  {  6  if(CurrentChild.nodeType == CurrentChild.TEXT_NODE)  7  Code += CurrentChild.textContent;  8  CurrentChild = CurrentChild.nextSibling;  9  }  10  return Code;  11 } 

It basically just cycles through the shader and collects the source code.

## Step 2: The "Simple" Cube

In order to draw objects in WebGL you are going to need the following three arrays:

• vertices; the points that make up your objects
• triangles; tells WebGL how to connect the vertices into surfaces
• texture coordinates; defines how the vertices are mapped on the texture image

This is referred to as UV mapping. For our example let's create a basic cube. I will split the cube into 4 vertices per side which connect into two triangles. let's make a variable that will hold a cube's arrays.

 1 var Cube = {  2  Vertices : [ // X, Y, Z Coordinates  3   4  //Front  5   6  1.0, 1.0, -1.0,  7  1.0, -1.0, -1.0,  8  -1.0, 1.0, -1.0,  9  -1.0, -1.0, -1.0,  10   11  //Back  12   13  1.0, 1.0, 1.0,  14  1.0, -1.0, 1.0,  15  -1.0, 1.0, 1.0,  16  -1.0, -1.0, 1.0,  17   18  //Right  19   20  1.0, 1.0, 1.0,  21  1.0, -1.0, 1.0,  22  1.0, 1.0, -1.0,  23  1.0, -1.0, -1.0,  24   25  //Left  26   27  -1.0, 1.0, 1.0,  28  -1.0, -1.0, 1.0,  29  -1.0, 1.0, -1.0,  30  -1.0, -1.0, -1.0,  31   32  //Top  33   34  1.0, 1.0, 1.0,  35  -1.0, -1.0, 1.0,  36  1.0, -1.0, -1.0,  37  -1.0, -1.0, -1.0,  38   39  //Bottom  40   41  1.0, -1.0, 1.0,  42  -1.0, -1.0, 1.0,  43  1.0, -1.0, -1.0,  44  -1.0, -1.0, -1.0  45   46  ],  47  Triangles : [ // Also in groups of threes to define the three points of each triangle  48  //The numbers here are the index numbers in the vertex array  49   50  //Front  51   52  0, 1, 2,  53  1, 2, 3,  54   55  //Back  56   57  4, 5, 6,  58  5, 6, 7,  59   60  //Right  61   62  8, 9, 10,  63  9, 10, 11,  64   65  //Left  66   67  12, 13, 14,  68  13, 14, 15,  69   70  //Top  71   72  16, 17, 18,  73  17, 18, 19,  74   75  //Bottom  76   77  20, 21, 22,  78  21, 22, 23  79   80  ],  81  Texture : [ //This array is in groups of two, the x and y coordinates (a.k.a U,V) in the texture  82  //The numbers go from 0.0 to 1.0, One pair for each vertex  83   84  //Front  85   86  1.0, 1.0,  87  1.0, 0.0,  88  0.0, 1.0,  89  0.0, 0.0,  90   91   92  //Back  93   94  0.0, 1.0,  95  0.0, 0.0,  96  1.0, 1.0,  97  1.0, 0.0,  98   99  //Right  100   101  1.0, 1.0,  102  1.0, 0.0,  103  0.0, 1.0,  104  0.0, 0.0,  105   106  //Left  107   108  0.0, 1.0,  109  0.0, 0.0,  110  1.0, 1.0,  111  1.0, 0.0,  112   113  //Top  114   115  1.0, 0.0,  116  1.0, 1.0,  117  0.0, 0.0,  118  0.0, 1.0,  119   120  //Bottom  121   122  0.0, 0.0,  123  0.0, 1.0,  124  1.0, 0.0,  125  1.0, 1.0  126  ]  127 }; 

It may seem like a lot of data for a simple cube, however, in in part two of this tutorial, I will make a script that will import your 3D models so you don't have to worry about calculating these.

You may also be wondering why I made 24 points (4 for each side), when there is really only eight total unique points on a cube? I did this because you can only assign one texture coordinate per vertex; so if we would only put in the 8 points, then the whole cube would have to look the same because it would wrap the texture around all the sides that the vertex touches. But this way, each side has it's own points so we can put a different part of the texture on each side.

We now have this cube variable and are ready to start drawing it. Let's go back to the WebGL method and add a Draw function.

## Step 3: The Draw Function

The procedure for drawing objects in WebGL has a lot of steps; so, it's a good idea to make a function to simplify the process. The basic idea is to load the three arrays into WebGL buffers. We then connect these buffers to the attributes we defined in the shaders along with the transformation and perspective matrices. Next, we have to load the texture into memory, and, finally, we can call the draw command. So let's get started.

The following code goes inside the WebGL function:

 1 this.Draw = function(Object, Texture)  2 {  3  var VertexBuffer = this.GL.createBuffer(); //Create a New Buffer  4 5  //Bind it as The Current Buffer  6  this.GL.bindBuffer(this.GL.ARRAY_BUFFER, VertexBuffer);  7 8  // Fill it With the Data  9  this.GL.bufferData(this.GL.ARRAY_BUFFER, new Float32Array(Object.Vertices), this.GL.STATIC_DRAW);  10 11  //Connect Buffer To Shader's attribute  12  this.GL.vertexAttribPointer(this.VertexPosition, 3, this.GL.FLOAT, false, 0, 0);  13 14  //Repeat For The next Two  15  var TextureBuffer = this.GL.createBuffer();  16  this.GL.bindBuffer(this.GL.ARRAY_BUFFER, TextureBuffer);  17  this.GL.bufferData(this.GL.ARRAY_BUFFER, new Float32Array(Object.Texture), this.GL.STATIC_DRAW);  18  this.GL.vertexAttribPointer(this.VertexTexture, 2, this.GL.FLOAT, false, 0, 0); 
 1  var TriangleBuffer = this.GL.createBuffer();  2  this.GL.bindBuffer(this.GL.ELEMENT_ARRAY_BUFFER, TriangleBuffer);  3  //Generate The Perspective Matrix  4  var PerspectiveMatrix = MakePerspective(45, this.AspectRatio, 1, 10000.0);  5 6  var TransformMatrix = MakeTransform(Object);  7 8  //Set slot 0 as the active Texture  9  this.GL.activeTexture(this.GL.TEXTURE0);  10 11  //Load in the Texture To Memory  12  this.GL.bindTexture(this.GL.TEXTURE_2D, Texture);  13 14  //Update The Texture Sampler in the fragment shader to use slot 0  15  this.GL.uniform1i(this.GL.getUniformLocation(this.ShaderProgram, "uSampler"), 0);  16 17  //Set The Perspective and Transformation Matrices  18  var pmatrix = this.GL.getUniformLocation(this.ShaderProgram, "PerspectiveMatrix");  19  this.GL.uniformMatrix4fv(pmatrix, false, new Float32Array(PerspectiveMatrix));  20 21  var tmatrix = this.GL.getUniformLocation(this.ShaderProgram, "TransformationMatrix");  22  this.GL.uniformMatrix4fv(tmatrix, false, new Float32Array(TransformMatrix));  23 24  //Draw The Triangles  25  this.GL.drawElements(this.GL.TRIANGLES, Object.Trinagles.length, this.GL.UNSIGNED_SHORT, 0);  26 }; 

The vertex shader positions, rotates, and scales your object based on the transformation and perspective matrices. We will go more in depth into transformations in the second part of this series.

I have added two functions: MakePerspective() and MakeTransform(). These just generate the necessary 4x4 Matrices for WebGL. The MakePerspective() function accepts the vertical field of view, the aspect ratio, and the nearest and farthest points as arguments. Anything that is closer than 1 unit and farther than 10000 units will not be displayed, but you can edit these values to get the effect you are looking for. Now let's take a look at these two functions:

 1 function MakePerspective(FOV, AspectRatio, Closest, Farest){  2  var YLimit = Closest * Math.tan(FOV * Math.PI / 360);  3  var A = -( Farest + Closest ) / ( Farest - Closest );  4  var B = -2 * Farest * Closest / ( Farest - Closest );  5  var C = (2 * Closest) / ( (YLimit * AspectRatio) * 2 );  6  var D = (2 * Closest) / ( YLimit * 2 );  7  return [  8  C, 0, 0, 0,  9  0, D, 0, 0,  10  0, 0, A, -1,  11  0, 0, B, 0  12  ];  13 }  14 function MakeTransform(Object){  15  return [  16  1, 0, 0, 0,  17  0, 1, 0, 0,  18  0, 0, 1, 0,  19  0, 0, -6, 1  20  ];  21 } 

Both these matrices effect the final look of your objects, but the perspective matrix edits your '3D world' like the field of view and the visible objects while the transformation matrix edits the individual objects like their rotation scale and position. With this done we are almost ready to draw, all that's left is a function to convert an image into a WebGL texture.

Loading a texture is a two step process. First we have to load an image like you would in a standard JavaScript application, and then we have to convert it to a WebGL texture. So let's start with the second part since we are already in the JS file. Add the following at the bottom of the WebGL function right after the Draw command:

 1 this.LoadTexture = function(Img){  2  //Create a new Texture and Assign it as the active one  3  var TempTex = this.GL.createTexture();  4  this.GL.bindTexture(this.GL.TEXTURE_2D, TempTex);  5   6  //Flip Positive Y (Optional)  7  this.GL.pixelStorei(this.GL.UNPACK_FLIP_Y_WEBGL, true);  8   9  //Load in The Image  10  this.GL.texImage2D(this.GL.TEXTURE_2D, 0, this.GL.RGBA, this.GL.RGBA, this.GL.UNSIGNED_BYTE, Img);  11   12  //Setup Scaling properties  13  this.GL.texParameteri(this.GL.TEXTURE_2D, this.GL.TEXTURE_MAG_FILTER, this.GL.LINEAR);  14  this.GL.texParameteri(this.GL.TEXTURE_2D, this.GL.TEXTURE_MIN_FILTER, this.GL.LINEAR_MIPMAP_NEAREST);  15  this.GL.generateMipmap(this.GL.TEXTURE_2D);  16   17  //Unbind the texture and return it.  18  this.GL.bindTexture(this.GL.TEXTURE_2D, null);  19  return TempTex;  20 }; 

It's worth noting that your textures have to be in even byte sizes, or you will receive an error; so they have to be dimensions, like 2x2, 4x4, 16x16, 32x32, and so on. I added the line to flip the Y coordinates simply because my 3D application's Y coordinates were backward, but it will depend on what you are using. This is due to some programs making 0 in the Y axis the top left corner and some applications make it the bottom left corner. The scaling properties that I set just tell WebGL how the image should up-scale and down-scale. You can play around with different options to get different effects, but I thought these worked best.

Now that we are done with the JS file, let's return to the HTML file and implement all of this.

## Step 5: Wrapping It Up

As I mentioned earlier, WebGL renders to a canvas element. That's all we need in the body section. After adding the canvas element, your html page should look like the following:

 1   2   3   4   5   8   9   10   11  Your Browser Doesn't Support HTML5's Canvas.  12   13   14   15   16   17   18   19  

It's a pretty simple page. In the head area I have linked to our JS file. Now let's go implement our Ready function, which gets called when the page loads:

 1 //This will hold our WebGL variable  2 var GL;  3   4 //Our finished texture  5 var Texture;  6   7 //This will hold the textures image  8 var TextureImage;  9   10 function Ready(){  11  GL = new WebGL("GLCanvas", "FragmentShader", "VertexShader");  12  TextureImage = new Image();  13  TextureImage.onload = function(){  14  Texture = GL.LoadTexture(TextureImage);  15  GL.Draw(Cube, Texture);  16  };  17  TextureImage.src = "Texture.png";  18 } 

So we create a new WebGL object and pass in the IDs for the canvas and shaders. Next, we load the texture image. Once loaded, we call the Draw() method with the Cube and the Texture. If you followed along, your screen should have a static cube with a texture on it.

Now even though I said we will cover transformations next time, I can't just leave you with a static square; it's not 3D enough. Let's go back and add a small rotation. In the HTML file, change the onload function to look like so:

 1 TextureImage.onload = function(){  2  Texture = GL.LoadTexture(TextureImage);  3  setInterval(Update, 33);  4 }; 

This will call a function called Update() every 33 milliseconds which will give us a frame rate of about 30 fps. Here is the update function:

 1 function Update(){  2  GL.GL.clear(16384 | 256);  3  GL.Draw(GL.Cube, Texture);  4 } 

This is a fairly simple function; it clears the screen and then draws the updated Cube. Now, let's go to the JS file to add the rotation code.

## Step 6: Adding Some Spin

I'm not going to fully implement transformations, because I'm saving that for next time, but let's add a rotation around the Y-axis. The first thing to do is add a Rotation variable to our Cube object. This will keep track of the current angle, and allow us to keep incrementing the rotation. So the top of your Cube variable should look like this:

 1 var Cube = {  2  Rotation : 0,  3  //The Other Three Arrays  4 }; 

Now let's update the MakeTransform() function to incorporate the rotation:

 1 function MakeTransform(Object){  2  var y = Object.Rotation * (Math.PI / 180.0);  3  var A = Math.cos(y);  4  var B = -1 * Math.sin(y);  5  var C = Math.sin(y);  6  var D = Math.cos(y);  7  Object.Rotation += .3;  8  return [  9  A, 0, B, 0,  10  0, 1, 0, 0,  11  C, 0, D, 0,  12  0, 0, -6, 1  13  ];  14 } 

## Conclusion

And that's it! In the next tutorial, we will cover loading models and performing transformations. I hope you enjoyed this tutorial; feel free to leave any questions or comments that you might have below.