hdr-canvas 0.0.12 → 0.1.0

package/README.md

@@ -2,6 +2,8 @@
 
 This module contains a collection of functions and classes to work with the HDR support for HTML `canvas` elements in chromium based (like Chrome, Edge, Opera and Brave) browsers.
 
+All changes and a bit of context are part of the [release notes for 0.1.0](docs/release-notes-0.1.0.md).
+
 **This should only be considered as proof of concept or alpha code, don't use it in production environments!**
 
 **Even if the display of HDR images works, the HDR support for the `canvas` element needs the browser flag `enable-experimental-web-platform-features` to be enabled. For example, open chrome://flags#enable-experimental-web-platform-features in Chrome to activate it.**
@@ -16,7 +18,7 @@ Import the required function(s):
 import { checkHDR, checkHDRCanvas } from "hdr-canvas";
 ```
 
-## Examples `checkHDRCanvas()`
+## Example `checkHDRCanvas()`
 
 The functions return `true` if HDR is supported, example:
 
@@ -35,12 +37,26 @@ This can be useful to add a warning (using the [`fillText()`](https://developer.
 ## Example `checkHDRCanvas()`
 
 ```javascript
+const hdrCanvasStatus = document.getElementById("hdr-check-status")! as HTMLDivElement;
 if (checkHDRCanvas()) {
-  hdrCanvas.innerText = "HDR Canvas are supported";
-  hdrCanvas.style.color = "green";
+  hdrCanvasStatus.innerText = "HDR Canvas are supported";
+  hdrCanvasStatus.style.color = "green";
+} else {
+  hdrCanvasStatus.innerText = "HDR Canvas are not supported";
+  hdrCanvasStatus.style.color = "red";
+}
+```
+
+## Example `checkHDRVideo()`
+
+```javascript
+const hdrCanvasStatus = document.getElementById("hdr-check-status")! as HTMLDivElement;
+if (checkHDRVideo()) {
+  hdrCanvasStatus.innerText = "HDR Video is supported";
+  hdrCanvasStatus.style.color = "green";
 } else {
-  hdrCanvas.innerText = "HDR Canvas are not supported";
-  hdrCanvas.style.color = "red";
+  hdrCanvasStatus.innerText = "HDR Video is not supported";
+  hdrCanvasStatus.style.color = "red";
 }
 ```
 
@@ -55,7 +71,9 @@ const colorSpace = "rec2100-hlg";
 canvas.configureHighDynamicRange({ mode: "extended" });
 const ctx = canvas.getContext("2d", {
   colorSpace: colorSpace,
-  pixelFormat: "float16"
+  colorType: "float16"
+  // Use this for Chrome < 133
+  //pixelFormat: "float16"
 });
 ```
 
@@ -71,12 +89,12 @@ import { initHDRCanvas } from "hdr-canvas";
 
 It's now also possible to use a HDR enabled Canvas by wrapping the browser internal `getContext()` function, by calling `defaultGetContextHDR()`.
 
-```
-import {defaultGetContextHDR, checkHDR, checkHDRCanvas} from 'hdr-canvas';
+```javascript
+import { defaultGetContextHDR, checkHDR, checkHDRCanvas } from "hdr-canvas";
 
 if (checkHDR() && checkHDRCanvas()) {
   defaultGetContextHDR();
-  console.log('Enabled HDR Canvas');
+  console.log("Enabled HDR Canvas");
 }
 ```
 
@@ -86,18 +104,18 @@ if (checkHDR() && checkHDRCanvas()) {
 
 Use the method `resetGetContext()` to undo the changes by `defaultGetContextHDR()`.
 
-```
-import {resetGetContext} from 'hdr-canvas';
+```javascript
+import { resetGetContext } from "hdr-canvas";
 
 resetGetContext();
 ```
 
-## Importing `Uint16Image`
+## Importing `Float16Image`
 
-Afterwards one can use [ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData) with a `float16` array, first the `Uint16Image` needs to be imported:
+Afterwards one can use [ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData) with a `float16` array, first the `Float16Image` needs to be imported:
 
 ```javascript
-import { Uint16Image } from "hdr-canvas";
+import { Float16Image } from "hdr-canvas";
 ```
 
 ## Example: Loading an image
@@ -115,7 +133,7 @@ var hdrCanvas = document.createElement("canvas");
 hdrCanvas.width = image.width;
 hdrCanvas.height = image.height;
 
-const rec210hglImage = Uint16Image.fromImageData(imData);
+const rec210hglImage = Float16Image.fromImageData(imData);
 
 const ctx = initHDRCanvas(hdrCanvas);
 ctx.putImageData(rec210hglImage.getImageData(), 0, 0);
@@ -133,8 +151,8 @@ import HDRWebGPURenderer from "hdr-canvas/three/HDRWebGPURenderer.js";
 
 **Note:** Starting Three.js 167 the WebGPU renderer is the new default renderer. This has several consequences for the required imports. Use this import instead of the official one and if your using Vite _don't_ provide an import map of resolver alias configuration.
 
-```
-import * as THREE from 'three/src/Three.js';
+```javascript
+import * as THREE from "three/src/Three.js";
 ```
 
 Use it as you'll do with a `WebGPURenderer`.
@@ -147,7 +165,7 @@ renderer = new HDRWebGPURenderer({ canvas: canvas, antialias: true });
 
 Starting from Three.js version 167 you need to fix imported UHDR Textures, otherwise they will appear black:
 
-```
+```javascript
 model = gltf.scene;
 model.traverse((element) => {
   if (element?.material?.type != undefined) {
@@ -164,22 +182,35 @@ scene.add(model);
 This currently doesn't work with Firefox, due to missing support for HDR and only partial WebGPU support.
 One can import `WebGPU` and use also a HDR check to guard from errors:
 
-```
-import WebGPU from 'hdr-canvas/three/WebGPU.js';
+```javascript
+import WebGPU from "hdr-canvas/three/WebGPU.js";
 ```
 
 Only use the provided renderer if the browser supports WebGPU and HDR:
 
-```
+```javascript
 if (WebGPU.isAvailable() && checkHDRCanvas()) {
-  renderer = new HDRWebGPURenderer({canvas: canvas, antialias: true});
+  renderer = new HDRWebGPURenderer({ canvas: canvas, antialias: true });
 } else {
-  renderer = new THREE.WebGLRenderer({canvas: canvas, antialias: true});
+  renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true });
 }
 ```
 
 # Examples
 
+## Bundled examples
+
+Some of the examples above are also part of this repository.
+
+```console
+npm i
+npm run dev
+```
+
+Open This URL in your browser: [http://localhost:5173/](http://localhost:5173/), you can also access them directly from [GitHub](https://cmahnke.github.io/hdr-canvas/).
+
+## Old examples on my blog:
+
 All examples requires a Chromium based browser (like Chrome, Edge, Opera and Brave) and a HDR-enable monitor.
 
 - [Contrast enhancement for UV images using HDR](https://christianmahnke.de/en/post/hdr-image-analysis/)
@@ -192,9 +223,75 @@ All examples requires a Chromium based browser (like Chrome, Edge, Opera and Bra
 
 The following things might be improved:
 
-- Try to detect change of screen for HDR detection
-- Improve speed
-  - Provide WebWorker
-- Documentation
-  - Link to browser HDR support
-  - Document `Uint16Image`
+- [x] Change `pixelFormat` in `HTMLCanvasElement.getContext("2d")` to `colorType` (["unorm8", "float16"]) while keeping some downward compatibility - [#151](https://github.com/cmahnke/hdr-canvas/issues/151)
+- [ ] Try to detect change of screen for HDR detection - [#107](https://github.com/cmahnke/hdr-canvas/issues/107)
+- [ ] Remove `Uint16Image`
+- [ ] Improve speed
+  - [ ] Provide WebWorker
+- [ ] Documentation
+  - [ ] Link to browser HDR support
+  - [x] Document `Uint16Image`
+- [ ] Tests and examples
+  - [x] Provide examples from blog
+  - [x] Provide simple sanity tests
+
+# References
+
+## Browser HDR
+
+- [`dynamic-range` Media Query](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/dynamic-range)
+- [HDR Capability Detection](https://github.com/w3c/media-capabilities/blob/main/hdr_explainer.md)
+- [HDR `HTMLCanvasElement`](https://github.com/w3c/ColorWeb-CG/blob/main/hdr_html_canvas_element.md)
+
+### Older
+
+- [Adding support for High Dynamic Range (HDR) imagery to HTML Canvas: a baseline proposal](https://github.com/whatwg/html/issues/9461)
+- [HDR Canvas Example](https://ccameron-chromium.github.io/webgl-examples/canvas-hdr.html)
+
+## Sources
+
+This section contains different definitions, which can be helpful to impkement HDR related things
+
+- [`CanvasRenderingContext2DSettings` in Chromium](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/modules/canvas/canvas2d/canvas_rendering_context_2d_settings.idl)
+- [`ImageData` in Chromium](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/html/canvas/image_data.idl)
+- [`TypeScript DOM reference`](https://github.com/microsoft/TypeScript-DOM-lib-generator/blob/main/baselines/dom.generated.d.ts)
+
+## Workflow on related changes to web APIs
+
+**This is considered to be experimental**, currently we're waiting for TypeSript to pick up the changes made to the web APIs. See [microsoft/TypeScript-DOM-lib-generator#2107](https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/2107)
+
+### Along the spec
+
+1. Change to the WhatsWG spec - [Issue Tracker](https://github.com/whatwg/html)
+2. Change apporoved
+3. MDN picks up spec change - [Create an issue](https://github.com/mdn/content/issues)
+4. Changes are popagated to the [TypeScript generated DOM library](https://github.com/microsoft/TypeScript-DOM-lib-generator)
+
+### By custom TypeScript types
+
+1. Extend `src/types`, try to extend existing interfaces
+
+## Generating updated TypeScript types
+
+Starting with one of the next monor versions (maybe 0.2.0) the prefered way is to update the browser / DOM types instead of adding our own HDR types. The existing types will continue to exist for now. This change reflects improvements in browser support and should make transitioning to standard base types later on.
+
+The basic workflow is as follows:
+
+- [Update the definitions](https://github.com/microsoft/TypeScript-DOM-lib-generator?tab=readme-ov-file#contribution-guidelines)
+- Regenerate the types (needs the MDN submodule to be checked out)
+
+To make this repaetable add patches to this repository:
+
+Edit the types, for example to change existing definitions, see [Update the definitions](https://github.com/microsoft/TypeScript-DOM-lib-generator?tab=readme-ov-file#contribution-guidelines)
+
+```
+cd node_modules/@typescript/dom-lib-generator/
+vi inputfiles/overridingTypes.jsonc
+```
+
+To generate a patch pmake sure, that the Git submmodule is remove, otherwise `patch-package` will fail.
+
+```
+node scripts/git-submodules.js -c -d node_modules/@typescript/dom-lib-generator/
+npx patch-package @typescript/dom-lib-generator
+```

package/dist/@types/hdr-canvas.d.ts

@@ -6,6 +6,8 @@ import { ColorTypes } from 'colorjs.io';
 type HDRHTMLCanvasOptionsType = "mode";
 type HDRHTMLCanvasOptions = { [key in HDRHTMLCanvasOptionsType]?: string };
 
+type HDRImageDataArray = ImageDataArray | Float16Array | Uint16Array;
+
 interface HDRHTMLCanvasElement extends HTMLCanvasElement {
   configureHighDynamicRange(options: HDRHTMLCanvasOptions): void;
   _getContext(contextId: string, options?: object): RenderingContext | null;
@@ -13,45 +15,91 @@ interface HDRHTMLCanvasElement extends HTMLCanvasElement {
 
 interface HDRImageData {
   readonly colorSpace: PredefinedColorSpace;
-  readonly data: Uint8ClampedArray | Uint16Array;
+  readonly data: HDRImageDataArray | Uint16Array;
   readonly height: number;
   readonly width: number;
 }
 
 // See https://github.com/w3c/ColorWeb-CG/blob/main/hdr_html_canvas_element.md
-// "rec2100-display-linear" is left out beacause of mapping issues
+// "rec2100-display-linear" is left out because of mapping issues
 type HDRPredefinedColorSpace = "display-p3" | "srgb" | "rec2100-hlg" | "rec2100-pq";
 
-type Uint16ImagePixelCallback = (red: number, green: number, blue: number, alpha: number) => Uint16Array;
-declare class Uint16Image {
-    height: number;
-    width: number;
-    data: Uint16Array;
+//enum HDRPredefinedColorSpace {"display-p3", "srgb", "rec2100-hlg", "rec2100-pq", "rec2100-display-linear"};
+
+/**
+ * A callback function that receives the red, green, blue, and alpha values of a pixel
+ * and returns a new `Float16Array` with the modified values.
+ *
+ * @callback HDRImagePixelCallback
+ * @param {number} red - The red channel value (0-65535).
+ * @param {number} green - The green channel value (0-65535).
+ * @param {number} blue - The blue channel value (0-65535).
+ * @param {number} alpha - The alpha channel value (0-65535).
+ * @returns {ImageDataArray} A new `Float16Array` containing the four channel values.
+ */
+type HDRImagePixelCallback = (red: number, green: number, blue: number, alpha: number) => HDRImageDataArray;
+
+interface CanvasRenderingContext2DHDR extends CanvasRenderingContext2D {}
+
+declare abstract class HDRImage {
     static DEFAULT_COLORSPACE: HDRPredefinedColorSpace;
     static SDR_MULTIPLIER: number;
     static COLORSPACES: Record<HDRPredefinedColorSpace, ColorTypes>;
+    data: HDRImageDataArray;
+    height: number;
+    width: number;
+    constructor(width: number, height: number);
+    static fromImageData(imageData: HDRImageData | ImageData): HDRImage;
+    static fromImageDataArray(width: number, height: number, imageDataArray: Uint8ClampedArray | Uint8ClampedArray<ArrayBufferLike>): HDRImage;
+    static loadSDRImageData(url: URL): Promise<ImageData | undefined>;
+    getPixel(w: number, h: number): HDRImageDataArray;
+    setPixel(w: number, h: number, px: number[]): void;
+    abstract setImageData(imageData: HDRImageData | ImageData): void;
+    abstract getImageData(): ImageData | null;
+    abstract fill(color: number[]): this | undefined;
+    abstract pixelCallback(fn: HDRImagePixelCallback): void;
+    clone(): this;
+}
+
+declare class Uint16Image extends HDRImage {
+    data: Uint16Array;
     colorSpace: HDRPredefinedColorSpace;
     constructor(width: number, height: number, colorspace?: string);
-    fill(color: number[]): Uint16Image | undefined;
-    getPixel(w: number, h: number): Uint16Array;
-    setPixel(w: number, h: number, px: number[]): void;
+    fill(color: number[]): this | undefined;
     static scaleUint8ToUint16(val: number): number;
     getImageData(): ImageData | null;
     static convertPixelToRec2100_hlg(pixel: Uint8ClampedArray): Uint16Array;
     static convertArrayToRec2100_hlg(data: Uint8ClampedArray): Uint16Array;
-    pixelCallback(fn: Uint16ImagePixelCallback): void;
-    static loadSDRImageData(url: URL): Promise<HDRImageData | undefined>;
+    pixelCallback(fn: HDRImagePixelCallback): void;
     static fromImageData(imageData: HDRImageData): Uint16Image;
     static fromURL(url: URL): Promise<Uint16Image | undefined>;
     setImageData(imageData: HDRImageData): void;
-    clone(): Uint16Image;
+}
+
+declare class Float16Image extends HDRImage {
+    data: Float16Array;
+    static DEFAULT_PIXELFORMAT: ImageDataPixelFormat;
+    colorSpace: HDRPredefinedColorSpace;
+    pixelFormat: ImageDataPixelFormat;
+    constructor(width: number, height: number, colorspace?: string, pixelFormat?: string);
+    fill(color: number[]): this | undefined;
+    static scaleUint8ToFloat16(val: number): number;
+    getImageData(): ImageData | null;
+    static convertPixelToRec2100_hlg(pixel: Uint8ClampedArray): Float16Array;
+    static convertArrayToRec2100_hlg(data: Uint8ClampedArray): Float16Array;
+    pixelCallback(fn: HDRImagePixelCallback): void;
+    static fromImageData(imageData: HDRImageData): Float16Image;
+    static fromImageDataArray(width: number, height: number, imageDataArray: Uint8ClampedArray | Uint8ClampedArray<ArrayBufferLike>): Float16Image;
+    static fromURL(url: URL): Promise<Float16Image | undefined>;
+    setImageData(imageData: HDRImageData): void;
+    clone(): this;
 }
 
 declare function checkHDR(): boolean;
 declare function checkHDRCanvas(): boolean;
 
-declare function initHDRCanvas(canvas: HDRHTMLCanvasElement): RenderingContext | null;
+declare function initHDRCanvas(canvas: HDRHTMLCanvasElement): CanvasRenderingContext2DHDR | null;
 declare function defaultGetContextHDR(): void;
 declare function resetGetContext(): void;
 
-export { Uint16Image, checkHDR, checkHDRCanvas, defaultGetContextHDR, initHDRCanvas, resetGetContext };
+export { Float16Image, HDRImage, Uint16Image, checkHDR, checkHDRCanvas, defaultGetContextHDR, initHDRCanvas, resetGetContext };