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

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

Something I just thought of: We're using the same definition for initially creating the drawing buffer (getContext) and restoring the drawing buffer: both point at 2.2.  Is this the right thing to do?  This appears to allow the context to be restored with different WebGLContextAttributes than it had before.  While I could (with some contortionism) contrive a use for this, in practice I think it won't actually happen and that it's just one more obscurity to worry about for "correct" context lost handling.

(This gives me a more general thought--creating contexts should always be consistent within the same execution environment.  I'll bring that up in a separate thread; it would solve this question as a side-effect.)

Reordered for dependencies:

On Wed, Dec 7, 2011 at 8:30 PM, Kenneth Russell <[email protected]> wrote:
> > - Defining "Invalidate all WebGLObject instances" more precisely.
> Let's fix this next. If you could suggest some wording I'll incorporate it.

Add to 5.3: Each WebGLObject has an invalidated flag, which is initially unset.
5.12.2: "Invalidate all WebGLObject instances..." becomes "4. Set the invalidated flag[link] of each WebGLObject instance created by this context."
5.14: "If any argument to the method is a WebGLObject which has been invalidated" becomes "If any argument to the method is a WebGLObject with its invalidated flag[link] set".

isTexture: Return true if texture's invalidated flag is unset and false otherwise.
isBuffer: Return true if buffer's invalidated flag is unset and false otherwise.
isFramebuffer: Return true if framebuffer's invalidated flag is unset and false otherwise.
isProgram: Return true if program's invalidated flag is unset and false otherwise.
isRenderbuffer: Return true if renderbuffer's invalidated flag is unset and false otherwise.
isShader: Return true if shader's invalidated flag is unset and false otherwise.

(None of these need "Returns false if the context's webgl context lost flag is set"; if that flag is set, the invalidated flag is always set.)

Should deleteTexture, etc. also set the invalidated flag?  Should deleteTexture, etc. raise an error if called with a WebGLTexture which has been invalidated?  If texture deletion and context-loss-invalidation are treated as the same thing (which seems to make sense, at least on first examination), then they probably shouldn't.

> > 5.14 doesn't say what the function (eg. getTexParameter) returns if passed
> > an invalidated texture.  It just says to generate an error and return.  I
> > think this should return the same thing it would if the context itself was
> > lost (eg. steps 1.1 and 1.2).  I'm having trouble thinking of a nice way to
> > spec that without copying-and-pasting those steps; I'll think about this and
> > get back if I come up with something.
> Added some words referring to the value that would be returned if the
> context were lost. What do you think?

Hmm.  Putting aside the wording for a moment, there's a odd side-effect: it's impossible for a function with a non-nullable return type to take a WebGLObject.  The return type would be undefined when we return in 2.3.  Maybe rename "explicit context lost handling" to "explicit error handling", making it a list of functions which simply skip these global error handling steps (a superset of what it does now).

Something like this:

1. If the called method is in the list of methods with explicit error handling, perform the implementation of the called method, return its result and terminate these steps.
2. Let use default return value be false.
3. If the webgl context lost flag is set, let use default return value be true.
4. If any argument to the method is a WebGLObject with its invalidated flag set, generate an INVALID_OPERATION error and let use default return value be true.
5. If use default return value is true, perform the following steps:
    5.1. If the return type of the called method is any or any nullable type, return null.
    5.2. Terminate this algorithm without calling the method implementation.
6. Otherwise, perform the implementation of the called method and return its result.

(This could probably be more concise, but it seems clear.)

> I see. All of these references have been updated in the new draft.
> Please point out if any were missed.

Also "Create a drawing buffer" in 2.1 step 5 and 5.15.3 step 3, linking to 2.2.

"Queue a task" -> http://dev.w3.org/html5/spec/webappapis.html#queue-a-task

> > - WebIDL now has a "dictionary" type, for specifying dictionaries of options
> > to functions.  We should use it here; it handles some finer details.  (For
> > example, if passed an object with getters, are they used?  If so, what order
> > are they called in?)  Using the same mechanism will make sure we answer
> > these details in the same way as other APIs.  I'm not sure exactly what this
> > will look like; DOM event constructors
> > (http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#constructing-events)
> > is probably a good starting point.
> To be clear, are you suggesting to make WebGLContextAttributes a
> dictionary? I don't see any other place in the spec where one would be
> relevant. Currently it's specified as [Callback], which seems to be
> sufficient for our purposes (taking user objects as arguments and also
> allowing the type to be returned from methods).

The second parameter passed to getContext would be a dictionary.  The WebGLContextAttributes type exposed by getContextAttributes would be unchanged.  DOM4 event constructors (eg. http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-customevent) are a good example of how to do this.  WebGLContextAttributesInit would look like:

dictionary WebGLContextAttributesInit {
    boolean alpha = true;
    boolean depth = true;
    boolean stencil = false;
    boolean antialias = true;
    boolean premultipliedAlpha = true;
    boolean preserveDrawingBuffer = false;

Step 4 of 2.1 would become something like:

4. If getContext() was invoked with a second argument, let options be that argument.  Otherwise, let options be an empty dictionary.
5. Convert options to an IDL value of type WebGLContextAttributesInit.  If the conversion threw an uncaught exception, then abort this algorithm, with that exception being passed through to the caller.
6. For each dictionary member present in options, find the attribute on contextAttributes whose identifier matches the key of the dictionary member, and then set the attribute to the value of that dictionary member.

References I used for this text are DOM4 [1] ("for each dictionary member..."), HTML structured clone[2] for passing through exceptions, and some suggested text and other edits from the WebIDL editor [3][4].  "Convert" should be a reference to [5] in WebIDL (rather than bold).  Several keywords in the DOM4 text are also links to WebIDL ("dictionary member", "identifier", etc.); please see [1].

Results of this (consistent with eg. DOM4 event constructors):

- Getter behavior is defined.  If _javascript_ getters are used, all getters for defined properties are guaranteed to be called; always in the order defined in the dictionary; and exceptions during these calls propagate outward.
- Conversion is defined, eg. canvas.getContext("webgl", {alpha: "text"}) results in alpha being true.
- Conversion errors are defined, eg. canvas.getContext("webgl", "pizza") throws TypeError.

The defaults listed in 5.2.1 would be removed, since they're defined by the IDL.

[1] http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#constructing-events
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#safe-passing-of-structured-data
[3] http://krijnhoetmer.nl/irc-logs/whatwg/20111208#l-205
[4] http://krijnhoetmer.nl/irc-logs/whatwg/20111209#l-178
[5] http://dev.w3.org/2006/webapi/WebIDL/#dfn-convert-ecmascript-to-idl-value

The task source for queued events needs to be defined: "The task source for these tasks is the WebGL task source."  I'm not sure where that should go; it affects the API globally.

Glenn Maynard