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
-- The WebGL 1.0.2 spec is what passes
for documentation
-- The OpenGL ES 1.0 Shader Language
Document
-- The WebGL 1.0 Quick Reference Card
