Proposed canvas and WebGL cleanup

client/html/generated/src/interface/WebGLRenderingContext.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 // WARNING: Do not edit - generated code.
 
 interface WebGLRenderingContext extends CanvasRenderingContext {
 
   static final int ACTIVE_ATTRIBUTES = 0x8B89;
 
@@ skipping 784 matching lines @@
   void stencilFuncSeparate(int face, int func, int ref, int mask);
 
   void stencilMask(int mask);
 
   void stencilMaskSeparate(int face, int mask);
 
   void stencilOp(int fail, int zfail, int zpass);
 
   void stencilOpSeparate(int face, int fail, int zfail, int zpass);
 
-  void texImage2D(int target, int level, int internalformat, int format_OR_width, int height_OR_type, var border_OR_canvas_OR_image_OR_pixels, [int format, int type, ArrayBufferView pixels]);
+  /**
+   * http://www.khronos.org/registry/webgl/specs/latest/webgl.idl
+   * The version of texImage2D that accepts HTML elements has
+   * been renamed to [texImage2DHtml].
+   */
+  void texImage2D(int target, int level, int internalformat,
+      int width, int height, int border, int format, int type,
+      ArrayBufferView pixels);
+
+  /**
+   * This method corresponds to the version of the texImage2D method that
+   * accepts an [image] that is an [:ImageData:], [:ImageElement:],
+   * [:CanvasElement:] or [:VideoElement:].
+   */
+  void texImage2DHtml(int target, int level, int internalformat, int format, int type, var image);

[Jacob, 2011/11/04 19:07:05]

I'm not a huge fan of these two names.
Keeping these two methods as one method was unnecessarily confusing as different
args are required for each version.

I believe the version I've left as texImage2D is the fast path while
texImage2DHtml is the slow version.
I'm open to other names.  
It looks like some python bindings split these into multiple function names
along what looks like somewhat similar lines (one of their two versions takes a
multi-dimension array so just like the case of Canvas, ImageElement, etc the
width and height do not make sense to specify.
http://pyopengl.sourceforge.net/documentation/manual/glTexImage2D.3G.html

[nweiz, 2011/11/04 21:09:06]

Maybe call the second method texHtml2D?

[Jacob, 2011/11/04 22:26:13]

for webgl the convention is to append cryptic strings at the end of method names
to specify different types of input args.
That convention also has the benefit that if using an IDE< all the similar
methods will be grouped together making it clear which version you want.
One more option:
texImage2DDrawable
given we are considering adding a Drawable interface that matches the for DOM
classes.
That name is still up for debate and I'd be thrilled if we could find a better
marker interface name.

 
   void texParameterf(int target, int pname, num param);
 
   void texParameteri(int target, int pname, int param);
 
+  // TODO(jacobr): same transformation as for texImage2D
   void texSubImage2D(int target, int level, int xoffset, int yoffset, int format_OR_width, int height_OR_type, var canvas_OR_format_OR_image_OR_pixels, [int type, ArrayBufferView pixels]);
 
   void uniform1f(WebGLUniformLocation location, num x);
 
   void uniform1fv(WebGLUniformLocation location, Float32Array v);
 
   void uniform1i(WebGLUniformLocation location, int x);
 
   void uniform1iv(WebGLUniformLocation location, Int32Array v);
 
@@ skipping 44 matching lines @@
   void vertexAttrib3fv(int indx, Float32Array values);
 
   void vertexAttrib4f(int indx, num x, num y, num z, num w);
 
   void vertexAttrib4fv(int indx, Float32Array values);
 
   void vertexAttribPointer(int indx, int size, int type, bool normalized, int stride, int offset);
 
   void viewport(int x, int y, int width, int height);
 }