hdr-canvas 0.0.13 → 0.1.1

package/dist/index.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 };

package/docs/release-notes-0.1.0.md

@@ -0,0 +1,47 @@
+# `hdr-canvas` 0.1.0
+
+# Introduction
+
+Since the last release many areas of handling HDR content in the browser have evolved.
+Most notably is certainly the introduction of the `Float16Array` in the `ImageData` constructor:
+
+- The [WhatWG spec](https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagedataarray), [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ImageData/ImageData#syntax) and [BCD](https://github.com/mdn/browser-compat-data/issues/27547)) have been updated accordingly. You can test your own browser using `new ImageData(new Float16Array(4), 1, 1, {pixelFormat:"rgba-float16"})`.
+  - Still open in [Firefox](https://bugzil.la/1958830)
+  - Hidden behind flag in [Safari](https://webkit.org/b/291196)
+  - Chromium has implemented it starting with [137](https://source.chromium.org/chromium/chromium/src/+/refs/tags/137.0.7104.0:third_party/blink/renderer/core/html/canvas/image_data.idl): \*\*The `ImageData` constructor only accepts `Float16Array` instead of `Uint16Array`. This makes older versions of this module obsolete, since they targeted the chromium specific solution.
+  - If Safari enables it by default it will be also in the [Typescript DOM types](https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/2107)
+
+As [@reitowo](https://github.com/reitowo) pointed out, there has been a change to the `getContext("2d")` method. The key `pixelFormat` has been replaced by `colorType`.
+
+In parallel there have been changes to the UltraHDR image format, especially the encoding of gain map metadata. While this used to be don in XMP it's now done according to ISO 21496-1. This has been adopted by Google and Apple in newer OS versions like Android 15 and iOS 18 to avoid cross-platform fragmentation. The [UltraHDR Library](https://github.com/google/libultrahdr) has already changed to using the [ISO format as default](https://github.com/google/libultrahdr/blob/main/docs/building.md).
+
+Currently the ThreeJS UHDR loader doesn't know how to handle this change, see [mrdoob/three.js#32293](https://github.com/mrdoob/three.js/issues/32293).
+
+# Key Changes & New Features
+
+- Better support for official Web-APIs
+  - Use `Float16Array` instead of `Uint16Array`
+  - Use the correct option for initializing 2D canvas context
+
+## Improved Documentation
+
+The documentation have been greatly improved, there is now also a [site](https://cmahnke.github.io/hdr-canvas/) including the examples and API docs.
+
+## Examples
+
+The examples from the blog are now part of this repository:
+
+- [`tests/site/assets/ts/hdr-three.js.ts`](tests/site/assets/ts/hdr-three.js.ts) - Three JS with HDR texture
+- [`tests/site/assets/ts/image-slider.ts`](tests/site/assets/ts/image-slider.ts) - Generated HDR content
+- [`tests/site/assets/ts/main.ts`](tests/site/assets/ts/main.ts) - feature detection
+
+These example are also avalable on the new [documentation site](https://cmahnke.github.io/hdr-canvas/)
+
+## Advocacy
+
+Since the changes by the WhatWG weren't picked up already there had to be some Issues in the relevant repos to be raised.
+
+- [mdn/content#40639](https://github.com/mdn/content/issues/40639)
+- [mdn/browser-compat-data#27547](https://github.com/mdn/browser-compat-data/issues/27547)
+- [microsoft/TypeScript-DOM-lib-generator#2107](https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/2107)
+- [mrdoob/three.js#32293](https://github.com/mrdoob/three.js/issues/32293).

package/docs/release-notes-0.1.1.md

@@ -0,0 +1,19 @@
+# `hdr-canvas` 0.1.1
+
+# Introduction
+
+Since the last release many areas of handling HDR content in the browser have evolved. This also applies for WebGPU renderings using ThreeJS
+
+The changes in initializing a `canvas for a Rendere are described in the [explainer](https://github.com/ccameron-chromium/webgpu-hdr/blob/main/EXPLAINER.md).
+
+The important change is the renaming from `colorMetadata` to:
+
+```
+toneMapping: { mode: "extended" }
+```
+
+This is also reflected by the ThreeJS API so a custom HDR WebGPU Renderer and Backend aren't strictly needed anymore. They will be removed soon.
+
+# Key Changes & New Features
+
+- Fix ThreeJS HDR Renderer and Backend

package/docs/release.md

@@ -0,0 +1,13 @@
+# How to release a new version
+
+# Create a tag
+
+```
+git tag 0.1.0
+```
+
+# Create a release on GitHub
+
+- https://github.com/cmahnke/hdr-canvas/releases/new
+- Add Title and notes
+- Check "Set as the latest release"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hdr-canvas",
-  "version": "0.0.13",
+  "version": "0.1.1",
   "description": "HDR capable HTML canvas",
   "main": "dist/hdr-canvas.cjs",
   "module": "dist/hdr-canvas.js",
@@ -25,19 +25,33 @@
     "dist/@types",
     "three",
     "src",
+    "docs",
+    "scripts",
+    "patches",
     "rollup.config.mjs",
     "tsconfig.json",
     "README",
     "LICENCE"
   ],
   "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=24",
+    "deno": ">=1.43",
+    "bun": ">=1.1.23"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "lint": "eslint . -c eslint.config.mjs --report-unused-disable-directives",
+    "lint": "npm run eslint && npm run stylelint",
+    "eslint": "eslint . -c eslint.config.mjs --report-unused-disable-directives",
+    "stylelint": "stylelint -c tests/site/stylelint.config.js 'tests/**/*.scss'",
+    "knip": "knip",
     "tsc": "tsc",
     "build": "rimraf ./dist ./build && tsc && rollup --config",
+    "dev": "npm run jsdoc && vite -c tests/site/vite.config.js",
+    "site": "npm run jsdoc && vite -c tests/site/vite.config.js build",
     "clean": "rimraf ./dist ./build",
-    "format": "prettier . --check"
+    "format": "prettier . --check",
+    "jsdoc": "jsdoc -c jsdoc.config.json -r .",
+    "test": "vitest --config tests/site/vite.config.js"
   },
   "repository": {
     "type": "git",
@@ -56,20 +70,41 @@
   },
   "homepage": "https://github.com/cmahnke/hdr-canvas#readme",
   "devDependencies": {
-    "@eslint/js": "^9.15.0",
-    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@eslint/js": "^9.39.1",
+    "@eslint/markdown": "^7.5.1",
+    "@fontsource-utils/scss": "^0.2.2",
+    "@fontsource-variable/league-spartan": "^5.2.8",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.1",
-    "@types/eslint__js": "^8.42.3",
-    "eslint": "^9.15.0",
-    "prettier": "^3.3.3",
-    "rimraf": "^6.0.1",
-    "rollup": "^4.27.3",
-    "rollup-plugin-dts": "^6.1.1",
-    "three": "^0.170.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@napi-rs/canvas": "^0.1.83",
+    "@types/jsdom": "^27.0.0",
+    "@types/semver": "^7.7.1",
+    "@types/three": "^0.181.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "@typescript/lib-dom": "npm:@types/web@^0.0.294",
+    "better-docs": "^2.7.3",
+    "eslint": "^9.39.1",
+    "file-url": "^4.0.0",
+    "globals": "^16.5.0",
+    "jsdoc": "^4.0.5",
+    "jsdom": "^27.2.0",
+    "knip": "^5.70.2",
+    "pkg-types": "^2.3.0",
+    "prettier": "^3.7.1",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.53.3",
+    "rollup-plugin-dts": "^6.3.0",
+    "sass": "^1.94.2",
+    "semver": "^7.7.3",
+    "stylelint": "^16.26.1",
+    "stylelint-config-standard-scss": "^16.0.0",
+    "three": "^0.181.2",
     "tslib": "^2.8.1",
-    "typescript": "^5.6.3",
-    "typescript-eslint": "^8.15.0"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^7.2.4",
+    "vitest": "^4.0.14"
   },
   "dependencies": {
     "colorjs.io": "^0.5.2"

package/patches/@typescript+dom-lib-generator+0.0.1.patch

@@ -0,0 +1,46 @@
+diff --git a/node_modules/@typescript/dom-lib-generator/inputfiles/overridingTypes.jsonc b/node_modules/@typescript/dom-lib-generator/inputfiles/overridingTypes.jsonc
+index 7c11453..c7f0bbb 100644
+--- a/node_modules/@typescript/dom-lib-generator/inputfiles/overridingTypes.jsonc
++++ b/node_modules/@typescript/dom-lib-generator/inputfiles/overridingTypes.jsonc
+@@ -4035,6 +4035,23 @@
+                     }
+                 ]
+             },
++            {
++                "name": "ImageDataArray",
++                "typeParameters": [
++                    {
++                        "name": "ArrayBuffer"
++                    }
++                ],
++                "type": [
++                    {
++                        "type": "Uint8ClampedArray"
++                    },
++                    {
++                        "type": "Float16Array"
++                    }
++                ],
++                "overrideType": "Uint8ClampedArray<ArrayBuffer> | Float16Array<ArrayBuffer>"
++            },
+             {
+                 "name": "ReadableStreamReader",
+                 "typeParameters": [
+diff --git a/node_modules/@typescript/dom-lib-generator/inputfiles/removedTypes.jsonc b/node_modules/@typescript/dom-lib-generator/inputfiles/removedTypes.jsonc
+index 8089030..d93ee40 100644
+--- a/node_modules/@typescript/dom-lib-generator/inputfiles/removedTypes.jsonc
++++ b/node_modules/@typescript/dom-lib-generator/inputfiles/removedTypes.jsonc
+@@ -410,13 +410,6 @@
+                     }
+                 }
+             },
+-            "ImageDataSettings": {
+-                "members": {
+-                    "member": {
+-                        "pixelFormat": null // Blink experimental only as of 2025-04
+-                    }
+-                }
+-            },
+             "IntersectionObserverInit": {
+                 "members": {
+                     "member": {

package/scripts/check.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -e
+
+npm ci
+npm run lint
+npm run format
+npx tsc -b --verbose
+npx rollup --config
+npx prettier --check .
+npm run build
+npm run site

package/scripts/git-submodules.js

@@ -0,0 +1,175 @@
+import { existsSync, rmSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import git from "isomorphic-git";
+import http from "isomorphic-git/http/node";
+import * as fs from "node:fs";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+const argv = yargs(hideBin(process.argv))
+  .option("directory", {
+    alias: "d",
+    type: "string",
+    default: process.cwd(),
+    description: "The root directory containing the .gitmodules file."
+  })
+  .option("force", {
+    alias: "f",
+    type: "boolean",
+    default: false,
+    description: "Force a clean checkout by removing existing directories."
+  })
+  .option("verbose", {
+    alias: "v",
+    type: "boolean",
+    default: false,
+    description: "Show verbose output during the cloning process."
+  })
+  .option("list", {
+    alias: "l",
+    type: "boolean",
+    default: false,
+    description: "List submodules and their directories in a table."
+  })
+  .option("clean", {
+    alias: "c",
+    type: "boolean",
+    default: false,
+    description: "Remove all directories listed in the .gitmodules file."
+  })
+  .option("timeout", {
+    alias: "t",
+    type: "number",
+    default: 120000, // Default timeout of 120 seconds (120000ms)
+    description: "Set the timeout for git operations in milliseconds."
+  })
+  .check((argv) => {
+    const actionFlags = [argv.list, argv.clean];
+    const trueFlags = actionFlags.filter((flag) => flag === true);
+    if (trueFlags.length > 1) {
+      throw new Error("Please use only one of the action flags: --list or --clean.");
+    }
+    return true;
+  })
+  .help()
+  .alias("help", "h").argv;
+
+function getSubmoduleEntries(dir) {
+  const gitmodulesPath = resolve(dir, ".gitmodules");
+  if (!existsSync(gitmodulesPath)) {
+    console.error(`Error: No .gitmodules file found in the specified directory: ${dir}`);
+    process.exit(1);
+  }
+
+  const gitmodulesContent = readFileSync(gitmodulesPath, "utf8");
+  const submoduleEntries = gitmodulesContent.split("\n\n").filter((entry) => entry.trim().startsWith("[submodule"));
+  if (submoduleEntries.length === 0) {
+    console.log("No submodules found in .gitmodules file. Exiting.");
+    process.exit(0);
+  }
+
+  const submodules = [];
+  for (const entry of submoduleEntries) {
+    const lines = entry.split("\n").map((line) => line.trim());
+    let pathValue, urlValue;
+    for (const line of lines) {
+      if (line.startsWith("path =")) {
+        pathValue = line.split("=")[1].trim();
+      } else if (line.startsWith("url =")) {
+        urlValue = line.split("=")[1].trim();
+      }
+    }
+    if (pathValue && urlValue) {
+      submodules.push({ path: pathValue, url: urlValue });
+    }
+  }
+  return submodules;
+}
+
+function printTable(data) {
+  const table = [
+    ["URL", "Path"],
+    ["---", "---"]
+  ];
+  data.forEach((sub) => {
+    table.push([`\`${sub.url}\``, `\`${sub.path}\``]);
+  });
+
+  const maxCols = [0, 0];
+  table.forEach((row) => {
+    maxCols[0] = Math.max(maxCols[0], row[0].length);
+    maxCols[1] = Math.max(maxCols[1], row[1].length);
+  });
+
+  table.forEach((row) => {
+    const formattedRow = `| ${row[0].padEnd(maxCols[0])} | ${row[1].padEnd(maxCols[1])} |`;
+    console.log(formattedRow);
+  });
+}
+
+async function main() {
+  const dir = resolve(argv.directory);
+  const submodules = getSubmoduleEntries(dir);
+
+  if (argv.list) {
+    console.log("Submodules in .gitmodules:");
+    printTable(submodules);
+    return;
+  }
+
+  if (argv.clean) {
+    console.log("Removing submodule directories...");
+    for (const sub of submodules) {
+      const submoduleDir = resolve(dir, sub.path);
+      if (existsSync(submoduleDir)) {
+        console.log(`Removing directory: ${submoduleDir}`);
+        rmSync(submoduleDir, { recursive: true, force: true });
+      } else {
+        console.log(`Directory not found, skipping: ${submoduleDir}`);
+      }
+    }
+    console.log("Clean operation complete.");
+    return;
+  }
+
+  for (const sub of submodules) {
+    const submoduleDir = resolve(dir, sub.path);
+
+    if (argv.verbose) {
+      console.log(`Processing submodule:`);
+      console.log(`  URL: ${sub.url}`);
+      console.log(`  Path: ${submoduleDir}`);
+    } else {
+      console.log(`Cloning submodule from ${sub.url} into ${submoduleDir}...`);
+    }
+
+    try {
+      if (argv.force && existsSync(submoduleDir)) {
+        if (argv.verbose) {
+          console.log(`Force flag enabled. Removing existing directory: ${submoduleDir}`);
+        }
+        rmSync(submoduleDir, { recursive: true, force: true });
+      } else if (existsSync(submoduleDir)) {
+        if (argv.verbose) {
+          console.log(`Directory ${submoduleDir} already exists. Skipping clone.`);
+        }
+        continue;
+      }
+
+      await git.clone({
+        fs: fs,
+        http: { ...http, timeout: argv.timeout },
+        dir: submoduleDir,
+        url: sub.url,
+        singleBranch: true,
+        depth: 1
+      });
+
+      console.log(`Successfully cloned submodule into ${submoduleDir}.`);
+    } catch (error) {
+      console.error(`Error cloning submodule into ${submoduleDir}:`, error.message);
+    }
+  }
+}
+
+main();