@colordx/gpu 0.1.0 → 0.2.0

package/README.md

@@ -5,9 +5,13 @@
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-ffc200?labelColor=764be5)](https://github.com/dkryaklin/colordx-gpu/blob/main/package.json)
 [![MIT license](https://img.shields.io/badge/license-MIT-ffc200?labelColor=764be5)](https://github.com/dkryaklin/colordx-gpu/blob/main/LICENSE)
 
-GPU companion for [**@colordx/core**](https://github.com/dkryaklin/colordx) — renders OKLCH / CIE LCH gamut-slice charts in a single WebGL2 draw call, with sRGB / Display-P3 / Rec.2020 classification and crisp gamut-boundary lines. The shader math is generated from colordx's own constants, so the GPU renders exactly the colors the library computes.
+[**@colordx/core**](https://github.com/dkryaklin/colordx)'s color math, running on the GPU.
 
-A full chart repaint — every pixel converted from OKLCH, classified against three gamuts, boundary lines drawn — takes **well under a millisecond** on the GPU. The same work on the CPU costs tens of milliseconds across a whole worker pool. That turns "repaint after the slider settles" into "repaint every frame while dragging", and removes pixel count as a constraint: charts can be fullscreen.
+**The idea:** a color library converts one color at a time, and on the CPU that's the right tool for app logic. But a whole class of color work is *per-pixel*: gamut visualizations, picker charts, gradients, image filters. There you don't want to convert a color — you want to convert **millions of them, every frame**. `@colordx/gpu` takes colordx's conversions — OKLCH/OKLab, CIE LCH/Lab (D50), Display-P3, Rec.2020, gamut tests — and generates GLSL from the library's own constants, so the exact same math runs in a shader at GPU speed. A parity test suite locks the two implementations together: if colordx's math ever changes, the build fails before the shader can drift.
+
+What that buys you in practice: work that costs tens of milliseconds across a full worker pool on the CPU takes **well under a millisecond** as a single GPU draw — fast enough to recompute every visible pixel on every frame of a slider drag, at any canvas size up to fullscreen.
+
+**What ships today** is the first module built on that foundation: a gamut-slice chart renderer (the core of every OKLCH/LCH picker UI) — slice planes through the color space with sRGB / Display-P3 / Rec.2020 classification and crisp gamut-boundary lines. Next up: the GLSL chunks as public API so you can compose colordx math into your own shaders, gradient strips, and a WebGPU batch-conversion path — see the [Roadmap](#roadmap).
 
 ## Performance
 
@@ -75,9 +79,10 @@ Renders one gamut slice. Returns `false` while the WebGL context is lost (it re-
 | `showP3` | Also paint the P3-only region (sRGB-only pixels otherwise) |
 | `showRec2020` | Also paint the Rec.2020-only region |
 | `borderP3`, `borderRec2020` | RGBA arrays (0–1) for the boundary lines |
+| `borderWidth` | Boundary line width in device pixels (default `1` — a hairline, half a CSS pixel on a 2× display) |
 | `p3Output` | Encode output as Display-P3 and switch the drawing buffer to `display-p3` (Chrome 104+, Safari 16.4+; silently stays sRGB elsewhere) |
 
-Pixels outside every enabled gamut are transparent. Boundary lines are analytic contours of the gamut overflow field (`fwidth`-based), so they stay ~1.5 px crisp at any canvas size or DPR.
+Pixels outside every enabled gamut are transparent. Boundary lines are anti-aliased analytic contours of the gamut overflow field (`fwidth`-based), `borderWidth` device pixels wide at any canvas size or DPR.
 
 ### `renderer.destroy()`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@colordx/gpu",
-  "version": "0.1.0",
-  "description": "GPU companion for @colordx/core — WebGL2 gamut-slice chart rendering with sRGB/Display-P3/Rec.2020 classification, generated from colordx's own color math",
+  "version": "0.2.0",
+  "description": "colordx color math on the GPU — OKLCH/LCH conversions and gamut tests as generated GLSL, parity-tested against @colordx/core. Ships a WebGL2 gamut-slice chart renderer; shader chunks and WebGPU batch conversion on the roadmap",
   "author": "Dmitrii Kriaklin",
   "license": "MIT",
   "homepage": "https://colordx.dev",

package/src/glsl.js

@@ -64,6 +64,7 @@ uniform float u_value;
 uniform float u_xMax, u_yMax;
 uniform bool u_showP3, u_showRec2020, u_p3Out;
 uniform vec4 u_borderP3, u_borderRec2020;
+uniform float u_borderWidth;  // device pixels
 
 const float GAP = 1e-7;       // RENDER_GAP twin
 
@@ -76,10 +77,25 @@ float overflow(vec3 c) {
   vec3 d = max(c - 1.0, -c);
   return max(d.r, max(d.g, d.b));
 }
+// coverage of a u_borderWidth-px-wide band centered on the field's zero
+// contour: fwidth(field) is the field's change across one device pixel, so
+// dividing by it converts field distance to pixel distance
+float contour(float field) {
+  float px = max(fwidth(field), 1e-12);
+  return clamp((0.5 * u_borderWidth + 0.5) - abs(field) / px, 0.0, 1.0);
+}
+// composite the border over the fill by its pixel coverage; alpha only
+// grows so a translucent border can't punch a hole in an opaque fill
+vec4 blendBorder(vec4 fill, vec4 border, float cov) {
+  float a = cov * border.a;
+  return vec4(mix(fill.rgb, border.rgb, a), max(fill.a, a));
+}
 
 void main() {
-  // gl_FragCoord y is bottom-up, matching the picker's paintPixel flip
-  vec2 uv = gl_FragCoord.xy / u_res;
+  // gl_FragCoord y is bottom-up, matching the picker's paintPixel flip.
+  // Sample where the CPU painter did: column corner on x, and its
+  // one-pixel y offset (paintPixel wrote row y to height - y).
+  vec2 uv = (gl_FragCoord.xy + vec2(-0.5, 0.5)) / u_res;
   float l, c, h;
   if (u_plane == 0)      { l = uv.x * u_xMax; c = uv.y * u_yMax; h = u_value; }
   else if (u_plane == 1) { h = uv.x * u_xMax; c = uv.y * u_yMax; l = u_value; }
@@ -101,17 +117,22 @@ void main() {
     vec3 enc = u_p3Out
       ? srgbEncode(clamp(linP3, 0.0, 1.0))
       : srgbEncode(clamp(lin, 0.0, 1.0));
+    // match the CPU painter's Math.floor(255 * v) quantization; the small
+    // bias absorbs fp32 jitter where 255 * v lands on an integer
+    enc = floor(enc * 255.0 + 1e-3) / 255.0;
     col = vec4(enc, 1.0);
   }
 
-  // boundary lines, ~1.5px crisp contours of the gamut overflow fields
-  float wS = 0.75 * fwidth(fs);
-  float wP = 0.75 * fwidth(fp);
+  // boundary lines: anti-aliased contours of the gamut overflow fields,
+  // u_borderWidth device pixels wide (a hairline by default, like the
+  // 1-device-pixel lines of a CPU painter)
+  float covS = contour(fs);
+  float covP = contour(fp);
   if (u_showP3) {
-    if (abs(fs) < wS && inP) col = u_borderP3;
-    if (u_showRec2020 && abs(fp) < wP && inR && !inS) col = u_borderRec2020;
+    if (inP) col = blendBorder(col, u_borderP3, covS);
+    if (u_showRec2020 && inR && !inS) col = blendBorder(col, u_borderRec2020, covP);
   } else if (u_showRec2020) {
-    if (abs(fs) < wS && inR) col = u_borderRec2020;
+    if (inR) col = blendBorder(col, u_borderRec2020, covS);
   }
 
   frag = vec4(col.rgb * col.a, col.a); // premultiplied alpha

package/src/index.d.ts

@@ -13,6 +13,12 @@ export interface ChartPaintOptions {
   borderP3: BorderRgba
   /** RGBA 0–1 for the P3↔Rec2020 (or sRGB↔Rec2020) boundary line */
   borderRec2020: BorderRgba
+  /**
+   * Boundary line width in device pixels (default 1 — a hairline, half a
+   * CSS pixel on a 2× display). Lines are anti-aliased, so fractional
+   * widths work.
+   */
+  borderWidth?: number
   /** Encode output for a display-p3 drawing buffer (wide-gamut displays) */
   p3Output?: boolean
   plane: ChartPlane
@@ -28,7 +34,11 @@ export interface ChartPaintOptions {
 
 export interface ChartRenderer {
   readonly canvas: HTMLCanvasElement
-  /** Release the WebGL context */
+  /**
+   * Release GPU resources and make the renderer inert. Does not lose the
+   * WebGL context (a canvas can only ever produce one), so a new renderer
+   * can be created on the same canvas afterwards.
+   */
   destroy(): void
   /** Render a slice; returns false while the WebGL context is lost */
   paint(opts: ChartPaintOptions): boolean

package/src/index.js

@@ -18,11 +18,16 @@ export function createChartRenderer(canvas, options = {}) {
     premultipliedAlpha: true,
     stencil: false,
   })
-  if (!gl) return null
+  if (!gl || gl.isContextLost()) return null
+
+  // dithering is on by default and driver-dependent; disable it so the
+  // float → 8-bit conversion is deterministic everywhere
+  gl.disable(gl.DITHER)
 
   let program = null
   let uniforms = null
   let contextLost = false
+  let destroyed = false
 
   function init() {
     const compile = (type, src) => {
@@ -45,17 +50,20 @@ export function createChartRenderer(canvas, options = {}) {
     uniforms = {}
     for (const name of [
       'u_res', 'u_plane', 'u_value', 'u_xMax', 'u_yMax',
-      'u_showP3', 'u_showRec2020', 'u_p3Out', 'u_borderP3', 'u_borderRec2020',
+      'u_showP3', 'u_showRec2020', 'u_p3Out',
+      'u_borderP3', 'u_borderRec2020', 'u_borderWidth',
     ]) {
       uniforms[name] = gl.getUniformLocation(program, name)
     }
   }
 
   canvas.addEventListener('webglcontextlost', e => {
+    if (destroyed) return
     e.preventDefault()
     contextLost = true
   })
   canvas.addEventListener('webglcontextrestored', () => {
+    if (destroyed) return
     contextLost = false
     init()
   })
@@ -66,10 +74,16 @@ export function createChartRenderer(canvas, options = {}) {
   return {
     canvas,
     destroy() {
-      gl.getExtension('WEBGL_lose_context')?.loseContext()
+      // Do NOT force-lose the context: a canvas can only ever produce one
+      // WebGL context, so losing it would break any later renderer on the
+      // same canvas (e.g. a React StrictMode remount). Just release the
+      // program and go inert; the context is reclaimed with the canvas.
+      destroyed = true
+      gl.deleteProgram(program)
+      program = null
     },
     paint(opts) {
-      if (contextLost) return false
+      if (destroyed || contextLost || !program) return false
 
       if ('drawingBufferColorSpace' in gl) {
         try {
@@ -92,6 +106,7 @@ export function createChartRenderer(canvas, options = {}) {
       gl.uniform1i(uniforms.u_p3Out, opts.p3Output ? 1 : 0)
       gl.uniform4fv(uniforms.u_borderP3, opts.borderP3)
       gl.uniform4fv(uniforms.u_borderRec2020, opts.borderRec2020)
+      gl.uniform1f(uniforms.u_borderWidth, opts.borderWidth ?? 1)
       gl.drawArrays(gl.TRIANGLES, 0, 3)
       return true
     },