8.4 - Viewports¶

After a projection transformation your models are ready for clipping, which discards any primitive elements (points, lines or triangles) that are not inside the camera’s field of view. After clipping its time to create an image!

This lesson describes how a scene’s geometric data is mapped to a 2D image.

The Viewport Transformation¶

Your geometric data has (x,y,z) values which are inside a 2-by-2-by-2 clipping volume centered at the origin. Its time for the pipeline to start creating a 2D image. The image will be mapped into a HTML canvas element, so the image is created to be the same size (in pixels) as the canvas element . A WebGL image uses a coordinate system that has an origin in the lower-left corner, with the +X axis going to the right and the +Y axis going up, as shown in the image to the right. The vertex data from the clipping volume needs to be mapped into image locations. This is done with two simple transformations:

Scale the (-1,-1) to (+1,+1) viewing window to the image’s width and height.
Offset the lower-left corner at (-width/2,-height/2) to the image’s origin.

In matrix format, this transformation is

1
0
0
0
0
1
0
0
0
0
1
0
width/2
height/2
0
1
*width/2
0
0
0
0
height/2
0
0
0
0
1
0
0
0
0
1
*x
y
z
1
=xImage
yImage
zDepth
1
Eq2

Notice that we are only transforming the x and y coordinated of each vertex because we are creating a 2D image. The z component is carried along with the vertex, but its value remains unchanged.

You don’t implement the viewport transformation. It is done internally by the graphics pipeline. But you can specify that you only want your rendering to fill part of a canvas. By default, the width and height of your canvas is the viewport’s width and height. If you would like to render a smaller image, you can specify an offset and a size for the smaller image using the gl.viewport(x_offset,y_offset,width,height) function. The x_offset and y_offset parameters specify the offset from the lower left corner and the width and height specify the size of rendered image. The transformation for this smaller image is:

1
0
0
0
0
1
0
0
0
0
1
0
x_offset
y_offset
0
1
*1
0
0
0
0
1
0
0
0
0
1
0
width/2
height/2
0
1
*width/2
0
0
0
0
height/2
0
0
0
0
1
0
0
0
0
1
*x
y
z
1
=xImage
yImage
zDepth
1
Eq2

The following demonstration program renders two separate images into a single canvas. The first image is displayed in the entire canvas, while the second image is displayed in the lower-right corner.

Show: Code Canvas Run Info

viewport_example_render.js

/**
 * create_ortho_render.js, By Wayne Brown, Spring 2016
 */

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

// Global definitions used in this code:
var Learn_webgl_matrix, console;

