Add draft documentation and updated API docs

Author: jeremyong

docs/js/extra.js

@@ -1,16 +1,20 @@
 (function () {
     'use strict';
 
+    var macros = {
+        '\\ee': '\\mathbf{e}',
+    };
+
     var katexMath = (function () {
         var maths = document.querySelectorAll('.arithmatex'),
             tex;
 
         for (var i = 0; i < maths.length; i++) {
             tex = maths[i].textContent || maths[i].innerText;
             if (tex.startsWith('\\(') && tex.endsWith('\\)')) {
-                katex.render(tex.slice(2, -2), maths[i], { 'displayMode': false });
+                katex.render(tex.slice(2, -2), maths[i], { 'displayMode': false, macros });
             } else if (tex.startsWith('\\[') && tex.endsWith('\\]')) {
-                katex.render(tex.slice(2, -2), maths[i], { 'displayMode': true });
+                katex.render(tex.slice(2, -2), maths[i], { 'displayMode': true, macros });
             }
         }
     });

docs/js/tutorial.js

@@ -0,0 +1,67 @@
+const vs_src = `
+    attribute vec4 a_pos;
+    uniform mat4 u_mvp;
+    uniform mat4 u_proj;
+
+    void main() {
+        gl_Position = u_proj * u_mvp * a_pos;
+    }
+`;
+
+const fs_src = `
+    void main() {
+        gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
+    }
+`
+
+function init_canvas(cv) {
+    const gl = cv.getContext('webgl');
+
+    gl.clearColor(0, 0, 0, 1.0);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+}
+
+function load_default(gl) {
+    const prog = link_program(gl, vs_src, fs_src);
+    if (!prog) {
+        return null;
+    }
+
+    return {
+        prog,
+        a_pos: gl.getAttribLocation(prog, 'a_pos'),
+        u_mvp: gl.getAttribLocation(prog, 'u_mvp'),
+        u_proj: gl.getAttribLocation(prog, 'u_proj'),
+    }
+}
+
+function load_shader(gl, type, source) {
+    const shader = gl.createShader(type);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        console.error(gl.getShaderInfoLog(shader));
+        gl.deleteShader(shader);
+        return null;
+    }
+    return shader;
+}
+
+function link_program(gl, vs, fs) {
+    const vert = load_shader(gl, gl.VERTEX_SHADER, vs);
+    const frag = load_shader(gl, gl.VERTEX_SHADER, fs);
+
+    const prog = gl.createProgram();
+    gl.attachShader(prog, vert);
+    gl.attachShader(prog, frag);
+    gl.linkProgram(prog);
+
+    if (!gl.getProgramParameter(shaderProgram, gl.LINK_STATUS)) {
+        console.error(gl.getProgramInfoLog(prog));
+        gl.deleteShader(vert);
+        gl.deleteShader(frag);
+        return null;
+    }
+
+    return prog;
+}

docs/tutorial.md

@@ -0,0 +1,31 @@
+!!! danger
+
+    You are currently reading a DRAFT that is available publicly to facilitate collaboration
+
+In the [introduction](../intro), we considered a set of three basis vectors $\ee_1$,
+$\ee_2$, and $\ee_3$. In addition, we pontificated a bit on why restricting ourselves to
+vectors can cause issues, and argued for the need for a richer structure to match the
+richness of the geometry. But how should we go about doing this?
+
+In 3-dimensions, it seems a bit unfair that only "arrows"
+can be represented. After all, our world is filled with objects that have area and
+volume too. Suppose we wanted to represent a unit area in the x-y plane. Let's give it
+a name, say $\ee_{12}$. It seems reasonable that the areas $\ee_{13}$ and $\ee_{23}$.
+But wait! Our choice of of index order seems a bit arbitrary. What about $\ee_{21}$,
+$\ee_{31}$ and $\ee_{32}$. If we follow our nose a bit, it seems reasonable that the
+area represented by $\ee_{12}$ should equal $-\ee_{21}$. After all, they possess opposite
+orientations from one another. What about elements with two repeated indices? Like $\ee_{11}$
+or $\ee_{33}$? Well, such elements can't reasonably span any area, so let's get back to
+how we should handle those in a moment. Like the unit vectors, it seems sensible to allow
+us to scale these area-elements with a weight (like $3\ee_{12}$) and add them together
+to create areas of arbitrary weight and orientation. So, for example, let's try to add
+$\ee_{12} + 2\ee_{23}$. What should its orientation be?
+
+TODO!
+
+For volumes, we have one choice that spans a non-zero volume which is $\ee_{123}$. We
+could have also chosen a different basis ordering, which again we'll get back to later.
+Let's call our single-index elements _vectors_ as before, the two-index elements _bivectors_,
+and the three-index elements _trivectors_.
+
+TODO!

docs/tutorial/exterior_algebra.md

@@ -0,0 +1,66 @@
+!!! danger
+
+    You are currently reading a DRAFT that is available publicly to facilitate collaboration
+
+<script src="../../js/tutorial.js"></script>
+
+This guide is meant to be a gentle intro to Projective Geometric Algebra,
+also referred to as $\mathbf{P}(\mathbb{R}^*_{3, 0, 1})$. It assumes no
+knowledge of quaternions and dual-quaternions, but if you have some familiarity
+of either, you may find yourself armed with a new appreciation for them. Also not assumed
+is any knowledge of abstract algebra, or any specific algebra closely related to Geometric
+Algebra (e.g. exterior algebra, Clifford Algebra, etc.).
+
+The emphasis first is on just getting familiarity with the notation and the various
+operations and what they do. The [references](../../references) page on the left contains
+some excellent references if you prefer a bottom up approach. Here though, the goal will
+be to build your intuition primarily through examples, and then introduce the formalism
+afterwards.
+
+!!! tip
+
+    Grab a pen and paper! You are expected to work out a number of expressions by hand
+    and _see_ for yourself that the formulae behave as advertised. Further, drawing pictures
+    is _very_ important to maintain the linkage between the algebra and the geometry.
+
+We're going to go straight to 3D, so hang on tight. Let's start with three perfectly
+ordinary basis vectors, $\ee_1$, $\ee_2$ and $\ee_3$. Now, normally when we think about
+vectors, we imagine that they have some length and direction. In this case, let's have
+$\ee_1$ point in the x-direction, $\ee_2$ point in the y-direction, $\ee_3$ point in the
+z-direction, and give all of them unit length. Each one of these basis vectors can be
+scaled by a weight, and we can take linear combinations of them to create any vector
+in our 3D space. So far, everything behaves just like your good ol' 3D vector space.
+
+Now, let's pause and consider for a moment what our vector space might be lacking. With
+vectors alone, we can certainly come up with ways to represent all sorts of things.
+Sometimes, vectors are arrows from the origin. Other times, we use vectors to mean the
+point terminated at by that arrow. Still other times, a vector is used to represent a
+plane through the origin by encoding the normal to the plane. In a way, vectors are
+somewhat encumbered due to the need to represent _all_ the various entities in geometry
+one way or another. But even if we try, we'll find that there are still aspects of geometry
+that we can't reasonably or easily represent with vectors. For example, what if the
+plane didn't go through the origin? I suppose we could use two vectors, one for the normal,
+and one to describe a point in the plane. What about a rotation? Maybe we use a vector
+for the axis, and a number for the rotation. Translations? Maybe the vector points in the
+direction of the translation and the length encodes the displacement. Do you see
+an issue with the way things are going with this thought exercise? All of these
+interpretations of what a "vector" is are not mutually compatible with one another! We
+certainly can't add a vector intended to be used as a rotation axis and a vector intended
+to be used as a plane normal and expect to have a consistent interpretation of the result.
+All of them need to be treated distinctly and live "in their own space" as it were, with
+very delicate code to keep the invisible boundaries between them uncrossed.
+
+Needless to say, mathematically, the situation described above leaves much to be desired.
+What we'd like is an algebra (aka the Geometric Algebra) that could describe all the entities
+we need (points, lines, planes, rotations, translations, to name a few) in a _unifying_
+framework glued by an operation which has a sensible meaning when its operands are any
+of the listed entities (aka the geometric product). To make this a reality though, we're
+going to need to move past our vector space and limited set of operations to an algebra
+that is much richer. This algebra (the Geometric Algebra) will have more operations than
+you're used to, and more "things" than you're used to, but that's to be expected. After all,
+geometry is far richer than just arrows emanating from the origin. Embracing the additional
+structure is in some sense, akin to embracing the reality that is geometry itself, and
+acknowledge that the algebra is going to need to play some catch up to describe the
+geometry more aptly. So, then, aside from vectors, what else do we need? In the next
+section, we'll describe the exterior algebra as a stepping stone to geometric algebra,
+so see you there!

docs/tutorial/intro.md

@@ -10,9 +10,10 @@ theme:
     tabs: false
   logo:
     icon: 'flip'
-site_url: https://jeremyong.com/klein
-repo_url: https://github.com/jeremyong/klein
-repo_name: 'jeremyong/klein'
+site_url: https://jeremyong.com/Klein/
+repo_url: https://github.com/jeremyong/Klein/
+edit_uri: ''
+repo_name: 'jeremyong/Klein'
 site_description: Klein - Realtime Projective Geometric Algebra
 site_author: Jeremy Ong
 copyright: 'Klein Copyright © 2020 Jeremy Ong'
@@ -36,19 +37,20 @@ nav:
       - 'Direction': 'api/kln::direction.md'
       - 'Mat4x4': 'api/kln::mat4x4.md'
       - 'Origin': 'api/kln::origin.md'
-  - 'Tutorial': 'tutorial.md'
+  - 'Tutorial':
+      - 'Introduction': 'tutorial/intro.md'
+      - 'Exterior Algebra': 'tutorial/exterior_algebra.md'
   - 'Klein Shell': 'shell.md'
   # - 'Benchmarks': 'benchmarks.md'
   - 'Roadmap': 'roadmap.md'
   - 'References': 'references.md'
 
-edit_uri: ''
-
 extra_css:
   - 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css'
 
 extra_javascript:
   - 'js/extra.js'
+  - 'https://cdnjs.cloudflare.com/ajax/libs/gl-matrix/2.8.1/gl-matrix-min.js'
   - 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js'
 
 markdown_extensions: