Getting Started with TWGL m4 (matrix library)

by Mike Gleicher on September 16, 2015

in 559 Graphics

For the programming assignments, you will need some basic matrix support to do transformations. You could program this yourself, but you are also welcome to use a matrix library that does it for you. Doing it yourself is good because you have to understand it – but it’s a lot of busywork. Learning to use a matrix library is a better idea, since its what you need in the “real world”.

For doing graphics, we need 4×4 matrices and the associated vectors. There are a few JavaScript libraries out there for this. glmatrix is the best known. I will recommend that you use the “m4” part of “twgl” since twgl will be useful later in the class. This isn’t a judgment on whether twgl.m4 is better than glmatrix – it’s good enough, and easy.

The twgl webpage is here. The link to the documentation is hidden at the bottom (documentation). Even then, you need to look in the upper right corner of the window to find the real things you need. The documentation for the matrix library (m4) is here – but that’s just for the matrix class. The vector class is documented separately. Even then, there are class documentation, but no general guidance on how to get started.

Hence, a tutorial.

Getting Started With TWGL

To use twgl, you need to load it in your html page (load it before your script). If you want to have it load fast, use the minified version. If you want to be able to read the code, use the other version. Either way, you need the “full” version so it has matrices.

I have put a copy of twgl on the graphics group web server so you can access it from JSBin programs. Or you can put the file in your local directory so it loads fast. For things you turn in, its best to refer to the online version – or you can turn in a copy of the library with your handin.

Loading twgl adds one global “variable” – twgl. This is using javascript objects as namespaces and modules (something to get used to as a JavaScript programmer). Within twgl, there is a field called “m4” that is another object that contains the matrix library. I find it’s easiest to create a variable called just “m4” so I don’t need to keep referring to twgl.m4.

4×4 matrices in twgl are actually 1D arrays of length 16 – not really 2D arrays. In fact, they aren’t even normal JavaScript arrays – they are special “Float32Array” which stores things so its easy to pass to WebGL (when you get to that). The m4 functions will take any array of length 16 when they expect a matrix. And the Float32Array generally work just like regular arrays (where each element is a number). Matrices are stored in column major order – which is a little weird. See my other tutorial for an explanation. GlMatrix has the same issue, and explains it on its webpage.

Similarly, points and vectors in twgl.m4 are arrays of length 3. It will always make Float32Array, but you can use any array of length 3 as input to its functions.

To help me experiment with twgl.m4, I wrote something simple that prints out points and matrices so I can try things out. You can look at it here. (link to jsbin, I am not embedding it).

One of the things you’ll notice is that twgl doesn’t have 4 vectors – just 3 vectors. It treats 3 vectors as 4 vectors as 4 vectors with the last component being 1. Most of the time it’s OK. If you have a transformation that does something to the W component (like a projection), when you use the m4.transformPoint function, it will do the divide by w for you. Beware.

Using TWGL.M4 with HTML5 Canvas

Most of the time, the HTML5 Canvas matrix stack is just fine. But, if you want to use twgl with it (for example, to practice using twgl before we get to WebGL, or a class assignment). The only trick is that you need to apply the transforms you have to each point yourself.

Here is a simple example – a triangle (what’s simpler? I guess I could have just made a line) spinning. Done with both regular canvas and with twgl. Rather than discussing it, I just put lots of comments in the code to help you understand. Again, the link is to JSBin – no embedding.

You probably want to understand this program.

Print Friendly, PDF & Email

Previous post: