phoria2 1.3.0 → 1.4.1

package/src/webgl/WebGLRenderer.js

@@ -3,6 +3,7 @@ import * as mat4 from '../math/mat4.js'
 import { Geometry } from '../geometry/Geometry.js'
 import { Material } from '../material/Material.js'
 import { CLIP_ONLY_FRAGMENT, MESH_VERTEX } from './shaders.js'
+import { hookFailed, hookFor, setHookUniforms } from './hooks.js'
 import { collect } from '../frame.js'
 import { checkNumber, checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '../validate.js'
 import { GLContext } from './context.js'
@@ -223,6 +224,11 @@ export class WebGLRenderer {
     const env = frame.environment
     const bg = frame.background
     const passes = gpu.loadPasses(!!frame.shadow || frame.spotShadows.length > 0 || !!frame.pointShadow || frame.outlines.length > 0 || (typeof env === 'object' && !!env.image) || (!!bg && !('getHex' in bg) && !!bg.image))
+    // shader hooks that read the clock read it in the shadow maps and outlines too
+    if (passes) {
+      passes.time = frame.time ?? 0
+      passes.cameraPosition = frame.camera.position
+    }
     this.#environment = passes && typeof env === 'object' ? passes.environment(env) : null
     if (passes && typeof env === 'object' && env.image && !this.#environment) {
       warnOnce(env, env.isHDR ? "this device can't render to float textures, which HDR environments need - lighting without it"
@@ -419,15 +425,25 @@ export class WebGLRenderer {
       else if (material.blending === 'multiply') defines.push('FOG_MULTIPLY')
     }
     if (clip) defines.push('CLIP')
+    // a material's own GLSL, spliced into this program
+    const hook = hookFor(material)
+    if (hook) defines.push(...hook.defines)
     const programs = this.#gpu.programs
-    const program = programs.get(kind, defines)
+    const program = programs.get(kind, defines, undefined, hook?.source)
     if (!programs.isReady(program)) {
       if (!this.#wait) {
         // still compiling: drawn once it's done, rather than holding up everything else
         this.info.compiling++
         return
       }
-      programs.ready(kind, defines)
+      programs.ready(kind, defines, undefined, hook?.source)
+    }
+    if (program.failed) {
+      // reported once; drawn without the hooks from the next frame
+      hookFailed(material, /** @type {import('./hooks.js').Hook} */ (hook), program.failed)
+      // counted as still compiling, so the View draws again - with the material's plain program
+      this.info.compiling++
+      return
     }
     gl.useProgram(program.program)
 
@@ -472,6 +488,7 @@ export class WebGLRenderer {
     }
     program.set('uColor', material.color)
     program.set('uOpacity', material.opacity)
+    if (hook) setHookUniforms(program, material, frame.time ?? 0, frame.camera.position, (t) => this.#gpu.resources.texture(t))
     if (fog) {
       program.set('uFogColor', fog.color)
       program.set('uFogRange', [fog.near, fog.far])

package/src/webgl/hooks.js

@@ -0,0 +1,121 @@
+// Shader hooks for the renderer: a material's GLSL turned into what the shaders splice in - uniform
+// declarations and the code - and the defines that switch it on, one program per distinct hook. A
+// hook that fails to compile is reported once, in terms of its own lines, and the material is drawn
+// without it from then on, rather than stopping the frame.
+import { Texture } from '../material/Texture.js'
+import { warnOnce } from '../validate.js'
+import { CLIP_ONLY_FRAGMENT, HOOK_HELPERS, HOOK_SOURCE_NUMBERS, LINES_VERTEX, MESH_VERTEX, POINTS_VERTEX, shaderSource } from './shaders.js'
+
+/** @import { Material, ShaderUniform } from '../material/Material.js' */
+/** @import { HookSource } from './shaders.js' */
+/** @import { Program } from './programs.js' */
+
+/**
+ * A material's hooks, ready to compile.
+ * @typedef {object} Hook
+ * @property {string} signature its code and uniform types - one program per signature
+ * @property {string[]} defines HOOK_VERTEX, HOOK_FRAGMENT, HOOK_LIT for the parts it has, and its id
+ * @property {HookSource} source what the shaders splice in
+ * @property {boolean} moves it has a vertex hook
+ */
+
+/** @type {Map<string, Hook>} */
+const hooks = new Map()
+/** Signatures that failed to compile: those materials draw without their hooks. @type {Set<string>} */
+const failed = new Set()
+/** @type {WeakMap<object, { types: string, hook: Hook | null }>} */
+const recent = new WeakMap()
+
+/** The GLSL type of a uniform's value. @param {ShaderUniform} v */
+function glslType(v) {
+  if (typeof v === 'number') return 'float'
+  if (v instanceof Texture) return 'sampler2D'
+  return `vec${/** @type {ArrayLike<number>} */ (v).length}`
+}
+
+// the uniforms phoria2's shaders declare, which a hook's own can't reuse
+let own = /** @type {Set<string> | null} */ (null)
+const ownUniforms = () => own ??= new Set([MESH_VERTEX, POINTS_VERTEX, LINES_VERTEX, CLIP_ONLY_FRAGMENT, ...['mesh', 'points', 'lines'].flatMap((k) => shaderSource(/** @type {any} */ (k), []))]
+  .flatMap((s) => [...s.matchAll(/uniform\s+\w+\s+(\w+)/g)].map((m) => m[1])))
+
+/**
+ * The hooks a material draws with, or null: none, or ones that failed to compile.
+ * @param {Material} material
+ * @returns {Hook | null}
+ */
+export function hookFor(material) {
+  const s = material.shader
+  if (!s) return null
+  const types = Object.entries(s.uniforms).map(([k, v]) => `${glslType(v)} ${k}`).join(';')
+  const last = recent.get(s)
+  if (last && last.types === types) return last.hook
+  const signature = JSON.stringify([s.vertex, s.fragment, s.lit, types])
+  let hook = failed.has(signature) ? null : hooks.get(signature) ?? null
+  if (!hook && !failed.has(signature)) {
+    const clash = Object.keys(s.uniforms).find((k) => ownUniforms().has(k))
+    if (clash) {
+      failed.add(signature)
+      warnOnce(material, `shader uniform '${clash}' is one of phoria2's own - give it another name; the material is drawn without its shader hooks`)
+    } else {
+      hook = {
+        signature,
+        defines: [...(s.vertex ? ['HOOK_VERTEX'] : []), ...(s.fragment ? ['HOOK_FRAGMENT'] : []), ...(s.lit ? ['HOOK_LIT'] : []), `HOOKS ${hooks.size + 1}`],
+        source: {
+          uniforms: ['uniform float uTime;', 'uniform vec3 cameraPosition;', ...types.split(';').filter(Boolean).map((t) => `uniform ${t};`)].join('\n'),
+          helpers: HOOK_HELPERS,
+          vertex: s.vertex, fragment: s.fragment, lit: s.lit,
+        },
+        moves: !!s.vertex,
+      }
+      hooks.set(signature, hook)
+    }
+  }
+  recent.set(s, { types, hook })
+  return hook
+}
+
+/**
+ * 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 function passDefines(hook, cuts) {
+  return hook.defines.filter((d) => d !== 'HOOK_LIT' && (cuts || d !== 'HOOK_FRAGMENT'))
+}
+
+/**
+ * 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 function setHookUniforms(program, material, time, camera, texture) {
+  program.set('uTime', time)
+  program.set('cameraPosition', camera)
+  const u = /** @type {NonNullable<Material['shader']>} */ (material.shader).uniforms
+  for (const name in u) {
+    const v = u[name]
+    program.set(name, v instanceof Texture ? texture(v) : v)
+  }
+}
+
+/**
+ * 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 function hookFailed(material, hook, log) {
+  failed.add(hook.signature)
+  recent.delete(/** @type {object} */ (material.shader))
+  const names = Object.fromEntries(Object.entries(HOOK_SOURCE_NUMBERS).map(([part, n]) => [n, part]))
+  const lines = log.split('\n').map((line) => /ERROR:\s*(\d+):(\d+):\s*(.*)/.exec(line)).filter((m) => !!m)
+  const own = lines.filter((m) => names[m[1]])
+  const where = own.length
+    ? own.map((m) => `shader.${names[m[1]]} line ${m[2]}: ${m[3]}`).join('; ')
+    : `in phoria2's shader around the hook: ${lines[0]?.[3] ?? log.trim().split('\n')[0]}`
+  const uniforms = Object.keys(/** @type {NonNullable<Material['shader']>} */ (material.shader).uniforms)
+  warnOnce(material, `a shader hook doesn't compile - ${where}. Hooks can use ${HOOK_NAMES}, uTime${uniforms.length ? `, ${uniforms.join(', ')}` : ''}, cameraPosition, and call hash, vnoise, snoise, snoised, vfbm, sfbm, sfbmd, voronoi, srgb, hsv2rgb, palette, fresnel, rotate2, rotate3, remap and saturate. The material is drawn without its hooks`)
+}
+
+const HOOK_NAMES = 'local, n, uv, index, size, along (vertex); base, emissive, normal, vUv, vWorldPosition, vNormal, vColor, pointUv, distance (fragment); color, base (lit)'

package/src/webgl/passes.js

@@ -5,6 +5,7 @@ import * as mat4 from '../math/mat4.js'
 import { irradianceSH } from '../irradiance.js'
 import { POINT_SHADOW_SIZE, SHADOW_MAP_SIZE, SPOT_ATLAS_SIZE } from '../shadow.js'
 import { CLIP, CLIP_ONLY_FRAGMENT, COMMON, EQUIRECT, FULLSCREEN_VERTEX, MESH_VERTEX, TONE_MAP } from './shaders.js'
+import { hookFor, passDefines, setHookUniforms } from './hooks.js'
 import { uvMatrix } from './resources.js'
 
 /** @import { Programs } from './programs.js' */
@@ -281,6 +282,10 @@ const ENV_LEVELS = 6
  */
 
 export class Passes {
+  /** The View's clock, for shader hooks that read uTime - set by the renderer each frame. */
+  time = 0
+  /** The camera's world position, for shader hooks' fresnel and cameraPosition - set each frame too. @type {ArrayLike<number>} */
+  cameraPosition = [0, 0, 0]
   /** @type {WeakMap<Texture, Environment>} */ #environments = new WeakMap()
   /** @type {{ texture: WebGLTexture, framebuffer: WebGLFramebuffer } | null} */ #shadow = null
   /** Spot lights' shadows, a tile each. @type {{ texture: WebGLTexture, framebuffer: WebGLFramebuffer } | null} */ #spotShadow = null
@@ -512,8 +517,13 @@ export class Passes {
       if (cutout) defines.push('ALPHA_TEST', ...(material.map ? ['MAP'] : []), ...(triplanar ? ['TRIPLANAR'] : []))
       // a map on the second UV set reads it here too
       if (cutout && material.map?.uvSet === 1 && item.geometry.uvs2) defines.push('UV2', 'uMapSet vUv2')
-      const program = this.programs.ready('depth', defines, DEPTH)
+      // shader hooks: the shadow of the moved shape, with a fragment hook's holes in it
+      const hook = hookFor(material)
+      if (hook) defines.push(...passDefines(hook, true))
+      const program = this.programs.ready('depth', defines, DEPTH, hook?.source)
+      if (program.failed) continue
       gl.useProgram(program.program)
+      if (hook) setHookUniforms(program, material, this.time, this.cameraPosition, (t) => this.resources.texture(t))
       program.set('uViewProjection', viewProjection)
       program.set('uModel', item.worldMatrix)
       if (item.clip) program.set('uClipPlane', item.clip.plane)
@@ -562,8 +572,13 @@ export class Passes {
       for (const item of outline.items) {
         const defines = item.instances ? ['INSTANCED'] : []
         if (item.clip) defines.push('CLIP')
-        const program = smooth ? this.programs.ready('outline-cover', defines, OUTLINE_COVER) : this.programs.ready('outline-mask', defines, OUTLINE_MASK)
+        // round the moved shape
+        const hook = hookFor(item.material)
+        if (hook) defines.push(...passDefines(hook, false))
+        const program = smooth ? this.programs.ready('outline-cover', defines, OUTLINE_COVER, hook?.source) : this.programs.ready('outline-mask', defines, OUTLINE_MASK, hook?.source)
+        if (program.failed) continue
         gl.useProgram(program.program)
+        if (hook) setHookUniforms(program, item.material, frame.time ?? 0, frame.camera.position, (t) => this.resources.texture(t))
         program.set('uViewProjection', frame.camera.viewProjection)
         program.set('uModel', item.worldMatrix)
         program.set('uMask', [outline.color[0], outline.color[1], outline.color[2], px / OUTLINE_MAX])

package/src/webgl/picking.js

@@ -3,6 +3,7 @@
 // instances there are, where testing rays against 100,000 instances on the CPU takes milliseconds.
 // Loaded the first time a View picks.
 import { CLIP, COMMON, LINES_VERTEX, MESH_VERTEX, POINTS_VERTEX } from './shaders.js'
+import { hookFor, passDefines, setHookUniforms } from './hooks.js'
 import * as mat4 from '../math/mat4.js'
 
 /** @import { Programs } from './programs.js' */
@@ -21,9 +22,16 @@ 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
+// a mesh's fragment hook: what it cuts away can't be picked
+in vec3 vNormal;
+in vec2 vUv;
+in vec3 vColor;
+#endif
+//@hook uniforms
 uniform uint uPickId;
 layout(location = 0) out uvec4 pickOut;
 ${COMMON}
@@ -32,6 +40,15 @@ 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;
@@ -233,7 +250,10 @@ export class Picker {
       if (sprites) defines.push('SPRITES')
     }
     if (kind === 'mesh' && item.clip) defines.push('CLIP')
-    const program = this.programs.ready(`pick-${kind}`, defines, SOURCES[kind])
+    const hook = hookFor(material)
+    if (hook) defines.push(...passDefines(hook, kind === 'mesh'))
+    const program = this.programs.ready(`pick-${kind}`, defines, SOURCES[kind], hook?.source)
+    if (program.failed) return
     gl.useProgram(program.program)
     program.set('uView', frame.camera.view)
     program.set('uProjection', this.#projection)
@@ -242,6 +262,7 @@ export class Picker {
     program.set('uPickId', id)
     program.set('uHighlightIndex', -2)
     if (item.clip) program.set('uClipPlane', item.clip.plane)
+    if (hook) setHookUniforms(program, material, frame.time ?? 0, frame.camera.position, (t) => this.resources.texture(t))
 
     if (kind === 'lines') {
       gl.disable(gl.CULL_FACE)

package/src/webgl/programs.js

@@ -4,7 +4,7 @@
 // draws again when they are done. Nothing waits on a status check until a program is used.
 import { shaderSource } from './shaders.js'
 
-/** @import { ShaderKind } from './shaders.js' */
+/** @import { HookSource, ShaderKind } from './shaders.js' */
 
 /**
  * @typedef {object} Program
@@ -13,10 +13,12 @@ import { shaderSource } from './shaders.js'
  * @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 class Programs {
@@ -49,13 +51,14 @@ export 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, defines, sources) {
+  get(kind, defines, sources, hooks = null) {
     const key = `${kind}|${defines.join(',')}`
     let p = this.#cache.get(key)
     if (!p) {
-      p = this.#start(key, shaderSource(sources ?? /** @type {ShaderKind} */ (kind), defines))
+      p = this.#start(key, shaderSource(sources ?? /** @type {ShaderKind} */ (kind), defines, hooks), !!hooks)
       this.#cache.set(key, p)
     }
     return p
@@ -65,10 +68,11 @@ export class Programs {
    * 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, defines, sources) {
-    const p = this.get(kind, defines, sources)
+  ready(kind, defines, sources, hooks = null) {
+    const p = this.get(kind, defines, sources, hooks)
     if (!p.ready) this.#finish(/** @type {Building} */ (p))
     return p
   }
@@ -115,9 +119,10 @@ export class Programs {
 
   /**
    * Start compiling and linking, without asking how it went - that would wait for it.
-   * @param {string} key @param {[string, string]} sources @returns {Program}
+   * @param {string} key @param {[string, string]} sources @param {boolean} [hooked] has a material's own code
+   * @returns {Program}
    */
-  #start(key, sources) {
+  #start(key, sources, hooked = false) {
     const gl = this.gl
     const shader = (type, source) => {
       const s = /** @type {WebGLShader} */ (gl.createShader(type))
@@ -132,7 +137,7 @@ export class Programs {
     gl.attachShader(program, fs)
     gl.linkProgram(program)
     /** @type {Building} */
-    const p = { program, key, frame: -1, ready: false, set() {}, shaders: [vs, fs], sources }
+    const p = { program, key, frame: -1, ready: false, set() {}, shaders: [vs, fs], sources, hooked }
     // without parallel compiling there is nothing to gain by waiting until it's used
     if (!this.#parallel) this.#finish(p)
     return p
@@ -143,6 +148,12 @@ export class Programs {
     const gl = this.gl
     const { program, key, shaders, sources } = p
     if (!gl.getProgramParameter(program, gl.LINK_STATUS) && !gl.isContextLost()) {
+      // a material's own code failing is its problem, not the frame's: kept to be reported
+      if (p.hooked) {
+        p.failed = shaders.map((s) => gl.getShaderParameter(s, gl.COMPILE_STATUS) ? '' : gl.getShaderInfoLog(s) ?? '').join('\n') || (gl.getProgramInfoLog(program) ?? 'failed to link')
+        p.ready = true
+        return
+      }
       // the shader that failed says why, with its source numbered to match the log
       shaders.forEach((s, i) => {
         if (gl.getShaderParameter(s, gl.COMPILE_STATUS)) return

package/src/webgl/resources.js

@@ -455,7 +455,7 @@ export class Resources {
       if (!d.isDrawable) return
       keys.add(d.geometry)
       if ('instanceMatrices' in d) keys.add(d)
-      for (const [, t] of d.material.textures) keys.add(t)
+      for (const [, t] of d.material.allTextures) keys.add(t)
     })
     for (const key of keys) {
       const users = this.#usedBy.get(key)