@woosh/meep-engine 2.169.3 → 2.169.6

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.169.3",
+  "version": "2.169.6",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/engine/ecs/terrain/ecs/layers/TerrainLayers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainLayers.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/terrain/ecs/layers/TerrainLayers.js"],"names":[],"mappings":"AA8EA;IAGQ;;;OAGG;IACH,QAFU,KAAK,YAAY,CAAC,CAEJ;IAExB;;;OAGG;IACH,YAFU,OAAO,CAEoD;IAMrE;;;OAGG;IACH,SAFU,kBAAkB,CAE8B;IAiB1D,2BAAsF;IAc1F;;;;;;MAKC;IAED;;;aAGC;IAED;;;;OAIG;IACH,gCAHW,MAAM,iBACN,MAAM,QAuChB;IAED;;;;OAIG;IACH,0DAyBC;IAED,sCAIC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACL,YAAY,CAIvB;IAED;;;;OAIG;IACH,8DAFa,MAAM,CAqBlB;IAED;;;;OAIG;IACH,kCAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;OAGG;IACH,SAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,gBAHW,YAAY,GACV,MAAM,CAWlB;IAED;;;;OAIG;IACH,mBAHW,YAAY,GACX,OAAO,CAIlB;IAED;;;;;;OAMG;IACH,0CAgCC;IAED;;;OAGG;IACH,iCAFW,MAAM,QAgChB;IAED,gBAGC;IAED,cAEC;IAGD,qBA4CC;CACJ;iBApagB,6CAA6C;6BAQjC,mBAAmB;oBAP5B,qCAAqC;mCALlD,OAAO;4BAAP,OAAO"}
+{"version":3,"file":"TerrainLayers.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/terrain/ecs/layers/TerrainLayers.js"],"names":[],"mappings":"AA0GA;IAGQ;;;OAGG;IACH,QAFU,KAAK,YAAY,CAAC,CAEJ;IAExB;;;OAGG;IACH,YAFU,OAAO,CAEoD;IAMrE;;;OAGG;IACH,SAFU,kBAAkB,CAE8B;IAuB1D,2BAAsF;IAc1F;;;;;;MAKC;IAED;;;aAGC;IAED;;;;OAIG;IACH,gCAHW,MAAM,iBACN,MAAM,QAuChB;IAED;;;;OAIG;IACH,0DAyBC;IAED,sCAIC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACL,YAAY,CAIvB;IAED;;;;OAIG;IACH,8DAFa,MAAM,CAqBlB;IAED;;;;OAIG;IACH,kCAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;OAGG;IACH,SAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,gBAHW,YAAY,GACV,MAAM,CAWlB;IAED;;;;OAIG;IACH,mBAHW,YAAY,GACX,OAAO,CAIlB;IAED;;;;;;OAMG;IACH,0CAqCC;IAED;;;OAGG;IACH,iCAFW,MAAM,QAgChB;IAED,gBAGC;IAED,cAEC;IAGD,qBA4CC;CACJ;iBA3cgB,6CAA6C;6BAajC,mBAAmB;oBAZ5B,qCAAqC;mCALlD,OAAO;4BAAP,OAAO"}

package/src/engine/ecs/terrain/ecs/layers/TerrainLayers.js

@@ -3,13 +3,13 @@ import {
     DataTexture,
     DataTexture2DArray,
     FloatType,
-    LinearEncoding,
     LinearFilter,
     LinearMipMapLinearFilter,
     NearestFilter,
     RepeatWrapping,
     RGBAFormat,
     RGFormat,
+    sRGBEncoding,
     UnsignedByteType
 } from "three";
 import { assert } from "../../../../../core/assert.js";
@@ -22,7 +22,12 @@ import { invokeObjectHash } from "../../../../../core/model/object/invokeObjectH
 import { computeStringHash } from "../../../../../core/primitives/strings/computeStringHash.js";
 import { sampler2d_scale } from "../../../../graphics/texture/sampler/resize/sampler2d_scale.js";
 import { Sampler2D } from "../../../../graphics/texture/sampler/Sampler2D.js";
