@solidrt/3d 0.0.50 → 0.0.52

package/src/model-file.ts

@@ -0,0 +1,122 @@
+// The baked model container (.srtm): ModelData as one file whose payload IS
+// the GPU layout, so loading it is a header parse plus typed-array views -
+// no per-vertex work. Written by tools/model.ts under bun (from parseGltf),
+// read by loadModel on flux; both ends are this pure module.
+//
+// Layout, all little-endian:
+//   "SRTM" u32 | version u32 | jsonLength u32 | json (padded to 4) | payload
+// The JSON header describes each block's byte range into the payload; every
+// block starts 4-aligned so Float32Array/Uint32Array views sit on it
+// directly. Images travel as their encoded files (PNG/JPEG bytes).
+
+import type { ModelData, ModelMaterial } from "./gltf.ts"
+import { layoutKey, layoutStride, STANDARD_FLOATS } from "./geometry.ts"
+
+/** "SRTM" read as a little-endian u32. */
+const MAGIC = 0x4d545253
+const VERSION = 1
+
+type Block = { offset: number; bytes: number }
+
+type PartHeader = Block & {
+  name: string
+  material: number
+  layout: string
+  vertexCount: number
+  indexBits: 16 | 32
+  index: Block
+}
+
+type Header = {
+  materials: ModelMaterial[]
+  images: Block[]
+  parts: PartHeader[]
+  bounds: number[]
+}
+
+/** Serialize a model into the .srtm container. */
+export function encodeModel(data: ModelData): Uint8Array {
+  let blocks: Uint8Array[] = []
+  let offset = 0
+  let push = (bytes: Uint8Array): Block => {
+    let block = { offset, bytes: bytes.byteLength }
+    blocks.push(bytes)
+    offset += bytes.byteLength
+    let pad = (4 - (offset % 4)) % 4
+    if (pad) {
+      blocks.push(new Uint8Array(pad))
+      offset += pad
+    }
+    return block
+  }
+
+  let parts: PartHeader[] = data.parts.map((part) => {
+    let g = part.geometry
+    if (layoutStride(g.layout) !== STANDARD_FLOATS) {
+      throw new Error("encodeModel: part '" + part.name + "' has a " + layoutKey(g.layout) + " layout; only standard is written")
+    }
+    let vertices = push(new Uint8Array(g.vertices.buffer, g.vertices.byteOffset, g.vertices.byteLength))
+    let index = push(new Uint8Array(g.indices.buffer, g.indices.byteOffset, g.indices.byteLength))
+    return {
+      ...vertices,
+      name: part.name,
+      material: part.material,
+      layout: "standard",
+      vertexCount: g.vertices.length / STANDARD_FLOATS,
+      indexBits: g.indices instanceof Uint32Array ? 32 : 16,
+      index,
+    }
+  })
+  let images = data.images.map((image) => push(image))
+  let header: Header = { materials: data.materials, images, parts, bounds: Array.from(data.bounds) }
+
+  let json = new TextEncoder().encode(JSON.stringify(header))
+  let jsonPadded = json.byteLength + ((4 - (json.byteLength % 4)) % 4)
+  let out = new Uint8Array(12 + jsonPadded + offset)
+  let dv = new DataView(out.buffer)
+  dv.setUint32(0, MAGIC, true)
+  dv.setUint32(4, VERSION, true)
+  dv.setUint32(8, json.byteLength, true)
+  out.set(json, 12)
+  let at = 12 + jsonPadded
+  for (let block of blocks) {
+    out.set(block, at)
+    at += block.byteLength
+  }
+  return out
+}
+
+/**
+ * Read a .srtm container back into ModelData. The geometry arrays are
+ * VIEWS onto `bytes` (copied once only when the input is not 4-aligned),
+ * so the bytes must outlive the model.
+ */
+export function decodeModel(bytes: Uint8Array): ModelData {
+  if (bytes.byteOffset % 4 !== 0) bytes = new Uint8Array(bytes)
+  let buffer = bytes.buffer as ArrayBuffer
+  let base = bytes.byteOffset
+  if (bytes.byteLength < 12) throw new Error("decodeModel: not a model file (too short)")
+  let head = new DataView(buffer, base, 12)
+  if (head.getUint32(0, true) !== MAGIC) throw new Error("decodeModel: not a model file (bad magic)")
+  let version = head.getUint32(4, true)
+  if (version !== VERSION) throw new Error("decodeModel: version " + version + ", expected " + VERSION)
+  let jsonLength = head.getUint32(8, true)
+  let header: Header = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, base + 12, jsonLength)))
+  let payload = base + 12 + jsonLength + ((4 - (jsonLength % 4)) % 4)
+
+  let parts = header.parts.map((part) => {
+    if (part.layout !== "standard") throw new Error("decodeModel: part '" + part.name + "' has an unsupported layout " + part.layout)
+    let indexCount = part.index.bytes / (part.indexBits / 8)
+    return {
+      name: part.name,
+      material: part.material,
+      geometry: {
+        vertices: new Float32Array(buffer, payload + part.offset, part.vertexCount * STANDARD_FLOATS),
+        indices: part.indexBits === 32 ? new Uint32Array(buffer, payload + part.index.offset, indexCount) : new Uint16Array(buffer, payload + part.index.offset, indexCount),
+        label: part.name,
+      },
+    }
+  })
+  let images = header.images.map((block) => new Uint8Array(buffer, payload + block.offset, block.bytes))
+  return { parts, materials: header.materials, images, bounds: Float32Array.from(header.bounds) }
+}

