hdr-canvas 0.0.13 → 0.1.0

package/src/hdr-canvas.ts

@@ -1,28 +1,72 @@
-import { Uint16Image } from "./Uint16Image";
+import { HDRImage } from "./HDRImage";
+import { getBrowserVersion } from "./browser-util";
 
-import type { HDRHTMLCanvasElement } from "./types/HDRCanvas.d.ts";
+import type { HDRHTMLCanvasElement, CanvasRenderingContext2DHDRSettings, CanvasRenderingContext2DHDR } from "./types/HDRCanvas.d.ts";
 
-const hdr_options = { colorSpace: Uint16Image.DEFAULT_COLORSPACE, pixelFormat: "float16" };
+/**
+ * Gets a `CanvasRenderingContext2DSettings` object configured for HDR.
+ * This function detects the browser version to determine the appropriate `colorType` for HDR support.
+ *
+ * @returns {CanvasRenderingContext2DHDRSettings} An options object for creating an HDR canvas context.
+ */
+export function getHdrOptions(): CanvasRenderingContext2DHDRSettings {
+  const hdrOptions: CanvasRenderingContext2DHDRSettings = { colorSpace: HDRImage.DEFAULT_COLORSPACE };
+  const browserMajorVersion = getBrowserVersion();
+  if (browserMajorVersion == null) {
+    console.warn(`Unsupported / untested browser (${navigator.userAgent}) detected - using more modern defaults`);
+    hdrOptions["colorType"] = "float16";
+  } else {
+    if (browserMajorVersion < 134) {
+      console.warn("Older Chrome / chromium based browser detected, using older `pixelFormat`");
+    } else {
+      hdrOptions["pixelFormat"] = "float16";
+    }
+  }
+
+  return hdrOptions;
+}
 
