Re: WebGL | 3D Context for Canvas API

Hi Arun,

On Dec 11, 2009, at 00:06 , Arun Ranganathan wrote:
> Today, the WebGL WG at Khronos [1] released a public draft of the WebGL specification [2], and we really welcome (and need) wide review.

Thanks for keeping us appraised of your progress, please continue to do so as WebGL progresses. It's exciting stuff indeed!

It would be great if someone (or several people) on this WG were to take an action to review this draft in detail. My 3D days are a bit too far away for me to get far into the technical side.

Some notes:

  - Could you clarify your usage of RFC 2119 normative terminology? You cite it in reference but it's unclear in the actual prose when a normative term is intended or when the editor might have used one such term as just regular English. Notably "shall" seems to be used a fair bit, which is a 2119 term but rarely used so that clarifying its use would be helpful. Furthermore it would be good if testable assertions were written as such (see http://dev.w3.org/2008/dev-ind-testing/extracting-test-assertions-pub.html), for instance "But the contents shall no longer be shown on the page" -> "When WebGLRenderingContext is detached from its Canvas object, the user agent MUST/SHALL stop displaying it" (or something like that).

  - Providing definitions of terms and cross-linking them throughout the document would be helpful.

  - 2.1 "Subsequent calls to getContext() with the same string shall return the same object" and "On subsequent calls to getContext() with the ‘webgl’ string, the passed WebGLContextAttributes object, if any, shall be ignored." Presumably that's subsequent calls on the same element object?

  - 2.2 "Changing either of [the width or height] attributes shall cause the drawing buffer to resize and its contents to be cleared to (0,0,0,0)." If I call setAttribute or use .width to set these to the same value that they already have (i.e. change them, but without changing the actual value) does the clearing take place?

  - 3 "textures, buffers (i.e., VBOs) framebuffers," There's a missing comma.

  - 3 "Furthermore, the DOM object is guaranteed to exist as long as the author has an explicit valid reference to it OR as long as it is bound by the underlying graphics library." There probably isn't a need to capitalise the "OR". What does it mean for a DOM object to be bound by an underlying graphics library? This sounds implementation specific though it appears to want to be normative.

  - 4.1 "If a caller attempts to access any data outside of that range, an implementation may choose to raise an exception, use the closest valid index, use 0, or any other approach that prevents it from providing access to uninitialized data." Is it possible that you would agree on a single error handling behaviour for this case?

  - 4.2 "the WebGL implementation must ensure that the shader cannot access either out of bounds or uninitialized data" Same thing, can it be defined what happens in such a case?

  - 5.1 "The keys identify the feature being set to the given value, which is typically a boolean ("true" or "false") or numeric value." The IDL and subsequent prose makes the values be DOMStrings. Automatic conversion will make it work anyway, but couldn't the API just accept "any" instead?

  - You don't ever use NoInterfaceObject, is the intent that all interfaces be exposed in the global scope?

  - 5.3 "The underlying object is created as if by calling glGenBuffers , bound as if by calling glBindBuffer and destroyed as if by calling glDeleteBuffers." (Similar discussion occurs in other interfaces). I understand that the idea is to expose a wrapper around OpenGL ES objects, and I assume that that's what's meant by "underlying object". A clear discussion of this (and an indication of whether it is acceptable to implement WebGL on something other than OpenGL so long as the output is the same — which I presume is the case) would be helpful. Also, since what a large bunch of these interfaces mean appears to depend on another document, it would be good to link to those definitions in that document, or if that proves impossible (e.g. because it's a PDF...) to inline a definition.

  - 5.9 WebGLObjectArray. Is the intent that it would be exposed as a JS Array? Same for other interfaces that look like arrays.

  - 5.11 "type of type GLenum. The data type of the requested variable." Where do I get that enum's values?

  - OMG, IDL templates!

  - 5.14 The interface contains typedefs that seem to be used elsewhere. It's unclear to me from WebIDL whether typedef declarations are scoped (in which case you'd have to move them out of the interface, and *gasp* perhaps use a module), or if the typedef namespace is just global.

  - Man, WebGLRenderingContext really is the mother of all interfaces! I think there's an award in there — comes out to 23 screenfuls here. This is just a thought but maybe it would be more readable if it were (editorially) somehow split into several sections that combined would be the full thing (as is done with the prose)? At the very least linking from the interface to the prose (and back, if possible) would make things easier, perhaps even just linking between IDL sections and prose sections. Perhaps the IDL could even include some direct links to the OpenGL man page?

  - 5.15 "These events are sent to the corresponding HTMLCanvasElement through the DOM Event System." It would be better to call it "DOM Level 2: Events" and to have a reference instead of a direct link (or to have both).

  - Also, "The resource attribute contains the resource that was lost, or null if all resources were lost." could be clarified a little bit. Right now it reads a bit like "Well I lost it so I'm giving it to you, unless I completely lost it" :)

Anyway, great work, I look forward to more!

--
Robin Berjon
  robineko — hired gun, higher standards
  http://robineko.com/

Received on Monday, 14 December 2009 11:35:52 UTC