@solidrt/3d 0.0.63 → 0.0.65

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
 
@@ -368,9 +368,12 @@ export const PBR = glsl`
  * unit vector TOWARD a directional light; a spot's axis toward the
  * light; unused for a point), `uLightPos[i]` (a spot's or point's world
  * position; unused for a directional), `uLightColor[i]` (rgb, intensity
- * folded in) and `uLightParams[i]` (cosInner, cosOuter, distance, decay
+ * folded in), `uLightParams[i]` (cosInner, cosOuter, distance, decay
  * - the cone cosines a spot fades between, the falloff cutoff and
- * exponent a spot or point attenuates by; unused for a directional).
+ * exponent a spot or point attenuates by; unused for a directional) and
+ * `uLightMask[i]` (the light's `layers` filter bitmask, all bits by
+ * default - lightVector skips a light whose mask misses the mesh's
+ * `uLayers`, see LIGHT_LOOKUP).
  * Compose it before LIGHT_LOOKUP; the stock lit program is the shape.
  */
 export const LIGHT_SLOTS = glsl`
@@ -380,6 +383,7 @@ export const LIGHT_SLOTS = glsl`
   uniform vec3 uLightPos[${MAX_LIGHTS}];
   uniform vec3 uLightColor[${MAX_LIGHTS}];
   uniform vec4 uLightParams[${MAX_LIGHTS}];
+  uniform int uLightMask[${MAX_LIGHTS}];
   const int LIGHT_DIRECTIONAL = 0;
   const int LIGHT_SPOT = 1;
   const int LIGHT_POINT = 2;
@@ -395,13 +399,24 @@ export const LIGHT_SLOTS = glsl`
  * spot's additionally faded across its cone from cosInner to cosOuter.
  * Zero means the light cannot reach the fragment - skip its shadow
  * lookup and its terms (the stock lit program does exactly that).
+ * The first test is the LAYER gate: a light whose `uLightMask[i]`
+ * misses the mesh's `uLayers` (the per-entry membership bitmask the
+ * scene seeds from `mesh.layers` and follows through setLayers) cannot
+ * reach it at all - Unity's cullingMask, Godot's light_cull_mask. Both
+ * operands are uniforms, so the branch is coherent per draw.
  */
 export const LIGHT_LOOKUP = glsl`
   // Floors the falloff divisors so a fragment at the light's own
   // position stays finite (Three's punctual-light rule).
   const float FALLOFF_MIN = 0.01;
 
+  uniform int uLayers;
+
   float lightVector(int i, vec3 worldPos, out vec3 l) {
+    if ((uLightMask[i] & uLayers) == 0) {
+      l = vec3(0.0);
+      return 0.0;
+    }
     if (uLightType[i] == LIGHT_DIRECTIONAL) {
       l = uLightDir[i];
       return 1.0;
@@ -523,6 +538,36 @@ export const SRGB = glsl`
   }
 `
 
+/**
+ * The buffer's blend space (SceneOptions.blendSpace): `uBlendSpace` is 0
+ * in a linear-light scene (the default; every scene writes it, since a
+ * shared program's uniform keeps the last drawn value across targets)
+ * and 1 in a display-space one, where the buffer holds sRGB-encoded
+ * display pixels and BLENDING runs on encoded values - what a capture
+ * trained against sRGB compositing expects. `vec3 blendSpaceOutput(vec3
+ * rgb, float alpha)` is the branch a buffer-writing fragment ends with:
+ * premultiplied linear in, and out either the same value (linear scene)
+ * or the un-premultiplied color clamped, encoded and re-premultiplied
+ * (display scene). Every stock fragment composes it through sceneOutput
+ * (and the skybox on its own); a CUSTOM fragment written for a
+ * display-space scene must end with it too, or its output blends in the
+ * wrong space. The encode carries its own name (not SRGB's
+ * linearToSrgb) so composing this set never collides with a fragment
+ * that also composes SRGB.
+ */
+export const BLEND_SPACE = glsl`
+  uniform float uBlendSpace;
+  vec3 blendSpaceEncode(vec3 c) {
+    c = clamp(c, 0.0, 1.0);
+    return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));
+  }
+  vec3 blendSpaceOutput(vec3 rgb, float alpha) {
+    if (uBlendSpace < 0.5) return rgb;
+    vec3 c = alpha > 0.0 ? rgb / alpha : rgb;
+    return blendSpaceEncode(c) * alpha;
+  }
+`
+
 /**
  * The LOD cross-fade: `uLodFade` is (threshold, side) - the scene writes
  * the band position of the level this entry draws (see createLod's
@@ -1079,7 +1124,8 @@ export type SceneSourceOptions = {
  *   vec4 sceneOutput(vec3 rgb, float alpha, vec3 position);
  *
  * `sceneLight` is light i seen from a world point: `dir` the unit vector
- * TOWARD it, `color` its rgb already attenuated (falloff, cone) and
+ * TOWARD it, `color` its rgb already attenuated (falloff, cone), layer
+ * masked (a light whose `layers` misses the mesh's, see LIGHT_LOOKUP) and
  * shadowed - zero when it cannot reach the fragment, and then no shadow
  * tap was spent. It is the accessor a custom light model loops over to
  * `uLightCount` (URP's GetAdditionalLight, Godot's light() inputs), and
@@ -1095,12 +1141,17 @@ export type SceneSourceOptions = {
  * stage carries the world position in.
  *
  * `sceneOutput` is the tail every library fragment ends with: fog over
- * the premultiplied color, clamped at zero, and that is the pixel the
- * scene buffer holds - LINEAR light, unclamped above (a sun disc of 40
- * stays 40 in a half-float buffer). Exposure, tone mapping and the sRGB
- * encode happen once per pixel in the target's resolve pass (RESOLVE),
- * never in a scene fragment: a fragment that writes fragColor directly
- * writes linear premultiplied light too.
+ * the premultiplied color, clamped at zero, then the blend-space branch
+ * (BLEND_SPACE), and that is the pixel the scene buffer holds. In a
+ * linear scene (the default) that is LINEAR light, unclamped above (a
+ * sun disc of 40 stays 40 in a half-float buffer), and exposure, tone
+ * mapping and the sRGB encode happen once per pixel in the target's
+ * resolve pass (RESOLVE), never in a scene fragment. In a display-space
+ * scene (SceneOptions.blendSpace) the tail encodes here instead, the
+ * buffer holds display pixels and there is no resolve. A fragment that
+ * writes fragColor directly follows the same contract: linear
+ * premultiplied light in a linear scene, blendSpaceOutput's result in a
+ * display-space one.
  *
  *   ${SCENE}
  *   void main() {
@@ -1125,6 +1176,7 @@ export function sceneSource(o: SceneSourceOptions = {}): string {
       lights
         ? `uniform vec3 uHemiSky;
     uniform vec3 uHemiGround;
