5.5 - Example 1: One Color per Model¶

We will render our simple pyramid model using a single color for all its faces. We need to examine the following issues:

How does the shader program process the model vertices?
How is the model data organized in an object buffer?
How is rendering actually performed?

The Shader Programs¶

Examine the shader programs in the following demo and then study their descriptions below.

Show: Code Canvas Run Info

shader01.vert
shader01.frag

A simple, manually defined 3D model. You can spin the model with your mouse.

Animate

Shader errors, Shader warnings, Javascript info

Open this webgl program in a new tab or window

Vertex Shader¶

Lines	Description
Lines	Description
7-8	The model will be rendered with the same transformation matrix for all vertices. And all faces will be rendered with the same color. These are `uniform` values that will be set once before a rendering starts. Notice the convention to start their names with a u_. This will help you track the types of your variables. (WebGL shaders could care less what you name your variables. This convention is for you - the programmer!)







7	a `mat4` is a 4x4 matrix; 16 floating point values.
7	a `mat4` is a 4x4 matrix; 16 floating point values.
8	a `vec4` is a vector of 4 floating point values; in this case a color defined as RGBA (red, green, blue, alpha).


10	The vertices will change for every triangle that is rendered. Therefore the variable, `a_Vertex`, is an attribute variable. It will get its values from a buffer object. A `vec3` is an array of 3 floating point values; (x,y,z).




12-15	The `main()` function is always the entry point for a shader. This function will be executed once for each vertex in the model.


14	This shader executes a single command on each vertex. It is multiplying a 4x4 matrix times a 4x1 vector using linear algebra matrix mulplication. WebGL shaders have matrix math built-in! Notice that the vertex has only three values (x,y,z) but 4 values are required for the matrix multiplication. The vertex is converted to a 4-component array, with the last component, the `w` component, set to 1.0.

Fragment Shader¶

Lines	Description
Lines	Description
7	The color of the pixels will be the same, so we have one `uniform` value, `u_Color`. Because the variable is global and has the same name as a global vertex shader variable, the variable is linked to the vertex shader‘s variable of the same name.




9-11	The `main()` function is always the entry point for a shader. This function will be executed once for each fragment of the rendered primitive (either a point, line or triangle.)



10	This shader executes a single command on each fragment. It is setting the color of the fragment.

The Buffer Object(s)¶

The only attribute that is changing to render this model is its vertices. Therefore, we only need one buffer object. Remember that a buffer object is a 1-dimensional, homogeneous array of floating point values. We need to gather up all of the vertices that define the triangles into a single array, and the order of the vertices matter. Before you create the array you need to decide how the triangles will be rendered. There are three choices: gl.TRIANGLE, gl.TRIANGLE_STRIP, or g.TRIANGLE_FAN. In addition, the vertices of each triangle must be in counter-clockwise order when looking at the front of the face. Our pyramid model can be rendered in a single ‘pass’ through the buffer object using either the gl.TRIANGLE or the gl.TRIANGLE_STRIP mode. Let’s keep it simple and use the gl.TRIANGLE mode for this example. (If you changed rendering modes, you would have to change the ordering of the vertices.)

Creating the buffer object is a pre-processing step which needs to happen only once. Let’s break the task into 2 parts:

Get the triangle vertices into a 1D array in the correct order. This is done by the _buildBufferObjectData() function in the code shown below.
Create and upload the vertices into the GPU’s memory. This is done by the _createBufferObject() function in the code shown below.

Note that these two functions are private functions of the JavaScript class definition and they are only called once when the constructor code is executed.

The 1D array that is created to fill the buffer object contains the data below for this example. Note that each consecutive three values represent one vertex.

[0.5, -0.25, 0.25, 0, 0.25, 0, -0.5, -0.25, 0.25, -0.5, -0.25, 0.25, 0, 0.25, 0, 0, -0.25, -0.5, 0, -0.25, -0.5, 0, 0.25, 0, 0.5, -0.25, 0.25, 0, -0.25, -0.5, 0.5, -0.25, 0.25, -0.5, -0.25, 0.25]

Show: Code Canvas Run Info

simple_model_render_01.js

/**
 * simple_model_render_01.js, By Wayne Brown, Fall 2015
 */

