@solidrt/3d 0.0.50 → 0.0.52

package/examples/sprites.tsx

@@ -0,0 +1,95 @@
+// Sprites: camera-facing quads turned in the vertex stage, so the camera
+// can circle and climb while no per-frame JS touches a single sprite. Two
+// billboard modes side by side: "full" glows that stay flat to the screen
+// whatever the camera does, and "fixed-y" trees that only yaw to follow
+// the camera and stay upright as it climbs - the classic upright sprite.
+// The spinning cube is the reference solid; the sprites' `scale` is their
+// world size, and their (ignored) rotation is never set.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { createTexture } from "@solidrt/core/gpu"
+import { box, Group, Mesh, PerspectiveCamera, plane, Scene, sprite, Sprite, unlit } from "@solidrt/3d"
+
+const SIZE = 720
+
+// A soft disc, alpha falling off from the center; premultiplied like every
+// texture the engine samples.
+function glow(): ReturnType<typeof createTexture> {
+  let n = 64
+  let data = new Uint8Array(n * n * 4)
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      let dx = (x + 0.5) / n - 0.5
+      let dy = (y + 0.5) / n - 0.5
+      let a = Math.max(0, 1 - Math.sqrt(dx * dx + dy * dy) * 2)
+      a = a * a
+      data.set([255 * a, 240 * a, 200 * a, 255 * a], (y * n + x) * 4)
+    }
+  }
+  return createTexture(data, n, n)
+}
+
+// A cutout tree: green triangle over a brown trunk, transparent elsewhere.
+function tree(): ReturnType<typeof createTexture> {
+  let n = 64
+  let data = new Uint8Array(n * n * 4)
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      let u = (x + 0.5) / n
+      let v = (y + 0.5) / n
+      let inCrown = v < 0.8 && Math.abs(u - 0.5) < v * 0.55
+      let inTrunk = v >= 0.8 && Math.abs(u - 0.5) < 0.08
+      let rgb = inCrown ? [40, 140, 60] : inTrunk ? [110, 70, 40] : [0, 0, 0]
+      let a = inCrown || inTrunk ? 255 : 0
+      data.set([rgb[0]!, rgb[1]!, rgb[2]!, a], (y * n + x) * 4)
+    }
+  }
+  return createTexture(data, n, n)
+}
+
+function App() {
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  // The camera circles the scene and climbs from eye level to well above
+  // it: the glows never change shape, the trees tilt away only as the
+  // view looks down on them.
+  let eye = () => {
+    let a = t() * 0.4
+    let elevation = 1.2 + 2.5 * (0.5 - 0.5 * Math.cos(t() * 0.5))
+    return [Math.sin(a) * 5, elevation, Math.cos(a) * 5] as [number, number, number]
+  }
+
+  let glows = sprite({ map: glow(), color: [1, 0.85, 0.5] })
+  let trees = sprite({ map: tree(), billboard: "fixed-y" })
+  let ringPositions = Array.from({ length: 8 }, (_, i) => {
+    let a = (i / 8) * Math.PI * 2
+    return [Math.cos(a) * 1.4, 0.9 + Math.sin(a * 2) * 0.3, Math.sin(a) * 1.4] as [number, number, number]
+  })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="sprites">
+          <PerspectiveCamera fov={50} position={eye()} lookAt={[0, 0.6, 0]} />
+          <Mesh
+            geometry={plane({ width: 8, height: 8 })}
+            material={unlit({ color: [0.16, 0.17, 0.22] })}
+            rotation={[-Math.PI / 2, 0, 0]}
+          />
+          <Mesh geometry={box({ width: 0.7, height: 0.7, depth: 0.7 })} material={unlit({ color: [0.85, 0.3, 0.3] })} position={[0, 0.35, 0]} rotation={[0, t(), 0]} />
+          <Group rotation={[0, -t() * 0.3, 0]}>
+            {ringPositions.map(p => (
+              <Sprite material={glows} position={p} scale={0.5} />
+            ))}
+          </Group>
+          <Sprite material={trees} position={[-2.2, 0.8, -1]} scale={[1.2, 1.6, 1]} />
+          <Sprite material={trees} position={[2.4, 0.9, 0.5]} scale={[1.4, 1.8, 1]} />
+          <Sprite material={trees} position={[0.8, 0.7, -2.6]} scale={[1, 1.4, 1]} />
+          <Sprite material={trees} position={[-1.5, 0.6, 2.2]} scale={[0.9, 1.2, 1]} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/sweep-paths.tsx

@@ -3,13 +3,12 @@
 // over the crate's edges like real webbing - while smooth-tagged points
 // share averaged normals, so the helix sweeps into ONE continuous coil
 // (per-segment boxes with unmitred gaps are exactly what this replaces).
-// tube() is the round-profile shorthand. Lit materials on purpose:
+// tube() is the round-profile shorthand. lit() materials on purpose:
 // creased vs smooth joints differ only in normals, which unlit color
 // would hide.
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
-import { box, Group, Mesh, PerspectiveCamera, plane, roundRect, Scene, shaderMaterial, sweep, tube, unlit } from "@solidrt/3d"
+import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, roundRect, Scene, sweep, tube, unlit } from "@solidrt/3d"
 import type { SweepPath } from "@solidrt/3d"
