@solidrt/3d 0.0.58 → 0.0.59

package/src/index.ts

@@ -5,11 +5,13 @@
 // without Solid components) and the component face (Scene/Mesh/Group/
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
-export { add, createGroup, getRotation, getTransform, lookAt, remove, setTransform, setTransition, setVisible, worldPosition } from "./node.ts"
-export type { NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
-export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, removeInstance, setCastShadow, setCulling, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, INSTANCE_FLOATS } from "./mesh.ts"
-export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceSlots, InstanceStyle, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions } from "./mesh.ts"
-export { createDirectionalLight, createHemisphereLight, createPointLight, createSpotLight, setLight, MAX_SHADOWS } from "./light.ts"
+export { add, createGroup, destroy, getMorphNames, getMorphWeights, getRotation, getTransform, lookAt, remove, setMorphWeights, setTransform, setTransition, setVisible, worldPosition } from "./node.ts"
+export type { LodConfig, MorphWeights, NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
+export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, setCastShadow, setCulling, setDrawRange, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, instanceAttribute, updateRecords, INSTANCE_FLOATS } from "./mesh.ts"
+export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceSlots, InstanceStream, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions, UpdateRecordsOptions } from "./mesh.ts"
+export { createDirectionalLight, createHemisphereLight, createPointLight, createSpotLight, setLight } from "./light.ts"
+// The shader-source caps, also on the /glsl subpath next to the sources they size.
+export { MAX_CASCADES, MAX_LIGHTS, MAX_SHADOW_MAPS } from "./glsl.ts"
 export type {
   DirectionalLight as DirectionalLightNode,
   DirectionalLightOptions,
@@ -25,36 +27,44 @@ export type {
   SpotLightOptions,
   SpotShadowOptions,
 } from "./light.ts"
-export { createScene } from "./scene.ts"
+export { createInstancedLod, createLod, setLod } from "./lod.ts"
+export type { InstancedLodLevel, InstancedLodOptions, LodLevel, LodOptions } from "./lod.ts"
+export { createScene, resolveParams } from "./scene.ts"
 export { feedPointer } from "./scene-pointer.ts"
-export type { Capsule, EnvironmentOptions, FogOptions, Hit, Impact, MoveOptions, MoveResult, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, ViewHandle, ViewOptions, Volume } from "./scene.ts"
+export type { BloomOptions, Capsule, EnvironmentOptions, FogOptions, Hit, Impact, MoveOptions, MoveResult, OrientedBox, Overlap, QueryOptions, ReflectionProbe, ReflectionProbeOptions, ResolveInput, ResolveOptions, Scene as SceneHandle, SceneHandlers, SceneOptions, ScreenRay, SkyboxOptions, Sphere, ToneMapping, ViewHandle, ViewOptions, Volume } from "./scene.ts"
 export { moveAndSlide } from "./collision.ts"
 export type { MoveScene } from "./collision.ts"
-export { equirectToCube, loadEnvironment } from "./environment.ts"
-export { linearColor, linearToSrgb, srgbToLinear } from "./color.ts"
+export { bufferFormat, equirectToCube, loadEnvironment } from "./environment.ts"
+export type { BufferFormat } from "./environment.ts"
+export { linearColor, linearToSrgb, premultipliedColor, srgbToLinear } from "./color.ts"
 export type { CameraState, CameraUpdate, OrthoExtent } from "./camera.ts"
-export type { NodeTransition, NodeTransitionSpec } from "flux:spatial"
-export { disposeGeometry } from "./geometry-gpu.ts"
-export { box, circle, cone, cylinder, fillAttribute, fillColors, edgesGeometry, geometryBounds, geometryTopology, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, packGeometry, plane, ring, sphere, torus, torusKnot, transformGeometry, validateGeometry, wireframeGeometry, withAttribute, withColors, STANDARD_FLOATS, VERTEX_LAYOUTS } from "./geometry.ts"
-export type { AttributeFill, BoxOptions, CircleOptions, ColorFill, ConeOptions, CylinderOptions, Geometry, GeometryOptions, PlaneOptions, RingOptions, SphereOptions, TorusKnotOptions, TorusOptions, VertexLayout } from "./geometry.ts"
-export { fillet, roundRect, shape, triangulate } from "./profile.ts"
+export type { NodeMotionSpec, NodeTransition, NodeTransitionSpec } from "flux:spatial"
+export { computeVertexNormals, disposeGeometry, updateVertices } from "./geometry-gpu.ts"
+export type { GeometryBuffers, UpdateVerticesOptions } from "./geometry-gpu.ts"
+export { arrowHelper, axesHelper, box, box3Helper, capsule, capsuleHelper, circle, cone, cylinder, dodecahedron, fillAttribute, fillColors, edgesGeometry, mergeVertices, normalsHelper, toNonIndexed, withNormals, geometryBounds, geometryTopology, gridHelper, icosahedron, attributeAccess, geometryAttribute, geometryKey, geometryLayouts, geometrySlot, geometryStreams, geometryVertexCount, isFloatFormat, isFloatLayout, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, octahedron, packGeometry, packMorphTargets, plane, planeHelper, polyhedron, ring, sphere, tetrahedron, torus, torusKnot, transformGeometry, validateGeometry, wireframeGeometry, vertexBytes, vertexCount, vertexView, withAttribute, withColors, withMorphTargets, MORPH_ENTRY_TEXELS, MORPH_TEXEL_FLOATS, BASE_FLOATS, VERTEX_FORMATS, VERTEX_LAYOUTS } from "./geometry.ts"
+export type { ArrowHelperOptions, AttributeAccess, AttributeFill, VertexStream, WithAttributeOptions, AxesHelperOptions, BoxOptions, CapsuleHelperOptions, CapsuleOptions, CircleOptions, ColorFill, ConeOptions, CylinderOptions, FormatCodec, Geometry, GeometryOptions, GridHelperOptions, MorphTarget, MorphTargets, NormalsHelperOptions, PlaneHelperOptions, PlaneOptions, PolyhedronOptions, RingOptions, SphereOptions, TorusKnotOptions, TorusOptions, VertexLayout } from "./geometry.ts"
+export { fillet, roundRect, triangulate } from "./profile.ts"
 export type { Profile, ProfilePoint } from "./profile.ts"
-export { extrude, lathe, pathFrames, sweep, tube } from "./sweep.ts"
+export { extrude, lathe, pathFrames, polygon, sweep, tube } from "./sweep.ts"
 export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.ts"
-export { lit, shaderMaterial, shaderMaterialClass, sprite, standard, unlit } from "./material.ts"
-export type { LitOptions, Material, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, SpriteOptions, StandardOptions, UnlitOptions } from "./material.ts"
-export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedMesh, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, View3d, useScene } from "./components/index.ts"
+export { phong, shaderMaterial, shaderMaterialClass, sprite, standard, unlit } from "./material.ts"
+export type { LitOptions, Material, PhongOptions, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, SpriteOptions, StandardOptions, UnlitOptions } from "./material.ts"
+export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedLod, InstancedMesh, Lod, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SpotLight, Sprite, View3d, useScene } from "./components/index.ts"
 export type {
   CameraTarget,
   DirectionalLightProps,
   FirstPersonCameraProps,
   HemisphereLightProps,
+  InstancedLodProps,
   InstancedMeshProps,
   InstanceProps,
+  LodProps,
   MeshProps,
   OrbitCameraProps,
   PerspectiveCameraProps,
   PointerEventProps,
+  BubblingPointerEventProps,
+  GroupProps,
   PointLightProps,
   RecordMeshProps,
   ScenePointerProps,
@@ -72,11 +82,11 @@ export type { Model, ModelMaps, ModelOptions } from "./model.ts"
 export { bindSkeleton } from "./skeleton.ts"
 export { createMixer } from "./mixer.ts"
 export type { Mixer, MixerOptions, MixerPlayOptions } from "./mixer.ts"
-export { sampleChannel } from "./clip.ts"
+export { channelElements, sampleChannel } from "./clip.ts"
 export { createOrbitCamera } from "./orbit.ts"
-export type { OrbitAxes, OrbitCamera as OrbitCameraHandle, OrbitCameraOptions, OrbitPose, OrbitTarget } from "./orbit.ts"
+export type { OrbitAxes, OrbitCamera as OrbitCameraHandle, OrbitCameraOptions, OrbitPose, OrbitPoseState, OrbitTarget } from "./orbit.ts"
 export { createFirstPersonCamera } from "./first-person.ts"
-export type { FirstPersonAxes, FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions, FirstPersonPose, FirstPersonTarget } from "./first-person.ts"
+export type { FirstPersonAxes, FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions, FirstPersonPose, FirstPersonPoseState, FirstPersonTarget } from "./first-person.ts"
 export { firstPersonActions, firstPersonBindings, orbitActions, orbitBindings } from "./input.ts"
 export type { CameraDevices } from "./input.ts"
 // math's lookAt (the camera view matrix) stays on the /math subpath: the

package/src/light.ts

@@ -2,7 +2,7 @@
 // hemisphere ambient, their constructors and the setLight write path.
 // Scene reactions go through the node's SceneHooks (node.ts).
 
-import { MAX_CASCADES, MAX_LIGHTS } from "./glsl.ts"
+import { MAX_CASCADES } from "./glsl.ts"
 import type { Vec3 } from "./math.ts"
 import { makeNode } from "./node.ts"
 import type { SceneNode } from "./node.ts"
@@ -204,13 +204,12 @@ export type PointLightOptions = {
 }
 export type HemisphereLightOptions = { sky?: Vec3; ground?: Vec3; intensity?: number }
 
-/** Every light may cast; the real bound is the shadow-slot budget
- * (MAX_SHADOW_MAPS: a directional light claims `shadow.cascades` slots,
- * a point light six, a spot one, and a caster past the budget throws at
- * attach). Every map is a tile of the scene's one shadow atlas, so the
- * pass count never follows the caster count, the fill does. */
-export const MAX_SHADOWS = MAX_LIGHTS
-export { MAX_CASCADES }
+// Every light may cast; the bound is the shadow-slot budget
+// (MAX_SHADOW_MAPS in glsl.ts, exported from the root with MAX_LIGHTS and
+// MAX_CASCADES: a directional light claims `shadow.cascades` slots, a
+// point light six, a spot one). Every map is a tile of the scene's one
+// shadow atlas, so the pass count never follows the caster count, the
+// fill does.
 
 // The spot cone bounds: a half-angle in (0, 90] degrees, penumbra a
 // 0..1 fraction of it.

package/src/lod.ts

@@ -0,0 +1,148 @@
+// Level of detail: a group whose children are variants of one object,
+// nearest first, with the projected size below which each hands over to
+// the next; and the instanced form, a population whose every instance
+// picks its own level. The choice is the spatial core's, per target,
+// after each flush (okf/done/3d-lod.md): a thousand groups cost no JS
+// per frame. Three's LOD vocabulary over Unity's screen-relative model.
+import { add, createGroup } from "./node.ts"
+import type { LodConfig, SceneNode } from "./node.ts"
+import { createInstancedMesh, setCastShadow } from "./mesh.ts"
+import type { InstancedMesh, InstancedMeshOptions } from "./mesh.ts"
+import type { Geometry } from "./geometry.ts"
+import type { Material } from "./material.ts"
+
+/**
+ * One level of a LOD group: the node drawn at this level and `size`, the
+ * group's projected size - the diameter of the sphere around its levels'
+ * boxes (radius = half the box diagonal) as a fraction of the viewport
+ * height - BELOW which the level hands over to the next (Unity's screen
+ * relative transition height). The last level's size is the cull
+ * threshold: 0 keeps it drawn at any distance. For a perspective camera
+ * `size = radius / (distance * tan(fov / 2))`, so a tree whose box is 4
+ * across (radius 3.5) at 30 units under a 60 degree camera measures about
+ * 0.2.
+ */
+export type LodLevel = { node: SceneNode; size: number }
+
+export type LodOptions = {
+  /** The cross-fade band as a fraction of each threshold (default 0, a
+   * hard switch with hysteresis): a boundary at size `s` widens to
+   * `[s, s * (1 + fade))`, in which both levels draw with complementary
+   * screen-hash dithers (the stock materials; a custom class composes
+   * LOD_FADE). Shadow tiles never fade: their depth pass switches hard
+   * at the band's midpoint. */
+  fade?: number
+}
+
+// A level's size and the band fraction, checked where the mistake is
+// made; the core re-checks with the same rules.
+function checkSizes(levels: { size: number }[], fade: number | undefined, site: string): number {
+  levels.forEach((l, k) => {
+    if (!(Number.isFinite(l.size) && l.size >= 0)) throw new Error(site + ": level " + k + " size must be a finite number >= 0, got " + l.size)
+    if (k > 0 && l.size >= levels[k - 1]!.size) throw new Error(site + ": level sizes must be strictly descending, nearest first (level " + k + ": " + l.size + " after " + levels[k - 1]!.size + ")")
+  })
+  let f = fade ?? 0
+  if (!(Number.isFinite(f) && f >= 0)) throw new Error(site + ": fade must be a finite fraction >= 0, got " + f)
+  return f
+}
+
+/**
+ * A LOD group (Three's LOD, Unity's LODGroup): a group node whose levels
+ * are its children, one drawn at a time by projected size on every
+ * target - the scene and each view by their own camera, shadow tiles by
+ * the scene camera, so a caster's shadow matches the level the camera
+ * sees. The choice is the spatial core's after each flush; zero JS per
+ * frame however many groups. Picking and collision through the scene see
+ * the level the scene draws (a view's pick the view's). The group is
+ * measured by the sphere around its levels' boxes; nested groups chain.
+ * Re-declare with setLod; `setLod(group, [])` makes it a plain group.
+ */
+export function createLod(levels: LodLevel[], opts?: LodOptions): SceneNode {
+  let group = createGroup()
+  setLod(group, levels, opts)
+  return group
+}
+
+/**
+ * Declare (or with an empty list clear) a node's LOD levels. A level is
+ * a direct child of the node: a parentless node is adopted as one here,
+ * a node parented elsewhere is refused (move it with `add` first - a
+ * declaration never re-parents behind your back). On the population of
+ * createInstancedLod the levels are sizes only (`{ size }`): its level
+ * meshes are fixed at creation.
+ */
+export function setLod(node: SceneNode, levels: (LodLevel | { size: number })[], opts?: LodOptions): void {
+  if (node._destroyed) throw new Error("setLod: the node was destroyed")
+  let fade = checkSizes(levels, opts?.fade, "setLod")
+  let population = node.kind === "mesh" && (node as InstancedMesh)._instances?.levels !== null && (node as InstancedMesh)._instances !== null
+  let config: LodConfig | null = null
+  if (levels.length > 0) {
+    let nodes = levels.map(l => ("node" in l ? l.node : null))
+    if (population) {
+      if (nodes.some(n => n !== null)) throw new Error("setLod: an instanced LOD's levels are its meshes, fixed at creation - pass sizes only")
+      let count = (node as InstancedMesh)._instances.levels!.length
+      if (levels.length !== count) throw new Error("setLod: an instanced LOD with " + count + " level meshes takes " + count + " sizes, got " + levels.length)
+    } else {
+      if (nodes.some(n => n === null)) throw new Error("setLod: every level names a node")
+      for (let n of nodes as SceneNode[]) {
+        if (n === node) throw new Error("setLod: a level cannot be the group itself")
+        if (n.kind === "instance") throw new Error("setLod: an instance is slot-bound to its mesh and cannot be a level")
+        if (n._destroyed) throw new Error("setLod: a level node was destroyed")
+        if (nodes.indexOf(n) !== nodes.lastIndexOf(n)) throw new Error("setLod: a node is listed twice")
+        if (n.parent !== null && n.parent !== node) throw new Error("setLod: a level must be a direct child of the group (or parentless, to be adopted); add it first")
+      }
+      for (let n of nodes as SceneNode[]) if (n.parent !== node) add(node, n)
+    }
+    config = { levels: levels.map((l, k) => ({ node: nodes[k]!, size: l.size })), fade }
+  }
+  node._lod = config
+  if (node._scene !== null) node._scene._bindLod(node)
+}
+
+/** One level of an instanced LOD: what the population draws at this
+ * level, and the projected size (per INSTANCE) below which it hands
+ * over - see LodLevel. */
+export type InstancedLodLevel = { geometry: Geometry; material: Material; size: number }
+
+export type InstancedLodOptions = InstancedMeshOptions &
+  LodOptions & {
+    /** Every level draws into the scene's shadow map (setCastShadow on
+     * each); default false. */
+    castShadow?: boolean
+  }
+
+/**
+ * An instanced LOD: one population whose every instance draws at the
+ * level its OWN projected size picks - a forest as three draw entries
+ * (mesh, simplified mesh, card) whatever the spread, the near trees full
+ * and the far ones cards. Returns the first level's mesh, which is the
+ * population: addInstance / `<Instance>` on it, its instance nodes place
+ * and pick as on any InstancedMesh, and the other levels are its
+ * children at identity, each with a matrix buffer of its own the core
+ * stages an instance's record into (`_instances.levels`, nearest first;
+ * their per-level style streams take setInstanceStyle together). A pick
+ * or pointer event on an instance names that first mesh whatever level
+ * the instance is drawn at (the instance is the population's). Records
+ * are target-agnostic, so instances pick by the SCENE camera and every
+ * view and shadow tile draws that choice; instanced levels switch hard
+ * with hysteresis (`fade` is refused). Layers and castShadow set on the
+ * population reach every level.
+ */
+export function createInstancedLod(levels: InstancedLodLevel[], opts?: InstancedLodOptions): InstancedMesh {
+  if (levels.length === 0) throw new Error("createInstancedLod: at least one level")
+  let fade = checkSizes(levels, opts?.fade, "createInstancedLod")
+  if (fade !== 0) throw new Error("createInstancedLod: instanced levels switch hard (a per-instance fade would need a per-record value); drop fade")
+  let meshes = levels.map((l, k) =>
+    createInstancedMesh(l.geometry, l.material, { capacity: opts?.capacity, bounds: opts?.bounds, label: opts?.label !== undefined ? opts.label + "-lod" + k : undefined }),
+  )
+  let population = meshes[0]!
+  let shared = population._instances.nodes
+  for (let m of meshes) {
+    m._instances.nodes = shared
+    m._instances.levels = meshes
+  }
+  for (let m of meshes.slice(1)) add(population, m)
+  population._lod = { levels: levels.map(l => ({ node: null, size: l.size })), fade }
+  if (opts?.castShadow === true) setCastShadow(population, true)
+  return population
+}