phoria2 1.3.0 → 1.4.1

package/dist/picking.js

@@ -1,22 +1,37 @@
-import { D as e, Ft as t, Lt as n, O as r, S as i, k as a, w as o } from "./core.js";
+import { A as e, C as t, D as n, M as r, S as i, T as a, Vt as o, j as s, w as c, zt as l } from "./core.js";
 // src/webgl/picking.js
-var s = 33, c = 4, l = `precision highp float;
+var u = 33, d = 4, f = `precision highp float;
 precision highp int;
 flat in uint vPickElement;
 #ifdef SPRITES
 in vec2 vUv;
 #endif
-#ifdef CLIP
+#if defined(CLIP) || defined(HOOK_FRAGMENT)
 in vec3 vWorldPosition;
 #endif
+#ifdef HOOK_FRAGMENT
+in vec3 vNormal;
+in vec2 vUv;
+in vec3 vColor;
+#endif
+//@hook uniforms
 uniform uint uPickId;
 layout(location = 0) out uvec4 pickOut;
-${o}
-${i}
+${n}
+${a}
 void main() {
 #ifdef CLIP
 clipAway(vWorldPosition);
 #endif
+#ifdef HOOK_FRAGMENT
+{
+vec4 base = vec4(vColor, 1.0);
+vec3 emissive = vec3(0.0);
+vec3 normal = normalize(vNormal);
+//@hook fragment
+if (base.a <= 0.0) discard;
+}
+#endif
 #ifdef ROUND
 #ifdef SPRITES
 vec2 p = vUv * 2.0 - 1.0;
@@ -27,11 +42,11 @@ if (dot(p, p) > 1.0) discard;
 #endif
 pickOut = uvec4(uPickId, vPickElement, floatBitsToUint(gl_FragCoord.z), 1u);
 }
