@solidrt/3d 0.0.48 → 0.0.50

package/src/material.ts

@@ -7,15 +7,15 @@
 //
 // Colors are straight [r, g, b, a?] 0..1 at the API and premultiplied here
 // once, at the boundary (the engine's pixel contract). An alpha below 1
-// does NOT blend yet: v1 pipelines draw opaque (blend "none"), so a
-// translucent color overwrites what is behind it. Transparency arrives
-// with the blend-factor vocabulary and back-to-front sorting (see
-// okf/research/scene-graph-3d.md, staging step 4).
+// blends only on a `transparent: true` material (Three's rule: the flag is
+// explicit, alpha alone still draws opaque). Transparent materials build
+// their pipeline with blend "alpha" and depthWrite off, and the scene draws
+// their meshes after the opaque ones, sorted back-to-front per mesh.
 //
-// Custom looks need no material system: the raw layer (compileShader /
-// createRenderPipeline in @solidrt/core/gpu) is first-class, and a scene
-// draws into an ordinary draw target - a custom-shaded mesh is a future
-// material class here, or the app's own addDraw beside the scene's.
+// Custom looks get the same split through shaderMaterialClass (one
+// program, instance() per parameterisation); shaderMaterial is a class with
+// a single instance. The raw layer (compileShader / createRenderPipeline in
+// @solidrt/core/gpu) stays first-class beneath both.
 
 import {
   compileShader,
@@ -55,6 +55,10 @@ export type Material = {
    * mesh whose geometry layout differs is rejected at add() - the strides
    * disagree, so a mismatch would render garbage, not just miss a channel. */
   layout?: VertexLayout
+  /** True when the pipeline blends over (blend "alpha", depthWrite off):
+   * the scene draws this material's meshes after every opaque one, sorted
+   * back-to-front by mesh origin, and re-sorts them when the camera moves. */
+  transparent?: boolean
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
@@ -96,23 +100,30 @@ const FRAGMENT_MAP_SRC = glsl`
 `
 
 let sharedVertex: ShaderStageId | undefined
-let pipelines: { color?: RenderPipelineId; map?: RenderPipelineId } = {}
+let pipelines: Partial<Record<UnlitClass, RenderPipelineId>> = {}
 
-function pipelineFor(kind: "color" | "map"): RenderPipelineId {
-  let existing = pipelines[kind]
+// One pipeline per unlit CLASS: fragment kind x transparency, since blend
+// state is pipeline state.
+type UnlitClass = "color" | "map" | "color-transparent" | "map-transparent"
+
+function pipelineFor(cls: UnlitClass): RenderPipelineId {
+  let existing = pipelines[cls]
   if (existing !== undefined) return existing
   if (sharedVertex === undefined) sharedVertex = compileShader("vertex", VERTEX_SRC, { header: true })
-  let fragment = compileShader("fragment", kind === "color" ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
+  let transparent = cls.endsWith("-transparent")
+  let fragment = compileShader("fragment", cls.startsWith("color") ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
     header: true,
   })
-  let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + kind })
+  let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + cls })
   let pipeline = createRenderPipeline(program, {
     attributes: VERTEX_LAYOUTS.standard,
     depth: true,
+    depthWrite: transparent ? false : undefined,
+    blend: transparent ? "alpha" : undefined,
     cull: "back",
-    label: "scene-unlit-" + kind,
+    label: "scene-unlit-" + cls,
   })
-  pipelines[kind] = pipeline
+  pipelines[cls] = pipeline
   return pipeline
 }
 
