Tutorials

These tutorials are targeted at people with a reasonable web programming knowledge (HTML and JavaScript languages) and a basic web 3D programming knowledge (WebGL API).

Tutorial 1 : The Math Component

This tutorial provides a basic overview of the Math component, showing some of the many mathematical and geometric tools handled by SpiderGL. It also contains some interesting examples of "out of place" and "in place" function, explaining the different use of these method calls.

View DemoDownload Source

One of the weak points of coding graphic applications with WebGL is the complete lack of mathematical structures. This is mainly due to the fact that JavaScript is a loosely typed language, that means that you can use the same variable for different types of information: in particular it provides only a single statement ("var") for the different primitives types (numeric, boolean or string), and two extra statements ("array" and "object") for complex types.

In order to fill these gaps SpiderGL supplies the Math component, which is entirely dedicated to mathematic and geometric tools provided to manage all those algebraic structures, such us vectors, matrices and quaternions, that are essentials for developing graphic applications.

The Math component is split in six classes, each of which relative to a particular algebraic structure contains fields and methods linked to it. These classes, easily accessible through the namespace system introduced in the previous lesson, are:

  • Mat3
  • Mat4
  • Quat
  • Vec2
  • Vec3
  • Vec4

Mat3 and Mat4 provide functions than operate respectively on 3x3 and 4x4 matrices (generally considered in column-major order), represented as standard JavaScript arrays of length 9 and 16.
Vec2, Vec3 and Vec4 provide functions that operate respectively on two-, three- and four- dimensional vectors (considered as column vectors), represented as standard JavaScript arrays of length 2, 3 and 4 respectively.
Lastly the Quat name space provides functions able to operate on quaternions, represented as standard JavaScript arrays of length 4.

Let us have a look at the source code of this tutorial. We leave out the HTML elements and the JavaScript from Lesson 0, and we will focus the attention on the JavaScript function called "tutorial".

In the first lines, after the definition of three (3-dimensional) JavaScript arrays (geometrically interpretable as points in 3D), it is shown some examples of SpiderGL math functions that manipulate them.
The first two of such methods perform two subtraction of combinations of 3-dimensional points earlier defined, using the command "sub" of the classes Vec3 (quickly accessible with the name space "SglVec3"). The results, from a geometric point of view, can be seen as the vector which applied to "point0" allow to obtain respectively "point1" and "point2". 

var vector01 = SglVec3.sub(point1, point0); 

var vector02 = SglVec3.sub(point2, point0);

The following code allows to calculate the normal to a plane containing the two vectors "vector01" and "vector02" just defined, as an example of how to combine two SpiderGL methods (in this case both places in the classes Vec3), such ""cross" (which performs the cross product over the input vectors) and "normalize" (which normalize the input vector). 

var normal = SglVec3.normalize(SglVec3.cross(vector01, vector02));

Everyone code 3D graphics application knows how important is to handle matrices (to project the scene, to rotate or translate geometric entities, etc.). The next lines of code show some methods suitable for these purposes among those that we can find in the math Mat4 class.
As first example, we calculate the 4x4 translation matrix corresponding to apply a specific translation vector: 

var translationMat = SglMat4.translation([1.0, 2.0, 3.0]);

The next code, instead, returns a 4-dimensional counter-clockwise rotation matrix taking as input a rotation angle (in radians) and a rotation (normalized) axis: 

var rotationMat = 
   SglMat4.rotationAngleAxis(sglDegToRad(75.0), [0.0, 1.0, 0.0]);

Note that the previous line of code contains another useful SpiderGl math method, that is "degToRad", to convert degrees in radians.
A geometric transformation matrix which composes the two transformation just calculated can be obtained by multiplying them together. This operation is extremely simple in SpiderGl, by using the "mul" method: 

var transformationMat = SglMat4.mul(translationMat, rotationMat);

All the examples presented so far show how to manage vectors and matrices "out of place", i.e. with a function call that returns a new array. But in some cases it is more comfortable and quicker to modified directly the input values. In this case SpiderGl provides the "in place" functions (recognizable by the "$" symbol at the end of the method name).
An example of that is: 

SglVec3.adds$(vector01, 1.5);

that allows to add all the values of a 3-dimensional input vector with a chosen scalar, but this time the function does not return anything and changes directly the first operand (in our example the "vector01" vector).
The possibility to use this two types of function call (available for mostly of the provided methods) is able to streamline the work of the programmer.
Note that the last line of code presents another SpiderGl math agreement: the "s" after the operation name ("add" in this case) means that the function takes a scalar as second operand.

That's enough for this lesson! However, we underline that this is just a small taste of the SpiderGL mathematical component capabilities! For a complete overview we remind to browse the online documentation of the code.

In the next tutorial we will explain how SpiderGL manages the various file requests, both in the synchronous and in the asynchronous way.

Tutorials List