package/src/model.ts

@@ -0,0 +1,105 @@
+// Models in a scene: ModelData (parsed glTF or a decoded .srtm) becomes a
+// Group of meshes, one per part, with the images uploaded as textures and
+// a material per glTF material - Three's `gltf.scene`, an object you add
+// to the scene and place with setTransform. The model owns what it
+// created (geometry buffers, textures): dispose() frees them and detaches
+// the group. loadGltf / loadModel are the read-then-create conveniences
+// over flux:fs; parseGltf / decodeModel + createModel are the primitives
+// under them, for bytes obtained any other way (a binary import, a fetch).
+
+import { file } from "flux:fs"
+import { decodeImage } from "@solidrt/core"
+import { createTexture, destroyTexture } from "@solidrt/core/gpu"
+import type { TextureId } from "@solidrt/core/gpu"
+import { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
+import type { ModelData, ModelMaterial } from "./gltf.ts"
+import { decodeModel } from "./model-file.ts"
+import { disposeGeometry } from "./geometry-gpu.ts"
+import { lit } from "./material.ts"
+import type { Material } from "./material.ts"
+import { add, createGroup, createMesh, remove } from "./scene.ts"
+import type { Mesh, SceneNode } from "./scene.ts"
+
+export type ModelOptions = {
+  /** The material for each glTF material (default: `lit` with its color,
+   * map and transparency). `map` is the uploaded base color texture, or
+   * null. Called once per material, shared by every part using it. */
+  material?: (material: ModelMaterial, map: TextureId | null) => Material
+  /** Debug name for the textures. */
+  label?: string
+}
+
+/** A model in the scene: a Group whose children are the parts' meshes. */
+export type Model = SceneNode & {
+  kind: "group"
+  /** The parts by name, in file order; each `mesh` is a child of the model. */
+  parts: { name: string; mesh: Mesh }[]
+  /** One per glTF material, in file order. */
+  materials: Material[]
+  /** Local [minX, minY, minZ, maxX, maxY, maxZ] over every part. */
+  bounds: Float32Array
+  /** Detach the model and free its geometry buffers and textures. */
+  dispose(): void
+}
+
+/**
+ * Build the scene object for parsed model data: upload its images (repeat
+ * wrap, mipmapped), make a material per glTF material, a mesh per part,
+ * all under one Group. Synchronous - the data is already in memory.
+ */
+export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
+  let label = opts.label
+  let textures: TextureId[] = data.images.map((bytes, i) => {
+    let image = decodeImage(bytes)
+    return createTexture(image.data, image.width, image.height, {
+      wrap: "repeat",
+      mipmap: true,
+      autoFree: false,
+      label: label ? label + "-image" + i : undefined,
+    })
+  })
+  let make = opts.material ?? ((m: ModelMaterial, map: TextureId | null): Material => lit({ color: m.color, map: map ?? undefined, transparent: m.transparent }))
+  let materials = data.materials.map((m) => make(m, m.map === null ? null : textures[m.map]!))
+
+  let model = createGroup() as Model
+  model.parts = data.parts.map((part) => {
+    let material = materials[part.material]
+    if (material === undefined) throw new Error("createModel: part '" + part.name + "' names a missing material " + part.material)
+    let mesh = createMesh(part.geometry, material)
+    add(model, mesh)
+    return { name: part.name, mesh }
+  })
+  model.materials = materials
+  model.bounds = data.bounds
+  model.dispose = () => {
+    if (model.parent !== null) remove(model)
+    for (let part of model.parts) disposeGeometry(part.mesh.geometry)
+    for (let id of textures) destroyTexture(id)
+    textures.length = 0
+  }
+  return model
+}
+
+/**
+ * Read a .glb or .gltf (with its external .bin and image files, resolved
+ * next to it) and build the model. The parse runs on the runtime - fine
+ * for models of tens of thousands of vertices; bake bigger ones with
+ * `srt tool 3d/model` and use loadModel.
+ */
+export async function loadGltf(path: string, opts?: ModelOptions): Promise<Model> {
+  let bytes = await file(path).bytes()
+  let files = new Map<string, Uint8Array>()
+  if (!isGlb(bytes)) {
+    let dir = path.slice(0, path.lastIndexOf("/") + 1)
+    for (let uri of gltfExternalUris(bytes)) {
+      if (!files.has(uri)) files.set(uri, await file(dir + decodeURIComponent(uri)).bytes())
+    }
+  }
+  return createModel(parseGltf(bytes, (uri) => files.get(uri)!), opts)
+}
+
+/** Read a baked .srtm model (`srt tool 3d/model`) and build it: no parsing,
+ * the geometry views the file's bytes directly. */
+export async function loadModel(path: string, opts?: ModelOptions): Promise<Model> {
+  return createModel(decodeModel(await file(path).bytes()), opts)
+}

