WebGL2 Fundamentals, lessons that start from WebGL rather than from OpenGL

The argument for not teaching OpenGL

The premise of the series is stated in the first lines of the project documentation and it is a pedagogical position rather than a technical claim. Most WebGL lessons are based off OpenGL, and the reasoning given against that is age: OpenGL is twenty years old, its lessons do not match WebGL well, the APIs have changed too much, and the ideas behind OpenGL and its tutorials are out of date with WebGL, OpenGL ES 3.0 and the world of shaders. From there comes the series argument that WebGL is actually a very simple API, and that what makes it look complicated is the way it is used, with the complications added by the programmer rather than by the API. The stated goal of the lessons is to show that simplicity while also teaching the fundamentals of 2D math and 3D math, so a reader can write their own WebGL programs and understand the complexity other programmers pile on top. The site itself is at webgl2fundamentals.org.

The lesson catalogue is organised by topic, not by project

The translation metadata doubles as a table of contents for the whole series, and it is worth reading as a curriculum. The categories are fundamentals, image processing, matrices, 2D translation rotation scale and matrix math, 3D, lighting, structure and organization, geometry, textures, rendering to a texture, 2D, text, misc and reference. That ordering is the argument of the series in compressed form. A reader starts with fundamentals, picks up the 2D math and matrix material, moves into 3D, then lighting, then the practical graphics topics, and finishes with rendering to a texture as the bridge to the more advanced work. Image processing sits early because it needs almost no geometry, which is a common first practical step. The primary language recorded for the repository is HTML, which fits a site whose content is prose plus runnable examples rather than a library with an API.

Translations are a directory, a config file and a table of contents

The translation system is the most detailed part of the project documentation, and it explains how a site of this kind stays maintainable across languages. Each translation lives in a folder under `webgl/lessons/<country-code>`, and three files are required: a `langinfo.hanson`, an `index.md` and a `toc.html`. The `langinfo.hanson` file holds the language-specific options, in a format called Hanson that is JSON-like but allows comments, which matters because the file is meant to be edited by translators. The fields cover the language name shown in the selection menu, the caption that appears under examples, the title and description on each page, the link to the language root, the HTML that appears after the article and before the comments, the message shown for untranslated articles, the phrase for the table of contents, and a mapping from the English category names to their translations.

{
  // The language (will show up in the language selection menu)
  language: 'English',

  // Title that appears on each page
  title: 'WebGL Fundamentals',

  // Basic description that appears on each page
  description: 'Learn WebGL from the ground up. No magic',

  // the phrase "Table of Contents"
  toc: "Table of Contents",
}

How a missing translation is handled

The build process solves the linking problem in a way that is worth stealing. If an article has an English markdown file in `webgl/lessons` but no counterpart in a given language, the build generates a placeholder HTML file for it and fills it with the `missing` message from the language config, which includes a link back to the original English article. The stated reason is to make it easy to include links in one article that point to another article which has not been translated yet, so a translator does not have to go back and fix already translated articles; you translate one article at a time and leave the links as they are, and they resolve to placeholders until someone catches up. Articles carry front matter at the top with a title, a description used in RSS and social media tags, a category, and localized table of contents text, and one field is flagged as staying in English. The table of contents template is shared between the index and every article, and the only parts that are not auto-generated are the links at the end, which a translator may adjust.

Diagrams take their labels from the URL

The interactive diagrams are localised through query parameters, which is a neat piece of engineering and explains why the documentation spends time on it. A diagram with a slider named rotation can be given a translated label by appending a query parameter to its URL, and for two or more translations the parameters are separated with an ampersand. Since characters like equals, hash and ampersand are not allowed raw in a URL, they have to be uri encoded, which the documentation shows in a worked example. For labels that are baked into the example code rather than exposed as options, you have to look inside the example itself, and the documentation shows the `lang` object pattern used for that, with a default English string for each label that a translation overrides by passing the same option. The effect is that a diagram in a Japanese lesson shows Japanese axis labels without the tutorial having to fork the example. There is also a per-language stylesheet option, included only if it exists, used mainly to pick fonts, and the author asks explicitly that ligature code fonts not be used because they hide the characters a tutorial needs to show.

How the site is built and served

The build is Grunt based, with a custom lesson builder and a live editor pulled from GitHub at pinned tags. The `package.json` shows the toolchain: grunt and grunt-cli with the clean, copy, watch, eslint and jsdoc tasks, the eslint plugins for google camelcase, html, one variable per var, optional comma spacing and require trailing comma, plus a dependency check step, a static server called servez, and minami for the generated documentation. The scripts show the intended workflow: `build` runs the dependency check and then grunt, `watch` rebuilds continuously, `start` serves the `out` directory, and the test command checks the generated HTML for errors with a script named check-all-the-errors. The dependency check exists because the lesson builder and live editor are referenced by commit tag rather than by a published version, so the tags have to be verified before a build. The repository also has a `3rdparty/` directory, a `build/` directory, a `source_assets/` directory, a `CNAME` for the domain, and a `toc.hanson` at the root holding the master table of contents.

What is unfinished, and how it is said

Two honest caveats close out the picture. The first is that the project says outright that this is work in progress and invites contributions, with a `todo.md` at the root tracking what remains, and the contributing guidance asks new article authors to take one step at a time, not to do two or more things in a single step, to explain new math in the simplest terms possible, and ideally to use diagrams. That is a description of a curriculum under construction rather than a finished textbook. The second is a licensing inconsistency worth checking before you reuse anything. The repository is recorded as BSD-3-Clause, while the `package.json` in the same repository names MIT in its licence field, and the `LICENSE` file at the root is the authority. Nothing in the project documentation explains the discrepancy, so anyone redistributing the lesson text or the examples should read the file rather than trust the badge.

Editorial conclusion

Adopt this tutorial series if you are learning WebGL2 and want the mental model to match the API you will actually ship, and skip it if you need a specific topic reference or a production library, because it is a set of lessons in progress rather than a maintained framework. Verify three things before you rely on it: that the lesson you need exists, since the project states it is work in progress and a todo file tracks what is not yet written; which language version you land on, since some articles are untranslated and show a placeholder instead; and that the licensing is what you expect, because the repository is recorded as BSD-3-Clause while the package metadata in the repository names MIT.

Frequently asked questions

Official sources

1. gfxfundamentals/webgl2-fundamentals on GitHub
2. Issues
3. License: BSD-3-Clause
4. Project website
5. README