Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Do not change default return type for getImageData #105

Merged
merged 1 commit into from
Jul 31, 2023
Merged

Do not change default return type for getImageData #105

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 8 additions & 14 deletions canvas_float.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,10 +95,7 @@ In the interface `CanvasImageData`, the functions `createImageData` and `getImag

If the `ImageDataSettings` specifies `colorType`, then the resulting `ImageData` will have that specified `colorType`.

If the `ImageDataSettings` does not specify `colorType`, then the resulting `ImageData`'s `colorType` will be as follows:

* If the `CanvasImageData` has a `colorType` of `"unorm8"`, then the `ImageData`'s `colorType` will be `"unorm8"`.
* If the `CanvasImageData` has a `colorType` of `"float16"`, then the `ImageData`'s `colorType` will be `"float32"`.
If the `ImageDataSettings` does not specify `colorType`, then the resulting `ImageData`'s `colorType` will be `"unorm8"`.

### Values outside of the `[0, 1]` interval

Expand Down Expand Up @@ -277,17 +274,14 @@ E.g, one would write `255` instead of `1.0`.

This can be avoided by examining the `colorType` member the `ImageData`.

### Choice of defaulting `getImageData` to `Float32Array` for `"float16"` canvas

There exists a trade-off in the default behavior of `getImageData` for a `"float16"` canvas.
### Choice of defaulting `getImageData` to `"unorm8"`

Suppose one is to default to returning a `Uint8ClampedArray`.
The benefit of this behavior is that there is a lesser likelihood of falling into the above mentioned pitfall.
The downside of this behavior is that a `getImageData` and then `putImageData` round-trip will lose precision.
Historically, all calls to `getImageData` have returned an `ImageData` with a `Uint8ClampedArray`.

Suppose one is to default to returning a `Float32Array`.
The benefit of this behavior is that a `getImageData` and then `putImageData` round-trip will not lose precision.
The downside is that there is a higher likelihood of falling into the above mentioned pitfall.
Changing the default type that is returned by this function will break any software that relies on
that default type, which is currently all software that uses this function.

This is resolved in favor of preserving round-trip precision, following the decision with respect to the default behavior for `colorSpace` for `getImageData`.
Changing the default type that is returned by this function will significantly hinder the adoption
of `"float16"` canvas, because no application can change the backing of any canvas without first
ensuring that all libraries that it uses have been updated to support all possible return values.