palette-shader 0.19.0 → 0.20.0

package/README.md

@@ -174,10 +174,21 @@ viz.removeColor([0.659, 0.855, 0.863]);
 
 Cancel the animation frame, release all WebGL resources (programs, textures, framebuffer, buffer, VAO), and remove the canvas from the DOM.
 
+### `render()`
+
+Force a synchronous render immediately, bypassing the `requestAnimationFrame` schedule. Use this when the canvas (or its WebGL drawing buffer) must reflect the latest state right now — for example before reading pixels back from the canvas in the same JS tick.
+
+```js
+viz.render();
+// canvas drawing buffer is now up to date — safe to readPixels(...)
+```
+
 ### `getColorAtUV(x, y)`
 
 Returns the current shader result at normalized UV coordinates (`0–1` on both axes) as `[r, g, b]` in `0–1` sRGB. This reads directly from the WebGL render target (or outline source buffer), not from DOM canvas sampling.
 
+When a paint is already pending (state changed since the last frame) it renders first; when the render target is already current it skips the redundant render and reads back directly. If you need to guarantee a fresh render as a side effect, call `render()` explicitly.
+
 ```js
 const color = viz.getColorAtUV(0.5, 0.5); // center
 ```

package/dist/palette-shader.d.ts

@@ -40,6 +40,10 @@ declare abstract class BasePaletteRenderer {
     get width(): number;
     get height(): number;
     resize(width: number, height?: number | null): void;
+    /** Force a synchronous render immediately, bypassing the rAF schedule.
+     *  Use when the canvas/FBO must reflect the latest state right now — e.g.
+     *  before reading pixels back from the canvas. */
+    render(): void;
     set palette(palette: ColorList);
     get palette(): ColorList;
     set pixelRatio(value: number);

package/dist/palette-shader.js

@@ -142,7 +142,7 @@ ${_}`);
 function H(r, t) {
   r.bindTexture(r.TEXTURE_2D, t), r.texParameteri(r.TEXTURE_2D, r.TEXTURE_MIN_FILTER, r.NEAREST), r.texParameteri(r.TEXTURE_2D, r.TEXTURE_MAG_FILTER, r.NEAREST), r.texParameteri(r.TEXTURE_2D, r.TEXTURE_WRAP_S, r.CLAMP_TO_EDGE), r.texParameteri(r.TEXTURE_2D, r.TEXTURE_WRAP_T, r.CLAMP_TO_EDGE);
 }
-function O(r, t, n) {
+function S(r, t, n) {
   if (n.length === 0) throw new Error("Palette must contain at least one color");
   const e = new Float32Array(n.length * 4);
   n.forEach(([a, o, s], i) => {
@@ -1299,7 +1299,7 @@ vec3 closestColor(vec3 color, sampler2D paletteTexture) {
 
   return closest;
 }
-`, S = `
+`, O = `
 precision highp float;
 layout(location = 0) in vec2 a_position;
 out vec2 vUv;
@@ -2024,7 +2024,7 @@ class lt {
     this.paletteState = t, this.cssWidth = n, this.cssHeight = e, this.pixelRatioState = a, this.observeResize = o, this.containerElement = s, this.canvasElement = document.createElement("canvas"), this.canvasElement.classList.add(i);
     const l = this.canvasElement.getContext("webgl2");
     if (!l) throw new Error("WebGL2 not supported");
-    this.glContext = l, this.paletteTexture = l.createTexture(), H(l, this.paletteTexture), O(l, this.paletteTexture, this.paletteState), this.metricTexture = l.createTexture(), H(l, this.metricTexture);
+    this.glContext = l, this.paletteTexture = l.createTexture(), H(l, this.paletteTexture), S(l, this.paletteTexture, this.paletteState), this.metricTexture = l.createTexture(), H(l, this.metricTexture);
   }
   normalizeInvertAxes(t) {
     const n = /* @__PURE__ */ new Set();
@@ -2088,9 +2088,15 @@ class lt {
     const { pw: e, ph: a } = this.syncCanvasSize(t, n ?? t);
     this.onSurfaceResized(e, a), this.schedulePaint();
   }
+  /** Force a synchronous render immediately, bypassing the rAF schedule.
+   *  Use when the canvas/FBO must reflect the latest state right now — e.g.
+   *  before reading pixels back from the canvas. */
+  render() {
+    this.destroyed || (this.flushScheduledPaint(), this.renderFrame());
+  }
   set palette(t) {
     if (t.length === 0) throw new Error("Palette must contain at least one color");
-    this.paletteState = t, O(this.glContext, this.paletteTexture, t), this.metricPaletteDirty = !0, this.schedulePaint();
+    this.paletteState = t, S(this.glContext, this.paletteTexture, t), this.metricPaletteDirty = !0, this.schedulePaint();
   }
   get palette() {
     return this.paletteState.slice();
@@ -2130,14 +2136,14 @@ class Xt extends lt {
   #g = null;
   #C = null;
   #y = null;
-  #O = null;
+  #S = null;
   // 1×1 float FBO for getColorAtUV_float (lazily created)
   #m = null;
   #p = null;
   #h = null;
   #I = null;
   #D = null;
-  #S = null;
+  #O = null;
   #P = null;
   #w = null;
   #A = !0;
@@ -2191,11 +2197,11 @@ class Xt extends lt {
       x[this.#c],
       this.#_
     );
-    this.#t = y(t, this.#k(), n, S), this.#u = t.getUniformLocation(this.#t, "progress"), this.#T = t.getUniformLocation(this.#t, "paletteTexture"), this.#b = t.getUniformLocation(this.#t, "paletteMetricTexture"), this.#R = t.getUniformLocation(this.#t, "uPaletteSize"), this.metricPaletteDirty = !0, this.#A = !0;
+    this.#t = y(t, this.#k(), n, O), this.#u = t.getUniformLocation(this.#t, "progress"), this.#T = t.getUniformLocation(this.#t, "paletteTexture"), this.#b = t.getUniformLocation(this.#t, "paletteMetricTexture"), this.#R = t.getUniformLocation(this.#t, "uPaletteSize"), this.metricPaletteDirty = !0, this.#A = !0;
   }
   #x() {
     const t = this.glContext;
-    this.#g = y(t, {}, it, S), this.#C = t.getUniformLocation(this.#g, "colorMap"), this.#y = t.getUniformLocation(this.#g, "outlineWidth"), this.#O = t.getUniformLocation(this.#g, "resolution"), this.#s = t.createTexture(), this.#e = t.createFramebuffer(), this.#L(this.canvas.width, this.canvas.height);
+    this.#g = y(t, {}, it, O), this.#C = t.getUniformLocation(this.#g, "colorMap"), this.#y = t.getUniformLocation(this.#g, "outlineWidth"), this.#S = t.getUniformLocation(this.#g, "resolution"), this.#s = t.createTexture(), this.#e = t.createFramebuffer(), this.#L(this.canvas.width, this.canvas.height);
   }
   #L(t, n) {
     const e = this.glContext;
@@ -2216,7 +2222,7 @@ class Xt extends lt {
   renderFrame() {
     this.#r && (this.#E(), this.#r = !1);
     const t = this.glContext;
-    t.bindFramebuffer(t.FRAMEBUFFER, this.#e), t.useProgram(this.#t), this.uploadMetricPalette(this.#R), t.uniform1f(this.#u, this.#d), t.activeTexture(t.TEXTURE0), t.bindTexture(t.TEXTURE_2D, this.paletteTexture), t.uniform1i(this.#T, 0), t.activeTexture(t.TEXTURE1), t.bindTexture(t.TEXTURE_2D, this.metricTexture), t.uniform1i(this.#b, 1), t.clearColor(0, 0, 0, 0), t.clear(t.COLOR_BUFFER_BIT), t.bindVertexArray(this.#a), t.drawArrays(t.TRIANGLE_STRIP, 0, 4), t.bindFramebuffer(t.FRAMEBUFFER, null), t.useProgram(this.#g), t.activeTexture(t.TEXTURE0), t.bindTexture(t.TEXTURE_2D, this.#s), t.uniform1i(this.#C, 0), t.uniform1f(this.#y, this.#_ ? 0 : this.#v), t.uniform2f(this.#O, this.canvas.width, this.canvas.height), t.clearColor(0, 0, 0, 0), t.clear(t.COLOR_BUFFER_BIT), t.drawArrays(t.TRIANGLE_STRIP, 0, 4), t.bindVertexArray(null);
+    t.bindFramebuffer(t.FRAMEBUFFER, this.#e), t.useProgram(this.#t), this.uploadMetricPalette(this.#R), t.uniform1f(this.#u, this.#d), t.activeTexture(t.TEXTURE0), t.bindTexture(t.TEXTURE_2D, this.paletteTexture), t.uniform1i(this.#T, 0), t.activeTexture(t.TEXTURE1), t.bindTexture(t.TEXTURE_2D, this.metricTexture), t.uniform1i(this.#b, 1), t.clearColor(0, 0, 0, 0), t.clear(t.COLOR_BUFFER_BIT), t.bindVertexArray(this.#a), t.drawArrays(t.TRIANGLE_STRIP, 0, 4), t.bindFramebuffer(t.FRAMEBUFFER, null), t.useProgram(this.#g), t.activeTexture(t.TEXTURE0), t.bindTexture(t.TEXTURE_2D, this.#s), t.uniform1i(this.#C, 0), t.uniform1f(this.#y, this.#_ ? 0 : this.#v), t.uniform2f(this.#S, this.canvas.width, this.canvas.height), t.clearColor(0, 0, 0, 0), t.clear(t.COLOR_BUFFER_BIT), t.drawArrays(t.TRIANGLE_STRIP, 0, 4), t.bindVertexArray(null);
   }
   // ── Public API ──────────────────────────────────────────────────────────────
   destroy() {
@@ -2228,10 +2234,10 @@ class Xt extends lt {
   setColor(t, n) {
     if (n < 0 || n >= this.paletteState.length)
       throw new Error(`Index ${n} out of range`);
-    this.paletteState[n] = t, O(this.glContext, this.paletteTexture, this.paletteState), this.metricPaletteDirty = !0, this.schedulePaint();
+    this.paletteState[n] = t, S(this.glContext, this.paletteTexture, this.paletteState), this.metricPaletteDirty = !0, this.schedulePaint();
   }
   addColor(t, n) {
-    this.paletteState.splice(n ?? this.paletteState.length, 0, t), O(this.glContext, this.paletteTexture, this.paletteState), this.metricPaletteDirty = !0, this.schedulePaint();
+    this.paletteState.splice(n ?? this.paletteState.length, 0, t), S(this.glContext, this.paletteTexture, this.paletteState), this.metricPaletteDirty = !0, this.schedulePaint();
   }
   removeColor(t) {
     const n = typeof t == "number" ? t : this.paletteState.findIndex(
@@ -2241,7 +2247,7 @@ class Xt extends lt {
     if (n < 0 || n >= this.paletteState.length)
       throw new Error(`Index ${n} out of range`);
     if (this.paletteState.length === 1) throw new Error("Palette must contain at least one color");
-    this.paletteState.splice(n, 1), O(this.glContext, this.paletteTexture, this.paletteState), this.metricPaletteDirty = !0, this.schedulePaint();
+    this.paletteState.splice(n, 1), S(this.glContext, this.paletteTexture, this.paletteState), this.metricPaletteDirty = !0, this.schedulePaint();
   }
   getColorAtUV(t, n) {
     if (!Number.isFinite(t) || !Number.isFinite(n))
@@ -2279,13 +2285,13 @@ class Xt extends lt {
         this.#_,
         !0
       );
-      this.#h = y(e, s, i, S), this.#I = e.getUniformLocation(this.#h, "progress"), this.#D = e.getUniformLocation(this.#h, "paletteTexture"), this.#S = e.getUniformLocation(
+      this.#h = y(e, s, i, O), this.#I = e.getUniformLocation(this.#h, "progress"), this.#D = e.getUniformLocation(this.#h, "paletteTexture"), this.#O = e.getUniformLocation(
         this.#h,
         "paletteMetricTexture"
       ), this.#P = e.getUniformLocation(this.#h, "uPaletteSize"), this.#w = e.getUniformLocation(this.#h, "uvOverride"), this.#A = !1;
     }
     const a = e.getParameter(e.VIEWPORT);
-    e.bindFramebuffer(e.FRAMEBUFFER, this.#m), e.viewport(0, 0, 1, 1), e.useProgram(this.#h), e.uniform2f(this.#w, t, n), e.uniform1f(this.#I, this.#d), e.uniform1i(this.#P, this.paletteState.length), e.activeTexture(e.TEXTURE0), e.bindTexture(e.TEXTURE_2D, this.paletteTexture), e.uniform1i(this.#D, 0), e.activeTexture(e.TEXTURE1), e.bindTexture(e.TEXTURE_2D, this.metricTexture), e.uniform1i(this.#S, 1), e.clearColor(0, 0, 0, 0), e.clear(e.COLOR_BUFFER_BIT), e.bindVertexArray(this.#a), e.drawArrays(e.TRIANGLE_STRIP, 0, 4), e.flush();
+    e.bindFramebuffer(e.FRAMEBUFFER, this.#m), e.viewport(0, 0, 1, 1), e.useProgram(this.#h), e.uniform2f(this.#w, t, n), e.uniform1f(this.#I, this.#d), e.uniform1i(this.#P, this.paletteState.length), e.activeTexture(e.TEXTURE0), e.bindTexture(e.TEXTURE_2D, this.paletteTexture), e.uniform1i(this.#D, 0), e.activeTexture(e.TEXTURE1), e.bindTexture(e.TEXTURE_2D, this.metricTexture), e.uniform1i(this.#O, 1), e.clearColor(0, 0, 0, 0), e.clear(e.COLOR_BUFFER_BIT), e.bindVertexArray(this.#a), e.drawArrays(e.TRIANGLE_STRIP, 0, 4), e.flush();
     const o = new Float32Array(4);
     return e.readPixels(0, 0, 1, 1, e.RGBA, e.FLOAT, o), e.bindFramebuffer(e.FRAMEBUFFER, null), e.bindVertexArray(null), e.viewport(a[0], a[1], a[2], a[3]), [o[0], o[1], o[2]];
   }
@@ -2346,7 +2352,7 @@ class Xt extends lt {
   /** @deprecated use PaletteViz.paletteToRGBA */
   static paletteToTexture = D;
 }
-function Ot(r) {
+function St(r) {
   const t = [], n = [], e = r, a = [
     // axisIndex, sign, uAxis, vAxis, uSign, vSign
     // +X face
@@ -2377,7 +2383,7 @@ function Ot(r) {
   }
   return { vertices: new Float32Array(t), indices: new Uint32Array(n) };
 }
-function St(r, t, n = 0) {
+function Ot(r, t, n = 0) {
   const e = [], a = [], o = r, s = -n, l = 1 + n - s;
   for (let _ = t; _ >= 0; _--) {
     const b = s + l * _ / t, C = e.length / 3;
@@ -2547,13 +2553,13 @@ class Ht extends lt {
   #g = 0;
   #C = null;
   #y = null;
-  #O = null;
+  #S = null;
   #m = null;
   #p = null;
   #h = null;
   #I = null;
   #D = null;
-  #S = null;
+  #O = null;
   #P = null;
   #w = null;
   #A = null;
@@ -2602,7 +2608,7 @@ class Ht extends lt {
       return;
     }
     this.#s = this.#n ? this.#U() : 0;
-    const { vertices: n, indices: e } = this.#n ? St(2, this.#s, Y) : Ot(64);
+    const { vertices: n, indices: e } = this.#n ? Ot(2, this.#s, Y) : St(64);
     this.#T = e.length, this.#r = t.createBuffer(), t.bindBuffer(t.ARRAY_BUFFER, this.#r), t.bufferData(t.ARRAY_BUFFER, n, t.STATIC_DRAW), this.#u = t.createBuffer(), t.bindBuffer(t.ELEMENT_ARRAY_BUFFER, this.#u), t.bufferData(t.ELEMENT_ARRAY_BUFFER, e, t.STATIC_DRAW), this.#a = t.createVertexArray(), t.bindVertexArray(this.#a), t.bindBuffer(t.ARRAY_BUFFER, this.#r), t.enableVertexAttribArray(0), t.vertexAttribPointer(0, 3, t.FLOAT, !1, 0, 0), t.bindBuffer(t.ELEMENT_ARRAY_BUFFER, this.#u), t.bindVertexArray(null);
   }
   #U() {
@@ -2667,7 +2673,7 @@ class Ht extends lt {
       E[this.#o],
       this.#n
     ), a = this.#e ? xt : Et;
-    this.#t = y(t, this.#J(), n, a), this.#l = y(t, this.#J(), e, a), this.#y = t.getUniformLocation(this.#t, "uMVP"), this.#O = t.getUniformLocation(this.#l, "uMVP"), this.#m = t.getUniformLocation(this.#t, "uPosition"), this.#p = t.getUniformLocation(this.#l, "uPosition"), this.#h = t.getUniformLocation(this.#t, "paletteTexture"), this.#I = t.getUniformLocation(this.#t, "paletteMetricTexture"), this.#D = t.getUniformLocation(this.#t, "uPaletteSize"), this.#S = t.getUniformLocation(this.#t, "uColorRotation"), this.#P = t.getUniformLocation(this.#l, "uColorRotation"), this.#w = t.getUniformLocation(this.#t, "uSliceOffset"), this.#A = t.getUniformLocation(this.#l, "uSliceOffset"), this.metricPaletteDirty = !0;
+    this.#t = y(t, this.#J(), n, a), this.#l = y(t, this.#J(), e, a), this.#y = t.getUniformLocation(this.#t, "uMVP"), this.#S = t.getUniformLocation(this.#l, "uMVP"), this.#m = t.getUniformLocation(this.#t, "uPosition"), this.#p = t.getUniformLocation(this.#l, "uPosition"), this.#h = t.getUniformLocation(this.#t, "paletteTexture"), this.#I = t.getUniformLocation(this.#t, "paletteMetricTexture"), this.#D = t.getUniformLocation(this.#t, "uPaletteSize"), this.#O = t.getUniformLocation(this.#t, "uColorRotation"), this.#P = t.getUniformLocation(this.#l, "uColorRotation"), this.#w = t.getUniformLocation(this.#t, "uSliceOffset"), this.#A = t.getUniformLocation(this.#l, "uSliceOffset"), this.metricPaletteDirty = !0;
   }
   #G(t, n, e, a) {
     const o = this.glContext;
@@ -2678,7 +2684,7 @@ class Ht extends lt {
   }
   #Q() {
     const t = this.glContext;
-    this.#x = t.createTexture(), this.#L = t.createRenderbuffer(), this.#E = t.createFramebuffer(), this.#K(this.canvas.width, this.canvas.height), this.#B = t.createBuffer(), t.bindBuffer(t.ARRAY_BUFFER, this.#B), t.bufferData(t.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), t.STATIC_DRAW), this.#F = t.createVertexArray(), t.bindVertexArray(this.#F), t.enableVertexAttribArray(0), t.vertexAttribPointer(0, 2, t.FLOAT, !1, 0, 0), t.bindVertexArray(null), this.#M = y(t, {}, it, S), this.#X = t.getUniformLocation(this.#M, "colorMap"), this.#H = t.getUniformLocation(this.#M, "outlineWidth"), this.#V = t.getUniformLocation(this.#M, "resolution");
+    this.#x = t.createTexture(), this.#L = t.createRenderbuffer(), this.#E = t.createFramebuffer(), this.#K(this.canvas.width, this.canvas.height), this.#B = t.createBuffer(), t.bindBuffer(t.ARRAY_BUFFER, this.#B), t.bufferData(t.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), t.STATIC_DRAW), this.#F = t.createVertexArray(), t.bindVertexArray(this.#F), t.enableVertexAttribArray(0), t.vertexAttribPointer(0, 2, t.FLOAT, !1, 0, 0), t.bindVertexArray(null), this.#M = y(t, {}, it, O), this.#X = t.getUniformLocation(this.#M, "colorMap"), this.#H = t.getUniformLocation(this.#M, "outlineWidth"), this.#V = t.getUniformLocation(this.#M, "resolution");
   }
   #K(t, n) {
     const e = this.glContext;
@@ -2715,20 +2721,20 @@ class Ht extends lt {
     const t = this.glContext;
     t.bindFramebuffer(t.FRAMEBUFFER, this.#E), t.clearColor(0, 0, 0, 0), t.clear(t.COLOR_BUFFER_BIT | t.DEPTH_BUFFER_BIT), (this.#n || this.#e) && (t.colorMask(!1, !1, !1, !1), this.#n ? this.#Y(
       this.#l,
-      this.#O,
+      this.#S,
       this.#p,
       this.#P,
       this.#A
     ) : (this.#G(
       this.#l,
-      this.#O,
+      this.#S,
       this.#p,
       this.#P
-    ), t.bindVertexArray(this.#a), t.drawElements(t.TRIANGLES, this.#T, t.UNSIGNED_INT, 0), t.bindVertexArray(null)), t.colorMask(!0, !0, !0, !0), t.clear(t.COLOR_BUFFER_BIT), t.depthFunc(t.EQUAL), t.depthMask(!1)), this.#n ? t.useProgram(this.#t) : this.#G(this.#t, this.#y, this.#m, this.#S), this.uploadMetricPalette(this.#D), t.activeTexture(t.TEXTURE0), t.bindTexture(t.TEXTURE_2D, this.paletteTexture), t.uniform1i(this.#h, 0), t.activeTexture(t.TEXTURE1), t.bindTexture(t.TEXTURE_2D, this.metricTexture), t.uniform1i(this.#I, 1), this.#n ? this.#Y(
+    ), t.bindVertexArray(this.#a), t.drawElements(t.TRIANGLES, this.#T, t.UNSIGNED_INT, 0), t.bindVertexArray(null)), t.colorMask(!0, !0, !0, !0), t.clear(t.COLOR_BUFFER_BIT), t.depthFunc(t.EQUAL), t.depthMask(!1)), this.#n ? t.useProgram(this.#t) : this.#G(this.#t, this.#y, this.#m, this.#O), this.uploadMetricPalette(this.#D), t.activeTexture(t.TEXTURE0), t.bindTexture(t.TEXTURE_2D, this.paletteTexture), t.uniform1i(this.#h, 0), t.activeTexture(t.TEXTURE1), t.bindTexture(t.TEXTURE_2D, this.metricTexture), t.uniform1i(this.#I, 1), this.#n ? this.#Y(
       this.#t,
       this.#y,
       this.#m,
-      this.#S,
+      this.#O,
       this.#w
     ) : (t.bindVertexArray(this.#a), t.drawElements(t.TRIANGLES, this.#T, t.UNSIGNED_INT, 0), t.bindVertexArray(null)), (this.#n || this.#e) && (t.depthMask(!0), t.depthFunc(t.LESS)), t.bindFramebuffer(t.FRAMEBUFFER, null), t.disable(t.DEPTH_TEST), t.useProgram(this.#M), t.activeTexture(t.TEXTURE0), t.bindTexture(t.TEXTURE_2D, this.#x), t.uniform1i(this.#X, 0), t.uniform1f(this.#H, this.#_ ? 0 : this.#v), t.uniform2f(this.#V, this.canvas.width, this.canvas.height), t.clearColor(0, 0, 0, 0), t.clear(t.COLOR_BUFFER_BIT), t.bindVertexArray(this.#F), t.drawArrays(t.TRIANGLE_STRIP, 0, 4), t.bindVertexArray(null), t.enable(t.DEPTH_TEST);
   }