Members
# constant ABI_VERSION
ABI version of the kernel interface, checked by the JS loader.
# constant DISPLAY_CHANGE_POLL_FALLBACK_MS
Default polling fallback when no media query change listener can be attached.
# constant DISPLAY_CHANGE_POLL_FALLBACK_MS
Default polling fallback when no media query change listener can be attached.
# constant DISPLAY_CHANGE_QUERIES
Media queries re-evaluated by onDisplayChange.
# constant DISPLAY_CHANGE_QUERIES
Media queries re-evaluated by onDisplayChange.
# constant WASM_MIN_VALUES
Minimum Float16Array length (values, not pixels) for dispatching to WASM.
Below this the call + copy overhead outweighs the kernel win.
# constant WASM_MIN_VALUES
Minimum Float16Array length (values, not pixels) for dispatching to WASM.
Below this the call + copy overhead outweighs the kernel win.
Methods
# arena_alloc()
Bump-allocates size bytes (8-byte aligned), growing memory as needed.
The pointer, or 0 on failure.
# arena_reset()
Resets the arena; the next alloc reuses memory from the arena base.
# checkColorGamutP3() → {boolean}
Check if the Display P3 color gamut is supported using the (color-gamut: p3) CSS Media Query.
See https://developer.mozilla.org/en-US/docs/Web/CSS/@media/color-gamut
boolean
# checkColorGamutRec2020() → {boolean}
Check if the Rec.2020 color gamut is supported using the (color-gamut: rec2020) CSS Media Query.
Note that almost no consumer display covers Rec.2020, so false is the normal answer
even on good HDR monitors.
See https://developer.mozilla.org/en-US/docs/Web/CSS/@media/color-gamut
boolean
# checkDynamicRangeHigh() → {boolean}
Check if a high dynamic range is supported using the (dynamic-range: high) CSS Media Query.
This says nothing about the supported color gamut, combine it with checkWCG
(or use checkHDR for both) to distinguish HDR-only from HDR with wide color gamut.
See https://developer.mozilla.org/en-US/docs/Web/CSS/@media/dynamic-range
boolean
# checkFloat16Array() → {boolean}
Check if Float16Array is supported, to be used in {ImageData}
boolean
# checkHDR() → {boolean}
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. Note that HDR usually includes WCG, use checkWCG and checkDynamicRangeHigh to detect both capabilities separately (see https://github.com/cmahnke/hdr-canvas/issues/23). This function is kept as composite check for backwards compatibility.
boolean
# checkHDRBitDepth() → {boolean}
Check if the supported bit depth is larger then 8
Note that this is only a heuristic: browsers commonly report a colorDepth of 24
even on HDR displays, and WCG-only screens (display-p3, still 8 bit per channel)
are not distinguished from SDR. On multi-screen setups (see
https://github.com/cmahnke/hdr-canvas/issues/107) re-call this - and the other
checks - when the screen changes, e.g. via onDisplayChange, because
one-shot results go stale once the window moves to another display.
boolean
# checkHDRCanvas() → {boolean}
Check if HDR content is supported in a {HTMLCanvasElement} by tying to get a HDR enabled {CanvasRenderingContext2D}
Note that this requires both HDR (dynamic range) and WCG support plus Float16Array,
use checkWCGCanvas to detect WCG-only canvas support (e.g. Safari / Firefox on macOS).
boolean
# checkWCG() → {boolean}
Check if Wide Color Gamut (WCG) content is supported using the (color-gamut: p3)
and (color-gamut: rec2020) CSS Media Queries.
This detects WCG independently of HDR: Safari and Firefox on macOS support WCG
(display-p3) canvases without supporting HDR, see https://github.com/cmahnke/hdr-canvas/issues/23.
boolean
# checkWCGCanvas() → {boolean}
Check if Wide Color Gamut (WCG) content is supported in a {HTMLCanvasElement}
by trying to get a display-p3 enabled {CanvasRenderingContext2D}.
Unlike checkHDRCanvas this doesn't require Float16Array / HDR support,
so it also returns true on WCG-only browsers like Safari or Firefox on macOS.
boolean
# f32ToF16()
Encodes f32 to raw f16 bits with round-to-nearest-even.
# gain_run()
Multiplies quads RGBA pixels at ptr by per-channel gains, in place.
Alpha uses ga (pass 1 to preserve it).
# getDisplayCapabilities()
Returns the current display capabilities as a single snapshot.
# getHdrOptions() → {CanvasRenderingContext2DHDRSettings}
Gets a CanvasRenderingContext2DSettings object configured for HDR.
This function detects the browser version to determine the appropriate colorType for HDR support.
An options object for creating an HDR canvas context.
CanvasRenderingContext2DHDRSettings
# getWcgOptions() → {CanvasRenderingContext2DHDRSettings}
Gets a CanvasRenderingContext2DSettings object configured for Wide Color Gamut (WCG).
This uses the display-p3 color space without requiring HDR (float16 / extended tone mapping),
so it also works on WCG-only browsers like Safari or Firefox on macOS.
See https://github.com/cmahnke/hdr-canvas/issues/23
An options object for creating a WCG canvas context.
CanvasRenderingContext2DHDRSettings
# initHDRCanvas(canvas) → {CanvasRenderingContext2DHDR|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.
Parameters:
| Name | Type | Description |
|---|---|---|
canvas |
HDRHTMLCanvasElement
|
The canvas element to initialize. |
The 2D rendering context, or null if the context cannot be created. Can be cast down to CanvasRenderingContext2D or RenderingContext
CanvasRenderingContext2DHDR
|
null
# isSafari() → {boolean}
Detects Safari based on the user agent string. This is used to work around Safari's different HDR canvas support.
true if the browser is Safari.
boolean
# isWasmEnabled()
Whether WASM acceleration is enabled (opt-in via setWasmEnabled(true)).
# isWasmReady()
Whether a WASM kernel instance is currently instantiated and cached.
# matchMediaQuery(query) → {boolean}
Safely evaluates a CSS media query, returning false if matchMedia isn't available.
Parameters:
| Name | Type | Description |
|---|---|---|
query |
string
|
The media query to evaluate. |
true if the query matches.
boolean
# onDisplayChange(callback, optionsopt) → {function}
Subscribe to display capability changes (e.g. the window moves between an HDR
and an SDR / external screen), see https://github.com/cmahnke/hdr-canvas/issues/107.
Uses media query change events where available, with optional polling fallback
(automatic when no change listener can be attached).
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
callback |
DisplayChangeCallback
|
Invoked with the new capabilities on change. |
|
options |
DisplayChangeOptions
|
<optional> |
Polling configuration. |
Unsubscribe function that removes all listeners and timers.
function
# setWasmEnabled()
Enables or disables the experimental WASM acceleration (default: disabled).
# tryApplyGainWasm()
Runs the WASM gain kernel in place over data (raw f16 bits, RGBA quads).
Alpha is multiplied by ga (pass 1 to preserve it).
true if the kernel ran, false if the caller should use the JS
implementation instead. Never throws.
Type Definitions
# DisplayChangeCallback(capabilities)
Callback invoked with the new display capabilities when they change.
Parameters:
| Name | Type | Description |
|---|---|---|
capabilities |
DisplayCapabilities
|
# DisplayChangeCallback(capabilities)
Callback invoked with the new display capabilities when they change.
Parameters:
| Name | Type | Description |
|---|---|---|
capabilities |
DisplayCapabilities
|
# HDRImagePixelCallback(red, green, blue, alpha, red, green, blue, alpha) → {ImageDataArray}
A callback function that receives the red, green, blue, and alpha values of a pixel
and returns a new Float16Array with the modified values.
Parameters:
| Name | Type | Description |
|---|---|---|
red |
number
|
The red channel value (float, |
green |
number
|
The green channel value (float, |
blue |
number
|
The blue channel value (float, |
alpha |
number
|
The alpha channel value ( |
red |
number
|
|
green |
number
|
|
blue |
number
|
|
alpha |
number
|
A new Float16Array containing the four channel values.
ImageDataArray
# HDRImagePixelCallback(red, green, blue, alpha, red, green, blue, alpha) → {ImageDataArray}
A callback function that receives the red, green, blue, and alpha values of a pixel
and returns a new Float16Array with the modified values.
Parameters:
| Name | Type | Description |
|---|---|---|
red |
number
|
The red channel value (float, |
green |
number
|
The green channel value (float, |
blue |
number
|
The blue channel value (float, |
alpha |
number
|
The alpha channel value ( |
red |
number
|
|
green |
number
|
|
blue |
number
|
|
alpha |
number
|
A new Float16Array containing the four channel values.
ImageDataArray
object
# KernelExports
Experimental WASM acceleration for Float16Image pixel loops.
Disabled by default: enable explicitly with setWasmEnabled(true).
The WASM kernel is inlined as base64 (no .wasm asset URL handling), and
every accelerated call falls back to plain JS when WebAssembly is
unavailable, denied (e.g. CSP without wasm-unsafe-eval), or fails for any
other reason. The WASM path never throws.
Measured reality (Node 24, gain over 12 M values): JS ~12 ms vs WASM ~51 ms
with only ~3 ms of that in copies. Engines with native Float16Array
convert via hardware F16C instructions that this scalar kernel can't beat,
so keep the flag off for gain. The loader stays as tested infrastructure
for future compute-heavy kernels where arithmetic intensity amortizes the
copy cost.
Properties:
| Name | Type | Description |
|---|---|---|
memory |
WebAssembly.Memory
|
|
ABI_VERSION |
WebAssembly.Global
|
|
arena_reset |
function
|
|
arena_alloc |
function
|
|
gain_run |
function
|
object
# KernelExports
Experimental WASM acceleration for Float16Image pixel loops.
Disabled by default: enable explicitly with setWasmEnabled(true).
The WASM kernel is inlined as base64 (no .wasm asset URL handling), and
every accelerated call falls back to plain JS when WebAssembly is
unavailable, denied (e.g. CSP without wasm-unsafe-eval), or fails for any
other reason. The WASM path never throws.
Measured reality (Node 24, gain over 12 M values): JS ~12 ms vs WASM ~51 ms
with only ~3 ms of that in copies. Engines with native Float16Array
convert via hardware F16C instructions that this scalar kernel can't beat,
so keep the flag off for gain. The loader stays as tested infrastructure
for future compute-heavy kernels where arithmetic intensity amortizes the
copy cost.
Properties:
| Name | Type | Description |
|---|---|---|
memory |
WebAssembly.Memory
|
|
ABI_VERSION |
WebAssembly.Global
|
|
arena_reset |
function
|
|
arena_alloc |
function
|
|
gain_run |
function
|