-export function initHDRCanvas(canvas: HDRHTMLCanvasElement): RenderingContext | null {
+/**
+ * Initializes a given `HTMLCanvasElement` for HDR and returns its 2D rendering context.
+ * It first configures the canvas for high dynamic range and then gets the 2D context with HDR options.
+ *
+ * @param {HDRHTMLCanvasElement} canvas - The canvas element to initialize.
+ * @returns {CanvasRenderingContext2DHDR | null} The 2D rendering context, or `null` if the context cannot be created. Can be cast down to `CanvasRenderingContext2D` or `RenderingContext`
+ */
+export function initHDRCanvas(canvas: HDRHTMLCanvasElement): CanvasRenderingContext2DHDR | null {
   canvas.configureHighDynamicRange({ mode: "extended" });
-  const ctx = canvas.getContext("2d", hdr_options);
-  return ctx;
+  const ctx = canvas.getContext("2d", getHdrOptions());
+  return ctx as CanvasRenderingContext2DHDR;
 }
 
+/**
+ * Patches the `getContext` method of `HTMLCanvasElement` to default to HDR settings.
+ * This allows all subsequent calls to `getContext('2d')` to be HDR-enabled without
+ * explicitly passing the HDR options.
+ *
+ * @remarks
+ * This function modifies the global `HTMLCanvasElement.prototype` and should be used with caution.
+ */
 /* eslint-disable  @typescript-eslint/no-explicit-any */
 export function defaultGetContextHDR() {
   (HTMLCanvasElement.prototype as HDRHTMLCanvasElement)._getContext = HTMLCanvasElement.prototype.getContext;
   (HTMLCanvasElement.prototype as any).getContext = function (type: string, options: object) {
     if (options !== undefined) {
-      options = Object.assign({}, options, hdr_options);
+      options = Object.assign({}, options, getHdrOptions());
     } else {
-      options = hdr_options;
+      options = getHdrOptions();
     }
     return (this as HDRHTMLCanvasElement)._getContext(type, options);
   };
 }
 
+/**
+ * Resets the `getContext` method of `HTMLCanvasElement` to its original behavior.
+ * This reverses the changes made by `defaultGetContextHDR`.
+ *
+ * @remarks
+ * This function only works if `defaultGetContextHDR` has been previously called.
+ */
 /* eslint-disable  @typescript-eslint/no-explicit-any */
 export function resetGetContext() {
   if (typeof (HTMLCanvasElement.prototype as HDRHTMLCanvasElement)._getContext === "function") {

package/src/hdr-check.ts

@@ -1,3 +1,26 @@
+import { getHdrOptions } from "./hdr-canvas";
+
+// See https://developer.mozilla.org/en-US/docs/Web/CSS/@media/video-dynamic-range
+
+/** Check if HDR video is supported using a CSS Media Query.
+ * @returns {boolean}
+ */
+export function checkHDRVideo(): boolean {
+  try {
+    const dynamicRangeVideoHighMQ: boolean = window.matchMedia("(video-dynamic-range: high)").matches;
+    if (dynamicRangeVideoHighMQ) {
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/** Check if HDR content (like images) are supported using two CSS Media Queries:
+ * One for HDR content itself and another one for the rec2020 colorspace
+ * @returns {boolean}
+ */
 export function checkHDR(): boolean {
   try {
     const bitsPerChannel: number = screen.colorDepth / 3;
@@ -18,39 +41,34 @@ export function checkHDR(): boolean {
     }
     return false;
   } catch (e) {
-    /* eslint-disable no-console */
-    console.error("Bad window.screen test", e);
-    /* eslint-enable */
+    console.error("Exception during check for HDR", e);
     return false;
   }
 }
 
+/** Check if HDR content is supported in a {HTMLCanvasElement} by tying to get a HDR enabled {CanvasRenderingContext2D}
+ * @returns {boolean}
+ */
 export function checkHDRCanvas(): boolean {
-  const colorSpace: string = "rec2100-pq";
-
   try {
     const canvas: HTMLCanvasElement = document.createElement("canvas");
     if (!canvas.getContext) {
       return false;
     }
-    const ctx: CanvasRenderingContext2D | null = <CanvasRenderingContext2D>canvas.getContext("2d", {
-      colorSpace: colorSpace,
-      pixelFormat: "float16"
-    });
+
+    const options = getHdrOptions();
+    const ctx: CanvasRenderingContext2D | null = <CanvasRenderingContext2D>canvas.getContext("2d", options);
     //canvas.drawingBufferColorSpace = colorSpace;
     //canvas.unpackColorSpace = colorSpace;
     if (ctx === null) {
       return false;
     }
     return true;
-    /* eslint-disable no-console, @typescript-eslint/no-unused-vars */
-  } catch (e) {
-    //console.error("Bad canvas ColorSpace test", e);
+  } catch {
     console.error(
       "Bad canvas ColorSpace test - make sure that the Chromium browser flag 'enable-experimental-web-platform-features' has been enabled"
     );
 
     return false;
   }
-  /* eslint-enable */
 }

package/src/index.ts

@@ -1,3 +1,5 @@
 export { Uint16Image } from "./Uint16Image";
+export { Float16Image } from "./Float16Image";
+export { HDRImage } from "./HDRImage";
 export { checkHDR, checkHDRCanvas } from "./hdr-check";
 export { initHDRCanvas, defaultGetContextHDR, resetGetContext } from "./hdr-canvas";

package/src/types/HDRCanvas.d.ts

@@ -4,6 +4,8 @@
 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;
@@ -11,15 +13,44 @@ 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";
 
 //enum HDRPredefinedColorSpace {"display-p3", "srgb", "rec2100-hlg", "rec2100-pq", "rec2100-display-linear"};
 
-export { HDRHTMLCanvasElement, HDRPredefinedColorSpace, HDRImageData };
+/**
+ * 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 {}
+
+interface CanvasRenderingContext2DHDRSettings {
+  colorSpace: HDRPredefinedColorSpace;
+  pixelFormat?: "uint8" | "float16";
+  colorType?: "unorm8" | "float16";
+}
+
+export {
+  HDRHTMLCanvasElement,
+  HDRPredefinedColorSpace,
+  HDRImageDataArray,
+  HDRImageData,
+  HDRImagePixelCallback,
+  CanvasRenderingContext2DHDR,
+  CanvasRenderingContext2DHDRSettings
+};

package/src/types/ImageData.d.ts

@@ -0,0 +1,17 @@
+export {};
+
+declare global {
+  var ImageDataSettings: {
+    prototype: ImageDataSettings;
+    pixelFormat?: ImageDataPixelFormat;
+  };
+
+  var ImageData: {
+    prototype: ImageData;
+    pixelFormat: ImageDataPixelFormat;
+  };
+
+  type ImageDataArray = Uint8ClampedArray | Float16Array;
+
+  type ImageDataPixelFormat = "rgba-unorm8" | "rgba-float16";
+}

package/three/HDRWebGPUBackend.js

@@ -1,8 +1,25 @@
 import WebGPUBackend from 'three/src/renderers/webgpu/WebGPUBackend.js';
 import { GPUFeatureName, GPUTextureFormat } from 'three/src/renderers/webgpu/utils/WebGPUConstants.js';
 
+/**
+ * An HDR-enabled WebGPU backend for three.js, extending the standard `WebGPUBackend`.
+ * This class configures the WebGPU context to support High Dynamic Range rendering
+ * by setting the output color space to "rec2100-hlg".
+ * **You should never have the need to use this!**
+ *
+ * @class
+ * @augments {WebGPUBackend}
+ */
+
 class HDRWebGPUBackend extends WebGPUBackend {
 
+  /**
+   * Initializes the backend, including requesting a WebGPU device and configuring the context.
+   * This method overrides the parent `init` to set a specific HDR color space.
+   *
+   * @param {WebGLRenderer} renderer - The three.js renderer instance.
+   * @returns {Promise<void>} A promise that resolves when the initialization is complete.
+   */
   // See https://github.com/mrdoob/three.js/blob/master/examples/jsm/renderers/webgpu/WebGPUBackend.js#L123
   async init( renderer ) {
 
@@ -67,6 +84,11 @@ class HDRWebGPUBackend extends WebGPUBackend {
 		const alphaMode = parameters.alpha ? 'premultiplied' : 'opaque';
 
     // See https://github.com/ccameron-chromium/webgpu-hdr/blob/main/EXPLAINER.md#example-use
+    /**
+     * Configures the WebGPU context with HDR settings.
+     * The `colorSpace` is set to `rec2100-hlg` for High Dynamic Range support.
+     * @see {@link https://github.com/ccameron-chromium/webgpu-hdr/blob/main/EXPLAINER.md#example-use | WebGPU HDR Explainer}
+     */
 		this.context.configure( {
 			device: this.device,
 			format: GPUTextureFormat.BGRA8Unorm,

package/three/HDRWebGPURenderer.js

@@ -4,7 +4,22 @@ import Renderer from 'three/src/renderers/common/Renderer.js';
 import WebGLBackend from 'three/src/renderers/webgl-fallback/WebGLBackend.js';
 import HDRWebGPUBackend from './HDRWebGPUBackend.js';
 
+/**
+ * HDR enabled WebGPURenderer.
+ *
+ * @class
+ * @augments {Renderer}
+ * @fires contextrestored
+ * @fires contextlost
+ * @see {@link https://threejs.org/docs/#api/en/renderers/WebGLRenderer | WebGLRenderer}
+ */
 class HDRWebGPURenderer extends Renderer {
+  /**
+   * Creates an instance of HDRWebGPURenderer.
+   *
+   * @constructor
+   * @param {object} [parameters={}] - The parameters for the renderer.
+   */
   constructor( parameters = {} ) {
 
 		let BackendClass;
@@ -31,6 +46,10 @@ class HDRWebGPURenderer extends Renderer {
 
 		super( backend, parameters );
 
+    /**
+     * @type {boolean}
+     * @default true
+     */
 		this.isWebGPURenderer = true;
 
 	}

package/tsconfig.json

@@ -5,21 +5,27 @@
     "removeComments": true,
     "preserveConstEnums": true,
     "sourceMap": true,
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "noEmit": false,
     "noEmitOnError": true,
     "esModuleInterop": true,
     "strict": true,
     "strictNullChecks": true,
+    "strictPropertyInitialization": false,
     "declaration": true,
-    "allowJs": false,
-    "skipLibCheck": false,
-    "target": "es2022",
+    "allowJs": true,
+    "skipLibCheck": true,
+    "target": "es2024",
     "outDir": "dist",
     "declarationDir": "dist",
     "typeRoots": ["./node_modules/@types"],
-    "lib": ["dom", "es2022"]
+    "lib": ["es2024"],
+    "paths": {
+      "~/hdr-canvas/three/*": ["./three/*"],
+      "~/hdr-canvas/*": ["./src/*"],
+      "three": ["./node_modules/@types/three"]
+    }
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "tests/site/**/*", "tests/*"],
   "exclude": ["node_modules", "**/*.spec.ts", "three/**/*"]
 }

package/dist/hdr-canvas.d.ts

@@ -1,4 +0,0 @@
-import type { HDRHTMLCanvasElement } from "./types/HDRCanvas.d.ts";
-export declare function initHDRCanvas(canvas: HDRHTMLCanvasElement): RenderingContext | null;
-export declare function defaultGetContextHDR(): void;
-export declare function resetGetContext(): void;