Proposed canvas and WebGL cleanup

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

Index: client/html/generated/src/interface/WebGLRenderingContext.dart
diff --git a/client/html/generated/src/interface/WebGLRenderingContext.dart b/client/html/generated/src/interface/WebGLRenderingContext.dart
index 5645c5eb0aa95c673f27721e925a668fb6c79d23..33dca9c9fd7d57ae51f79846a1bc95b5e9a796e3 100644
--- a/client/html/generated/src/interface/WebGLRenderingContext.dart
+++ b/client/html/generated/src/interface/WebGLRenderingContext.dart
@@ -802,12 +802,27 @@ interface WebGLRenderingContext extends CanvasRenderingContext {
 
   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);