-import { sampler2d_ensure_uint8_RGBA } from "../../../../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
+import {
+    sampler2d_linear_f16_to_srgb_u8
+} from "../../../../graphics/texture/sampler/sampler2d_linear_f16_to_srgb_u8.js";
+import {
+    sampler2d_srgb_u8_to_linear_f16
+} from "../../../../graphics/texture/sampler/sampler2d_srgb_u8_to_linear_f16.js";
 import { TerrainLayer } from "./TerrainLayer.js";
 
 class ScaledTextureKey {
@@ -74,6 +79,29 @@ const scaled_texture_cache = new Cache({
     }
 });
 
+/**
+ * Resample an sRGB uint8 RGBA layer sampler to the given size.
+ *
+ * Resize in linear light. Averaging sRGB-encoded bytes mixes in gamma space and
+ * comes out too dark, the same defect the shader used to have. Float16 is the
+ * intermediate so the round trip through linear costs no precision against the
+ * 8-bit source, at half the footprint of float32.
+ *
+ * @param {Sampler2D} sampler
+ * @param {number} width
+ * @param {number} height
+ * @returns {Sampler2D}
+ */
+function rescale_layer_sampler(sampler, width, height) {
+    const linear = sampler2d_srgb_u8_to_linear_f16(sampler);
+
+    const scaled_linear = Sampler2D.float16(4, width, height);
+
+    sampler2d_scale(linear, scaled_linear);
+
+    return sampler2d_linear_f16_to_srgb_u8(scaled_linear);
+}
+
 const DEFAULT_RESOLUTION = 512;
 
 export class TerrainLayers {
@@ -112,8 +140,14 @@ export class TerrainLayers {
         this.texture.minFilter = LinearMipMapLinearFilter;
 
         this.texture.generateMipmaps = true;
-        this.texture.encoding = LinearEncoding;
-        this.texture.internalFormat = 'RGBA8';
+
+        // Layer diffuse maps are authored in sRGB. Using an sRGB internal format makes the
+        // hardware decode each texel to linear BEFORE filtering, so bilinear/trilinear taps
+        // and the splat weight blend in TerrainShader all average in linear space.
+        // Consequence: the shader must NOT decode again.
+        this.texture.encoding = sRGBEncoding;
+        this.texture.internalFormat = 'SRGB8_ALPHA8';
+
         this.texture.needsUpdate = true;
 
         this.scalesTexture = new DataTexture(new Float32Array(64), 32, 1, RGFormat, FloatType);
@@ -321,27 +355,32 @@ export class TerrainLayers {
         if (layerSampler.width === resolution_x && layerSampler.height === resolution_y) {
             //layer's data matches texture dimensions, we can just copy the data directly
             return layer.diffuse;
-        } else {
+        }
 
-            // check cache
-            const key = ScaledTextureKey.from(layer.textureDiffuseURL, resolution);
-            const existing = scaled_texture_cache.get(key);
+        const uri = layer.textureDiffuseURL;
 
-            if (existing !== null) {
-                return existing;
-            }
+        // The cache identifies pixels by their source URL, which only works for layers that
+        // were actually loaded from one. A layer whose diffuse sampler is assigned
+        // programmatically keeps the default empty URL, and every such layer would collide on
+        // ("", resolution) and silently get the first one's pixels back. Those layers rescale
+        // on every call instead; nothing about the URL-backed path changes.
+        if (uri === "") {
+            return rescale_layer_sampler(layerSampler, resolution_x, resolution_y);
+        }
 
-            const scaledLayerSampler = Sampler2D.uint8(4, resolution_x, resolution_y);
+        // check cache
+        const key = ScaledTextureKey.from(uri, resolution);
+        const existing = scaled_texture_cache.get(key);
 
-            sampler2d_scale(layerSampler, scaledLayerSampler);
+        if (existing !== null) {
+            return existing;
+        }
 
-            // Ensure result is uint8 RGBA
-            const rgba = sampler2d_ensure_uint8_RGBA(scaledLayerSampler);
+        const rgba = rescale_layer_sampler(layerSampler, resolution_x, resolution_y);
 
-            scaled_texture_cache.put(key, rgba);
+        scaled_texture_cache.put(key, rgba);
 
-            return rgba;
-        }
+        return rgba;
     }
 
     /**

package/src/engine/graphics/geometry/instancing/InstancedMeshGroup.d.ts

@@ -192,7 +192,14 @@ export class InstancedMeshGroup {
 }
 export type CacheKey = {
     color: Material;
+    /**
+     * material for the depth shadow pass, used by directional and spot lights
+     */
     depth: Material;
+    /**
+     * material for the distance shadow pass, used by point lights
+     */
+    distance: Material;
 };
 import { BufferGeometry } from 'three';
 import { Mesh } from 'three';