-import { HEMISPHERE, LAMBERT, LIT_VERTEX } from "@solidrt/3d/glsl"
 
 const SIZE = 720
 
@@ -17,23 +16,6 @@ function App() {
   let [spin, setSpin] = createSignal(0)
   onFrame(tick => setSpin(tick / 4000))
 
-  // One hemisphere + lambert look per color (a material instance is the
-  // pipeline handle, so each look is created once and shared).
-  let lit = (r: number, g: number, b: number) =>
-    shaderMaterial({
-      vertex: LIT_VERTEX,
-      fragment: `
-        in vec3 vNormal;
-        ${HEMISPHERE}
-        ${LAMBERT}
-        void main() {
-          vec3 n = normalize(vNormal);
-          vec3 l = normalize(vec3(0.5, 0.8, 0.4));
-          vec3 base = vec3(${r}, ${g}, ${b});
-          fragColor = vec4(base * (hemisphere(n, vec3(0.45), vec3(0.22)) + 0.8 * lambert(n, l)), 1.0);
-        }`,
-    })
-
   // The strap hugs the crate at half its thickness; every bend is a bare
   // (sharp) point, so each fold creases exactly on a crate edge.
   let o = 0.013
@@ -45,7 +27,7 @@ function App() {
     [-0.3 + o, o, 0],
     [0.15, o, 0],
   ]
-  let strap = sweep(roundRect(0.3, 0.026, 0.008), strapPath, "strap")
+  let strap = sweep(roundRect(0.3, 0.026, 0.008), strapPath, { label: "strap" })
 
   // A smooth-tagged helix: one continuous tube, not a stack of segments.
   let coilPath: SweepPath = []
@@ -53,22 +35,24 @@ function App() {
     let a = (i / 60) * Math.PI * 5
     coilPath.push({ p: [0.85 + Math.cos(a) * 0.35, 0.055 + i * 0.0095, Math.sin(a) * 0.35], smooth: true })
   }
-  let coil = tube(coilPath, 0.05, 12, "coil")
+  let coil = tube(coilPath, { radius: 0.05, radialSegments: 12, label: "coil" })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="sweep-paths">
           <PerspectiveCamera fov={55} position={[0, 1.9, 3.9]} lookAt={[0, 0.35, 0]} />
+          <HemisphereLight sky={[0.45, 0.45, 0.45]} ground={[0.22, 0.22, 0.22]} />
+          <DirectionalLight direction={[-0.5, -0.8, -0.4]} intensity={0.8} />
           <Mesh
-            geometry={plane(6, 6, "floor")}
+            geometry={plane({ width: 6, height: 6, label: "floor" })}
             material={unlit({ color: [0.16, 0.17, 0.22] })}
             rotation={[-Math.PI / 2, 0, 0]}
           />
           <Group rotation={[0, spin(), 0]}>
-            <Mesh geometry={box(1, 0.6, 0.8)} material={lit(0.55, 0.42, 0.28)} position={[-0.8, 0.3, 0]} />
-            <Mesh geometry={strap} material={lit(0.9, 0.55, 0.2)} />
-            <Mesh geometry={coil} material={lit(0.45, 0.6, 0.8)} />
+            <Mesh geometry={box({ width: 1, height: 0.6, depth: 0.8 })} material={lit({ color: [0.55, 0.42, 0.28] })} position={[-0.8, 0.3, 0]} />
+            <Mesh geometry={strap} material={lit({ color: [0.9, 0.55, 0.2] })} />
+            <Mesh geometry={coil} material={lit({ color: [0.45, 0.6, 0.8] })} />
           </Group>
         </Scene>
       </view>

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "license": "MIT",
+  "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
   "type": "module",
   "main": "src/index.ts",
@@ -13,10 +14,11 @@
   "files": [
     "src/",
     "examples/",
+    "demos/",
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.0",
-    "@solidrt/core": "0.0.50"
+    "@solidjs/signals": "2.0.0-rc.1",
+    "@solidrt/core": "0.0.52"
   }
 }

