[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


Some minor issues:

In 2.1 it says "drawing buffer lost flag" but in 5.14 it says "webgl context lost flag"

In 5.15.2 it says

"getError returns CONTEXT_LOST_WEBGL the first time it is called while the context is lost. Afterward it will return NO_ERROR until the context has been restored."

That to me suggests that after the context is restorde I might get old errors. I think it used to say something about clearing all errors. Should it still say something like that?

On Tue, Dec 6, 2011 at 3:06 PM, Kenneth Russell <kbr@google.com> wrote:
On Wed, Nov 16, 2011 at 5:48 PM, Glenn Maynard <glenn@zewt.org> wrote:
> 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.
> Sounds fine.  I could use git-svn with GitHub, if someone over there is
> familiar with it.

Sorry for the long delay getting back to this.

The changes discussed above have been applied to this copy of the spec:


Here are the details of the changes, which are also in the Subversion
history of the file:

 - Section 2 (Context Creation and Drawing Buffer Presentation)
  - Removed two redundant sentences from introductory paragraph
  - Section 2.1
    - Renamed from "The canvas element" to "Context Creation"
    - Incorporated Glenn's suggested changes to this section, with slight
      modifications to setting up of context creation attributes and
      firing of context creation error
    - Added citation of WHATWG Wiki defining 'webgl' context type for
  - Section 2.2
    - Added sentence at beginning defining term "create a drawing buffer"
    - Moved statement about which context creation attributes must be
      honored to this section from Section 2.1
 - Section 5.2 (WebGLContextAttributes)
  - Changed "native object" to "user object" to match Web IDL spec
 - Section 5.14 (The WebGL context)
  - Added introductory text about handling of lost contexts and
    invalidated WebGLObjects
  - Changed docs for getContextAttributes() indicating it returns a new
    object each time
  - Changed isContextLost() to refer to context lost flag defined earlier
 - Section 5.15 (WebGLContextEvent)
  - Defined "fire a WebGL context event"
 - Section 5.15.2 (The Context Lost Event)
  - Defined in terms of sequence of steps
  - Incorporated previously-defined behavior of various methods while
    context is lost

How do these look at least as a start? What should be done next?