package/src/engine/graphics/geometry/instancing/InstancedMeshGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InstancedMeshGroup.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/geometry/instancing/InstancedMeshGroup.js"],"names":[],"mappings":"AAyCA;IAqiBI;;;;;OAKG;IACH,sBAJW,oBAAoB,uBAElB,kBAAkB,CAS9B;IA5iBG;;;;OAIG;IACH,wBAA2B;IAE3B;;;;OAIG;IACH,gCAAmC;IAEnC;;;OAGG;IACH,cAAc;IAEd;;;OAGG;IACH,UAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,YAFU,MAAM,CAEK;IACrB;;;OAGG;IACH,cAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,cAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,gBAFU,MAAM,CAEQ;IAExB;;;;OAIG;IACH,6BAAgC;IAEhC;;;;OAIG;IACH,kCAAqC;IAGrC;;;;;OAKG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,8BAAiC;IAEjC;;;;OAIG;IACH,wBAAuC;IAEvC;;;;OAIG;IACH,mBAAsB;IAEtB,eAAiB;IACjB,kBAAoB;IAEpB;;;;OAIG;IACH,oBAAqC;IAErC,kFAAqC;IAErC,mBAAqB;IAGzB,qBA8BC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,+BAcC;IAED;;;OAGG;IACH,4BAEC;IAED,gBAIC;IAED;;;OAGG;IACH,sBAFW,oBAAoB,QAU9B;IA4CD;;;OAGG;IACH,4BAFW,MAAM,QAAQ,GAAC,MAAM,cAAc,QAS7C;IAED;;;OAGG;IACH,kBAFW,MAAM,QAWhB;IAED;;;OAGG;IACH,qBAFW,MAAM,QA6BhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,aACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,QAIjD;IAED;;;;OAIG;IACH,kBAHW,MAAM,SACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,QAIjD;IAED;;;;;;;OAOG;IACH,6BANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAWhB;IAED,+BAMC;IAED;;;;OAIG;IACH,qCAEC;IAED;;;OAGG;IACH,0BAKC;IAED;;;OAGG;IACH,YAFY,MAAM,MAAI,CAIrB;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,4DAH2C,IAAI,uBAiB9C;IAED;;;OAGG;IACH,6BAoDC;IAED,cAiEC;;CAgBJ;;;;;+BAllBM,OAAO;qBAAP,OAAO"}
+{"version":3,"file":"InstancedMeshGroup.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/geometry/instancing/InstancedMeshGroup.js"],"names":[],"mappings":"AA2CA;IA2jBI;;;;;OAKG;IACH,sBAJW,oBAAoB,uBAElB,kBAAkB,CAS9B;IAlkBG;;;;OAIG;IACH,wBAA2B;IAE3B;;;;OAIG;IACH,gCAAmC;IAEnC;;;OAGG;IACH,cAAc;IAEd;;;OAGG;IACH,UAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,YAFU,MAAM,CAEK;IACrB;;;OAGG;IACH,cAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,cAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,gBAFU,MAAM,CAEQ;IAExB;;;;OAIG;IACH,6BAAgC;IAEhC;;;;OAIG;IACH,kCAAqC;IAGrC;;;;;OAKG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,8BAAiC;IAEjC;;;;OAIG;IACH,wBAAuC;IAEvC;;;;OAIG;IACH,mBAAsB;IAEtB,eAAiB;IACjB,kBAAoB;IAEpB;;;;OAIG;IACH,oBAAqC;IAErC,kFAAqC;IAErC,mBAAqB;IAGzB,qBA+BC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,+BAcC;IAED;;;OAGG;IACH,4BAEC;IAED,gBAIC;IAED;;;OAGG;IACH,sBAFW,oBAAoB,QAU9B;IAgED;;;OAGG;IACH,4BAFW,MAAM,QAAQ,GAAC,MAAM,cAAc,QAU7C;IAED;;;OAGG;IACH,kBAFW,MAAM,QAWhB;IAED;;;OAGG;IACH,qBAFW,MAAM,QA6BhB;IAED;;;;OAIG;IACH,sBAHW,MAAM,aACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,QAIjD;IAED;;;;OAIG;IACH,kBAHW,MAAM,SACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,QAIjD;IAED;;;;;;;OAOG;IACH,6BANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAWhB;IAED,+BAMC;IAED;;;;OAIG;IACH,qCAEC;IAED;;;OAGG;IACH,0BAKC;IAED;;;OAGG;IACH,YAFY,MAAM,MAAI,CAIrB;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,4DAH2C,IAAI,uBAiB9C;IAED;;;OAGG;IACH,6BAoDC;IAED,cAiEC;;CAgBJ;;;;;;;;;;;;+BAzmBM,OAAO;qBAAP,OAAO"}

