Canvas ImageData comments

 From the "Pixel manipulation" section:

"readonly attribute int[] data;" - should that look like a JS Array 
object? I've seen one person write "imagedata.data.join(', ')" (for 
debugging), relying on the Array methods being there, so it might be 
good (for functionality and for interoperability) if that worked.

"If the first argment to the method is null or not an ImageData object 
that was returned by createImageData() or getImageData()" - how can you 
get an ImageData object that wasn't returned by one of those methods? If 
it's possible, things should be changed to make that impossible (since 
such an object is unusable). If it's impossible, it's pointless to list 
those methods, and makes it harder for anyone to add a new way to return 
ImageData (e.g. a getImageData on a 3D context) since they'll have to 
update that putImageData definition each time.

"If any of the arguments to createImageData() or getImageData() are 
infinite or NaN, or if either the sw or sh arguments are zero, the 
method must instead raise an INDEX_SIZE_ERR exception.", and "If any of 
the arguments to the method are infinite or NaN, the method must raise 
an INDEX_SIZE_ERR exception." - shouldn't infinite/NaN be handled with 
NOT_SUPPORTED_ERR, for consistency with every other method? If so, that 
case shouldn't need mentioning here, since it's implicitly handled by 
"Common conformance requirements for APIs exposed to JavaScript".

"If the number is not an integer, it must be rounded to the nearest 
integer using the IEEE 754r roundTiesToEven rounding mode." - perhaps 
that should be convertToIntegerTiesToEven to be slightly more precise, 
since roundTiesToEven is a generic (not necessarily integer) algorithm.

"for all values of x and y where dirtyX ≤ x < dirtyX+dirtyWidth and 
dirtyY ≤ y < dirtyY+dirtyHeight" - should say "for all integer values of 
x and y ..."

Step 5 ("If, after those changes, either dirtyWidth or dirtyHeight is 
negative or zero, stop these steps without affecting the canvas.") is 
redundant and useless, since step 6 will have no effect anyway when 
either of those conditions holds.

"the pixel with coordinate (x_{device}+x, y_{device}+y)" - they were 
called "dx_{device}" etc earlier - should be consistent.

"Thus, while one could create an ImageData object, one would not 
necessarily know what resolution the canvas expected" - that doesn't 
make sense to me. It would make sense as "Thus, while one might wish to 
create an ImageData object by specifying the <code>width</code> and 
<code>height</code> attributes directly, one would not ..."

"In the following example, the script first obtains the size of the 
canvas backing store, and then generates a few new ImageData objects 
which can be used." - no it doesn't.

"The putImageData(imagedata, dx, dy, dirtyX, dirtyY, dirtyWidth, 
dirtyHeight) method writes data from ImageData structures back to the 
canvas." - should say "The putImageData(imagedata, dx, dy) and 
putImageData(imagedata, dx, dy, ...) methods write ...", else it'll 
confuse people into thinking the dirty arguments are required. (Also, 
it'd be nice if there was link from here back up to the IDL so people 
can check the declarations.)

"the following must result in no visible changes to the rendering: 
context.putImageData(context.getImageData(x, y, w, h), x, y); ...for any 
value of x and y." - should say "for any values of x, y, w and h."

"The values of the data array may be changed" - abuse of RFC2119 
keyword. ('MAY' is defined in terms of implementations optionally 
supporting a feature, and having to interoperate with implementations 
that include and exclude that feature, so it makes no sense here.)

Typos:
  "rectanglewhose"
  "argment"
  "the heightmember of the imagedata structure"
  "thr pixels"
  "crateImageData"

-- 
Philip Taylor
pjt47@cam.ac.uk

Received on Wednesday, 30 April 2008 01:34:19 UTC