//-------------------------------------------------------------------------
// Build, create, copy and render 3D objects specific to a particular
// model definition and particular WebGL shaders.
//-------------------------------------------------------------------------
var SceneViewportExampleRender = function (learn, vshaders_dictionary,
                                fshaders_dictionary, models, controls) {

// Private variables
  var self = this;
  var canvas_id = learn.canvas_id;
  var out = learn.out;
  var canvas_width;
  var canvas_height;

var gl = null;
  var program = null;
  var render_models = {};

var matrix = new Learn_webgl_matrix();
  var transform = matrix.create();
  var view_Rx = matrix.create();
  var view_Ry = matrix.create();
  var translate = matrix.create();
  matrix.translate(translate, -2, -2, -4.0);
  var scale = matrix.create();
  var base = matrix.create();
  matrix.scale(scale,6,6,6);

var world_camera = matrix.create();
  var camera = matrix.create();
  matrix.lookAt(camera, 0, 0, 5, 0, 0, 0, 0, 1, 0);
  var camera_distance = 10;

var world_orth = matrix.createOrthographic(-10, 10, -10, 10, -100, 100);

matrix.setIdentity(view_Rx);
  matrix.setIdentity(view_Ry);

// Public variables that will possibly be used or changed by event handlers.
  self.canvas = null;
  self.angle_x = 20.0 * 0.017453292519943295;
  self.angle_y = 10.0 * 0.017453292519943295;

self.fovy = 45.0;
  self.aspect = 1.0;
  self.near = 1.0;
  self.far = 10.0;
  self.change_canvas_size = false;

// For the 2nd canvas render
  var canvas2;
  var gl2;
  var program2;
  var render_models2 = {};
  var camera2 = matrix.create();
  matrix.lookAt(camera2, 0, 0, 5, 0, 0, 0, 0, 1, 0);

var model_names = ["textz","texty","textx","cubey","cubex","cubez","cube_center"];

//-----------------------------------------------------------------------
  function _setFrustumVertices() {
    var half_fovy = (self.fovy / 2) *  0.017453292519943295;
    var zn = self.near;
    var zf = self.far;
    var yn = self.near * Math.tan(half_fovy);
    var xn = yn * self.aspect;
    var yf = self.far * Math.tan(half_fovy);
    var xf = yf * self.aspect;

//l 1 2 3 4 1
//l 5 6 7 8 5
//l 1 5
//l 2 6
//l 3 7
//l 4 8
    var vertices = new Float32Array(
      [  xf,  yf, -zf,    xf, -yf, -zf, // line 1-2
         xf, -yf, -zf,   -xf, -yf, -zf, // line 2-3
        -xf, -yf, -zf,   -xf,  yf, -zf, // line 3-4
        -xf,  yf, -zf,    xf,  yf, -zf, // line 4-1
         xn,  yn, -zn,    xn, -yn, -zn, // line 5-6
         xn, -yn, -zn,   -xn, -yn, -zn, // line 6-7
        -xn, -yn, -zn,   -xn,  yn, -zn, // line 7-8
        -xn,  yn, -zn,    xn,  yn, -zn, // line 8-5
         xf,  yf, -zf,    xn,  yn, -zn, // line 1-5
         xf, -yf, -zf,    xn, -yn, -zn, // line 2-6
        -xf, -yf, -zf,   -xn, -yn, -zn, // line 3-7
        -xf,  yf, -zf,   -xn,  yn, -zn  // line 4-8
      ]
    );
    render_models.viewing_volume.updateBufferObject(render_models.viewing_volume.lines_vertex_buffer_id, vertices);
  }

//-----------------------------------------------------------------------
  this.render = function () {
    var j, ex, ey, ez, dist;

gl.viewport(0, 0, canvas_width, canvas_height);
    gl.scissor(0, 0, canvas_width, canvas_height);

// Clear the entire canvas window background with the clear color
    // out.display_info("Clearing the screen");
    gl.clearColor(0.95, 0.95, 0.95, 1.0);
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

// Calculate and set the camera for the entire rendering
    ex = Math.sin(self.angle_x) * camera_distance;
    ez = Math.cos(self.angle_x) * camera_distance;
    ey = Math.sin(self.angle_y) * camera_distance;
    dist = Math.sqrt(ex * ex + ey * ey + ez * ez);
    ex = (ex / dist) * camera_distance;
    ey = (ey / dist) * camera_distance;
    ez = (ez / dist) * camera_distance;
    matrix.lookAt(world_camera, ex, ey, ez, 0, 0, 0, 0, 1, 0);

// Create the base transform which is built upon for all other transforms
    matrix.multiplySeries(base, world_orth, world_camera);

// render the frustum
    _setFrustumVertices();
    render_models.viewing_volume.render(base);

// Create the base transform which is built upon for all other transforms
    matrix.multiplySeries(transform, base, camera);

// Draw each model
    for (j = 0; j < model_names.length; j += 1) {
      render_models[model_names[j]].render(transform);
    }

// Combine the transforms into a single transformation
    matrix.multiplySeries(transform, transform, translate);

// Draw each model
    for (j = 0; j < model_names.length; j += 1) {
      render_models[model_names[j]].render(transform);
    }

self.render2();
  };

//-----------------------------------------------------------------------
  this.render2 = function () {
    var j, width, height, x_offset, y_offset;

// Assume the 2nd window has a size that is half of the canvas.
    width = canvas_width / 2;
    height = canvas_height / 2;

// Adjust the size of the window based on the aspect ratio.
    if (self.change_canvas_size) {
      if (self.aspect >= 1) {
        height = width / self.aspect;
      } else {
        width = self.aspect * height;
      }
    }

x_offset = canvas_width - width;
    y_offset = 0;

gl.viewport(x_offset, y_offset, width, height);
    gl.scissor(x_offset, y_offset, width, height);

// Clear the entire canvas window background with the clear color
    // out.display_info("Clearing the screen");
    gl.clearColor(0.8, 0.8, 0.8, 1.0);
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

// Build individual transforms
    var perspective = matrix.createPerspective(self.fovy, self.aspect, self.near, self.far);

// Combine the transforms into a single transformation
    matrix.multiplySeries(transform, perspective, camera);

// Draw each model
    for (j = 0; j < model_names.length; j += 1) {
      render_models[model_names[j]].render(transform);
    }

// Combine the transforms into a single transformation
    matrix.multiplySeries(transform, transform, translate);

// Draw each model
    for (j = 0; j < model_names.length; j += 1) {
      render_models[model_names[j]].render(transform);
    }

};

//-----------------------------------------------------------------------
  this.delete = function () {
    var j, name;

// Clean up shader programs
    gl.deleteShader(program.vShader);
    gl.deleteShader(program.fShader);
    gl.deleteProgram(program);

// Delete each model's VOB
    for (j = 0; j < models.number_models; j += 1) {
      name = models[j].name;
      render_models[name].delete(gl);
    }

// Remove all event handlers
    var id = '#' + canvas_id;
    $( id ).unbind( "mousedown", events.mouse_drag_started );
    $( id ).unbind( "mouseup", events.mouse_drag_ended );
    $( id ).unbind( "mousemove", events.mouse_dragged );
    events.removeAllEventHandlers();

// Disable any animation
    self.animate_active = false;
  };

//-----------------------------------------------------------------------
  // Object constructor. One-time initialization of the scene.

// Get the rendering context for the canvas
  self.canvas = learn.getCanvas(canvas_id);
  if (self.canvas) {
    gl = learn.getWebglContext(self.canvas);
  }
  if (!gl) {
    return;
  }

// Set the size of the canvas
  canvas_width = self.canvas.clientWidth;
  canvas_height = self.canvas.clientHeight;

gl.enable(gl.SCISSOR_TEST);

// Set up the rendering program and set the state of webgl
  program = learn.createProgram(gl, vshaders_dictionary["shader05"], fshaders_dictionary["shader05"]);

gl.useProgram(program);

gl.enable(gl.DEPTH_TEST);

// Create Vertex Object Buffers for the models
  var j, name;
  for (j = 0; j < model_names.length; j += 1) {
    name = model_names[j];
    console.log(name);
    render_models[name] = new Learn_webgl_model_render_05(gl, program, models[name], out);
  }

render_models.viewing_volume = new Create_dynamic_model(gl, program, models.viewing_volume, out);

// Set up callbacks for user and timer events
  var events;
  events = new CreateViewportExampleEvents(self, controls);

var id = '#' + canvas_id;
  $( id ).mousedown( events.mouse_drag_started );
  $( id ).mouseup( events.mouse_drag_ended );
  $( id ).mousemove( events.mouse_dragged );

};