package/src/engine/graphics/geometry/instancing/InstancedMeshGroup.js

@@ -7,6 +7,7 @@ import {
     LineSegments,
     Mesh,
     MeshDepthMaterial,
+    MeshDistanceMaterial,
     RGBADepthPacking
 } from 'three';
 import { Cache } from "../../../../core/cache/Cache.js";
@@ -26,7 +27,8 @@ import { rewriteMaterial } from "./rewriteMaterial.js";
 /**
  * @typedef {Object} CacheKey
  * @property {Material} color
- * @property {Material} depth
+ * @property {Material} depth material for the depth shadow pass, used by directional and spot lights
+ * @property {Material} distance material for the distance shadow pass, used by point lights
  */
 
 /**
@@ -180,6 +182,7 @@ export class InstancedMeshGroup {
             new_object.receiveShadow = this.mesh.receiveShadow;
 
             new_object.customDepthMaterial = this.mesh.customDepthMaterial;
+            new_object.customDistanceMaterial = this.mesh.customDistanceMaterial;
         }
 
         this.mesh = new_object;
@@ -269,24 +272,44 @@ export class InstancedMeshGroup {
 
         material.onBeforeCompile = composeCompile(sourceMaterial.onBeforeCompile, rewriteMaterial);
 
-        //we need a custom depth material to ensure shadows will be drawn correctly
+        // We need custom shadow materials to ensure shadows will be drawn correctly.
+        //
+        // Instancing here is not three's own: the per-instance transform lives in an
+        // `instanceMatrix` attribute on our InstancedBufferGeometry and is applied by the
+        // `rewriteMaterial` shader patch, NOT by three's `USE_INSTANCING` (which keys off
+        // `Object3D.isInstancedMesh`, and this mesh is a plain Mesh). So every material
+        // this geometry is ever drawn with has to carry the patch, or that draw renders
+        // every instance at the local origin.
+        //
+        // There are two shadow passes and they take different materials: depth for
+        // directional and spot lights, distance for point lights (which compare world-space
+        // distance to the light rather than projected depth). Both are honoured by
+        // ThreeLightBinding, which prefers `customDepthMaterial`/`customDistanceMaterial`
+        // over its own unpatched fallbacks.
         const depthMaterial = new MeshDepthMaterial({
             depthPacking: RGBADepthPacking,
         });
 
-        //if the source material uses alpha testing - enable it on the depth material
+        const distanceMaterial = new MeshDistanceMaterial();
+
+        //if the source material uses alpha testing - enable it on the shadow materials
         if (material.alphaTest !== 0) {
             depthMaterial.alphaTest = material.alphaTest;
             depthMaterial.map = material.map;
+
+            distanceMaterial.alphaTest = material.alphaTest;
+            distanceMaterial.map = material.map;
         }
 
         depthMaterial.onBeforeCompile = rewriteMaterial;
+        distanceMaterial.onBeforeCompile = rewriteMaterial;
 
         const cachedMaterial = StaticMaterialCache.Global.acquire(material);
 
         return {
             color: cachedMaterial,
-            depth: StaticMaterialCache.Global.acquire(depthMaterial)
+            depth: StaticMaterialCache.Global.acquire(depthMaterial),
+            distance: StaticMaterialCache.Global.acquire(distanceMaterial)
         };
 
     }
@@ -302,6 +325,7 @@ export class InstancedMeshGroup {
 
         this.mesh.material = m.color;
         this.mesh.customDepthMaterial = m.depth;
+        this.mesh.customDistanceMaterial = m.distance;
     }
 
     /**

package/src/engine/graphics/shaders/TerrainShader.js

@@ -161,19 +161,6 @@ function fragment() {
     
     ${ShaderChunks.random}
     
-    vec4 blendSplatTextures(const in vec4 tex0, const in vec4 tex1, const in vec4 tex2, const in vec4 tex3, const in vec4 splat){
-    
-       float b0 = splat[0];
-       
-       float b1 = splat[1];
-       
-       float b2 = splat[2];
-       
-       float b3 = splat[3];
-       
-       return (tex0*b0 + tex1*b1 + tex2*b2 + tex3*b3) / (b0 + b1 + b2 + b3);
-    }
-   
     void randomBlend(in vec2 uv, inout vec3 v, float level){
        vec3 noise = vec3( rand(uv.x*12.9898 + uv.y*78.233), rand(uv.x*10.9898 + uv.y*73.233) , rand(uv.x*6.9898 + uv.y*71.233));
        v = v*(1.0 - level) + noise*level;
@@ -264,8 +251,10 @@ function fragment() {
         return tile_color * tile_data;
     }
     
+    // Returns linear-space colour: diffuseMaps uses an sRGB internal format, so texture()
+    // hands back already-decoded texels and the weighted average below is done in linear space.
     vec4 computeSplatMix(vec2 uv){
-        
+
         float weightSum = 0.0;
         vec4 colorSum = vec4(0.0);
         
@@ -291,11 +280,9 @@ function fragment() {
     out highp vec4 pc_fragColor;
     
     void main() { 
+        // already linear, the sampler decoded it
         vec4 splatDiffuseColor = computeSplatMix(vUv);
-                
-        //decode the texture
-        splatDiffuseColor = sRGBToLinear( splatDiffuseColor );
-        
+
         //ensure it is fully opaque
         splatDiffuseColor.a = 1.0;
         

package/src/engine/graphics/texture/sampler/sampler2d_linear_f16_to_srgb_u8.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Encodes a linear-light RGBA image back to 8-bit sRGB.
+ *
+ * Reverse of {@link sampler2d_srgb_u8_to_linear_f16}, and the last step of a linear-space
+ * resize. The conversion saturates: linear values outside [0,1] are clamped rather than
+ * wrapped, since the 8-bit output cannot represent them.
+ *
+ * The alpha channel is NOT transfer-encoded, it is merely scaled back to 0..255.
+ *
+ * @param {Sampler2D} input RGBA, linear light. Any numeric backing store, float16 in the resize path.
+ * @returns {Sampler2D} 8-bit RGBA, sRGB-encoded
+ * @throws {Error} if the input is not 4-channel
+ */
+export function sampler2d_linear_f16_to_srgb_u8(input: Sampler2D): Sampler2D;
+import { Sampler2D } from "./Sampler2D.js";
+//# sourceMappingURL=sampler2d_linear_f16_to_srgb_u8.d.ts.map