/**
 * 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";

//-------------------------------------------------------------------------
/**
 * Given a model description, create the buffer objects needed to render
 * the model. This is very closely tied to the shader implementations.
 * @param gl Object The WebGL state and API
 * @param program Object The shader program the will render the model.
 * @param model Simple_model The model data.
 * @param model_color The color of the model faces.
 * @param out Object Can display messages to the webpage.
 * @constructor
 */
window.SimpleModelRender_01 = function (gl, program, model, model_color, out) {

var self = this;

// Variables to remember so the model can be rendered.
  var number_triangles = 0;
  var triangles_vertex_buffer_id = null;

// Shader variable locations
  var a_Vertex_location = null;
  var u_Color_location = null;
  var u_Transform_location = null;

var edge_color = new Float32Array( [0.0, 0.0, 0.0, 1.0]); // BLACK

//-----------------------------------------------------------------------
  /**
   * Create a Buffer Object in the GPU's memory and upload data into it.
   * @param gl Object The WebGL state and API
   * @param data TypeArray An array of data values.
   * @returns Number a unique ID for the Buffer Object
   * @private
   */
  function _createBufferObject(gl, data) {
    // Create a buffer object
    var buffer_id;

buffer_id = gl.createBuffer();
    if (!buffer_id) {
      out.displayError('Failed to create the buffer object for ' + model.name);
      return null;
    }

// Make the buffer object the active buffer.
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer_id);

// Upload the data for this buffer object to the GPU.
    gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);

return buffer_id;
  }

//-----------------------------------------------------------------------
  /**
   * Using the model data, build a 1D array for the Buffer Object
   * @private
   */
  function _buildBufferObjectData() {
    var j, k, m, nv, numberVertices, triangle, vertex, vertices3;

// Create a 1D array that holds all of the  for the triangles
    if (model.triangles.length > 0) {
      number_triangles = model.triangles.length;
      numberVertices = number_triangles * 3;
      vertices3 = new Float32Array(numberVertices * 3);

nv = 0;
      for (j = 0; j < model.triangles.length; j += 1) {
        triangle = model.triangles[j];

for (k = 0; k < 3; k += 1) {
          vertex = triangle.vertices[k];

for (m = 0; m < 3; m += 1, nv += 1) {
            vertices3[nv] = vertex[m];
          }
        }
      }

triangles_vertex_buffer_id = _createBufferObject(gl, vertices3);
    }

// Release the temporary vertex array so the memory can be reclaimed.
    vertices3 = null;
  }

//-----------------------------------------------------------------------
  /**
   * Get the location of the shader variables in the shader program.
   * @private
   */
  function _getLocationOfShaderVariables() {
    // Get the location of the shader variables
    u_Color_location     = gl.getUniformLocation(program, 'u_Color');
    u_Transform_location = gl.getUniformLocation(program, 'u_Transform');
    a_Vertex_location    = gl.getAttribLocation(program,  'a_Vertex');
  }

//-----------------------------------------------------------------------
  // These one-time tasks set up the rendering of the models.
  _buildBufferObjectData();
  _getLocationOfShaderVariables();

//-----------------------------------------------------------------------
  /**
   * Delete the Buffer Objects associated with this model.
   * @param gl Object The WebGL state and API.
   */
  self.delete = function (gl) {
    if (number_triangles > 0) {
      gl.deleteBuffer(triangles_vertex_buffer_id);
    }
  };

//-----------------------------------------------------------------------
  /**
   * Render the model.
   * @param gl Object The WebGL state and API.
   * @param transform 4x4Matrix The transformation to apply to the model vertices.
   */
  self.render = function (gl, transform) {
    var j, start;

// 1. Render the triangles:

// Set the transform for all the triangle vertices
    gl.uniformMatrix4fv(u_Transform_location, false, transform);

// Set the color for all of the triangle faces
    gl.uniform4fv(u_Color_location, model_color);

// Activate the model's vertex Buffer Object
    gl.bindBuffer(gl.ARRAY_BUFFER, triangles_vertex_buffer_id);

// Bind the vertices Buffer Object to the 'a_Vertex' shader variable
    gl.vertexAttribPointer(a_Vertex_location, 3, gl.FLOAT, false, 0, 0);
    gl.enableVertexAttribArray(a_Vertex_location);

// Draw all of the triangles
    gl.drawArrays(gl.TRIANGLES, 0, number_triangles * 3);

// 2. Render the edges around each triangle:

// Set the color for all of the edges
    gl.uniform4fv(u_Color_location, edge_color);

// Draw a line_loop around each of the triangles
    for (j = 0, start = 0; j < number_triangles; j += 1, start += 3) {
      gl.drawArrays(gl.LINE_LOOP, start, 3);
    }

};