An example of a viewport rendering. The entire canvas is being rendered with a view of a virtual world, while a second rendering is being placed into a lower-right viewport.

Manipulate the parameters of the createPerspective(fovy,aspect,near,far) function:

fovy : 5.0 179	Field-of-view (y axis) = 45 degrees
aspect : 0.1 5.0	aspect = 1.00 (width/height) Change canvas size to match aspect ratio.
near : 0.1 10.0	near = 1.0
far : 2.0 20.0	far = 10.0

Shader errors, Shader warnings, Javascript info

Open this webgl program in a new tab or window

To accomplish the two renderings in a single canvas you also have to use a gl.SCISSOR_TEST. The default behavior for all WebGL commands is to operate on the entire image it is creating. If you want to change only a portion of the image, you can enable the gl.SCISSOR_TEST and set the limits of the image that can be changed. If you study the code in the above example, the initialization code for the program enables the scissor test in line 266:

gl.enable(gl.SCISSOR_TEST);

When the entire canvas is rendered, the viewport and the scissor limits are set to the entire canvas in lines 131-132:

gl.viewport(0, 0, canvas_width, canvas_height);
gl.scissor(0, 0, canvas_width, canvas_height);

When the smaller image is rendered, the viewport and the scissor limits are set to the lower-right corner of the canvas in lines 195-196:

gl.viewport(x_offset, y_offset, width, height);
gl.scissor(x_offset, y_offset, width, height);

Mouse Events into World Locations¶

You sometime need to convert the location of a mouse cursor into a location in your 3D virtual scene. Since you are viewing a 3D world, a mouse location actually identifies an infinite number of points that lie on a ray from the camera through the mouse’s location into the 3D world. You can convert a mouse location into a viewing window location using simple proportions. Study the two diagrams below.

The screen coordinates used by a mouse have the +Y axis going down the screen, but this does not matter if you use the same distances for your proportions. In both diagrams we measure distances from the left side and the top side. We use the variables left, right, bottom and top that were used to define our projection matrices to describe the world viewing window. Let’s use canvas_width and canvas_height to describe the size of the canvas window. The relative distances in both windows must be the same. Therefore:

x_mouse / canvas_width  === (x_world - left) / (right - left)
y_mouse / canvas_height === (top - y_world)  / (top - bottom)

If you know a mouse location, (x_mouse, y_mouse), you can solve the above equations to calculate the equivalent location in the virtual world on the viewing window. That is:

x_world = [(x_mouse / canvas_width) * (right - left)] + left;
y_world = top - [(y_mouse / canvas_height) * (top - bottom)];

If you want to convert a location in the viewing window to a mouse location, you can solve to get these equations:

x_mouse = [(x_world - left) / (right - left)] * canvas_width;
y_mouse = [(top - y_world)  / (top - bottom)] * canvas_height;

Glossary¶

viewport: The portion of an HTML canvas you want to render into. The default viewport is the entire canvas.

Next Section - 8.5 - Summary of Projections and Viewports