package/src/engine/graphics/texture/sampler/sampler2d_linear_f16_to_srgb_u8.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler2d_linear_f16_to_srgb_u8.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/sampler/sampler2d_linear_f16_to_srgb_u8.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;GAYG;AACH,uDAJW,SAAS,GACP,SAAS,CA8BrB;0BAnDyB,gBAAgB"}

package/src/engine/graphics/texture/sampler/sampler2d_linear_f16_to_srgb_u8.js

@@ -0,0 +1,54 @@
+import { convert_channel_linear_to_sRGB } from "../../../../core/color/sRGB/linear_to_sRGB.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { Sampler2D } from "./Sampler2D.js";
+
+/**
+ *
+ * @param {number} linear
+ * @returns {number} sRGB-encoded byte, 0..255
+ */
+function encode_channel(linear) {
+    return Math.round(clamp(convert_channel_linear_to_sRGB(linear), 0, 1) * 255);
+}
+
+/**
+ * Encodes a linear-light RGBA image back to 8-bit sRGB.
+ *
+ * Reverse of {@link sampler2d_srgb_u8_to_linear_f16}, and the last step of a linear-space
+ * resize. The conversion saturates: linear values outside [0,1] are clamped rather than
+ * wrapped, since the 8-bit output cannot represent them.
+ *
+ * The alpha channel is NOT transfer-encoded, it is merely scaled back to 0..255.
+ *
+ * @param {Sampler2D} input RGBA, linear light. Any numeric backing store, float16 in the resize path.
+ * @returns {Sampler2D} 8-bit RGBA, sRGB-encoded
+ * @throws {Error} if the input is not 4-channel
+ */
+export function sampler2d_linear_f16_to_srgb_u8(input) {
+    if (input.itemSize !== 4) {
+        throw new Error(`Input must have 4 channels exactly, instead got '${input.itemSize}'`);
+    }
+
+    const width = input.width;
+    const height = input.height;
+
+    const output = Sampler2D.uint8(4, width, height);
+
+    const source = input.data;
+    const destination = output.data;
+
+    const texel_count = width * height;
+
+    for (let i = 0; i < texel_count; i++) {
+        const address = i * 4;
+
+        destination[address] = encode_channel(source[address]);
+        destination[address + 1] = encode_channel(source[address + 1]);
+        destination[address + 2] = encode_channel(source[address + 2]);
+
+        // alpha carries no transfer function
+        destination[address + 3] = Math.round(clamp(source[address + 3], 0, 1) * 255);
+    }
+
+    return output;
+}

