Re: [Public WebGL] Help with the WebGL Context Lost specification

On Tue, Nov 15, 2011 at 9:59 PM, Kenneth Russell <kbr@google.com> wrote:

3. If getContext() was invoked with a second argument, options, let context's context creation parameters be options, otherwise let it be the empty object, {}.
4. Create a drawing buffer using the settings specified in context's context creation parameters, and associate the drawing buffer with context.

We'll need to integrate the language from section 2.1 and 2.2 about handling of context creation parameters, buffers attached to the drawing buffer, etc. Perhaps these new steps can go at the beginning of Section 5.13 as you suggested, we can delete a little language from Section 2, and refer to Section 2 to define creation of the drawing buffer.

Â
The steps I meant in front of 5.13 are things that apply to all (or most) entry points.Â That is, something like:

Before performing the implementation of any method of the WebGLRenderingContext interface, the following steps must be performed:

1. If webgl context lost flag is set, and the called method is not in the list of methods with explicit context lost handling, perform the following steps and terminate this algorithm.
1.1. If the return type of the called method is any or any nullable type, return null.
1.2. Terminate this algorithm without calling the method implementation.
2. Otherwise, perform the implementation of the called method and return its result.

The following methods have explicit context lost handling:
- isContextLost, checkFramebufferStatus, getAttribLocation, getVertexAttribOffset, isBuffer, isEnabled, isFramebuffer, isProgram, isRenderbuffer, isShader, isTexture

This is a bit awkward, since I'm not aware of anything like this in other specs to draw from, but it's a start.Â I'm ignoring the concurrent thread about null return values (if that does lead to API changes, this is probably where they'd go).Â The synchronous context loss issue would also affect this; this is where checking for a newly lost context would go.

The isBuffer, etc. functions are in the list because their return value depends on the lost object flag of their argument; they don't care whether the context itself is currently lost or not, and should return false even if webgl context lost flag is set, not null.

Something this also needs to allow is handling extensions: extension methods (which aren't methods of WebGLRenderingContext) also need to perform these steps.Â If getExtension had a base interface instead of just returning "object" then it could just say "any method of the WebGLRenderingContext or any WebGLExtension interface...".Â I suppose "any method of the WebGLRenderingContext interface or any method of an interface returned by getExtension" might work.

Or perhaps we can rewrite section 2 to mainly comprise your steps, and delete most of Section 5.14. Do you have a preference?

I think the first paragraph of 2.1 can be removed: that's all either defined here, or by the upstream Canvas API itself.Â (Canvas already defines the "Subsequent calls to getContext ..." behavior, for example, so it doesn't need to be duplicated here.)

I wouldn't try to rewrite the drawing buffer creation parts of section 2 right now, since it'd be biting off too much at once.Â I'd add eg. "To create a drawing buffer, the following must be performed" somewhere at the top of section 2.Â That ties it to step 4 above ("4. Create a drawing buffer using the settings..."; note the change in italics), defining what that step in the algorithm means.

We'll need to add another step indicating that if creation of the drawing buffer fails, a webglcontextcreation error is fired at the canvas.

Right:

4. Create a drawing buffer using the settings specified in context's context creation parameters.
5. If drawing buffer creation failed, perform the following steps:
5.1. Fire an event with the name webglcontextcreationerror at canvas.
5.2. Return null and terminate these steps.
6. Associate the created drawing buffer with context.
7. Return context.

This reminds me of an issue that we discussed at length but didn't reach a conclusion: this algorithm is never supposed to return null, and doing so breaks things in the getContext spec.Â I'll raise that discussion again later.

Step 4 ("invalidate...") is loose.Â It would be more precise to set a flag on each object (eg. a lost object flag), and (as above) where queries, etc. are defined, say "if the lost object flag is set, return false; otherwise...".

This raises an excellent point; the current text around invalidating WebGLObjects (in the definition of the webglcontextrestored event) is really underspecified. As you suggest above, I'd really like to centralize the definition of invalidation of these objects, because modifying the spec of every entry point taking a WebGLObject to handle context loss will be hard to maintain. Perhaps we could create a separate paragraph or sequence of steps about invalidation of objects, refer to it, and expand it as needed.

This might be doable as part of the text sketched above: "if any parameter is an object with a lost object flag, and that flag is set, set the WebGL error state and return".

I'd like to punt on this and context loss interruption for the moment, so we don't get bogged down trying to solve too many things at once.

What would you think about creating a copy of the spec in the Subversion repository to which we can apply your edits and see how they look? I don't know how easy or difficult it would be to get you write access, but Gregg, I or others can help check in your changes as they evolve.