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[1].
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[2] 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 ([3]) and 2d canvas[4]. It omits all mention of "first" and "subsequent calls", since canvas.getContext already describes that case. HTML defines "fire a simple event"[5], 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.
[1]
http://dev.w3.org/html5/spec/the-canvas-element.html#dom-canvas-getcontext
[2]
http://dev.w3.org/html5/spec/the-canvas-element.html#getcontext-return[3]
http://dev.w3.org/html5/spec/the-canvas-element.html#primary-context
[4]
http://dev.w3.org/html5/2dcontext/#conformance-requirements[5]
http://dev.w3.org/html5/pf-summary/browsers.html#fire-a-simple-event