package/src/engine/graphics/texture/sampler/sampler2d_srgb_u8_to_linear_f16.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Decodes an 8-bit sRGB RGBA image into linear light, stored as float16.
+ *
+ * Intended as the first step of a resize: averaging sRGB-encoded values is wrong, because
+ * the encoding is non-linear, and the result comes out too dark. Decode first, resize in
+ * linear, then re-encode with {@link sampler2d_linear_f16_to_srgb_u8}.
+ *
+ * Float16 holds linear values in [0,1] with ~3 decimal digits of precision, which is finer
+ * than the 8-bit encoding it came from and half the footprint of float32. Note that V8 does
+ * not yet specialize Float16Array element access, so this is not a good fit for a per-frame
+ * hot loop — it is meant for load-time work whose result gets cached.
+ *
+ * The alpha channel is NOT transfer-encoded, matching how the GPU treats SRGB8_ALPHA8: only
+ * RGB goes through the curve, alpha is already linear and is merely normalized to [0,1].
+ *
+ * @param {Sampler2D} input 8-bit RGBA, sRGB-encoded
+ * @returns {Sampler2D} RGBA float16, linear light, values in [0,1]
+ * @throws {Error} if the input is not 4-channel, or is not 8-bit
+ */
+export function sampler2d_srgb_u8_to_linear_f16(input: Sampler2D): Sampler2D;
+import { Sampler2D } from "./Sampler2D.js";
+//# sourceMappingURL=sampler2d_srgb_u8_to_linear_f16.d.ts.map