package/src/components.tsx

@@ -10,11 +10,20 @@ import { createContext, createEffect, onCleanup, untrack, useContext } from "@so
 import type { Element, ParentComponent, TextureId, VoidComponent } from "@solidrt/core"
 import {
   add,
+  createDirectionalLight,
   createGroup,
+  createHemisphereLight,
+  createInstancedMesh,
   createMesh,
   createScene,
+  createSprite,
+  disposeInstances,
   remove,
   setGeometry,
+  setInstanceCount,
+  setInstances,
+  setLight,
+  setCastShadow,
   setMaterial,
   setMeshParams,
   setRenderOrder,
@@ -22,7 +31,7 @@ import {
   setVisible,
 } from "./scene.ts"
 import type { ShaderParams } from "@solidrt/core/gpu"
-import type { Mesh as MeshNode, Scene as SceneHandle, SceneNode, ScenePointerEvent } from "./scene.ts"
+import type { DirectionalLight as DirectionalLightNode, HemisphereLight as HemisphereLightNode, InstancedMesh as InstancedMeshNode, Mesh as MeshNode, Scene as SceneHandle, SceneNode, ScenePointerEvent, ShadowOptions } from "./scene.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Material } from "./material.ts"
 import type { Quat, Vec3 } from "./math.ts"
@@ -99,6 +108,9 @@ export type SceneProps = {
    * `scene.background = color` is `clearColor` here. */
   background?: string
   label?: string
+  /** Multisample count (1, 2, 4 or 8; default 1): anti-aliased mesh edges.
+   * Fixed at creation. */
+  samples?: 1 | 2 | 4 | 8
   ref?: (scene: SceneHandle) => void
   /**
    * Compose the output yourself: called once (untracked) with the scene's
@@ -127,7 +139,7 @@ export type SceneProps = {
  */
 export let Scene: ParentComponent<SceneProps> = props => {
   let scene = untrack(() =>
-    createScene(props.width, props.height, { clearColor: props.clearColor, label: props.label }),
+    createScene(props.width, props.height, { clearColor: props.clearColor, label: props.label, samples: props.samples }),
   )
   createEffect(
     () => [props.width, props.height] as const,
@@ -182,9 +194,34 @@ export type MeshProps = TransformProps & PointerEventProps & {
   params?: ShaderParams
   /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
   renderOrder?: number
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. Needs a `castShadow` DirectionalLight to show. */
+  castShadow?: boolean
   ref?: (mesh: MeshNode) => void
 }
 
+// The mesh-side props Mesh and Sprite share (Sprite has no geometry).
+function syncMesh(mesh: MeshNode, props: SpriteProps): void {
+  createEffect(
+    () => props.material,
+    m => setMaterial(mesh, m),
+    { defer: true },
+  )
+  createEffect(
+    () => props.params,
+    p => {
+      if (p !== undefined) setMeshParams(mesh, p)
+    },
+  )
+  createEffect(
+    () => props.renderOrder,
+    o => setRenderOrder(mesh, o ?? 0),
+  )
+  syncNode(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => remove(mesh))
+}
+
 /** One draw entry: geometry drawn with a material at a transform. */
 export let Mesh: VoidComponent<MeshProps> = props => {
   let ctx = useContext(SceneContext)
@@ -195,6 +232,81 @@ export let Mesh: VoidComponent<MeshProps> = props => {
     g => setGeometry(mesh, g),
     { defer: true },
   )
+  createEffect(
+    () => props.castShadow,
+    c => setCastShadow(mesh, c === true),
+  )
+  syncMesh(mesh, props)
+  return null
+}
+
+export type SpriteProps = TransformProps & PointerEventProps & {
+  /** A `sprite()` material (any material draws, only a sprite one turns). */
+  material: Material
+  /** Per-mesh uniforms, merge semantics - as on Mesh. */
+  params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
+  ref?: (mesh: MeshNode) => void
+}
+
+/** A camera-facing unit quad (createSprite as a component): no geometry
+ * prop, `scale` is its world size, rotation is ignored. */
+export let Sprite: VoidComponent<SpriteProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createSprite(props.material))
+  add(ctx.parent, mesh)
+  syncMesh(mesh, props)
+  return null
+}
+
+export type InstancedMeshProps = TransformProps & PointerEventProps & {
+  geometry: Geometry
+  /** Must declare instanceAttributes (shaderMaterialClass). */
+  material: Material
+  /** Interleaved per-instance records (stride = the material's instance
+   * attributes summed). Reactive; a later array larger than the buffer
+   * grows it (capacity doubles into a replacement buffer). */
+  records: Float32Array
+  /** How many records draw; default all of the latest `records`. */
+  count?: number
+  /** LOCAL bounds covering every instance ([minX..maxZ]), fixed at
+   * creation. Without them the mesh has no picking leaf, so pointer events
+   * never target it. */
+  bounds?: ArrayLike<number>
+  /** Per-mesh uniforms, merge semantics - as on Mesh. */
+  params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
+  ref?: (mesh: InstancedMeshNode) => void
+}
+
+/** One draw entry covering N instances: geometry repeated per record of
+ * `records` (createInstancedMesh as a component). The record buffer is
+ * component-owned and freed on unmount. */
+export let InstancedMesh: VoidComponent<InstancedMeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() =>
+    createInstancedMesh(props.geometry, props.material, props.records, props.count, { bounds: props.bounds }),
+  )
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.records,
+    r => setInstances(mesh, r, untrack(() => props.count)),
+    { defer: true },
+  )
+  createEffect(
+    () => props.count,
+    c => {
+      if (c !== undefined) setInstanceCount(mesh, c)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
   createEffect(
     () => props.material,
     m => setMaterial(mesh, m),
@@ -212,7 +324,7 @@ export let Mesh: VoidComponent<MeshProps> = props => {
   )
   syncNode(mesh, props)
   untrack(() => props.ref)?.(mesh)
-  onCleanup(() => remove(mesh))
+  onCleanup(() => disposeInstances(mesh))
   return null
 }
 
@@ -240,3 +352,59 @@ export let PerspectiveCamera: VoidComponent<PerspectiveCameraProps> = props => {
   )
   return null
 }
+
+export type HemisphereLightProps = { sky?: Vec3; ground?: Vec3; intensity?: number; ref?: (light: HemisphereLightNode) => void }
+
+/** The scene's ambient term as a node (createHemisphereLight); one per
+ * scene, the last mounted wins. */
+export let HemisphereLight: VoidComponent<HemisphereLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() => createHemisphereLight({ sky: props.sky, ground: props.ground, intensity: props.intensity }))
+  add(ctx.parent, light)
+  createEffect(
+    () => [props.sky, props.ground, props.intensity] as const,
+    ([sky, ground, intensity]) => setLight(light, { sky, ground, intensity }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}
+
+export type DirectionalLightProps = TransformProps & {
+  /** Travel direction in the node's local space; default [0, -1, 0]. */
+  direction?: Vec3
+  color?: Vec3
+  intensity?: number
+  /** Render a shadow map from this light (any directional light may;
+   * each is a pass). Its shadow camera sits at the light's WORLD
+   * position, so give a casting light a `position` above the scene. */
+  castShadow?: boolean
+  /** Shadow-map options (mapSize, bias, normalBias, camera frustum),
+   * merged key by key. */
+  shadow?: ShadowOptions
+  ref?: (light: DirectionalLightNode) => void
+}
+
+/** A directional light node (createDirectionalLight): a parent Group's
+ * rotation turns it; up to MAX_LIGHTS per scene, in mount order. */
+export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() =>
+    createDirectionalLight({
+      direction: props.direction,
+      color: props.color,
+      intensity: props.intensity,
+      castShadow: props.castShadow,
+      shadow: props.shadow,
+    }),
+  )
+  add(ctx.parent, light)
+  syncNode(light, props)
+  createEffect(
+    () => [props.direction, props.color, props.intensity, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, castShadow, shadow]) => setLight(light, { direction, color, intensity, castShadow, shadow }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}