A simple, manually defined 3D model. You can spin the model with your mouse.

Animate

Shader errors, Shader warnings, Javascript info

Open this webgl program in a new tab or window

Access to Shader Variables¶

To render a model, you will set some values in your shader program and then issue the gl.drawArrays() command. But you have a problem. Your data is in RAM in your JavaScript program, while your shader program is a compiled program on the GPU. How can you pass data to the shader? This is a 2 step process:

Pre-processing: Get the location of a variable in the shader program. This is equivalent to an index that could be used as an array lookup. The location of a variable in a shader program will never change, so the location only needs to be retrieved once.
Use a variable’s location in a shader program to update it.

To get a variable’s location in a shader program, use one of the appropriate WebGL functions:

uint getUniformLocation(Object shader_program, string variable_name);
ulong getAttribLocation(Object shader_program, string variable_name);

Examples of these functions can be found in lines 133-135 of the demo code above.

To set a variable’s value in a shader program, use one of the appropriate WebGL functions:

void uniform[1234][fi](uint location, value1, value2, value3, ...);
void uniform[1234][fi]v(uint location, Array values);
void uniformMatrix[234]fv(uint location, bool transpose, Array matrix);

The characters in brackets, [234], represent the number of values to be set. The [fi] means you are setting either a floating point value, f, or an integer value, i. You can send values as discrete variables, or as multiple values in a single array. The functions that use arrays end in a v. Examples of setting the values of shader program variables can be found at lines 158, 161, and 176 in the above demo code.

Linking a Buffer Object to an Attribute Variable¶

An attribute variable pulls its values from an array. The array will typically be stored in a buffer object. The positions in the array that are used is determined by the 2^nd and 3^rd parameters in your call to gl.drawArrays(mode, start, count). The start parameter gives the starting array index, while the count parameter specifies how many vertices to use. You must enable the use of ‘vertex arrays’ before you can access values from a buffer object. Linking our a_Vertex attribute variable in our shader program to the buffer object looks like this:

gl.bindBuffer(gl.ARRAY_BUFFER, triangles_vertex_buffer_id);

gl.enableVertexAttribArray(a_Vertex_location);

gl.vertexAttribPointer(a_Vertex_location, 3, gl.FLOAT, false, 0, 0);

First, you must make a particular buffer object active. This is done with the bindBuffer command. Then you enable getting data from buffer objects with the enableVertexAttribArray function. Then you describe the organization of the values in the buffer object using a call to vertexAttribPointer. The 1^st parameter, a_Vertex_location, is the location in the compiled shader program of the variable that will be set from the buffer’s values. Let’s delay a formal description of the other parameters until later. For now, the other parameters tell the shader that the vertex data has 3 values per vertex and the values are all floating point.

Rendering¶

In the example code, the gl.drawArrays(mode, start, count) command is called 5 times. (See lines 171 and 180.) Let’s discuss why.

The shader is written to render with a single color. We want to render a red pyramid with black edges. Therefore we must call drawArrays() at least twice: once when the color is set to red, and a second time after the color has been changed to black. Examine the demo code. Notice that the color is set to red in line 161 and then the triangles are rendered in line 171. Then the color is changed to black in line 176 (the edge_color), and then the same vertices in the buffer object are used to draw the triangle edges using the gl.LINE_LOOP mode. However, this can’t be done with a single draw command because the vertices are not organized that way in the buffer object. So we have to step through the buffer and change the starting index each time.

Summary¶

In the next few lessons we will modify our model, our shader programs, and our rendering code to produce more sophisticated graphics. It is important that you understand the concepts presented above before proceeding to the next lesson. So make a second pass through this lesson before proceeding.

Next Section - 5.6 - Example 2: One Color per Triangle