@@ -121,6 +132,9 @@ export type UnlitOptions = {
   color?: [number, number, number] | [number, number, number, number]
   /** A texture id to sample (tinted by `color` when both are given). */
   map?: TextureId
+  /** Blend over what is behind (color alpha and map alpha both count).
+   * Without it an alpha below 1 still draws opaque. See Material.transparent. */
+  transparent?: boolean
 }
 
 /**
@@ -132,10 +146,16 @@ export function unlit(opts: UnlitOptions = {}): Material {
   let color = opts.color ?? [1, 1, 1]
   let a = color.length === 4 ? color[3] : 1
   let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  let transparent = opts.transparent === true
   if (opts.map !== undefined) {
-    return { pipeline: () => pipelineFor("map"), params: { uColor }, textures: { uMap: opts.map } }
+    return {
+      pipeline: () => pipelineFor(transparent ? "map-transparent" : "map"),
+      params: { uColor },
+      textures: { uMap: opts.map },
+      transparent,
+    }
   }
-  return { pipeline: () => pipelineFor("color"), params: { uColor } }
+  return { pipeline: () => pipelineFor(transparent ? "color-transparent" : "color"), params: { uColor }, transparent }
 }
 
 // Mirrors the engine's own preamble rule: a source carrying its own
@@ -144,7 +164,46 @@ function needsHeader(source: string): boolean {
   return !source.trimStart().startsWith("#version")
 }
 
-export type ShaderMaterialOptions = {
+// The scene-background pass (scene.setBackground). The vertex stage is the
+// engine's own attributeless fullscreen triangle (gl_VertexID, no vertex
+// buffer), emitting the SAME vUV the shader-target contract provides: 0..1
+// with origin at the displayed top-left - so a backdrop fragment written
+// for createShaderTexture ports verbatim.
+const BACKGROUND_VERTEX = glsl`
+  out vec2 vUV;
+  void main() {
+    vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+    vUV = p;
+    gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+  }
+`
+
+// Pipeline fragments get no vUV from the engine preamble (a pipeline's
+// varyings are its own), so the background slot injects the full
+// shader-target fragment contract itself: vUV, fragColor, iResolution.
+const BACKGROUND_FRAGMENT_PREAMBLE =
+  "#version 300 es\nprecision highp float;\nin vec2 vUV;\nout vec4 fragColor;\nuniform vec2 iResolution;\n"
+
+/** The scene's background pipeline (internal - reached via
+ * scene.setBackground): depth-free, attributeless, drawn as entry zero of
+ * the scene pass. */
+export function backgroundPipeline(fragment: string, label: string): { pipeline: RenderPipelineId; program: ProgramId } {
+  let vs = compileShader("vertex", BACKGROUND_VERTEX, { header: true })
+  let fs = compileShader(
+    "fragment",
+    needsHeader(fragment) ? BACKGROUND_FRAGMENT_PREAMBLE + fragment : fragment,
+    { header: false },
+  )
+  let program = linkProgram(vs, fs, { label })
+  destroyShader(vs)
+  destroyShader(fs)
+  let pipeline = createRenderPipeline(program, { label })
+  return { pipeline, program }
+}
+
+/** The class half of a shader material: sources and pipeline state, the
+ * things one compiled program fixes. */
+export type ShaderMaterialClassOptions = {
   /**
    * Vertex stage GLSL. MUST declare and use `uniform mat4 uModel` (the
    * mesh's world matrix, written per entry whenever the mesh moves) and
@@ -167,11 +226,16 @@ export type ShaderMaterialOptions = {
    */
   vertex: string
   fragment: string
-  /** Uniform seeds beyond the standard set; update per mesh later with
-   * setMeshParams. */
-  params?: ShaderParams
-  textures?: Record<string, TextureId>
-  /** Pipeline state; defaults match unlit: depth: true, cull: "back". */
+  /** Blend over what is behind, with the scene sorting this material's
+   * meshes back-to-front after the opaque ones (see Material.transparent).
+   * Sets the pipeline defaults blend "alpha" and depthWrite false; the
+   * fragment must write premultiplied output (`vec4(rgb * a, a)`). Defaults
+   * to true whenever `blend` is set to anything but "none": every blended
+   * draw belongs after the opaques so it depth-tests against them, and
+   * back-to-front is harmless for the order-independent modes. */
+  transparent?: boolean
+  /** Pipeline state; defaults match unlit: depth: true, cull: "back",
+   * and for transparent materials blend "alpha", depthWrite: false. */
   depth?: boolean
   depthWrite?: boolean
   blend?: BlendMode
@@ -180,18 +244,41 @@ export type ShaderMaterialOptions = {
   label?: string
 }
 
+/** The instance half of a shader material: uniform seeds and sampler
+ * bindings for one parameterisation of a class's program. */
+export type ShaderMaterialInstanceOptions = {
+  /** Uniform seeds beyond the standard set; update per mesh later with
+   * setMeshParams. */
+  params?: ShaderParams
+  textures?: Record<string, TextureId>
+}
+
+export type ShaderMaterialOptions = ShaderMaterialClassOptions & ShaderMaterialInstanceOptions
+
 /**
- * A material from your own GLSL: the custom-look escape hatch, first-class
- * next to unlit. Sources without a `#version` line get the standard
- * pipeline preamble (`fragColor`, `iResolution`).
- *
- * The INSTANCE is the pipeline handle: two calls with identical sources
- * compile two pipelines - there is no dedupe by source value (a hidden
- * cache keyed by content is the anti-pattern the GPU layer avoids
- * throughout). Create one per look at app scope, share it across meshes,
- * and `dispose()` it if the app is done with the look for good.
+ * One program and pipeline, many parameterisations: the class/instance
+ * split unlit has internally, for your own GLSL. `instance()` returns a
+ * Material sharing the class's pipeline with its own params/textures - the
+ * class compiles once, and dispose() is on the class alone (instances hold
+ * nothing of their own).
  */
-export function shaderMaterial(opts: ShaderMaterialOptions): Material {
+export type ShaderMaterialClass = {
+  instance(opts?: ShaderMaterialInstanceOptions): Material
+  /** Destroy the shared program and pipeline. Instances still in use draw
+   * nothing valid afterwards. */
+  dispose(): void
+}
+
+/**
+ * A material class from your own GLSL: sources without a `#version` line
+ * get the standard pipeline preamble (`fragColor`, `iResolution`). Two
+ * calls with identical sources compile two programs - there is no dedupe by
+ * source value (a hidden cache keyed by content is the anti-pattern the GPU
+ * layer avoids throughout); the class IS the app-owned split. Create one
+ * per program at app scope, `instance()` per look, and `dispose()` the class
+ * when the app is done with the look for good.
+ */
+export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMaterialClass {
   // The standard-set contract, checked where the mistake is made: a vertex
   // stage that never mentions the matrices cannot place meshes, and with
   // shared params skipping undeclared names the omission would otherwise
@@ -208,30 +295,34 @@ export function shaderMaterial(opts: ShaderMaterialOptions): Material {
   // Attributes live in the vertex stage only, so unlike the uNormal scan
   // there is nothing to look for in the fragment source.
   let layout: VertexLayout = /\baColor\b/.test(opts.vertex) ? "colored" : "standard"
+  let normalMatrix = /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment)
+  let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
+  let depth = opts.depth ?? true
+  let pipelineFor = (): RenderPipelineId => {
+    if (pipeline === undefined) {
+      let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
+      let fs = compileShader("fragment", opts.fragment, { header: needsHeader(opts.fragment) })
+      program = linkProgram(vs, fs, { label: opts.label })
+      destroyShader(vs)
+      destroyShader(fs)
+      pipeline = createRenderPipeline(program, {
+        attributes: VERTEX_LAYOUTS[layout],
+        depth,
+        // depthWrite needs a depth buffer, so the transparent default
+        // only applies when there is one.
+        depthWrite: opts.depthWrite ?? (transparent && depth ? false : undefined),
+        blend: opts.blend ?? (transparent ? "alpha" : undefined),
+        cull: opts.cull ?? "back",
+        topology: opts.topology,
+        label: opts.label,
+      })
+    }
+    return pipeline
+  }
   return {
-    normalMatrix: /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment),
-    layout,
-    pipeline() {
-      if (pipeline === undefined) {
-        let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
-        let fs = compileShader("fragment", opts.fragment, { header: needsHeader(opts.fragment) })
-        program = linkProgram(vs, fs, { label: opts.label })
-        destroyShader(vs)
-        destroyShader(fs)
-        pipeline = createRenderPipeline(program, {
-          attributes: VERTEX_LAYOUTS[layout],
-          depth: opts.depth ?? true,
-          depthWrite: opts.depthWrite,
-          blend: opts.blend,
-          cull: opts.cull ?? "back",
-          topology: opts.topology,
-          label: opts.label,
-        })
-      }
-      return pipeline
+    instance(inst = {}) {
+      return { normalMatrix, layout, transparent, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
     },
-    params: opts.params ?? {},
-    textures: opts.textures,
     dispose() {
       if (pipeline !== undefined) {
         destroyRenderPipeline(pipeline)
@@ -244,3 +335,20 @@ export function shaderMaterial(opts: ShaderMaterialOptions): Material {
     },
   }
 }
+
+/**
+ * A material from your own GLSL: the custom-look escape hatch, first-class
+ * next to unlit. A class with a single instance - `shaderMaterialClass()`
+ * is the form for one program with many parameterisations.
+ *
+ * The INSTANCE is the pipeline handle: two calls with identical sources
+ * compile two pipelines - there is no dedupe by source value. Create one
+ * per look at app scope, share it across meshes, and `dispose()` it if the
+ * app is done with the look for good.
+ */
+export function shaderMaterial(opts: ShaderMaterialOptions): Material {
+  let cls = shaderMaterialClass(opts)
+  let material = cls.instance(opts)
+  material.dispose = cls.dispose
+  return material
+}

package/src/math.ts

@@ -57,6 +57,48 @@ export function transformPoint(out: Vec4, m: Mat4, p: Vec3): Vec4 {
   return out
 }
 
+/**
+ * Transform a DIRECTION by m's upper 3x3 (w = 0: rotation and scale apply,
+ * translation does not). The ray-direction counterpart of transformPoint.
+ */
+export function transformVector(out: Vec3, m: Mat4, v: Vec3): Vec3 {
+  let x = v[0], y = v[1], z = v[2]
+  out[0] = m[0] * x + m[4] * y + m[8] * z
+  out[1] = m[1] * x + m[5] * y + m[9] * z
+  out[2] = m[2] * x + m[6] * y + m[10] * z
+  return out
+}
+
+/**
+ * Invert an AFFINE matrix - a world or local matrix whose bottom row is
+ * 0,0,0,1, NOT a projection: the upper 3x3 inverts by cofactors and the
+ * translation is pulled back through it. Picking's world-to-local step.
+ * `out` may alias `m`. A degenerate (zero-scale) matrix yields the raw
+ * cofactors instead of NaNs, the same policy as normalMatrix.
+ */
+export function invertAffine(out: Mat4, m: Mat4): Mat4 {
+  let a = m[0], b = m[4], c = m[8]
+  let d = m[1], e = m[5], f = m[9]
+  let g = m[2], h = m[6], i = m[10]
+  let tx = m[12], ty = m[13], tz = m[14]
+  let c00 = e * i - f * h
+  let c01 = f * g - d * i
+  let c02 = d * h - e * g
+  let det = a * c00 + b * c01 + c * c02
+  let s = 1 / (det || 1)
+  let r00 = c00 * s, r01 = (c * h - b * i) * s, r02 = (b * f - c * e) * s
+  let r10 = c01 * s, r11 = (a * i - c * g) * s, r12 = (c * d - a * f) * s
+  let r20 = c02 * s, r21 = (b * g - a * h) * s, r22 = (a * e - b * d) * s
+  out[0] = r00; out[1] = r10; out[2] = r20; out[3] = 0
+  out[4] = r01; out[5] = r11; out[6] = r21; out[7] = 0
+  out[8] = r02; out[9] = r12; out[10] = r22; out[11] = 0
+  out[12] = -(r00 * tx + r01 * ty + r02 * tz)
+  out[13] = -(r10 * tx + r11 * ty + r12 * tz)
+  out[14] = -(r20 * tx + r21 * ty + r22 * tz)
+  out[15] = 1
+  return out
+}
+
 /** out = a * b (column vectors: b applies first). out may alias a or b. */
 export function multiply(out: Mat4, a: Mat4, b: Mat4): Mat4 {
   let a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3]

package/src/order.ts

@@ -0,0 +1,51 @@
+// Draw-list ordering for a scene: a pure function of the live meshes and the
+// camera's view matrix, with no GUI import, so the check rig
+// (checks/order-check.ts) runs it headless on flux against a linear oracle.
+// The scene calls it whenever the order is dirty and hands the result to
+// setDrawOrder.
+
+import type { Mat4, Vec3 } from "./math.ts"
+
+/** The slice of a Mesh the sort reads (field names match Mesh so the
+ * scene passes its meshes straight through). */
+export type Orderable<T> = {
+  _entry: T | null
+  _transparent: boolean
+  renderOrder: number
+  _center: Vec3
+}
+
+/**
+ * Draw order: `first` (the background entry, if any), then opaque meshes by
+ * renderOrder with add order within a key, then transparent meshes by
+ * renderOrder then back-to-front by the view-space depth of the world-bounds
+ * center. The center, not the origin (Three's key), so geometry built
+ * off-origin sorts by where it is; and not the nearest bounds point, which
+ * would draw a large translucent ground plane over the small translucents
+ * resting on it. Per-mesh only: no per-triangle sort, no OIT.
+ */
+export function orderEntries<T>(meshes: readonly Orderable<T>[], view: Mat4, first?: T): T[] {
+  let opaque: Orderable<T>[] = []
+  let transparent: Orderable<T>[] = []
+  for (let m of meshes) {
+    if (m._entry === null) continue
+    ;(m._transparent ? transparent : opaque).push(m)
+  }
+  // Array sort is stable, so equal keys keep add order.
+  opaque.sort((a, b) => a.renderOrder - b.renderOrder)
+  if (transparent.length > 1) {
+    // The camera looks down -z in view space, so farther is more negative
+    // and ascending depth is back-to-front.
+    let depth = new Map<Orderable<T>, number>()
+    for (let m of transparent) {
+      let c = m._center
+      depth.set(m, view[2] * c[0] + view[6] * c[1] + view[10] * c[2] + view[14])
+    }
+    transparent.sort((a, b) => a.renderOrder - b.renderOrder || depth.get(a)! - depth.get(b)!)
+  }
+  let order: T[] = []
+  if (first !== undefined) order.push(first)
+  for (let m of opaque) order.push(m._entry!)
+  for (let m of transparent) order.push(m._entry!)
+  return order
+}