package/src/engine/graphics/texture/sampler/sampler2d_srgb_u8_to_linear_f16.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler2d_srgb_u8_to_linear_f16.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/sampler/sampler2d_srgb_u8_to_linear_f16.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;GAkBG;AACH,uDAJW,SAAS,GACP,SAAS,CAqCrB;0BAlEyB,gBAAgB"}

package/src/engine/graphics/texture/sampler/sampler2d_srgb_u8_to_linear_f16.js

@@ -0,0 +1,68 @@
+import { convert_channel_sRGB_to_linear } from "../../../../core/color/sRGB/sRGB_to_linear.js";
+import { Sampler2D } from "./Sampler2D.js";
+
+/**
+ * Decoded linear value for every possible sRGB byte. The input domain is only 256 values
+ * wide, so the transfer function is evaluated once per value instead of once per channel.
+ * @type {Float32Array}
+ */
+const SRGB_BYTE_TO_LINEAR = new Float32Array(256);
+
+for (let i = 0; i < 256; i++) {
+    SRGB_BYTE_TO_LINEAR[i] = convert_channel_sRGB_to_linear(i / 255);
+}
+
+/**
+ * Decodes an 8-bit sRGB RGBA image into linear light, stored as float16.
+ *
+ * Intended as the first step of a resize: averaging sRGB-encoded values is wrong, because
+ * the encoding is non-linear, and the result comes out too dark. Decode first, resize in
+ * linear, then re-encode with {@link sampler2d_linear_f16_to_srgb_u8}.
+ *
+ * Float16 holds linear values in [0,1] with ~3 decimal digits of precision, which is finer
+ * than the 8-bit encoding it came from and half the footprint of float32. Note that V8 does
+ * not yet specialize Float16Array element access, so this is not a good fit for a per-frame
+ * hot loop — it is meant for load-time work whose result gets cached.
+ *
+ * The alpha channel is NOT transfer-encoded, matching how the GPU treats SRGB8_ALPHA8: only
+ * RGB goes through the curve, alpha is already linear and is merely normalized to [0,1].
+ *
+ * @param {Sampler2D} input 8-bit RGBA, sRGB-encoded
+ * @returns {Sampler2D} RGBA float16, linear light, values in [0,1]
+ * @throws {Error} if the input is not 4-channel, or is not 8-bit
+ */
+export function sampler2d_srgb_u8_to_linear_f16(input) {
+    if (input.itemSize !== 4) {
+        throw new Error(`Input must have 4 channels exactly, instead got '${input.itemSize}'`);
+    }
+
+    const source_constructor = input.data.constructor;
+
+    if (source_constructor !== Uint8Array && source_constructor !== Uint8ClampedArray) {
+        // the decode is a 256-entry lookup, a wider type would index past the end of it
+        throw new Error(`Input must be 8-bit, instead got '${source_constructor.name}'`);
+    }
+
+    const width = input.width;
+    const height = input.height;
+
+    const output = Sampler2D.float16(4, width, height);
+
+    const source = input.data;
+    const destination = output.data;
+
+    const texel_count = width * height;
+
+    for (let i = 0; i < texel_count; i++) {
+        const address = i * 4;
+
+        destination[address] = SRGB_BYTE_TO_LINEAR[source[address]];
+        destination[address + 1] = SRGB_BYTE_TO_LINEAR[source[address + 1]];
+        destination[address + 2] = SRGB_BYTE_TO_LINEAR[source[address + 2]];
+
+        // alpha carries no transfer function
+        destination[address + 3] = source[address + 3] / 255;
+    }
+
+    return output;
+}