+    uniform int uHemiMask;
     ${LIGHT_SLOTS}
     ${LIGHT_LOOKUP}`
         : ""
@@ -1147,10 +1199,11 @@ export function sceneSource(o: SceneSourceOptions = {}): string {
     ${env ? ENVIRONMENT : ""}
     ${fog ? FOG : ""}
     ${lights ? sceneShadeSource(receiveShadow, env) : ""}
+    ${BLEND_SPACE}
 
     vec4 sceneOutput(vec3 rgb, float alpha, vec3 position) {
       ${fog === "additive" ? "rgb = fogAdditive(rgb, position, uCamPos);" : fog ? "rgb = fog(rgb, alpha, position, uCamPos);" : ""}
-      return vec4(max(rgb, vec3(0.0)), alpha);
+      return vec4(blendSpaceOutput(max(rgb, vec3(0.0)), alpha), alpha);
     }
   `
 }
@@ -1160,8 +1213,9 @@ export const SCENE = sceneSource()
 
 // The light accessor and the two shade functions, over the sets
 // sceneSource composed before them. A light that cannot reach the point
-// is skipped whole (no shadow tap, no terms), the gate the stock lit
-// program always had.
+// - out of falloff, outside its cone, or layer-masked off the mesh - is
+// skipped whole (no shadow tap, no terms), the gate the stock lit
+// program always had. The hemisphere masks the same way (uHemiMask).
 function sceneShadeSource(receiveShadow: boolean, env: boolean): string {
   return glsl`
     struct SceneLight {
@@ -1180,7 +1234,7 @@ function sceneShadeSource(receiveShadow: boolean, env: boolean): string {
     vec3 shadeBlinn(Surface s, vec3 position) {
       vec3 n = s.normal;
       vec3 v = normalize(uCamPos - position);
-      vec3 light = hemisphere(n, uHemiSky, uHemiGround);
+      vec3 light = (uHemiMask & uLayers) != 0 ? hemisphere(n, uHemiSky, uHemiGround) : vec3(0.0);
       light += s.ambient;
       vec3 spec = vec3(0.0);
       for (int i = 0; i < ${MAX_LIGHTS}; i++) {
@@ -1201,7 +1255,7 @@ function sceneShadeSource(receiveShadow: boolean, env: boolean): string {
       vec3 v = normalize(uCamPos - position);
       vec3 diffuseColor = s.base.rgb * (1.0 - s.metalness);
       vec3 f0 = mix(vec3(DIELECTRIC_F0) * s.base.a, s.base.rgb, s.metalness);
-      vec3 light = hemisphere(n, uHemiSky, uHemiGround);
+      vec3 light = (uHemiMask & uLayers) != 0 ? hemisphere(n, uHemiSky, uHemiGround) : vec3(0.0);
       ${env ? "light += envIrradiance(n);" : ""}
       light += s.ambient;
       vec3 spec = vec3(0.0);

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

@@ -7,8 +7,8 @@
 
 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 { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, setCastShadow, setCulling, setDrawRange, setEnvironment, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, instanceAttribute, updateRecords, INSTANCE_FLOATS } from "./mesh.ts"
+export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceOrderOptions, 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"
@@ -31,7 +31,7 @@ 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 { 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 type { BlendSpace, 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 { bufferFormat, equirectToCube, loadEnvironment } from "./environment.ts"
@@ -49,7 +49,7 @@ export { extrude, lathe, pathFrames, polygon, sweep, tube } from "./sweep.ts"
 export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.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, Shot, Shots } from "./components/index.ts"
+export { DirectionalLight, FirstPersonCamera, Group, HemisphereLight, Instance, InstancedLod, InstancedMesh, Lod, Mesh, OrbitCamera, PerspectiveCamera, PointLight, RecordMesh, Scene, SplatMesh, SpotLight, Sprite, View3d, useScene, Shot, Shots } from "./components/index.ts"
 export type {
   CameraTarget,
   DirectionalLightProps,
@@ -69,6 +69,7 @@ export type {
   RecordMeshProps,
   ScenePointerProps,
   SceneProps,
+  SplatMeshProps,
   SpotLightProps,
   SpriteProps,
   TransformProps,
@@ -76,11 +77,15 @@ 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"
+export { createSplatMesh, loadSplat, splatMaterialClass, splatVertexSource, SPLAT_FRAGMENT, SPLAT_GROUP, SPLAT_ID_ATTRIBUTES } from "./splat.ts"
+export type { SplatMesh as SplatMeshNode, SplatMeshOptions } from "./splat.ts"
 export { bindSkeleton } from "./skeleton.ts"
 export type { BindSkeletonOptions } from "./skeleton.ts"
 export { createMixer } from "./mixer.ts"

package/src/light.ts

@@ -4,9 +4,14 @@
 
 import { MAX_CASCADES } from "./glsl.ts"
 import type { Vec3 } from "./math.ts"
+import { checkMask } from "./mesh.ts"
 import { makeNode } from "./node.ts"
 import type { SceneNode } from "./node.ts"
 
+// The default light layers mask: every bit set, so a light lights every
+// mesh unless told otherwise (the Unity and Godot default).
+const ALL_LAYERS = 0xffffffff
+
 /** The orthographic frustum a casting light renders its shadow map from,
  * in the light's own space (x right, y up, looking along its direction),
  * Three's DirectionalLightShadow camera. Everything outside it is lit. */
@@ -68,6 +73,10 @@ export type DirectionalLight = SceneNode & {
   /** Linear [r, g, b] 0..1. */
   color: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set): the light lights and
+   * shadows only the meshes whose `layers` intersect it - Unity's
+   * cullingMask, Godot's light_cull_mask. Write through setLight. */
+  layers: number
   /** Render a shadow map from this light (any directional light may;
    * each map is a full extra pass over the casting meshes); meshes with
    * `castShadow` draw into it, `lit` materials read it (unless
@@ -91,6 +100,9 @@ export type SpotLight = SceneNode & {
   /** Linear [r, g, b] 0..1. */
   color: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set; DirectionalLight.layers
+   * is the contract). */
+  layers: number
   /** Falloff cutoff in world units; the light is zero past it (0 = no
    * cutoff, Three's rule). */
   distance: number
@@ -146,6 +158,9 @@ export type PointLight = SceneNode & {
   /** Linear [r, g, b] 0..1. */
   color: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set; DirectionalLight.layers
+   * is the contract). */
+  layers: number
   /** Falloff cutoff in world units (0 = no cutoff). */
   distance: number
   /** Falloff exponent (default 2). */
@@ -169,6 +184,10 @@ export type HemisphereLight = SceneNode & {
   sky: Vec3
   ground: Vec3
   intensity: number
+  /** Layer filter bitmask (default all bits set; DirectionalLight.layers
+   * is the contract): a mesh outside it gets no hemisphere term (its own
+   * `Surface.ambient` still applies). */
+  layers: number
 }
 
 export type Light = DirectionalLight | SpotLight | PointLight | HemisphereLight
@@ -185,6 +204,9 @@ export type DirectionalLightOptions = {
   direction?: Vec3
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set (the light lights and
+   * shadows only meshes whose `layers` intersect it). */
+  layers?: number
   castShadow?: boolean
   /** Shadow-map options, merged key by key (setLight keeps unmentioned ones). */
   shadow?: ShadowOptions
@@ -193,6 +215,8 @@ export type SpotLightOptions = {
   direction?: Vec3
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set. */
+  layers?: number
   distance?: number
   angle?: number
   penumbra?: number
@@ -204,13 +228,21 @@ export type SpotLightOptions = {
 export type PointLightOptions = {
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set. */
+  layers?: number
   distance?: number
   decay?: number
   castShadow?: boolean
   /** Shadow-map options, merged key by key (setLight keeps unmentioned ones). */
   shadow?: SpotShadowOptions
 }
-export type HemisphereLightOptions = { sky?: Vec3; ground?: Vec3; intensity?: number }
+export type HemisphereLightOptions = {
+  sky?: Vec3
+  ground?: Vec3
+  intensity?: number
+  /** Layer filter bitmask, default all bits set. */
+  layers?: number
+}
 
 // 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
@@ -248,7 +280,14 @@ function mergeShadow(into: DirectionalLight["shadow"], update: ShadowOptions): v
   if (update.bias !== undefined) into.bias = update.bias
   if (update.normalBias !== undefined) into.normalBias = update.normalBias
   if (update.radius !== undefined) into.radius = checkRadius(update.radius)
-  if (update.camera !== undefined) Object.assign(into.camera, update.camera)
+  if (update.camera !== undefined) {
+    // Only the keys with a value: an undefined one is absent and keeps
+    // the extent, which the light projection reads as is.
+    for (let key of Object.keys(update.camera) as (keyof ShadowCamera)[]) {
+      let value = update.camera[key]
+      if (value !== undefined) into.camera[key] = value
+    }
+  }
   if (update.cascades !== undefined) {
     let n = update.cascades
     if (!Number.isInteger(n) || n < 1 || n > MAX_CASCADES) throw new Error("shadow.cascades must be an integer from 1 to " + MAX_CASCADES)
@@ -282,6 +321,7 @@ export function createDirectionalLight(opts: DirectionalLightOptions = {}): Dire
   light.direction = [...(opts.direction ?? [0, -1, 0])] as Vec3
   light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createDirectionalLight") : ALL_LAYERS
   light.castShadow = opts.castShadow === true
   light.shadow = { mapSize: 1024, bias: 0, normalBias: 0, radius: 1, camera: { left: -5, right: 5, top: 5, bottom: -5, near: 0.5, far: 500 }, cascades: 1, distance: null, splits: null }
   if (opts.shadow !== undefined) mergeShadow(light.shadow, opts.shadow)
@@ -295,6 +335,7 @@ export function createSpotLight(opts: SpotLightOptions = {}): SpotLight {
   light.direction = [...(opts.direction ?? [0, -1, 0])] as Vec3
   light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createSpotLight") : ALL_LAYERS
   light.distance = opts.distance ?? 0
   light.angle = opts.angle ?? 60
   light.penumbra = opts.penumbra ?? 0
@@ -321,6 +362,7 @@ export function createPointLight(opts: PointLightOptions = {}): PointLight {
   light.type = "point"
   light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createPointLight") : ALL_LAYERS
   light.distance = opts.distance ?? 0
   light.decay = opts.decay ?? 2
   light.castShadow = opts.castShadow === true
@@ -335,12 +377,13 @@ export function createHemisphereLight(opts: HemisphereLightOptions = {}): Hemisp
   light.sky = [...(opts.sky ?? [1, 1, 1])] as Vec3
   light.ground = [...(opts.ground ?? [0.2, 0.2, 0.2])] as Vec3
   light.intensity = opts.intensity ?? 1
+  light.layers = opts.layers !== undefined ? checkMask(opts.layers, "createHemisphereLight") : ALL_LAYERS
   return light
 }
 
 /** The write path for a light's own fields (color, intensity, direction,
- * the cone and falloff, or sky/ground); absent keys keep their value.
- * Its placement goes through setTransform like any node.
+ * layers, the cone and falloff, or sky/ground); absent keys keep their
+ * value. Its placement goes through setTransform like any node.
  * Frame-rate-safe. */
 export function setLight(light: DirectionalLight, update: DirectionalLightOptions): void
 export function setLight(light: SpotLight, update: SpotLightOptions): void
@@ -351,6 +394,15 @@ export function setLight(
   update: DirectionalLightOptions & SpotLightOptions & PointLightOptions & HemisphereLightOptions,
 ): void {
   if (update.intensity !== undefined) light.intensity = update.intensity
+  if (update.layers !== undefined) {
+    let mask = checkMask(update.layers, "setLight")
+    if (mask !== light.layers) {
+      light.layers = mask
+      // A casting light's shadow views re-filter their casters by the new
+      // mask (a re-attach, never a tile rebuild - the maps stay).
+      light._scene?._lightLayersChanged(light)
+    }
+  }
   if (light.type === "directional") {
     if (update.direction !== undefined) light.direction = [...update.direction] as Vec3
     if (update.color !== undefined) light.color = [...update.color] as Vec3

package/src/material.ts

@@ -52,6 +52,7 @@ import {
   phongFragment,
   litShadowFragment,
   litVertex,
+  BLEND_SPACE,
   SKIN_DECLS,
   SKIN_MATRIX,
   standardFragment,
@@ -140,6 +141,20 @@ export type Material = {
    * an entry under a fading LOD level switches hard at the band's
    * midpoint. */
   lodFade?: boolean
+  /** True when a stage declares `uLayers` (read from the source, like
+   * lodFade; every lit source composing LIGHT_LOOKUP does): the scene
+   * then seeds and follows the mesh's `layers` bitmask on entries drawn
+   * with this material, which is what lightVector masks lights against.
+   * Like the other declared-uniform flags, a source that declares
+   * uLayers without using it is rejected at add(). */
+  layered?: boolean
+  /** True when the fragment declares `uEnv` (read from the source, like
+   * layered; every source composing ENVIRONMENT does - `standard`
+   * always, `phong` with `reflectivity`): the scene then applies a
+   * mesh's own `environment` to entries drawn with this material. On a
+   * material without it the mesh's environment is a no-op, never an
+   * error - "no reflection" is already true. */
+  env?: boolean
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
@@ -1112,9 +1127,10 @@ export const SKYBOX_FRAGMENT = glsl`
   uniform samplerCube uSky;
   uniform float uSkyIntensity;
   uniform mat4 uSkyRotation;
+  ${BLEND_SPACE}
   void main() {
     vec3 dir = mat3(uSkyRotation) * normalize(vRay);
-    fragColor = vec4(max(texture(uSky, dir).rgb * uSkyIntensity, vec3(0.0)), 1.0);
+    fragColor = vec4(blendSpaceOutput(max(texture(uSky, dir).rgb * uSkyIntensity, vec3(0.0)), 1.0), 1.0);
   }
 `
 
@@ -1324,6 +1340,13 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   let morphed = /\buMorphs\b/.test(opts.vertex)
   // The LOD cross-fade is a fragment-stage discard (Material.lodFade).
   let lodFade = /\buLodFade\b/.test(opts.fragment)
+  // A source mentioning uLayers masks lights by the mesh's layers
+  // (Material.layered); either stage may light, so both are scanned.
+  let layered = /\buLayers\b/.test(opts.vertex) || /\buLayers\b/.test(opts.fragment)
+  // A source mentioning uEnv reflects the environment (Material.env; the
+  // \b keeps uEnvIntensity and friends from matching, but ENVIRONMENT
+  // always declares the sampler itself).
+  let env = /\buEnv\b/.test(opts.fragment)
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
   let cutout = opts.cutout === true
   let depth = opts.depth ?? true
@@ -1424,6 +1447,8 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         skinned,
         morphed,
         lodFade,
+        layered,
+        env,
         attributes,
         transparent,
         cutout,