package/src/orbit.ts

@@ -22,7 +22,7 @@
 // about that point instead - the spot under the fingers stays under the
 // fingers, with the target sliding toward it. Only the app can own that
 // mapping: screen-to-ray needs the projection and the element's placement
-// (fov, aspect, viewBox scaling), which live in the app's camera and layout,
+// (fov, aspect, designSize scaling), which live in the app's camera and layout,
 // not here.
 //
 // Anchored zoom leaves the target wherever the zoom carried it - possibly a
@@ -48,7 +48,7 @@
 import { createSignal } from "@solidjs/signals"
 import { createTransform } from "@solidrt/core"
 import type { PointerEvent } from "@solidrt/core"
-import type { Scene } from "./scene.ts"
+import type { CameraUpdate } from "./scene.ts"
 import type { Vec3 } from "./math.ts"
 
 // Baseline sensitivities at rotateSpeed/zoomSpeed 1, in radians per dragged
@@ -57,6 +57,9 @@ const DRAG_AZIMUTH = 0.008
 const DRAG_ELEVATION = 0.006
 const WHEEL_ZOOM = 0.0015
 
+/** What an orbit camera drives: a Scene, or one of its Views. */
+export type OrbitTarget = { setCamera(update: CameraUpdate): void }
+
 export type OrbitCameraOptions = {
   /** The point the camera orbits and looks at (default origin). */
   target?: Vec3
@@ -123,7 +126,7 @@ export type OrbitCamera = {
   /** Whether the auto-orbit is running. Reactive (signal-backed), so HUD
    * text can read it. */
   orbiting(): boolean
-  /** Advance the auto-orbit and push any pose change to the scene camera.
+  /** Advance the auto-orbit and push any pose change to the driven camera.
    * Call from onFrame with the frame's dt in seconds; returns whether the
    * pose changed. */
   update(dt: number): boolean
@@ -142,12 +145,13 @@ export type OrbitCamera = {
 let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
 
 /**
- * Create an orbit camera driving `scene`'s camera position and target (fov,
- * near, and far stay yours via scene.setCamera). The initial pose applies
- * immediately. In a component tree, reach the scene via `<Scene ref>` or
- * useScene() and hand the handlers to whichever element owns input.
+ * Create an orbit camera driving `camera`'s position and target, where
+ * `camera` is a Scene or one of its Views (fov, near, and far stay yours via
+ * its setCamera). The initial pose applies immediately. In a component tree,
+ * reach the scene via `<Scene ref>` or useScene() (a view via `<View ref>`)
+ * and hand the handlers to whichever element owns input.
  */
-export function createOrbitCamera(scene: Scene, options: OrbitCameraOptions = {}): OrbitCamera {
+export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptions = {}): OrbitCamera {
   let target: Vec3 = options.target ? [options.target[0], options.target[1], options.target[2]] : [0, 0, 0]
   let azimuth = options.azimuth ?? 0
   let elevation = options.elevation ?? 0
@@ -197,7 +201,7 @@ export function createOrbitCamera(scene: Scene, options: OrbitCameraOptions = {}
       target[2] + distance * ce * Math.cos(azimuth),
     ]
   }
-  let apply = () => scene.setCamera({ position: eye(), target })
+  let apply = () => camera.setCamera({ position: eye(), target })
 
   // Zoom by `ratio` (new distance over old, before clamping) about a world
   // anchor (null zooms toward the target). Scaling eye and target about the

package/src/order.ts

@@ -22,13 +22,20 @@ export type Orderable<T> = {
  * 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.
+ * resting on it. Per-mesh only: no per-triangle sort, no OIT. `entry`
+ * picks the id ordered for each mesh (default its own `_entry`; a view
+ * passes its per-mesh entries in its target).
  */
-export function orderEntries<T>(meshes: readonly Orderable<T>[], view: Mat4, first?: T): T[] {
+export function orderEntries<T>(
+  meshes: readonly Orderable<T>[],
+  view: Mat4,
+  first?: T,
+  entry: (m: Orderable<T>) => T | null = m => m._entry,
+): T[] {
   let opaque: Orderable<T>[] = []
   let transparent: Orderable<T>[] = []
   for (let m of meshes) {
-    if (m._entry === null) continue
+    if (entry(m) === null) continue
     ;(m._transparent ? transparent : opaque).push(m)
   }
   // Array sort is stable, so equal keys keep add order.
@@ -45,7 +52,7 @@ export function orderEntries<T>(meshes: readonly Orderable<T>[], view: Mat4, fir
   }
   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!)
+  for (let m of opaque) order.push(entry(m)!)
+  for (let m of transparent) order.push(entry(m)!)
   return order
 }

package/src/profile.ts

@@ -8,8 +8,8 @@
 // for custom flat work. The swept-solid generators consuming this
 // vocabulary - extrude, lathe, sweep, tube - live in sweep.ts.
 
-import { packIndices } from "./geometry.ts"
-import type { Geometry } from "./geometry.ts"
+import { packGeometry } from "./geometry.ts"
+import type { Geometry, GeometryOptions } from "./geometry.ts"
 import type { Vec2 } from "./math.ts"
 
 /** A profile point: `p` in profile space, `smooth` to share an averaged
@@ -298,7 +298,7 @@ export function roundRect(
  * profile's bounding box to the unit square like plane(); rotate flat the
  * same way: `rotation={[-Math.PI / 2, 0, 0]}`.
  */
-export function shape(profile: Profile, label?: string): Geometry {
+export function shape(profile: Profile, options: GeometryOptions = {}): Geometry {
   let pts = normalizeProfile(profile)
   let { minX, maxY, w, h } = profileBounds(pts)
   let px = pts.map((p) => p.x)
@@ -307,9 +307,5 @@ export function shape(profile: Profile, label?: string): Geometry {
   for (let p of pts) {
     verts.push(p.x, p.y, 0, 0, 0, 1, (p.x - minX) / w, (maxY - p.y) / h)
   }
-  return {
-    vertices: new Float32Array(verts),
-    indices: packIndices(earClip(px, py), pts.length),
-    label,
-  }
+  return packGeometry(verts, earClip(px, py), options)
 }