Information about WebGL for the Graphics Professional

There are many aspects of WebGL 1.0 that are somewhat documented and somewhat undocumented. These lacuna are very annoying. Well-meaning web pages that repeat tutorials for absolute beginners over and over again clutter the search engine space and make finding solutions diffiicult.

This post does not have information for beginners or dilettantes.   These notes are for the serious graphics person who is trying to get work done and wants to be more productive. Some of what follows are hard facts or details, some are loose impressions or generalizations.  

-- WebGL is deeply intertwined into Javascript, DOM and the browser, so you must know exactly what you are using because there are differences.

-- Chrome's javascript does not allow "const" in strict mode

-- Chrome's browser throws security violations when attempting to load a texture map

-- Firefox's javascript allows const and does not throw security violations (on linux)

-- Failure to test on your selected OS & browser delivery targets will bite you in the ass

-- You must be very aware of this as you desperately try to get information from the internet

-- Do not assume anything from other OpenGL's will be there.

-- WebGL is not OpenGL ES 2.0

-- WebGL 1.0.2 is derived from OpenGL ES 2.0, but they are not identical

-- WebGL is closeer to OpenGL ES than any of the other OpenGLs though

-- There are almost no carryovers of concepts and ideas and intent from the earlier OpenGLs

-- This is a VERY low level graphics interface, you will reinvent the wheel over and over

-- The WebGL shader language is the same as the shader language of OpenGL ES 1.0 GLSL.

-- Documentation is broken

-- The Khronos site does have a WebGL 1.0.2 specification.

-- The specification is highly concise (at best) or just incomplete (at worst)

-- The shader language is not described beyond the statement that it is the same as GLSL ES 1.0

-- The documentation for GLSL ES 1.0 Shader Language documentation is excellent (see link)

-- There is a pretty good concise WebGL synopsis in PDF form (see link)

-- There is no active forum, the one on Khronos was killed years ago

-- There are a few helpful tutorials on the Khronos site, but not too many, some are wrong

-- The examples on Khronos use techniques that have not worked for years (loading textures)

-- There are relevant articles on the Mozilla developer site, but they are incomplete and the

comments are closed

-- WebGL is fragile and unhelpful

-- Things have to be done exactly their way or it will not work

-- Once something does not work, other errors cascade from it, some of them inexplicable

-- Relentlessly check for webgl errors, do not assume things worked

-- Errors appear either as return codes from WebGL, or in browser error windows, or not at all

-- Most of the WebGL error messsages just say "error"

-- Remember that checking for errors will slow you down, so they must be removed for

production code
-- Sometimes when a problem is unsolvable, I move on to other problems, then come back,
rewrite from scratch using the exact same techniques and everything works.

-- Specific Issues

-- drawArrays "count" is not well defined. It probably wants the number of vertices,

not the number of drawn elements (e.g. triangles) or number of floats, etc.

-- drawElements restricts the number of elements to what will fit in a short. This is not

enough to be useful for many if not most applications

-- The documentation for how to load a texture is wrong and will cause security violations

on modern browsers, it is not clear how much the CORS solution helps
-- texture maps must be exact powers of two in size

-- "const" is not cross-browser, do not use

-- functions are only defined in the shader portion being compiled. A function defined in

a vertex shader will not be available in a fragment shader

-- functions must be defined before use (prototypes may work)

-- Recommendations

-- Use the strict mode of javascript

-- Write or pick a matrix manipulation package for javascript. I use gl-matrix.js

-- Expect to write your own display list manager, object manager, texture manager, etc

-- Expect to spend a lot of time reverse engineering the documentation

-- Be very cautious about what you read on the internet. It is often out of date or applies to

something else that sounds similar but isn't
-- Of course the above warning applies to this post as well.  

-- Test on your target platforms as you develop.  Don't be surprised at the end.

-- Links

-- Article on cross domain textures disabled

http://hacks.mozilla.org/2011/06/cross-domain-webgl-textures-disabled-in-firefox-5/

-- The WebGL 1.0.2 spec is what passes for documentation

http://www.khronos.org/registry/webgl/specs/latest/1.0/

-- The OpenGL ES 1.0 Shader Language Document

http://www.khronos.org/registry/gles/specs/2.0/GLSL_ES_Specification_1.0.17.pdf

-- The WebGL 1.0 Quick Reference Card

http://www.khronos.org/files/webgl/webgl-reference-card-1_0.pdf