-`, u = {
-	mesh: [r, l],
-	points: [a, l],
-	lines: [e, l]
-}, d = class {
+`, p = {
+	mesh: [s, f],
+	points: [r, f],
+	lines: [e, f]
+}, m = class {
 	#e = null;
 	#t = /* @__PURE__ */ new Uint32Array(4356);
 	#n = /* @__PURE__ */ new Float32Array(16);
@@ -46,79 +61,79 @@ pickOut = uvec4(uPickId, vPickElement, floatBitsToUint(gl_FragCoord.z), 1u);
 		this.#e = null, this.#a = null, this.#o = !1;
 	}
 	pick(e, t, n, r, i, a) {
-		let o = this.gl, c = this.#s(e, t, n, r, i, a);
-		return c ? (o.readPixels(0, 0, s, s, o.RGBA_INTEGER, o.UNSIGNED_INT, this.#t), o.bindFramebuffer(o.FRAMEBUFFER, null), this.#c(c)) : null;
+		let o = this.gl, s = this.#s(e, t, n, r, i, a);
+		return s ? (o.readPixels(0, 0, u, u, o.RGBA_INTEGER, o.UNSIGNED_INT, this.#t), o.bindFramebuffer(o.FRAMEBUFFER, null), this.#c(s)) : null;
 	}
 	pickAsync(e, t, n, r, i, a) {
 		if (this.#o) return null;
-		let o = this.gl, c = this.#s(e, t, n, r, i, a);
-		if (!c) return Promise.resolve(null);
-		let l = this.#l();
-		o.bindBuffer(o.PIXEL_PACK_BUFFER, l), o.readPixels(0, 0, s, s, o.RGBA_INTEGER, o.UNSIGNED_INT, 0), o.bindBuffer(o.PIXEL_PACK_BUFFER, null), o.bindFramebuffer(o.FRAMEBUFFER, null);
-		let u = o.fenceSync(o.SYNC_GPU_COMMANDS_COMPLETE, 0);
+		let o = this.gl, s = this.#s(e, t, n, r, i, a);
+		if (!s) return Promise.resolve(null);
+		let c = this.#l();
+		o.bindBuffer(o.PIXEL_PACK_BUFFER, c), o.readPixels(0, 0, u, u, o.RGBA_INTEGER, o.UNSIGNED_INT, 0), o.bindBuffer(o.PIXEL_PACK_BUFFER, null), o.bindFramebuffer(o.FRAMEBUFFER, null);
+		let l = o.fenceSync(o.SYNC_GPU_COMMANDS_COMPLETE, 0);
 		return o.flush(), this.#o = !0, new Promise((e) => {
 			let t = () => {
-				o.isContextLost() ? (this.#o = !1, e(null)) : o.clientWaitSync(u, 0, 0) === o.TIMEOUT_EXPIRED ? setTimeout(t, 1) : (o.deleteSync(u), o.bindBuffer(o.PIXEL_PACK_BUFFER, l), o.getBufferSubData(o.PIXEL_PACK_BUFFER, 0, this.#t), o.bindBuffer(o.PIXEL_PACK_BUFFER, null), this.#o = !1, e(this.#c(c)));
+				o.isContextLost() ? (this.#o = !1, e(null)) : o.clientWaitSync(l, 0, 0) === o.TIMEOUT_EXPIRED ? setTimeout(t, 1) : (o.deleteSync(l), o.bindBuffer(o.PIXEL_PACK_BUFFER, c), o.getBufferSubData(o.PIXEL_PACK_BUFFER, 0, this.#t), o.bindBuffer(o.PIXEL_PACK_BUFFER, null), this.#o = !1, e(this.#c(s)));
 			};
 			setTimeout(t, 0);
 		});
 	}
-	#s(e, t, r, i, a, o) {
-		let c = this.gl, l = f(e);
-		if (!l.length) return null;
-		let u = this.#d();
-		c.bindFramebuffer(c.FRAMEBUFFER, u.framebuffer), c.viewport(0, 0, s, s), c.disable(c.BLEND), c.disable(c.SCISSOR_TEST), c.enable(c.DEPTH_TEST), c.depthFunc(c.LEQUAL), c.depthMask(!0), c.clearBufferuiv(c.COLOR, 0, [
+	#s(e, t, n, r, i, a) {
+		let s = this.gl, c = h(e);
+		if (!c.length) return null;
+		let l = this.#d();
+		s.bindFramebuffer(s.FRAMEBUFFER, l.framebuffer), s.viewport(0, 0, u, u), s.disable(s.BLEND), s.disable(s.SCISSOR_TEST), s.enable(s.DEPTH_TEST), s.depthFunc(s.LEQUAL), s.depthMask(!0), s.clearBufferuiv(s.COLOR, 0, [
 			0,
 			0,
 			0,
 			0
-		]), c.clearBufferfv(c.DEPTH, 0, [1]);
-		let d = s, p = t / i * 2 - 1, m = 1 - r / a * 2, h = new Float32Array([
-			i / d,
+		]), s.clearBufferfv(s.DEPTH, 0, [1]);
+		let d = u, f = t / r * 2 - 1, p = 1 - n / i * 2, m = new Float32Array([
+			r / d,
 			0,
 			0,
 			0,
 			0,
-			a / d,
+			i / d,
 			0,
 			0,
 			0,
 			0,
 			1,
 			0,
+			-f * r / d,
 			-p * i / d,
-			-m * a / d,
 			0,
 			1
 		]);
-		return n(this.#n, h, e.camera.projection), n(this.#r, this.#n, e.camera.view), l.forEach((t, n) => this.#u(t, n + 1, e, a, o)), c.bindVertexArray(null), {
-			items: l,
-			cx: p,
-			cy: m,
-			width: i,
-			height: a
+		return o(this.#n, m, e.camera.projection), o(this.#r, this.#n, e.camera.view), c.forEach((t, n) => this.#u(t, n + 1, e, i, a)), s.bindVertexArray(null), {
+			items: c,
+			cx: f,
+			cy: p,
+			width: r,
+			height: i
 		};
 	}
 	#c({ items: e, cx: t, cy: n, width: r, height: i }) {
-		let a = this.#t, o = (e, t) => (t * s + e) * 4, l = a[o(16, 16)] ? o(16, 16) : -1, u = 0, d = 0;
-		if (l < 0) {
+		let a = this.#t, o = (e, t) => (t * u + e) * 4, s = a[o(16, 16)] ? o(16, 16) : -1, c = 0, l = 0;
+		if (s < 0) {
 			let t = Infinity;
-			for (let n = -4; n <= c; n++) for (let r = -4; r <= c; r++) {
+			for (let n = -4; n <= d; n++) for (let r = -4; r <= d; r++) {
 				let i = r * r + n * n;
 				if (i > 16 || i >= t) continue;
-				let s = o(16 + r, 16 + n), c = a[s];
-				c && e[c - 1].node.drawMode !== "triangles" && (l = s, t = i, u = r, d = n);
+				let u = o(16 + r, 16 + n), d = a[u];
+				d && e[d - 1].node.drawMode !== "triangles" && (s = u, t = i, c = r, l = n);
 			}
 		}
-		if (l < 0) return null;
-		let f = new Float32Array(new Uint32Array([a[l + 2]]).buffer)[0], p = [
-			t + u * 2 / r,
-			n + d * 2 / i,
+		if (s < 0) return null;
+		let f = new Float32Array(new Uint32Array([a[s + 2]]).buffer)[0], p = [
+			t + c * 2 / r,
+			n + l * 2 / i,
 			f * 2 - 1
 		];
 		return {
-			item: e[a[l] - 1],
-			element: a[l + 1],
+			item: e[a[s] - 1],
+			element: a[s + 1],
 			ndc: p
 		};
 	}
@@ -127,35 +142,39 @@ pickOut = uvec4(uPickId, vPickElement, floatBitsToUint(gl_FragCoord.z), 1u);
 		let e = this.gl;
 		return this.#a = e.createBuffer(), e.bindBuffer(e.PIXEL_PACK_BUFFER, this.#a), e.bufferData(e.PIXEL_PACK_BUFFER, this.#t.byteLength, e.STREAM_READ), e.bindBuffer(e.PIXEL_PACK_BUFFER, null), this.#a;
 	}
-	#u(e, n, r, i, a) {
-		let o = this.gl, { node: c, geometry: l, material: d, worldMatrix: f, instances: p } = e, m = c.drawMode, h = m === "points" ? "points" : m === "lines" ? "lines" : "mesh", g = ["PICK"];
-		p && g.push("INSTANCED");
-		let _ = h === "points" && c.drawsSprites;
-		h === "points" && (d.sizeAttenuation && g.push("SIZE_ATTENUATION"), d.map || g.push("ROUND"), _ && g.push("SPRITES")), h === "mesh" && e.clip && g.push("CLIP");
-		let v = this.programs.ready(`pick-${h}`, g, u[h]);
-		if (o.useProgram(v.program), v.set("uView", r.camera.view), v.set("uProjection", this.#n), v.set("uViewProjection", this.#r), v.set("uModel", f), v.set("uPickId", n), v.set("uHighlightIndex", -2), e.clip && v.set("uClipPlane", e.clip.plane), h === "lines") {
-			o.disable(o.CULL_FACE), v.set("uResolution", [s, s]), v.set("uWidth", d.width * a), v.set("uNear", r.camera.near);
-			let e = c.arrowBits ?? 0;
-			v.set("uArrows", e), v.set("uArrowSize", c.arrowPixels?.(d.width) * a || 0);
-			let t = this.resources.lines(l);
-			o.bindVertexArray(t.vao), o.drawArraysInstanced(o.TRIANGLES, 0, e ? 12 : 6, Math.min(t.count, Math.floor(l.drawnCount / 2)));
-		} else if (h === "points") {
-			if (o.disable(o.CULL_FACE), v.set("uSize", d.sizeAttenuation ? d.size : d.size * a), v.set("uScale", r.camera.projection[5] * i / 2), _) {
-				v.set("uResolution", [s, s]);
-				let e = this.resources.sprites(l);
-				o.bindVertexArray(e.vao), o.drawArraysInstanced(o.TRIANGLE_STRIP, 0, 4, e.count);
-				return;
-			}
-			let e = this.resources.mesh(l, null, !1);
-			o.bindVertexArray(e.vao), o.drawArrays(o.POINTS, 0, l.drawnVertices);
-		} else v.set("uNormalMatrix", this.#i), d.depthTest ? o.enable(o.DEPTH_TEST) : o.disable(o.DEPTH_TEST), d.doubleSided || e.clip?.cap ? o.disable(o.CULL_FACE) : (o.enable(o.CULL_FACE), o.cullFace(o.BACK), o.frontFace(t(f) < 0 ? o.CW : o.CCW)), this.resources.drawTriangles(l, p);
+	#u(e, n, r, a, o) {
+		let s = this.gl, { node: d, geometry: f, material: m, worldMatrix: h, instances: g } = e, _ = d.drawMode, v = _ === "points" ? "points" : _ === "lines" ? "lines" : "mesh", y = ["PICK"];
+		g && y.push("INSTANCED");
+		let b = v === "points" && d.drawsSprites;
+		v === "points" && (m.sizeAttenuation && y.push("SIZE_ATTENUATION"), m.map || y.push("ROUND"), b && y.push("SPRITES")), v === "mesh" && e.clip && y.push("CLIP");
+		let x = i(m);
+		x && y.push(...t(x, v === "mesh"));
+		let S = this.programs.ready(`pick-${v}`, y, p[v], x?.source);
+		if (!S.failed) {
+			if (s.useProgram(S.program), S.set("uView", r.camera.view), S.set("uProjection", this.#n), S.set("uViewProjection", this.#r), S.set("uModel", h), S.set("uPickId", n), S.set("uHighlightIndex", -2), e.clip && S.set("uClipPlane", e.clip.plane), x && c(S, m, r.time ?? 0, r.camera.position, (e) => this.resources.texture(e)), v === "lines") {
+				s.disable(s.CULL_FACE), S.set("uResolution", [u, u]), S.set("uWidth", m.width * o), S.set("uNear", r.camera.near);
+				let e = d.arrowBits ?? 0;
+				S.set("uArrows", e), S.set("uArrowSize", d.arrowPixels?.(m.width) * o || 0);
+				let t = this.resources.lines(f);
+				s.bindVertexArray(t.vao), s.drawArraysInstanced(s.TRIANGLES, 0, e ? 12 : 6, Math.min(t.count, Math.floor(f.drawnCount / 2)));
+			} else if (v === "points") {
+				if (s.disable(s.CULL_FACE), S.set("uSize", m.sizeAttenuation ? m.size : m.size * o), S.set("uScale", r.camera.projection[5] * a / 2), b) {
+					S.set("uResolution", [u, u]);
+					let e = this.resources.sprites(f);
+					s.bindVertexArray(e.vao), s.drawArraysInstanced(s.TRIANGLE_STRIP, 0, 4, e.count);
+					return;
+				}
+				let e = this.resources.mesh(f, null, !1);
+				s.bindVertexArray(e.vao), s.drawArrays(s.POINTS, 0, f.drawnVertices);
+			} else S.set("uNormalMatrix", this.#i), m.depthTest ? s.enable(s.DEPTH_TEST) : s.disable(s.DEPTH_TEST), m.doubleSided || e.clip?.cap ? s.disable(s.CULL_FACE) : (s.enable(s.CULL_FACE), s.cullFace(s.BACK), s.frontFace(l(h) < 0 ? s.CW : s.CCW)), this.resources.drawTriangles(f, g);
+		}
 	}
 	#d() {
 		if (this.#e) return this.#e;
 		let e = this.gl, t = e.createTexture();
-		e.activeTexture(e.TEXTURE15), e.bindTexture(e.TEXTURE_2D, t), e.texStorage2D(e.TEXTURE_2D, 1, e.RGBA32UI, s, s);
+		e.activeTexture(e.TEXTURE15), e.bindTexture(e.TEXTURE_2D, t), e.texStorage2D(e.TEXTURE_2D, 1, e.RGBA32UI, u, u);
 		let n = e.createRenderbuffer();
-		e.bindRenderbuffer(e.RENDERBUFFER, n), e.renderbufferStorage(e.RENDERBUFFER, e.DEPTH_COMPONENT24, s, s);
+		e.bindRenderbuffer(e.RENDERBUFFER, n), e.renderbufferStorage(e.RENDERBUFFER, e.DEPTH_COMPONENT24, u, u);
 		let r = e.createFramebuffer();
 		return e.bindFramebuffer(e.FRAMEBUFFER, r), e.framebufferTexture2D(e.FRAMEBUFFER, e.COLOR_ATTACHMENT0, e.TEXTURE_2D, t, 0), e.framebufferRenderbuffer(e.FRAMEBUFFER, e.DEPTH_ATTACHMENT, e.RENDERBUFFER, n), e.bindFramebuffer(e.FRAMEBUFFER, null), this.#e = {
 			framebuffer: r,
@@ -164,7 +183,7 @@ pickOut = uvec4(uPickId, vPickElement, floatBitsToUint(gl_FragCoord.z), 1u);
 		}, this.#e;
 	}
 };
-function f(e) {
+function h(e) {
 	let t = /* @__PURE__ */ new Map(), n = (e) => {
 		if (!e) return !0;
 		let r = t.get(e);
@@ -172,6 +191,6 @@ function f(e) {
 	}, r = [...e.opaque, ...e.transparent].filter((e) => n(e.node));
 	return [...r.filter((e) => e.material.depthTest), ...r.filter((e) => !e.material.depthTest)];
 }
-export { d as Picker };
+export { m as Picker };
 
 //# sourceMappingURL=picking.js.map

package/dist/picking.js.map

@@ -1 +1 @@
-{"version":3,"file":"picking.js","names":["mat4.determinant","LINES_VERTEX","determinant","multiply","MESH_VERTEX","CLIP","POINTS_VERTEX","COMMON","REGION","TOLERANCE","PICK_FRAGMENT","SOURCES","Picker","gl","programs","resources","#target","#pack","#waiting","region","#drawRegion","frame","x","y","width","height","pixelRatio","#pixels","#decode","buffer","#readBuffer","fence","poll","resolve","items","pickable","target","#ensureTarget","s","cx","cy","zoom","#projection","#viewProjection","#draw","item","i","p","at","py","px","best","bestX","bestY","bestD","dy","dx","d","o","id","depth","ndc","mode","node","kind","defines","instances","sprites","material","program","worldMatrix","arrows","buffers","geometry","#normal","color","framebuffer","seen","ok","n","v"],"sources":[],"mappings":""}
+{"version":3,"file":"picking.js","names":["mat4.determinant","LINES_VERTEX","passDefines","COMMON","POINTS_VERTEX","hookFor","CLIP","multiply","MESH_VERTEX","setHookUniforms","determinant","REGION","TOLERANCE","PICK_FRAGMENT","SOURCES","Picker","gl","programs","resources","#target","#pack","#waiting","region","#drawRegion","frame","x","y","width","height","pixelRatio","#pixels","#decode","buffer","#readBuffer","fence","poll","resolve","items","pickable","target","#ensureTarget","s","cx","cy","zoom","#projection","#viewProjection","#draw","item","i","p","at","py","px","best","bestX","bestY","bestD","dy","dx","d","o","id","depth","ndc","mode","node","kind","defines","instances","sprites","material","hook","program","worldMatrix","t","arrows","buffers","geometry","#normal","color","framebuffer","seen","ok","n","v"],"sources":[],"mappings":""}

package/dist/snapshot.js

@@ -1,4 +1,4 @@
-import { Tt as e } from "./core.js";
+import { kt as e } from "./core.js";
 // src/snapshot.js
 function t(t, n, { type: a = "image/png", quality: o, labels: s = !0 } = {}, c = []) {
 	let l = t;

package/dist/tooltip.js

@@ -1,4 +1,4 @@
-import { jt as e, kt as t } from "./core.js";
+import { Ft as e, Nt as t } from "./core.js";
 // src/tooltip.js
 var n = "\n:where(.phoria-tooltip) { position: fixed; left: 0; top: 0; z-index: 1000; pointer-events: none; max-width: 320px;\n  padding: 6px 10px; border-radius: 6px; background: rgba(20, 20, 24, 0.92); color: #fff;\n  font: 12px/1.45 system-ui, sans-serif; box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3); white-space: pre-line; }\n:where(.phoria-tooltip-title) { font-weight: 600; }\n:where(.phoria-tooltip-rows) { display: grid; grid-template-columns: auto auto; column-gap: 12px; }\n:where(.phoria-tooltip-rows > :nth-child(odd)) { opacity: 0.7; }\n:where(.phoria-tooltip-rows > :nth-child(even)) { text-align: right; font-variant-numeric: tabular-nums; }\n", r = 14, i = class {
 	el;

package/dist/types/View.d.ts

@@ -17,6 +17,7 @@ import type { CameraOptions } from './scene/cameras.js';
 import type { ColorInput, Vec3Input } from './types.js';
 import type { Node } from './scene/Node.js';
 import type { KeyboardOptions } from './keyboard.js';
+import type { DebugOptions } from './debug.js';
 export type RenderMode = 'auto' | 'always' | 'manual';
 export type ViewOptions = {
     /**
@@ -125,6 +126,11 @@ export type ViewOptions = {
      * on and no description, one is made from the scene (charts describe themselves)
      */
     description?: string | null;
+    /**
+     * pictures for checking a scene: lights, shadow cameras, bounds,
+     * normals, axes, the orbit target and a stats readout. true shows all but normals. Default false
+     */
+    debug?: boolean | DebugOptions;
 };
 export type ViewEvent = 'click' | 'hover';
 export type ViewHandler = (hit: Hit | null, event: PointerEvent | MouseEvent | null) => void;
@@ -195,6 +201,16 @@ export declare class View {
     get reducedMotion(): boolean;
     /** @param {'auto' | boolean} v */
     set reducedMotion(v: 'auto' | boolean);
+    /**
+     * Debug drawing, or false: what it shows, as DebugOptions. Assign true for everything but normals,
+     * options for some, or false. Its code loads the first time it's turned on.
+     *
+     *     view.debug = { lights: true, shadows: true, bounds: 'hovered', stats: 'bottom-right' }
+     * @returns {boolean | DebugOptions} the options in force, every one given, or false
+     */
+    get debug(): boolean | DebugOptions;
+    /** @param {boolean | DebugOptions} v */
+    set debug(v: boolean | DebugOptions);
     /**
      * What the view shows, for screen readers - the canvas's label - or null. With keyboard on and no
      * description, one is made from the scene.

package/dist/types/debug.d.ts

@@ -0,0 +1,74 @@
+import { Box3 } from './value/Box3.js';
+import type { FrameDescription } from './frame.js';
+import type { Hit } from './Raycaster.js';
+import type { Camera } from './scene/cameras.js';
+export type DebugOptions = {
+    /**
+     * each light: an arrow for directional ones, a small sphere and its range
+     * for point lights, a cone for spot lights - in the light's colour
+     */
+    lights?: boolean;
+    /**
+     * the box or cone each shadow is drawn from - the usual reason a shadow
+     * is cut off or soft
+     */
+    shadows?: boolean;
+    /**
+     * world bounding boxes - what culling and view.frame() see
+     */
+    bounds?: boolean | 'hovered';
+    /**
+     * short lines along vertex normals (meshes up to 5,000
+     * vertices each when all are shown)
+     */
+    normals?: boolean | 'hovered';
+    /**
+     * x, y and z at the origin, red, green and blue
+     */
+    axes?: boolean;
+    /**
+     * the point the camera orbits round
+     */
+    camera?: boolean;
+    /**
+     * a readout of
+     * frame time, draw calls, triangles, programs, textures and geometries, in a corner of the canvas
+     */
+    stats?: boolean | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+};
+export declare class DebugDraw {
+    #private;
+    overlay: HTMLElement;
+    /** @param {HTMLElement | null} overlay where the stats readout goes - the layer over the canvas */
+    constructor(overlay: HTMLElement | null);
+    /**
+     * Add the helpers to a frame about to be drawn, after everything in it. Returns how many items were
+     * added to each list, to take out again once it is drawn.
+     * @param {FrameDescription} frame @param {DebugOptions} o
+     * @param {{ camera: Camera, hovered: Hit | null, bounds: Box3 }} at
+     * @returns {{ opaque: number, transparent: number }}
+     */
+    add(frame: FrameDescription, o: DebugOptions, at: {
+        camera: Camera;
+        hovered: Hit | null;
+        bounds: Box3;
+    }): {
+        opaque: number;
+        transparent: number;
+    };
+    /**
+     * The corner readout, refreshed a few times a second.
+     * @param {DebugOptions['stats']} where
+     * @param {{ drawCalls: number, triangles: number, programs: number, textures: number, geometries: number, compiling: number }} info
+     * @param {number} frameMs time between drawn frames @param {number} cpuMs time the last frame took to draw
+     */
+    stats(where: DebugOptions['stats'], info: {
+        drawCalls: number;
+        triangles: number;
+        programs: number;
+        textures: number;
+        geometries: number;
+        compiling: number;
+    }, frameMs: number, cpuMs: number): void;
+    dispose(): void;
+}

package/dist/types/explain.d.ts

@@ -44,6 +44,10 @@ export type ExplainInfo = {
      * lines from nodes that describe themselves, such as charts
      */
     notes?: string[];
+    /**
+     * what debug drawing shows, when it is on
+     */
+    debug?: Record<string, unknown> | null;
 };
 /** @param {ExplainInfo} info @returns {string} */
 export declare function explain(info: ExplainInfo): string;

package/dist/types/frame.d.ts

@@ -272,6 +272,10 @@ export type FrameDescription = {
         drawn: number;
         culled: number;
     };
+    /**
+     * the View's clock in seconds, for shader hooks that read uTime
+     */
+    time?: number;
     /**
      * set by the View for hover highlighting
      */
@@ -414,6 +418,7 @@ export type FrameDescription = {
  * @property {PointShadowFrame | null} pointShadow a point light's shadow, all round it
  * @property {FrameCap[]} caps section planes' caps to fill, after the opaque pass
  * @property {{ drawn: number, culled: number }} stats
+ * @property {number} [time] the View's clock in seconds, for shader hooks that read uTime
  * @property {FrameHighlight | null} highlight set by the View for hover highlighting
  * @property {any[]} overlays HTML elements carried by the nodes drawn (node.overlay)
  * @property {boolean} interactive some node has a tooltip, highlight or pointer handler

package/dist/types/material/Material.d.ts

@@ -3,6 +3,39 @@ import { Texture } from './Texture.js';
 import type { ColorInput } from '../types.js';
 import type { TextureOptions } from './Texture.js';
 export type MapInput = Texture | TextureOptions | string;
+export type ShaderUniform = number | number[] | ColorInput | Texture;
+export type ShaderHooks = {
+    /**
+     * runs on each vertex before it is placed: change `local` (vec3, the
+     * geometry's own space) - and for meshes `n`, its normal; reads `uv` (meshes), `index` (the
+     * instance, point or segment), `size` (points: change it too) and `along` (lines: 0 at a
+     * segment's start, 1 at its end)
+     */
+    vertex?: string;
+    /**
+     * runs on each pixel before lighting: change `base` (vec4: linear
+     * colour and alpha) and, on meshes, `emissive` and `normal` (the shading normal, world space - bend it for
+     * relief lit per pixel); `discard` cuts the pixel away - shadows and
+     * picking too. Reads `vUv`, `vWorldPosition`, `vNormal` (meshes), `pointUv` and `index`
+     * (points), `distance` along the line and `index` the segment (lines)
+     */
+    fragment?: string;
+    /**
+     * runs after lighting: change `color` (vec3, linear) and `base.a` - glows,
+     * scanlines and fades the light doesn't touch
+     */
+    lit?: string;
+    /**
+     * values the hooks read, by name; change them on
+     * `material.shader.uniforms` and the View redraws
+     */
+    uniforms?: Record<string, ShaderUniform>;
+    /**
+     * how far, in world units, the vertex hook can move a vertex: bounds are
+     * padded by it for culling, framing and shadows. Without it a vertex hook turns frustum culling off
+     */
+    bounds?: number;
+};
 export type MaterialOptions = {
     name?: string;
     /**
@@ -207,6 +240,11 @@ export type MaterialOptions = {
      * Points: sized in the world, so smaller with distance (default true)
      */
     sizeAttenuation?: boolean;
+    /**
+     * GLSL of your own, run at fixed points in the shader - waves,
+     * dissolves, glows (default none)
+     */
+    shader?: ShaderHooks | null;
     /**
      * Lines: width in pixels (default 1)
      */
@@ -252,6 +290,10 @@ export declare class Material {
         colour: string;
         emissiveColor: string;
         alpha: string;
+        onBeforeCompile: string;
+        vertexShader: string;
+        fragmentShader: string;
+        uniforms: string;
     };
     /** @type {string} */ name: string;
     /** @type {number} */ opacity: number;
@@ -292,6 +334,16 @@ export declare class Material {
     /** Lines: how far the dashes have moved along. @type {number} */ dashOffset: number;
     /** @param {MaterialOptions} [options] */
     constructor(options?: MaterialOptions);
+    /**
+     * GLSL hooks run inside the shader, or null. Change its uniforms in place
+     * (`material.shader.uniforms.uAmount = 2`); assign a new object to change the code.
+     * @returns {Required<Omit<ShaderHooks, 'bounds'>> & { bounds: number | null } | null}
+     */
+    get shader(): (Required<Omit<ShaderHooks, 'bounds'>> & {
+        bounds: number | null;
+    }) | null;
+    /** @param {ShaderHooks | null} v */
+    set shader(v: ShaderHooks | null);
     /** Base colour; assign any colour input. @returns {Color} */
     get color(): Color;
     /** @param {ColorInput} v */

package/dist/types/watch.d.ts

@@ -1,14 +1,21 @@
 import type { Scene } from './scene/Scene.js';
 import type { Camera } from './scene/cameras.js';
+/** Does a material's shader hook read the clock? @param {{ vertex: string, fragment: string, lit: string }} h */
+export declare const usesTime: (h: {
+    vertex: string;
+    fragment: string;
+    lit: string;
+}) => boolean;
 export declare class ChangeWatch {
     #private;
     /**
      * Has anything that affects the picture changed since the last call? The first call says yes.
      * @param {Scene} scene
      * @param {Camera} camera
+     * @param {number} [time] the View's clock, which shader hooks reading uTime follow
      * @returns {boolean}
      */
-    changed(scene: Scene, camera: Camera): boolean;
+    changed(scene: Scene, camera: Camera, time?: number): boolean;
     /** Forget the last signature, so the next check reports a change. */
     reset(): void;
 }

package/dist/types/webgl/hooks.d.ts

@@ -0,0 +1,48 @@
+import { Texture } from '../material/Texture.js';
+import type { Material } from '../material/Material.js';
+import type { HookSource } from './shaders.js';
+import type { Program } from './programs.js';
+export type Hook = {
+    /**
+     * its code and uniform types - one program per signature
+     */
+    signature: string;
+    /**
+     * HOOK_VERTEX, HOOK_FRAGMENT, HOOK_LIT for the parts it has, and its id
+     */
+    defines: string[];
+    /**
+     * what the shaders splice in
+     */
+    source: HookSource;
+    /**
+     * it has a vertex hook
+     */
+    moves: boolean;
+};
+/**
+ * The hooks a material draws with, or null: none, or ones that failed to compile.
+ * @param {Material} material
+ * @returns {Hook | null}
+ */
+export declare function hookFor(material: Material): Hook | null;
+/**
+ * Defines for a pass that isn't the colour pass: the vertex hook always - so a shadow, an outline or
+ * a pick is of the moved shape - and the fragment hook only where its discards should cut (meshes'
+ * shadows and picks); never the lit hook.
+ * @param {Hook} hook @param {boolean} cuts
+ */
+export declare function passDefines(hook: Hook, cuts: boolean): string[];
+/**
+ * Set the hook's uniforms: the clock, where the camera is, and the material's own values.
+ * @param {Program} program @param {Material} material @param {number} time
+ * @param {ArrayLike<number>} camera the camera's world position
+ * @param {(t: Texture) => WebGLTexture} texture
+ */
+export declare function setHookUniforms(program: Program, material: Material, time: number, camera: ArrayLike<number>, texture: (t: Texture) => WebGLTexture): void;
+/**
+ * A program built with a material's hooks failed: say why, once, in the hook's own terms, and draw
+ * the material without them from now on.
+ * @param {Material} material @param {Hook} hook @param {string} log the compiler's
+ */
+export declare function hookFailed(material: Material, hook: Hook, log: string): void;

package/dist/types/webgl/passes.d.ts

@@ -73,6 +73,10 @@ export declare class Passes {
     gl: WebGL2RenderingContext;
     programs: Programs;
     resources: Resources;
+    /** The View's clock, for shader hooks that read uTime - set by the renderer each frame. */
+    time: number;
+    /** The camera's world position, for shader hooks' fresnel and cameraPosition - set each frame too. @type {ArrayLike<number>} */
+    cameraPosition: ArrayLike<number>;
     /** Rendering to float textures, which environments need. */
     floatTargets: boolean;
     /** @param {WebGL2RenderingContext} gl @param {Programs} programs @param {Resources} resources */

package/dist/types/webgl/programs.d.ts

@@ -1,4 +1,4 @@
-import type { ShaderKind } from './shaders.js';
+import type { HookSource, ShaderKind } from './shaders.js';
 export type Program = {
     program: WebGLProgram;
     key: string;
@@ -14,12 +14,18 @@ export type Program = {
      * compiled, linked and its uniforms found
      */
     ready: boolean;
+    /**
+     * the compiler's log, for a program with a material's shader hooks that
+     * failed - those are reported and drawn without, rather than thrown
+     */
+    failed?: string;
 };
 export type Building = Program & {
     shaders: [WebGLShader, WebGLShader];
     sources: [string, string];
+    hooked: boolean;
 };
-/** @import { ShaderKind } from './shaders.js' */
+/** @import { HookSource, ShaderKind } from './shaders.js' */
 /**
  * @typedef {object} Program
  * @property {WebGLProgram} program
@@ -27,9 +33,11 @@ export type Building = Program & {
  * @property {(name: string, value: any) => void} set set a uniform by name (ignored if the shader doesn't use it)
  * @property {number} frame the frame its per-frame uniforms were last set for
  * @property {boolean} ready compiled, linked and its uniforms found
+ * @property {string} [failed] the compiler's log, for a program with a material's shader hooks that
+ *   failed - those are reported and drawn without, rather than thrown
  */
 /**
- * @typedef {Program & { shaders: [WebGLShader, WebGLShader], sources: [string, string] }} Building
+ * @typedef {Program & { shaders: [WebGLShader, WebGLShader], sources: [string, string], hooked: boolean }} Building
  */
 export declare class Programs {
     #private;
@@ -45,16 +53,18 @@ export declare class Programs {
      * @param {ShaderKind | string} kind a drawable kind, or a pass's name when it brings its sources
      * @param {string[]} defines
      * @param {[string, string]} [sources] a pass's vertex and fragment shaders
+     * @param {HookSource | null} [hooks] a material's shader hooks, spliced in (its id is in the defines)
      * @returns {Program}
      */
-    get(kind: ShaderKind | string, defines: string[], sources?: [string, string]): Program;
+    get(kind: ShaderKind | string, defines: string[], sources?: [string, string], hooks?: HookSource | null): Program;
     /**
      * A program, waiting for it to finish compiling if it hasn't - for passes and picking, which
      * need their programs now.
      * @param {ShaderKind | string} kind @param {string[]} defines @param {[string, string]} [sources]
+     * @param {HookSource | null} [hooks]
      * @returns {Program}
      */
-    ready(kind: ShaderKind | string, defines: string[], sources?: [string, string]): Program;
+    ready(kind: ShaderKind | string, defines: string[], sources?: [string, string], hooks?: HookSource | null): Program;
     /**
      * Has it finished compiling? Asks without waiting, and finishes it (finding its uniforms) once
      * it has.