@solidrt/3d 0.0.64 → 0.0.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.64",
+  "version": "0.0.66",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -19,8 +19,11 @@
     "examples/",
     "AGENTS.md"
   ],
+  "devDependencies": {
+    "@solidrt/test": "0.0.66"
+  },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.9",
-    "@solidrt/core": "0.0.64"
+    "@solidjs/signals": "2.0.0-rc.13",
+    "@solidrt/core": "0.0.66"
   }
 }

package/src/environment-bake.ts

@@ -1,10 +1,10 @@
-// Environment baking: the pure pipeline behind `srt tool 3d/environment`
+// Environment baking: the pure pipeline behind `sol tool 3d/environment`
 // and its tests. A Radiance .hdr panorama is decoded to linear float, laid
 // onto the six faces of a cube, convolved level by level with the GGX lobe
 // `standard`'s split sum samples (Karis's importance sampling, the source
 // lod picked from each sample's solid angle - the Filament and Unity
 // method; Godot and Three convolve the same way at runtime), and packed
-// into the .srte container loadEnvironment uploads as an explicit rgba16f
+// into the .sol3e container loadEnvironment uploads as an explicit rgba16f
 // chain. Runs under bun and on the runtime alike: no GPU, no flux imports.
 //
 // Cube faces hold what a GL lookup of a world direction returns (GL's own
@@ -428,15 +428,15 @@ export function prefilterCube(base: CubeFaces, size: number): CubeFaces[] {
   return levels
 }
 
-// The .srte container: "SRTE" u32 | version u32 | size u32 | levels u32,
+// The .sol3e container: "SOLE" u32 | version u32 | size u32 | levels u32,
 // then the faces as float32 rgba, level-major, face-major - the exact
 // buffers createCubeTexture's explicit chain takes, viewed in place.
-/** "SRTE" read as a little-endian u32. */
-const MAGIC = 0x45545253
+/** "SOLE" read as a little-endian u32. */
+const MAGIC = 0x454c4f53
 const VERSION = 1
 const HEADER_BYTES = 16
 