package/src/geometry-gpu.ts

@@ -0,0 +1,97 @@
+// Geometry on the GPU: the lazy buffer step for geometry.ts's data. Buffers
+// (and the picking shape - the spatial core's own copy of positions, UVs
+// and indices for the triangle narrowphase, one per geometry however many
+// meshes share it) are created on first acquire and shared by every mesh
+// and scene drawing the geometry; each draw entry holds one reference, and
+// the buffers are
+// freed when the last reference is released - deferred to a microtask, so
+// a same-tick entry rebuild (a material swap, a geometry that comes right
+// back) keeps its upload. The handles and the reference count live in a
+// map private to this module, keeping Geometry itself plain data.
+// disposeGeometry frees immediately, the explicit override; either way the
+// geometry stays usable - fresh buffers are created on next acquire.
+
+import { createBuffer, destroyBuffer } from "@solidrt/core/gpu"
+import type { BufferId, IndexFormat } from "@solidrt/core/gpu"
+import { createShape, destroyShape } from "flux:spatial"
+import type { ShapeId } from "flux:spatial"
+import { layoutStride } from "./geometry.ts"
+import type { Geometry } from "./geometry.ts"
+
+/** An acquired reference to a geometry's GPU buffers: what a draw entry
+ * binds, and the token releaseGeometryBuffers takes - releasing the exact
+ * acquisition keeps the pairing correct however the caller's geometry
+ * fields have moved since. */
+export type GeometryBuffers = {
+  buffer: BufferId
+  index: BufferId
+  indexFormat: IndexFormat
+  /** The picking shape (positions at 0, uv at 6 of every layout). */
+  shape: ShapeId
+}
+
+type GpuEntry = GeometryBuffers & { geometry: Geometry; refs: number }
+
+let entries = new WeakMap<Geometry, GpuEntry>()
+
+/** The geometry's GPU buffers, created on first use, plus the index format
+ * the draw entry must bind them with. Takes a reference - pair every
+ * acquire with a releaseGeometryBuffers of the returned token when the
+ * entry built from it goes. */
+export function acquireGeometryBuffers(geometry: Geometry): GeometryBuffers {
+  let entry = entries.get(geometry)
+  if (entry === undefined) {
+    entry = {
+      geometry,
+      buffer: createBuffer(geometry.vertices, {
+        autoFree: false,
+        label: geometry.label ? geometry.label + "-verts" : undefined,
+      }),
+      index: createBuffer(geometry.indices, {
+        autoFree: false,
+        label: geometry.label ? geometry.label + "-indices" : undefined,
+      }),
+      indexFormat: geometry.indices instanceof Uint32Array ? "uint32" : "uint16",
+      shape: createShape(geometry.vertices, layoutStride(geometry.layout), 0, 6, geometry.indices),
+      refs: 0,
+    }
+    entries.set(geometry, entry)
+  }
+  entry.refs++
+  return entry
+}
+
+/** Release one acquire. At zero references the buffers are freed at the
+ * end of the microtask; an acquire before then keeps them, so a detach and
+ * re-attach in one tick never re-uploads. A token orphaned by an explicit
+ * disposeGeometry releases against the orphan, never against a successor's
+ * fresh buffers. */
+export function releaseGeometryBuffers(acquired: GeometryBuffers): void {
+  let entry = acquired as GpuEntry
+  if (entry.refs === 0) return
+  entry.refs--
+  if (entry.refs > 0) return
+  queueMicrotask(() => {
+    if (entries.get(entry.geometry) !== entry || entry.refs > 0) return
+    entries.delete(entry.geometry)
+    destroyBuffer(entry.buffer)
+    destroyBuffer(entry.index)
+    destroyShape(entry.shape)
+  })
+}
+
+/**
+ * Free the geometry's GPU buffers now, held references or not - the
+ * explicit override for geometry an app is done with for good. Draw
+ * entries created from them hold their own reference, so destruction order
+ * is safe; the geometry can be used again afterwards (fresh buffers are
+ * created on next use).
+ */
+export function disposeGeometry(geometry: Geometry): void {
+  let entry = entries.get(geometry)
+  if (entry === undefined) return
+  entries.delete(geometry)
+  destroyBuffer(entry.buffer)
+  destroyBuffer(entry.index)
+  destroyShape(entry.shape)
+}