I think it would be clearer if described as part of "2.1 The canvas Element". There are a couple other things I notice in that section.
- It says "when called for the first time", which raises the question: what happens if the first call fails and you call it again? It might succeed a second time, for example if hardware resources have since become available; the spec is unclear about this case. (For example, if the first call fails, the WebGLContextAttributes passed to a subsequent call should probably *not* be ignored.)
- It doesn't say that null is returned on error. That's way down in webglcontextcreationerror, which is an odd place to specify getContext behavior.
- The "first call/subsequent calls" logic should be unnecessary now: that behavior is specified by the Canvas element.
Also, it's not specified whether webglcontextcreationerror bubbles or is cancelable.
For what it's worth, this is how I'd describe it:
> 2.1 The canvas Element
> When the getContext method of a canvas [CANVAS]
element is to return a new object for the contextId
webgl, the user agent must run the following steps:
> 1. Create a new WebGLRenderingContext object and associated drawing buffer.
> 2. If an error is encountered creating these objects, fire a simple event named "webglcontextcreationerror" at the canvas element, clear the primary context of the canvas, return null and terminate these steps.
> 3. Return the WebGLRenderingContext.
This aligns with the wording used by the getContext () and 2d canvas. It omits all mention of "first" and "subsequent calls", since canvas.getContext already describes that case. HTML defines "fire a simple event", which also specifies that the event does not bubble and is not cancelable.
The "clear the primary context" part in step 2 shouldn't be necessary;
the getContext algorithm in the HTML should specify this. I'll mail whatwg asking about this, since getContext seems to assume that "Return a new object for contextId" can never fail.