-/** Serialize a prefiltered chain (prefilterCube's result) into the .srte container. */
+/** Serialize a prefiltered chain (prefilterCube's result) into the .sol3e container. */
 export function encodeEnvironment(levels: CubeFaces[], size: number): Uint8Array {
   if (levels.length !== mipLevels(size)) {
     throw new Error("encodeEnvironment: a " + size + " chain has " + mipLevels(size) + " levels, got " + levels.length)
@@ -459,14 +459,14 @@ export function encodeEnvironment(levels: CubeFaces[], size: number): Uint8Array
   return out
 }
 
-/** Read a .srte container back into its size and chain, the faces viewing
+/** Read a .sol3e container back into its size and chain, the faces viewing
  * the bytes in place (copied only if the buffer is not float-aligned). */
 export function decodeEnvironment(bytes: Uint8Array): { size: number; levels: CubeFaces[] } {
   if (bytes.byteLength < HEADER_BYTES) throw new Error("decodeEnvironment: not an environment file (too short)")
   let view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
   if (view.getUint32(0, true) !== MAGIC) throw new Error("decodeEnvironment: not an environment file (bad magic)")
   let version = view.getUint32(4, true)
-  if (version !== VERSION) throw new Error("decodeEnvironment: version " + version + ", expected " + VERSION + " - re-bake with srt tool 3d/environment")
+  if (version !== VERSION) throw new Error("decodeEnvironment: version " + version + ", expected " + VERSION + " - re-bake with sol tool 3d/environment")
   let size = view.getUint32(8, true)
   let count = view.getUint32(12, true)
   if (size < 1 || count !== mipLevels(size)) throw new Error("decodeEnvironment: a " + size + " chain has " + mipLevels(size) + " levels, file says " + count)

package/src/environment.ts

@@ -1,5 +1,5 @@
-// Environment helpers: the baked HDR environment loader (the .srte chain
-// `srt tool 3d/environment` writes), the equirectangular-to-cube
+// Environment helpers: the baked HDR environment loader (the .sol3e chain
+// `sol tool 3d/environment` writes), the equirectangular-to-cube
 // conversion a fetched LDR panorama needs at runtime, the GPU prefilter
 // that turns a rendered cube (a reflection probe's, a baked sky's) into
 // the roughness chain, and the placeholder cube a scene binds as uEnv
@@ -28,8 +28,8 @@ import type { CreateOptions, DrawId, ProgramId, RenderPipelineId, SamplerOptions
 import { decodeEnvironment, levelRoughness, mipLevels } from "./environment-bake.ts"
 
 /**
- * Read a baked environment (`srt tool 3d/environment sky.hdr -o
- * assets/sky.srte`) and upload it: the HDR cube with its GGX-prefiltered
+ * Read a baked environment (`sol tool 3d/environment sky.hdr -o
+ * assets/sky.sol3e`) and upload it: the HDR cube with its GGX-prefiltered
  * mip chain, as an explicit "rgba16f" chain - no generated mipmaps, so it
  * works on every device. The id is what `environment={{ cube }}` and
  * `background={{ cube }}` take (Three's `scene.environment` from an
@@ -147,7 +147,7 @@ const EQUIRECT_FACE = glsl`
  * photographed sky uploaded as such, "rgba8" (default) for data,
  * "rgba16f" for an HDR panorama (the cube keeps the range; renderable on
  * every device with half-float rendering, else it throws - the prefiltered
- * form of that panorama is `srt tool 3d/environment` plus
+ * form of that panorama is `sol tool 3d/environment` plus
  * loadEnvironment). The panorama's center column faces -Z and its top
  * row is +Y. Leave its wrap at the default clamp: `repeat` would also
  * wrap vertically and bleed the poles across the top and bottom rows,
@@ -280,7 +280,7 @@ export function bufferFormat(): BufferFormat {
  * `source`, a `mipmap: true` cube of the same size and format (a cube
  * draw target rendered sharp), one pass per face per level - 48 small
  * passes at 128. Three's PMREMGenerator, Unity's and Godot's probe
- * convolution, on the same roughness-to-level rule as the .srte chain
+ * convolution, on the same roughness-to-level rule as the .sol3e chain
  * (levelRoughness), so `standard` reads both alike.
  */
 export function createPrefilter(size: number, source: TextureId, format: BufferFormat, label: string): Prefilter {

package/src/geometry.ts

@@ -37,7 +37,7 @@
 // format's codec.
 //
 // Pure module by design - geometry is data, and every function here is
-// array math (the check rig checks/geometry-check.ts runs it headless on
+// array math (tests/geometry.test.ts runs it headless on
 // flux). The GPU buffer step lives in geometry-gpu.ts.
 
 import type { Topology, VertexAttribute, VertexFormat } from "@solidrt/core/gpu"

package/src/glsl.ts

@@ -19,7 +19,7 @@
 import type { CullMode, VertexAttribute } from "@solidrt/core/gpu"
 
 // core/gpu's glsl tag, aliased locally (it is String.raw) so this module
-// stays runtime-pure: no flux:gpu import, so the checks/ rigs and any
+// stays runtime-pure: no flux:gpu import, so the tests and any
 // bake-time tool can run it headless on bare flux.
 let glsl = String.raw
 
@@ -815,7 +815,7 @@ export function resolveFragment(source: string = DEFAULT_RESOLVE): string {
  * roughness - 0 the sharp base level, 1 the level whose faces are
  * ENV_ROUGH_FACE (4) texels wide, linear between (Godot's
  * `roughness * MAX_ROUGHNESS_LOD`; Unity's six LOD steps; Three maps
- * onto a 16-texel floor): the level a baked chain (`srt tool
+ * onto a 16-texel floor): the level a baked chain (`sol tool
  * 3d/environment`, loadEnvironment) convolves at that roughness, and a
  * generated chain merely box-filters - scaled by the intensity: the
  * prefiltered radiance of the split sum (`standard` multiplies it by PBR's

package/src/gltf.ts

@@ -16,10 +16,13 @@
 // data: buffers and images, and single-file .glb.
 //
 // Pure module by design - a parse is JSON plus typed-array views plus one
-// interleave loop per primitive, so it runs the same under bun (the bake
-// tool in tools/model.ts, the check rig) and on flux (loadGltf in
+// interleave loop per primitive, so it runs the same under bun (an app's
+// bake script, the check rig) and on flux (loadGltf in
 // model.ts). It never decodes images: material.map indexes the encoded
-// bytes in `images`, and uploading is the engine side's job.
+// files in `images`, and uploading is the engine side's job. An image is
+// a PNG or JPEG, or a KTX2 compressed texture (KHR_texture_basisu, whose
+// source a texture prefers over its plain one), kept with what its
+// source calls it.
 //
 // Outside the subset: Draco/meshopt-compressed meshes and any other
 // required extension throw naming it; tangents (the base channel and
@@ -44,6 +47,8 @@
 // the way Three fills userData, so app data authored as custom
 // properties arrives with the model.
 
+import type { TextureKind } from "@solidrt/core/textures"
+
 import { compose, decompose, det3, mat4, multiply, quatNormalize } from "./math.ts"
 import { linearToSrgb } from "./color.ts"
 import type { Mat4, Quat, Vec3 } from "./math.ts"
@@ -229,8 +234,13 @@ export type ModelData = {
   /** The file's animations (empty when it has none). */
   clips: ModelClip[]
   materials: ModelMaterial[]
-  /** Encoded image files (PNG/JPEG bytes) the materials' `map` index. */
-  images: Uint8Array[]
+  /** The images the materials' maps index. */
+  images: ModelImage[]
+  /** The KTX2 images transcoded for this device, by image index (the
+   * others absent): what `transcodeModelImages` adds and `createModel`
+   * uploads in place of the file. Never in a file; a parse and
+   * `decodeModel` leave it out. */
+  textures?: (ModelTexture | undefined)[]
   /** World-space rest-pose [minX, minY, minZ, maxX, maxY, maxZ] over every
    * part - each part's local box through its node's composed transform, and
    * a skinned part's per-joint boxes through the joints' rest transforms
@@ -355,6 +365,68 @@ const DEFAULT_MATERIAL: ModelMaterial = {
 }
 
 /** True when the bytes are a .glb container (the "glTF" magic). */
+/** One image of a model: its file as it is, and what its source calls
+ * it. */
+export type ModelImage = {
+  /** The encoded image file: PNG, JPEG or KTX2 bytes. */
+  bytes: Uint8Array
+  /** Its name in the document; without one the uri of its file, and
+   * "image<i>" (its index in the document) for a nameless image embedded
+   * there. Labels its texture, and is how an image embedded in a model
+   * is told from the others (`solidrt.textures`). */
+  name: string
+  /** The file a parse read it from, as the document names it (still
+   * percent-encoded), when it is a file of its own. Absent for an image
+   * embedded in its document, and on everything read from the container,
+   * which embeds its images. */
+  uri?: string
+}
+
+/** How a model samples one of its images: what decides its color space
+ * at upload and how it is compressed at bake. */
+export type ModelImageUse = {
+  /** A material samples it as color (base color, emissive): its texels
+   * are sRGB-encoded, as glTF stores those. Every other map is linear. */
+  srgb: boolean
+  /** What its errors cost, which picks its codec at bake time (the kinds
+   * of `solidrt.textures`): "normal" when any material samples it as a
+   * normal map, else "color" when it is a color map, else "data". An
+   * image several slots share takes the most demanding of them, and
+   * stays sRGB if one of them is a color slot. */
+  kind: TextureKind
+}
+
+/**
+ * How the model's materials sample each of its images, by image index.
+ * The one rule behind createModel's uploads and the bake's encodes, so a
+ * baked image is sampled as the same image unbaked.
+ */
+export function modelImageUses(data: Pick<ModelData, "images" | "materials">): ModelImageUse[] {
+  let uses: ModelImageUse[] = data.images.map(() => ({ srgb: false, kind: "data" }))
+  let at = (index: number | null): ModelImageUse | undefined => (index === null ? undefined : uses[index])
+  for (let m of data.materials) {
+    for (let color of [at(m.map), at(m.emissiveMap)]) {
+      if (color === undefined) continue
+      color.srgb = true
+      if (color.kind === "data") color.kind = "color"
+    }
+    let normal = at(m.normalMap)
+    if (normal !== undefined) normal.kind = "normal"
+  }
+  return uses
+}
+
+/** A compressed texture ready to upload: the payload `createTexture`
+ * takes at `format`, with the full mip chain when `mipmap`. The shape
+ * `transcodeTexture` returns. */
+export type ModelTexture = {
+  data: Uint8Array
+  width: number
+  height: number
+  format: "etc2-rgba8" | "etc2-rgba8-srgb" | "bc7-rgba8" | "bc7-rgba8-srgb" | "rgba8" | "rgba8-srgb"
+  mipmap: boolean
+}
+
 export function isGlb(bytes: Uint8Array): boolean {
   return bytes.length >= 12 && new DataView(bytes.buffer, bytes.byteOffset, 12).getUint32(0, true) === GLB_MAGIC
 }
@@ -363,7 +435,7 @@ export function isGlb(bytes: Uint8Array): boolean {
 // samples, and so the only images the parser ever opens: the prefetch
 // list (gltfExternalUris) and the parser's demand set are both derived
 // from this one table, so a channel added to the map is added here too or
-// checks/gltf-check.ts fails on its all-channels fixture.
+// tests/gltf.test.ts fails on its all-channels fixture.
 const SAMPLED_TEXTURES: ((material: any) => any)[] = [
   (m) => m.pbrMetallicRoughness?.baseColorTexture,
   (m) => m.normalTexture,
@@ -371,14 +443,21 @@ const SAMPLED_TEXTURES: ((material: any) => any)[] = [
   (m) => m.pbrMetallicRoughness?.metallicRoughnessTexture,
 ]
 
+// The image a texture samples: the KTX2 one where the file carries it
+// (KHR_texture_basisu), ahead of the plain source a file may keep beside
+// it as a fallback for loaders without the extension.
+function textureSource(texture: any): number | undefined {
+  return texture?.extensions?.KHR_texture_basisu?.source ?? texture?.source
+}
+
 // The image indices a document's materials sample (SAMPLED_TEXTURES
-// through textures[].source), the demand set imageSlot will meet.
+// through textureSource), the demand set imageSlot will meet.
 function sampledImages(gltf: any): Set<number> {
   let images = new Set<number>()
   for (let m of gltf.materials ?? []) {
     for (let channel of SAMPLED_TEXTURES) {
       let ref = channel(m)
-      let source = ref === undefined ? undefined : gltf.textures?.[ref.index]?.source
+      let source = ref === undefined ? undefined : textureSource(gltf.textures?.[ref.index])
       if (source !== undefined) images.add(source)
     }
   }
@@ -429,9 +508,9 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     }
     // Quantized attributes read through the normalized-integer path,
     // emissive strength is the emissive intensity, GPU instancing is
-    // read as placements; every other required extension changes what
-    // the file means.
-    if (ext !== "KHR_mesh_quantization" && ext !== "KHR_materials_emissive_strength" && ext !== "EXT_mesh_gpu_instancing") {
+    // read as placements, a KTX2 image is an image like another; every
+    // other required extension changes what the file means.
+    if (ext !== "KHR_mesh_quantization" && ext !== "KHR_materials_emissive_strength" && ext !== "EXT_mesh_gpu_instancing" && ext !== "KHR_texture_basisu") {
       throw new Error("parseGltf: the file requires the " + ext + " extension, which is not supported")
     }
   }
@@ -462,7 +541,7 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
 
   // Images are pulled in only when a material samples them, in first-use
   // order, so `map` indexes a compact list.
-  let images: Uint8Array[] = []
+  let images: ModelImage[] = []
   let imageSlots = new Map<number, number>()
   let imageSlot = (index: number): number => {
     let slot = imageSlots.get(index)
@@ -470,8 +549,12 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       let image = gltf.images?.[index]
       if (image === undefined) throw new Error("parseGltf: texture names a missing image " + index)
       let bytes = image.uri !== undefined ? external(image.uri, "image " + index) : bufferViewBytes(image.bufferView)
+      // A data: uri is the image embedded in the document, not a file.
+      let file: string | undefined = image.uri !== undefined && !image.uri.startsWith("data:") ? image.uri : undefined
+      let entry: ModelImage = { bytes, name: image.name ?? file ?? "image" + index }
+      if (file !== undefined) entry.uri = file
       slot = images.length
-      images.push(bytes)
+      images.push(entry)
       imageSlots.set(index, slot)
     }
     return slot
@@ -484,8 +567,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
   // (the prefetch list): a new channel goes in the table first.
   let textureSlot = (ref: any): number | null => {
     if (ref === undefined) return null
-    let texture = gltf.textures?.[ref.index]
-    return texture?.source !== undefined ? imageSlot(texture.source) : null
+    let source = textureSource(gltf.textures?.[ref.index])
+    return source !== undefined ? imageSlot(source) : null
   }
   let materials: ModelMaterial[] = (gltf.materials ?? []).map((m: any, i: number): ModelMaterial => {
     let pbr = m.pbrMetallicRoughness ?? {}

package/src/index.ts

@@ -77,10 +77,10 @@ export type {
   ShotProps,
   ShotsProps,
 } from "./components/index.ts"
-export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
-export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
+export { gltfExternalUris, isGlb, modelImageUses, parseGltf } from "./gltf.ts"
+export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelImage, ModelImageUse, ModelMaterial, ModelNode, ModelPart, ModelSkin, ModelTexture, UriResolver } from "./gltf.ts"
 export { decodeModel, encodeModel } from "./model-file.ts"
-export { createModel, loadGltf, loadModel } from "./model.ts"
+export { createModel, loadGltf, loadModel, transcodeModelImages } from "./model.ts"
 export type { Model, ModelMaps, ModelOptions } from "./model.ts"
 export { decodeSplat, encodeSplat, parseSplat, SPLAT_ATTRIBUTES, SPLAT_RECORD_BYTES, SPLAT_RECORD_TEXELS, SPLAT_SH_TEXELS, SPLAT_TEXEL_BYTES } from "./splat-data.ts"
 export type { ParseSplatOptions, SplatData, SplatFormat } from "./splat-data.ts"

package/src/mixer.ts

@@ -44,7 +44,7 @@
 
 import * as spatial from "flux:spatial"
 import type { NodeId } from "flux:spatial"
-import { on } from "srt:events"
+import { on } from "sol:events"
 import type { ModelChannel, ModelClip } from "./gltf.ts"
 import { channelElements, sampleChannel } from "./clip.ts"
 import type { Vec3 } from "./math.ts"

package/src/model-data.ts

@@ -1,20 +1,22 @@
 // @solidrt/3d/model - the model DATA side of the package without the
-// runtime: the glTF parser, the .srtm container and the pure geometry kit,
+// runtime: the glTF parser, the .sol3m container and the pure geometry kit,
 // for a script that bakes an app's own geometry under bun (or any host
 // with no flux). The package root imports `flux:*` and so loads only on
-// the runtime; this entry imports nothing that does. tools/model.ts (the
-// glTF bake) runs on exactly this surface, so an app's bake script and
-// the tool share one path:
+// the runtime; this entry imports nothing that does. tools/model.flux.ts
+// (the glTF bake) takes its model side from exactly this surface, so an
+// app's bake script and the tool share one path:
 //
 //   import { box, encodeModel, transformGeometry } from "@solidrt/3d/model"
-//   writeFileSync("assets/terrain.srtm", encodeModel({ nodes, parts, ... }))
+//   writeFileSync("assets/terrain.sol3m", encodeModel({ nodes, parts, ... }))
 //
 // createModel / loadModel on the runtime read what it writes. Keep this
-// entry pure: tests/model-data.test.ts imports it under bun and fails the
-// moment a runtime import creeps into the chain.
+// entry pure. tests/model-data.test.ts imports it on the bare flux binary
+// and fails the moment a gui or sol: import creeps into the chain; a
+// headless flux: import it would not notice, and a bake script under bun
+// would.
 
-export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
-export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
+export { gltfExternalUris, isGlb, modelImageUses, parseGltf } from "./gltf.ts"
+export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelImage, ModelImageUse, ModelMaterial, ModelNode, ModelPart, ModelSkin, ModelTexture, UriResolver } from "./gltf.ts"
 export { decodeModel, encodeModel } from "./model-file.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"

package/src/model-file.ts

@@ -1,10 +1,12 @@
-// The baked model container (.srtm): ModelData as one file whose payload IS
+// The baked model container (.sol3m): 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.
+// no per-vertex work. Written by tools/model.flux.ts (from parseGltf),
+// read by loadModel on flux; both ends are this pure module. An image
+// block carries the image file as it is, a PNG, a JPEG or a KTX2, under
+// the image's name.
 //
 // Layout, all little-endian:
-//   "SRTM" u32 | version u32 | jsonLength u32 | json (padded to 4) | payload
+//   "SOLM" 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), app
@@ -16,19 +18,19 @@
 // flipped index order) share the vertex block - decodeModel restores the
 // same identities, so the runtime uploads shared bytes once.
 
-import type { ModelChannel, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelSkin } from "./gltf.ts"
+import type { ModelChannel, ModelData, ModelExtras, ModelImage, ModelMaterial, ModelNode, ModelSkin } from "./gltf.ts"
 import { layoutStride, vertexView, VERTEX_FORMATS } from "./geometry.ts"
 import type { VertexAttribute } from "@solidrt/core/gpu"
 import type { Geometry, VertexLayout } from "./geometry.ts"
 
-/** "SRTM" read as a little-endian u32. */
-const MAGIC = 0x4d545253
+/** "SOLM" read as a little-endian u32. */
+const MAGIC = 0x4d4c4f53
 // Version 3 retained the node hierarchy - a node table (name/parent/TRS)
 // in the header, parts referencing their node, vertices NODE-LOCAL
 // instead of world-baked - and carries skins (joints + inverse binds,
 // parts in the "skinned" layout) and animation clips (channel
 // times/values as payload blocks). Version-2 files world-baked and have
-// none of it, so they are rejected - re-bake with `srt tool 3d/model`.
+// none of it, so they are rejected - re-bake with `sol tool 3d/model`.
 // Version 4 adds the metalness/roughness fields to the material records
 // (metalness, roughness, metalnessRoughnessMap); a version-3 file lacks
 // them, so it is rejected the same way rather than read as all-metal.
@@ -37,7 +39,7 @@ const MAGIC = 0x4d545253
 // carry packed channels; a version-5 file's "vec3" words do not parse.
 // Version 7 changes the named "skinned" layout's joints from float32x4 to
 // uint8x4 (an integer shader input), so a version-6 skinned part would
-// decode at the wrong stride; it is rejected. Re-bake with `srt tool
+// decode at the wrong stride; it is rejected. Re-bake with `sol tool
 // 3d/model`.
 // Version 8 carries morph targets: a part's packed targets block (names,
 // the sparse-by-vertex texels, the extent - see packMorphTargets), the
@@ -53,8 +55,11 @@ const MAGIC = 0x4d545253
 // shared blocks, see the header). A version-9 file has none of these and is rejected like
 // every earlier version rather than read as a file without them, so a
 // stale bake never silently drops the data an app relies on. Re-bake
-// with `srt tool 3d/model`.
-const VERSION = 10
+// with `sol tool 3d/model`.
+// Version 11 names the images: an image record is its block and the
+// image's name (ModelImage.name), which labels its texture. A
+// version-10 file has blocks alone and is rejected the same way.
+const VERSION = 11
 
 // The named layouts the container writes by name; a custom attribute-list
 // layout (a skinned primitive with COLOR_0, a withAttribute channel) is
@@ -76,6 +81,10 @@ function decodeLayout(layout: string | VertexAttribute[], name: string): VertexL
 
 type Block = { offset: number; bytes: number }
 
+/** One image: the block holding its file, and its name. The uri a parse
+ * read it from is not written: the container embeds the image. */
+type ImageHeader = Block & { name: string }
+
 /** One geometry of the table: its interleaved vertex block, index block
  * and packed morph targets. Blocks may be shared between entries. */
 type GeometryHeader = {
@@ -116,7 +125,7 @@ type ClipHeader = { name: string; duration: number; channels: ChannelHeader[] }
 type Header = {
   nodes: ModelNode[]
   materials: ModelMaterial[]
-  images: Block[]
+  images: ImageHeader[]
   geometries: GeometryHeader[]
   parts: PartHeader[]
   skins: SkinHeader[]
@@ -129,7 +138,7 @@ type Header = {
   blobs?: Record<string, Block>
 }
 
-/** Serialize a model into the .srtm container. */
+/** Serialize a model into the .sol3m container. */
 export function encodeModel(data: ModelData): Uint8Array {
   let blocks: Uint8Array[] = []
   let offset = 0
@@ -190,7 +199,7 @@ export function encodeModel(data: ModelData): Uint8Array {
     if (part.extras !== undefined) header.extras = part.extras
     return header
   })
-  let images = data.images.map((image) => push(image))
+  let images: ImageHeader[] = data.images.map((image) => ({ ...push(image.bytes), name: image.name }))
   let floats = (f: Float32Array): Block => push(new Uint8Array(f.buffer, f.byteOffset, f.byteLength))
   let skins: SkinHeader[] = data.skins.map((skin) => ({ joints: skin.joints, inverseBind: floats(skin.inverseBind), jointBounds: floats(skin.jointBounds) }))
   let clips: ClipHeader[] = data.clips.map((clip) => ({
@@ -228,7 +237,7 @@ export function encodeModel(data: ModelData): Uint8Array {
 }
 
 /**
- * Read a .srtm container back into ModelData. The geometry arrays are
+ * Read a .sol3m 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.
  */
@@ -277,7 +286,7 @@ export function decodeModel(bytes: Uint8Array): ModelData {
     if (part.extras !== undefined) out.extras = part.extras
     return out
   })
-  let images = header.images.map((block) => new Uint8Array(buffer, payload + block.offset, block.bytes))
+  let images: ModelImage[] = header.images.map((image) => ({ bytes: new Uint8Array(buffer, payload + image.offset, image.bytes), name: image.name }))
   let floats = (block: Block): Float32Array => new Float32Array(buffer, payload + block.offset, block.bytes / 4)
   let skins: ModelSkin[] = header.skins.map((skin) => ({ joints: skin.joints, inverseBind: floats(skin.inverseBind), jointBounds: floats(skin.jointBounds) }))
   let clips = header.clips.map((clip) => ({

package/src/model.ts

@@ -1,4 +1,4 @@
-// Models in a scene: ModelData (parsed glTF or a decoded .srtm) becomes a
+// Models in a scene: ModelData (parsed glTF or a decoded .sol3m) becomes a
 // Group carrying the file's node hierarchy - nested Groups with the file's
 // local TRS, each part's mesh under its node - with the images uploaded as
 // textures and a material per glTF material: Three's `gltf.scene`, an
@@ -13,15 +13,17 @@
 // 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).
+// way (a binary import, a fetch). Compressed images (KTX2, what `sol tool
+// 3d/model` bakes) are turned into this device's block format by
+// transcodeModelImages, the one asynchronous step between the two.
 
 import { file } from "flux:fs"
 import * as spatial from "flux:spatial"
-import { decodeImage, getOwner, isDisposed, onCleanup, runWithOwner } from "@solidrt/core"
+import { decodeImage, getOwner, isDisposed, isKtx2, onCleanup, runWithOwner, transcodeTexture } from "@solidrt/core"
 import type { Owner } from "@solidrt/core"
 import { createMutableTexture, createTexture, destroyTexture } from "@solidrt/core/gpu"
 import type { TextureId } from "@solidrt/core/gpu"
-import { gltfExternalUris, parseGltf } from "./gltf.ts"
+import { gltfExternalUris, modelImageUses, parseGltf } from "./gltf.ts"
 import type { ModelClip, ModelData, ModelExtras, ModelMaterial } from "./gltf.ts"
 import { decodeModel } from "./model-file.ts"
 import { disposeGeometry } from "./geometry-gpu.ts"
@@ -144,6 +146,20 @@ export type ModelSkinNodes = {
   jointBounds: Float32Array
 }
 
+/**
+ * Transcode the model's compressed images (KTX2) into this device's block
+ * format, off the JS thread (all are started at once; the runtime runs a
+ * few at a time), and return the data with them as `textures`; the images that are PNG or JPEG are left for
+ * createModel to decode. The step between a parse (or decodeModel) and
+ * createModel for data that may hold KTX2 images; loadModel and loadGltf
+ * run it. Data with no KTX2 image comes back as it is.
+ */
+export async function transcodeModelImages(data: ModelData): Promise<ModelData> {
+  if (!data.images.some((image) => isKtx2(image.bytes))) return data
+  let textures = await Promise.all(data.images.map((image) => (isKtx2(image.bytes) ? transcodeTexture(image.bytes) : undefined)))
+  return { ...data, textures }
+}
+
 /**
  * Build the scene object for parsed model data: upload its images (repeat
  * wrap, mipmapped, MODEL_ANISOTROPY; the base color and emissive images
@@ -151,24 +167,26 @@ export type ModelSkinNodes = {
  * rgba8), make a material per glTF material, the file's node hierarchy as
  * nested Groups, and a mesh per part under its node. Synchronous - the
  * data is already in memory.
+ *
+ * A compressed image uploads as transcodeModelImages left it: at the
+ * format and color space its file names, with the mip chain the file
+ * carries (none can be generated for compressed storage). Data holding a
+ * KTX2 image that was not transcoded throws.
  */
 export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   let label = opts.label
-  let colorImages = new Set<number>()
-  for (let m of data.materials) {
-    if (m.map !== null) colorImages.add(m.map)
-    if (m.emissiveMap !== null) colorImages.add(m.emissiveMap)
-  }
-  let textures: TextureId[] = data.images.map((bytes, i) => {
-    let image = decodeImage(bytes)
-    return createTexture(image.data, image.width, image.height, {
-      format: colorImages.has(i) ? "rgba8-srgb" : "rgba8",
-      wrap: "repeat",
-      mipmap: true,
-      anisotropy: MODEL_ANISOTROPY,
-      autoFree: false,
-      label: label ? label + "-image" + i : undefined,
-    })
+  let uses = modelImageUses(data)
+  let textures: TextureId[] = data.images.map((image, i) => {
+    let sampling = { wrap: "repeat" as const, anisotropy: MODEL_ANISOTROPY, autoFree: false, label: label ? label + "-" + image.name : image.name }
+    let ready = data.textures?.[i]
+    if (ready !== undefined) {
+      return createTexture(ready.data, ready.width, ready.height, { ...sampling, format: ready.format, mipmap: ready.mipmap })
+    }
+    if (isKtx2(image.bytes)) {
+      throw new Error("createModel: image '" + image.name + "' is a KTX2 compressed texture, which is transcoded before the model is created: await transcodeModelImages(data) first (loadModel and loadGltf do)")
+    }
+    let decoded = decodeImage(image.bytes)
+    return createTexture(decoded.data, decoded.width, decoded.height, { ...sampling, format: uses[i]!.srgb ? "rgba8-srgb" : "rgba8", mipmap: true })
   })
   let make = opts.material ?? ((m: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean, instanced: boolean): Material => {
     // An emissive factor of zero is emission OFF (the glTF product rule:
@@ -421,7 +439,7 @@ function buildOwned(owner: Owner | null, opts: ModelOptions | undefined, build:
  * 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.
+ * `sol tool 3d/model` and use loadModel.
  */
 export async function loadGltf(path: string, opts?: ModelOptions): Promise<Model> {
   let owner = getOwner()
@@ -434,13 +452,15 @@ export async function loadGltf(path: string, opts?: ModelOptions): Promise<Model
   for (let uri of gltfExternalUris(bytes)) {
     if (!files.has(uri)) files.set(uri, await file(dir + decodeURIComponent(uri)).bytes())
   }
-  return buildOwned(owner, opts, () => createModel(parseGltf(bytes, (uri) => files.get(uri)!), opts))
+  let data = await transcodeModelImages(parseGltf(bytes, (uri) => files.get(uri)!))
+  return buildOwned(owner, opts, () => createModel(data, opts))
 }
 
-/** Read a baked .srtm model (`srt tool 3d/model`) and build it: no parsing,
+/** Read a baked .sol3m model (`sol 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> {
   let owner = getOwner()
   let bytes = await file(path).bytes()
-  return buildOwned(owner, opts, () => createModel(decodeModel(bytes), opts))
+  let data = await transcodeModelImages(decodeModel(bytes))
+  return buildOwned(owner, opts, () => createModel(data, opts))
 }