Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Build level 1 of a mip chain from the level 0 reconstruction and decode the taps of every stored level before the blend (#896)

Nguyen Xuan An81dde4687cf1
diff --git a/bench/cycles-parity/texture-mips-bench.mjs b/bench/cycles-parity/texture-mips-bench.mjs
index 35938aca..9b141b32 100644
--- a/bench/cycles-parity/texture-mips-bench.mjs
+++ b/bench/cycles-parity/texture-mips-bench.mjs
@@ -10,6 +10,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
import { join, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { buildNativeInputV2, traceNative } from '../../packages/render-native/index.mjs';
+import { TEXTURE_KIND_RGBA8_SRGB, buildMipChain, mipLevelCount, mipLevelSize } from '../../packages/render-native/texture-mips.mjs';
import { createCamera } from '../../src/path-tracer.js';
export const CHECKER_SIDE = 64;
@@ -45,12 +46,12 @@ function floorGeometry() {
}
/** Traces the checker floor and returns linear rgb floats (width * height * 3, rows from the top). */
-export function renderFloor({ cameraName, textureMips, samples, seed, width, height }) {
+export function renderFloor({ cameraName, textureMips, samples, seed, width, height, image = checkerImage() }) {
const camera = createCamera(CAMERAS[cameraName], width, height);
const options = { width, height, samples, seed, bounces: 2, textureMips, backgroundColor: SKY_RADIANCE };
const input = buildNativeInputV2(
{
- materials: [{ color: [1, 1, 1], roughness: 1, metallic: 0, map: { image: checkerImage(), colorSpace: 'srgb' } }],
+ materials: [{ color: [1, 1, 1], roughness: 1, metallic: 0, map: { image, colorSpace: 'srgb' } }],
instances: [{ geometry: floorGeometry(), materialIndex: 0 }],
lights: {},
},
@@ -76,6 +77,35 @@ export function relativeMeanSquaredError(image, reference, width, height, firstR
return squaredDifference / squaredReference;
}
+const FAR_ROW_COUNT = 12;
+
+/** The mean value over the first `FAR_ROW_COUNT` rows from `firstRow` down, the rows nearest the horizon. */
+export function farRowMean(image, width, firstRow) {
+ let total = 0;
+ const start = firstRow * width * 3;
+ const end = (firstRow + FAR_ROW_COUNT) * width * 3;
+ for (let index = start; index < end; index++) {
+ total += image[index];
+ }
+ return total / (end - start);
+}
+
+/** The checker of one mip level as a standalone image: reading it at level 0 forces that level for the whole picture. */
+export function levelImages() {
+ const base = checkerImage();
+ const words = new Uint32Array(base.data.buffer, 0, CHECKER_SIDE * CHECKER_SIDE);
+ const chain = buildMipChain(TEXTURE_KIND_RGBA8_SRGB, words, CHECKER_SIDE, CHECKER_SIDE);
+ const images = [base];
+ let cursor = 0;
+ for (let level = 1; level < mipLevelCount(CHECKER_SIDE, CHECKER_SIDE); level++) {
+ const size = mipLevelSize(CHECKER_SIDE, CHECKER_SIDE, level);
+ const levelWords = chain.slice(cursor, cursor + size.width * size.height);
+ images.push({ width: size.width, height: size.height, data: new Uint8Array(levelWords.buffer, 0, levelWords.length * 4) });
+ cursor += levelWords.length;
+ }
+ return images;
+}
+
export function maxAbsoluteDifference(first, second) {
let largest = 0;
for (let index = 0; index < first.length; index++) {
@@ -111,16 +141,19 @@ async function runCameraSweep(settings, cameraName, metrics) {
const firstRow = cameraName === 'receding' ? Math.floor(height / 2) + 2 : 0;
const reference = renderFloor({ cameraName, textureMips: false, samples: referenceSamples, seed: 4242, width, height });
await writePicture(outputDirectory, `${cameraName}-reference`, reference);
- metrics[cameraName] = { referenceSamples, firstRow, runs: [] };
+ metrics[cameraName] = { referenceSamples, firstRow, farRowMeanReference: farRowMean(reference, width, firstRow), runs: [] };
for (const samples of SAMPLE_COUNTS) {
const errors = { off: [], on: [] };
let largestDifference = 0;
+ const farMeans = { off: 0, on: 0 };
for (let seed = 1; seed <= seedCount; seed++) {
const off = renderFloor({ cameraName, textureMips: false, samples, seed, width, height });
const on = renderFloor({ cameraName, textureMips: true, samples, seed, width, height });
errors.off.push(relativeMeanSquaredError(off, reference, width, height, firstRow));
errors.on.push(relativeMeanSquaredError(on, reference, width, height, firstRow));
largestDifference = Math.max(largestDifference, maxAbsoluteDifference(off, on));
+ farMeans.off += farRowMean(off, width, firstRow) / seedCount;
+ farMeans.on += farRowMean(on, width, firstRow) / seedCount;
if (seed === 1) {
await writePicture(outputDirectory, `${cameraName}-off-${samples}spp`, off);
await writePicture(outputDirectory, `${cameraName}-on-${samples}spp`, on);
@@ -135,6 +168,15 @@ async function runCameraSweep(settings, cameraName, metrics) {
relMseOffPerSeed: errors.off,
relMseOnPerSeed: errors.on,
largestPixelDifferenceOnVsOff: largestDifference,
+ farRowMeanOff: farMeans.off,
+ farRowMeanOn: farMeans.on,
+ });
+ }
+ if (cameraName === 'receding') {
+ // Each level alone, read at level 0 of its own texture: which step of the chain moves the far rows.
+ metrics.forcedLevels = levelImages().map((image, level) => {
+ const picture = renderFloor({ cameraName, textureMips: false, samples: 64, seed: 1, width, height, image });
+ return { level, side: image.width, farRowMean: farRowMean(picture, width, firstRow), relMse: relativeMeanSquaredError(picture, reference, width, height, firstRow) };
});
}
}
diff --git a/bench/cycles-parity/texture-mips-run-all.sh b/bench/cycles-parity/texture-mips-run-all.sh
index 2b9980a2..a94abc2d 100644
--- a/bench/cycles-parity/texture-mips-run-all.sh
+++ b/bench/cycles-parity/texture-mips-run-all.sh
@@ -27,7 +27,8 @@ run_step() {
prepare_baseline_checkout() {
rm -rf "$baseline_checkout"
git -C "$candidate_checkout" worktree prune
- git -C "$candidate_checkout" worktree add --detach "$baseline_checkout" HEAD \
+ local base_commit="${BASELINE_REF:-$(git -C "$candidate_checkout" merge-base HEAD origin/main 2>/dev/null || echo 27ea525b)}"
+ git -C "$candidate_checkout" worktree add --detach "$baseline_checkout" "$base_commit" \
&& ln -s "$candidate_checkout/node_modules" "$baseline_checkout/node_modules"
}
diff --git a/packages/render-native/FORMAT-v2.md b/packages/render-native/FORMAT-v2.md
index 3b4a9e8e..280c5967 100644
--- a/packages/render-native/FORMAT-v2.md
+++ b/packages/render-native/FORMAT-v2.md
@@ -359,9 +359,9 @@ Total stride: **32 bytes** (`2 × 16 B`), alignment: **16 bytes**.
One sampler reads every descriptor: `texture_sample` in `src/cycles/closure.wgsl`. Shading, bump, normal maps and the alpha tests of the integrator (the opacity of a cutout or blended surface, for camera, bounce and shadow rays) all go through it, so a surface is seen and shaded with the same wrap, filter and format. Wrap `0` repeats, `1` clamps and `2` mirrors in float UV space before the texel lookup; `nearest` picks the texel the wrapped UV falls in, otherwise the four neighbours are blended. `texture_texels` is one storage binding, so the pool of all textures (each texture padded to 16 bytes) must fit the device's storage binding size, at most 1 GiB. `buildNativeInputV2` refuses a pool past 1 GiB and the host refuses one past the device's binding size, each with an error that names the size and the limit. The struct sizes above do not change.
-**Mip levels (opt in).** Level `0` is the texture as given. When the mip count is above `1`, the levels follow level `0` in the same run of words, with no padding between them: level `k` has `max(1, width >> k)` by `max(1, height >> k)` texels, each level stored as level `0` is (`1` word per texel for `RGBA8_*` and `RG16_FLOAT`, `4` for `RGBA32_FLOAT`), and the whole run is padded to 16 bytes once. The kernel finds level `k` by walking from `data_offset` (`texture_level_descriptor`). The packer builds the chain with a 2 x 2 box filter (`texture-mips.mjs`): a 2 x 2 block averaged per channel, the bytes of an 8-bit map rounded, the floats of a float map as they are, alpha averaged like any channel (not weighted), an odd last row or column read twice. An sRGB map is averaged in linear light (decoded, averaged, encoded back to bytes); every other format is averaged on its stored values.
+**Mip levels (opt in).** Level `0` is the texture as given. When the mip count is above `1`, the levels follow level `0` in the same run of words, with no padding between them: level `k` has `max(1, width >> k)` by `max(1, height >> k)` texels, each level stored as level `0` is (`1` word per texel for `RGBA8_*` and `RG16_FLOAT`, `4` for `RGBA32_FLOAT`), and the whole run is padded to 16 bytes once. The kernel finds level `k` by walking from `data_offset` (`texture_level_descriptor`). The packer builds the chain in `texture-mips.mjs`. Level `1` is the integral of the level `0` reconstruction: each level `1` texel supersamples its footprint with 4 x 4 positions (respecting the wrap mode of the texture), at each position reads level `0` exactly as the kernel does (bilinear on the stored values, texel centres at `+0.5`, then the sRGB decode) and averages in linear light; an sRGB map is encoded back to bytes, float maps keep their floats unclamped, alpha is averaged on its stored value like any channel (not weighted). Levels `2` and up are a 2 x 2 box average of the level before, in linear light for an sRGB map and on the stored values for every other format (an odd last row or column is read twice).
-A texture stores levels only when `textureMips: true` is passed to the packer (or `mips: true` on that texture; `mips: false` overrides the option). The default is level `0` only, which is what Blender Cycles reads. A nearest-filtered texture or one of a single texel never stores levels. The dedupe key holds the mip count, so one image packed with and without levels is two descriptors. With `kernel_flags` bit `2048` set, the integrator keeps a ray cone per path (width at the ray origin, spread), and a hit passes the sampler the width of the ray footprint in UV units; the sampler turns it into `log2` of the footprint in texels (the larger of the two axes after `uv_scale`), reads level `0` while that is not above `0`, otherwise blends the two levels around it (trilinear, each level bilinear on the stored values, the blend decoded after, the order of level `0`) and stops at the last level. The alpha tests of the integrator and the bump taps always read level `0`.
+A texture stores levels only when `textureMips: true` is passed to the packer (or `mips: true` on that texture; `mips: false` overrides the option). The default is level `0` only, which is what Blender Cycles reads. A nearest-filtered texture or one of a single texel never stores levels. The dedupe key holds the mip count, so one image packed with and without levels is two descriptors. With `kernel_flags` bit `2048` set, the integrator keeps a ray cone per path (width at the ray origin, spread), and a hit passes the sampler the width of the ray footprint in UV units; the sampler turns it into `log2` of the footprint in texels (the larger of the two axes after `uv_scale`), reads level `0` while that is not above `0`, otherwise blends the two levels around it (trilinear) and stops at the last level. Level `0` is filtered on its stored values and decoded after, the order of #1030 (Blender Cycles); a level `1` and up holds the mean light of a footprint, so the kernel decodes each of its four taps before the bilinear blend, and the two levels of the trilinear blend in linear light. Blending two stored sRGB values and decoding the result would darken what the level holds. The alpha tests of the integrator and the bump taps always read level `0`.
---
diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjs
index f0d4cf67..b06b943b 100644
--- a/packages/render-native/pack-input-v2.mjs
+++ b/packages/render-native/pack-input-v2.mjs
@@ -454,7 +454,7 @@ function createTextureCollector({ textureMips } = {}) {
const levelZeroTexels = format === TEXTURE_FORMAT_RGBA32_FLOAT
? new Float32Array(packedWords.buffer, packedWords.byteOffset, levelZeroWordCount)
: levelZeroWords;
- packedWords = joinMipLevels(levelZeroWords, buildMipChain(mipKindOfFormat(format), levelZeroTexels, width, height));
+ packedWords = joinMipLevels(levelZeroWords, buildMipChain(mipKindOfFormat(format), levelZeroTexels, width, height, repeatU & 0x3, repeatV & 0x3));
anyTextureHasMips = true;
}
@@ -494,7 +494,7 @@ function createTextureCollector({ textureMips } = {}) {
padded.set(words.subarray(0, pixelCount));
if (mipCount > 1) {
const levelZeroWords = padded.slice(0, pixelCount);
- padded = joinMipLevels(levelZeroWords, buildMipChain(atlasKind, levelZeroWords, width, height));
+ padded = joinMipLevels(levelZeroWords, buildMipChain(atlasKind, levelZeroWords, width, height, repeat ? 0 : 1, repeat ? 0 : 1));
anyTextureHasMips = true;
}
let sumR = 0;
diff --git a/packages/render-native/src/cycles/closure.wgsl b/packages/render-native/src/cycles/closure.wgsl
index 8e29cb82..347e4988 100644
--- a/packages/render-native/src/cycles/closure.wgsl
+++ b/packages/render-native/src/cycles/closure.wgsl
@@ -120,7 +120,10 @@ fn texture_level_descriptor(desc: TextureDescriptor, level: u32, format: u32) ->
return level_desc;
}
-// Bilinear filter of one mip level on the stored values. The caller decodes the result (see texture_decode_filtered).
+// Bilinear filter of one mip level, returned decoded. Level 0 keeps the order of #1030: blend the stored values, decode the blend.
+// A level after it holds the mean, in linear light, of the level 0 reconstruction over its texel (texture-mips.mjs), so its
+// stored values are blended after the decode of each tap: a blend of two stored sRGB values decodes darker than the light they
+// hold, and nearly every read of a minified map is such a blend.
fn texture_filter_level(
desc: TextureDescriptor,
level: u32,
@@ -147,11 +150,18 @@ fn texture_filter_level(
let level_c10 = texture_fetch_texel(level_desc, level_ix1, level_iy0, format);
let level_c01 = texture_fetch_texel(level_desc, level_ix0, level_iy1, format);
let level_c11 = texture_fetch_texel(level_desc, level_ix1, level_iy1, format);
- return mix(mix(level_c00, level_c10, level_tx), mix(level_c01, level_c11, level_tx), level_ty);
+ if (level == 0u) {
+ return texture_decode_filtered(mix(mix(level_c00, level_c10, level_tx), mix(level_c01, level_c11, level_tx), level_ty), format);
+ }
+ let decoded_c00 = texture_decode_filtered(level_c00, format);
+ let decoded_c10 = texture_decode_filtered(level_c10, format);
+ let decoded_c01 = texture_decode_filtered(level_c01, format);
+ let decoded_c11 = texture_decode_filtered(level_c11, format);
+ return mix(mix(decoded_c00, decoded_c10, level_tx), mix(decoded_c01, decoded_c11, level_tx), level_ty);
}
-// Trilinear read for a footprint larger than a texel: the two levels around `level_of_detail` are each filtered on their stored
-// values, blended, and only then decoded, so an sRGB map keeps the order of the level 0 path.
+// Trilinear read for a footprint larger than a texel: the two levels around `level_of_detail` are each filtered and decoded
+// (see texture_filter_level) and blended in linear light.
fn texture_filter_trilinear(
desc: TextureDescriptor,
mip_count: u32,
@@ -168,10 +178,10 @@ fn texture_filter_trilinear(
let blend = clamped_detail - f32(lower_level);
let lower = texture_filter_level(desc, lower_level, format, wrap_u, wrap_v, u_wrapped, v_wrapped);
if (upper_level == lower_level) {
- return texture_decode_filtered(lower, format);
+ return lower;
}
let upper = texture_filter_level(desc, upper_level, format, wrap_u, wrap_v, u_wrapped, v_wrapped);
- return texture_decode_filtered(mix(lower, upper, blend), format);
+ return mix(lower, upper, blend);
}
// The one texture sampler of the kernel: shading (closure_sample_texture), bump, and the alpha tests of the integrator all
diff --git a/packages/render-native/src/cycles/mod.rs b/packages/render-native/src/cycles/mod.rs
index 59193847..9186551f 100644
--- a/packages/render-native/src/cycles/mod.rs
+++ b/packages/render-native/src/cycles/mod.rs
@@ -1172,10 +1172,21 @@ mod tests {
assert!(walk.contains("level_desc.width * level_desc.height * words_per_texel"));
assert!(walk.contains("max(level_desc.width >> 1u, 1u)"));
assert!(walk.contains("max(level_desc.height >> 1u, 1u)"));
- assert!(kernel.contains("return texture_decode_filtered(mix(lower, upper, blend), format);"));
+ assert!(kernel.contains("return mix(lower, upper, blend);"), "two decoded levels blend in linear light");
let level_start = kernel.find("fn texture_filter_level(").expect("the level filter exists");
let level_end = level_start + kernel[level_start..].find("\n}").expect("the level filter ends");
- assert!(!kernel[level_start..level_end].contains("texture_decode_filtered"), "a mip level is blended on stored values and decoded after, as level 0 is");
+ let level_filter = &kernel[level_start..level_end];
+ let level_zero_branch = level_filter.find("if (level == 0u) {").expect("level 0 has its own branch");
+ let first_decode = level_filter.find("let decoded_c00").expect("later levels decode their taps");
+ let level_zero_return = "return texture_decode_filtered(mix(mix(level_c00, level_c10, level_tx), mix(level_c01, level_c11, level_tx), level_ty), format);";
+ let return_position = level_filter.find(level_zero_return).expect("level 0 stays filter then decode (#1030)");
+ assert!(level_zero_branch < return_position && return_position < first_decode);
+ for tap in ["c00", "c10", "c01", "c11"] {
+ assert!(
+ level_filter.contains(&format!("let decoded_{tap} = texture_decode_filtered(level_{tap}, format);")),
+ "a level after 0 decodes tap {tap} before the blend"
+ );
+ }
}
#[test]
diff --git a/packages/render-native/texture-mips.mjs b/packages/render-native/texture-mips.mjs
index f8c5b6d5..237ba31d 100644
--- a/packages/render-native/texture-mips.mjs
+++ b/packages/render-native/texture-mips.mjs
@@ -1,14 +1,15 @@
// Mip chains for the texture pool of FORMAT-v2 (issue 896). Pure functions on typed arrays, no GPU.
//
// Level 0 is the texture as the caller gave it. Each level after it is half as wide and as high, rounded down and never less
-// than one texel, and is the plain average of the 2 x 2 texels of the level before it. A linear 8-bit map and a float map are
-// averaged on their stored values. An sRGB map is averaged in linear light and encoded back to bytes: the kernel still filters
-// its bytes and decodes the blend, as at level 0, but a level that held the mean of the stored bytes would read darker than
-// the mean of the light (a black and white checker: 0.21 against 0.5 once decoded), and a minified surface would turn
-// darker than the same surface supersampled. The alpha channel is averaged on its stored values and not weighted by itself, so a texel with alpha 0 pulls its
-// colour into the next level; a map whose alpha is a cutout should not ask for levels. Where a side has an odd length, the
-// last row or column has no pair: it is averaged with itself in the next level's last texel, and the one beyond the halved
-// size is not read. Normal maps are averaged as stored and are not normalised again; the kernel normalises the result.
+// than one texel. Level 1 is the integral of what the kernel reads at level 0: each level 1 texel is the mean, in linear light,
+// of the level 0 reconstruction (bilinear on the stored values with texel centres at +0.5, then the sRGB decode of an sRGB map)
+// over its footprint, taken at 4 x 4 positions with the wrap mode of the texture. A plain 2 x 2 box of decoded texels is not that
+// mean: the bilinear blend of two stored values decodes darker than the two decoded values, so a box would read too bright
+// against the level 0 picture of a high contrast map. Levels 2 and up are the 2 x 2 box of the level before: in linear light for
+// an sRGB map (decoded, averaged, encoded back to bytes), on the stored values otherwise; an odd last row or column is read
+// twice. The alpha channel is averaged on its stored values, not weighted by itself, so a texel with alpha 0 pulls its colour
+// into the next level; a map whose alpha is a cutout should not ask for levels. Normal maps are averaged as stored and are not
+// normalised again; the kernel normalises the result.
export const TEXTURE_KIND_RGBA8 = 'rgba8';
export const TEXTURE_KIND_RGBA8_SRGB = 'rgba8-srgb';
@@ -90,6 +91,24 @@ function wordsPerTexel(kind) {
return kind === TEXTURE_KIND_RGBA32_FLOAT ? 4 : 1;
}
+const SRGB_DECODE_TABLE_SIZE = 4096;
+const SRGB_DECODE_TABLE = (() => {
+ const table = new Float64Array(SRGB_DECODE_TABLE_SIZE + 1);
+ for (let index = 0; index <= SRGB_DECODE_TABLE_SIZE; index++) {
+ const encoded = index / SRGB_DECODE_TABLE_SIZE;
+ table[index] = encoded <= 0.04045 ? encoded / 12.92 : ((encoded + 0.055) / 1.055) ** 2.4;
+ }
+ return table;
+})();
+
+// The sRGB decode of a stored value in [0, 1], from a 4096 entry table with linear interpolation.
+function decodeStoredSrgb(stored) {
+ const position = Math.min(1, Math.max(0, stored)) * SRGB_DECODE_TABLE_SIZE;
+ const lower = Math.min(Math.floor(position), SRGB_DECODE_TABLE_SIZE - 1);
+ const blend = position - lower;
+ return SRGB_DECODE_TABLE[lower] * (1 - blend) + SRGB_DECODE_TABLE[lower + 1] * blend;
+}
+
/** The 32-bit words the levels after level 0 take, with no padding between levels. */
export function mipChainWordCount(kind, width, height) {
const levelCount = mipLevelCount(width, height);
@@ -189,12 +208,103 @@ function averageHalfPairLevel(source, destination, sourceWidth, sourceHeight, de
});
}
+const FIRST_LEVEL_POSITIONS_PER_AXIS = 4;
+
+// The kernel wrap of a texel index (texture_wrap_texel_index): repeat wraps, clamp and mirror clamp.
+function wrapTexelIndex(index, size, wrapMode) {
+ if (wrapMode === 0) {
+ const remainder = index % size;
+ return remainder < 0 ? remainder + size : remainder;
+ }
+ return Math.min(Math.max(index, 0), size - 1);
+}
+
+// Reads the stored value of one texel as four numbers in [0, 1] (floats as they are; a two-channel texture reads b = 0, a = 1).
+function createStoredTexelReader(kind, source) {
+ if (kind === TEXTURE_KIND_RGBA32_FLOAT) {
+ return (index, target) => {
+ for (let channel = 0; channel < 4; channel++) target[channel] = source[index * 4 + channel];
+ };
+ }
+ if (kind === TEXTURE_KIND_RG16_FLOAT) {
+ return (index, target) => {
+ target[0] = halfToFloat(source[index] & 0xffff);
+ target[1] = halfToFloat(source[index] >>> 16);
+ target[2] = 0;
+ target[3] = 1;
+ };
+ }
+ return (index, target) => {
+ const word = source[index];
+ for (let channel = 0; channel < 4; channel++) target[channel] = ((word >>> (channel * 8)) & 0xff) / 255;
+ };
+}
+
+function encodeFirstLevelTexel(kind, mean, destination, index) {
+ if (kind === TEXTURE_KIND_RGBA32_FLOAT) {
+ for (let channel = 0; channel < 4; channel++) destination[index * 4 + channel] = mean[channel];
+ return;
+ }
+ if (kind === TEXTURE_KIND_RG16_FLOAT) {
+ destination[index] = (floatToHalf(mean[0]) | (floatToHalf(mean[1]) << 16)) >>> 0;
+ return;
+ }
+ let packed = 0;
+ for (let channel = 0; channel < 4; channel++) {
+ const isLinearLightChannel = kind === TEXTURE_KIND_RGBA8_SRGB && channel < 3;
+ const byteValue = isLinearLightChannel ? linearToSrgbByte(mean[channel]) : Math.round(Math.min(1, Math.max(0, mean[channel])) * 255);
+ packed |= byteValue << (channel * 8);
+ }
+ destination[index] = packed >>> 0;
+}
+
+function integrateFirstLevel(kind, source, sourceSize, destination, destinationSize, wrapU, wrapV) {
+ const read = createStoredTexelReader(kind, source);
+ const corners = [new Float64Array(4), new Float64Array(4), new Float64Array(4), new Float64Array(4)];
+ const sampleColor = new Float64Array(4);
+ const sum = new Float64Array(4);
+ const decodesSrgb = kind === TEXTURE_KIND_RGBA8_SRGB;
+ const positions = FIRST_LEVEL_POSITIONS_PER_AXIS;
+ for (let row = 0; row < destinationSize.height; row++) {
+ for (let column = 0; column < destinationSize.width; column++) {
+ sum.fill(0);
+ for (let subRow = 0; subRow < positions; subRow++) {
+ const coordinateY = (row + (subRow + 0.5) / positions) / destinationSize.height * sourceSize.height - 0.5;
+ const baseY = Math.floor(coordinateY);
+ const blendY = coordinateY - baseY;
+ const rowTop = wrapTexelIndex(baseY, sourceSize.height, wrapV) * sourceSize.width;
+ const rowBottom = wrapTexelIndex(baseY + 1, sourceSize.height, wrapV) * sourceSize.width;
+ for (let subColumn = 0; subColumn < positions; subColumn++) {
+ const coordinateX = (column + (subColumn + 0.5) / positions) / destinationSize.width * sourceSize.width - 0.5;
+ const baseX = Math.floor(coordinateX);
+ const blendX = coordinateX - baseX;
+ const left = wrapTexelIndex(baseX, sourceSize.width, wrapU);
+ const right = wrapTexelIndex(baseX + 1, sourceSize.width, wrapU);
+ read(rowTop + left, corners[0]);
+ read(rowTop + right, corners[1]);
+ read(rowBottom + left, corners[2]);
+ read(rowBottom + right, corners[3]);
+ for (let channel = 0; channel < 4; channel++) {
+ const top = corners[0][channel] * (1 - blendX) + corners[1][channel] * blendX;
+ const bottom = corners[2][channel] * (1 - blendX) + corners[3][channel] * blendX;
+ sampleColor[channel] = top * (1 - blendY) + bottom * blendY;
+ sum[channel] += decodesSrgb && channel < 3 ? decodeStoredSrgb(sampleColor[channel]) : sampleColor[channel];
+ }
+ }
+ }
+ for (let channel = 0; channel < 4; channel++) sum[channel] /= positions * positions;
+ encodeFirstLevelTexel(kind, sum, destination, row * destinationSize.width + column);
+ }
+ }
+}
+
/**
* The levels after level 0 of one texture, one after the other, as 32-bit words. `texels` holds level 0 without padding:
* one word per texel for `rgba8` and `rgba8-srgb` (bytes r, g, b, a from the low byte) and `rg16f` (two halves, r in the low half), four
- * floats per texel for `rgba32f`. Returns an empty array for a texture of one texel.
+ * floats per texel for `rgba32f`. `wrapU` and `wrapV` are the wrap modes of the texture (0 repeat, 1 clamp, 2 mirror) and matter
+ * for level 1 only. Returns an empty array for a texture of one texel.
*/
-export function buildMipChain(kind, texels, width, height) {
+export function buildMipChain(kind, texels, width, height, wrapU = 0, wrapV = 0) {
requireTextureSide(width, height);
const levelCount = mipLevelCount(width, height);
const chain = new Uint32Array(mipChainWordCount(kind, width, height));
@@ -219,7 +329,11 @@ export function buildMipChain(kind, texels, width, height) {
const levelWords = destinationSize.width * destinationSize.height * wordsPerTexel(kind);
const destinationWords = chain.subarray(cursor, cursor + levelWords);
const destination = isFloat ? new Float32Array(destinationWords.buffer, destinationWords.byteOffset, levelWords) : destinationWords;
- average(source, destination, sourceSize.width, sourceSize.height, destinationSize.width, destinationSize.height);
+ if (level === 1) {
+ integrateFirstLevel(kind, source, sourceSize, destination, destinationSize, wrapU, wrapV);
+ } else {
+ average(source, destination, sourceSize.width, sourceSize.height, destinationSize.width, destinationSize.height);
+ }
source = destination;
sourceSize = destinationSize;
cursor += levelWords;
diff --git a/tests/native-texture-mips.test.js b/tests/native-texture-mips.test.js
index e4a2103f..74cc18f2 100644
--- a/tests/native-texture-mips.test.js
+++ b/tests/native-texture-mips.test.js
@@ -104,41 +104,66 @@ test('half floats round trip the values a mip average produces', () => {
assert.equal(floatToHalf(1.00048828125), floatToHalf(1), 'a tie rounds to the even neighbour');
});
-test('an 8-bit chain averages the stored bytes of each 2 x 2 block, alpha included, with rounding', () => {
- const level0 = new Uint32Array([
- packedWord(0, 0, 0, 255), packedWord(255, 255, 255, 255),
- packedWord(255, 255, 255, 255), packedWord(0, 0, 0, 255),
- ]);
- const chain = buildMipChain(TEXTURE_KIND_RGBA8, level0, 2, 2);
- assert.equal(chain.length, 1);
- assert.equal(chain[0], packedWord(128, 128, 128, 255));
- const transparent = new Uint32Array([packedWord(200, 0, 0, 0), packedWord(0, 0, 0, 255), packedWord(0, 0, 0, 255), packedWord(0, 0, 0, 255)]);
- assert.equal(buildMipChain(TEXTURE_KIND_RGBA8, transparent, 2, 2)[0], packedWord(50, 0, 0, 191), 'alpha is averaged, not used as a weight');
+const BLACK_WHITE_CHECKER_4X4 = () => Uint32Array.from(
+ { length: 16 },
+ (_, index) => ((index % 4) + Math.floor(index / 4)) % 2 === 0 ? packedWord(0, 0, 0, 255) : packedWord(255, 255, 255, 255),
+);
+
+function byteOf(word, channel) {
+ return (word >>> (channel * 8)) & 0xff;
+}
+
+test('level 1 of an 8-bit chain is the mean of the level 0 reconstruction, levels after it are 2 x 2 boxes', () => {
+ const chain = buildMipChain(TEXTURE_KIND_RGBA8, BLACK_WHITE_CHECKER_4X4(), 4, 4);
+ assert.equal(chain.length, 4 + 1);
+ for (let texel = 0; texel < 5; texel++) {
+ assert.ok(Math.abs(byteOf(chain[texel], 0) - 127.5) <= 2, `texel ${texel} of the chain is ${byteOf(chain[texel], 0)}`);
+ assert.equal(byteOf(chain[texel], 3), 255);
+ }
+ const rampAlpha = new Uint32Array([packedWord(10, 0, 0, 0), packedWord(10, 0, 0, 255), packedWord(10, 0, 0, 255), packedWord(10, 0, 0, 255)]);
+ const alphaChain = buildMipChain(TEXTURE_KIND_RGBA8, rampAlpha, 2, 2);
+ assert.ok(Math.abs(byteOf(alphaChain[0], 3) - 191.25) <= 2, 'alpha is the plain mean, not a weight');
+ assert.equal(byteOf(alphaChain[0], 0), 10, 'a colour that does not change stays');
});
-test('a chain of an uneven or thin texture keeps every level the size the kernel walks to', () => {
- const level0 = Uint32Array.from({ length: 5 * 3 }, (_, index) => packedWord(index * 10, 0, 0, 255));
- const chain = buildMipChain(TEXTURE_KIND_RGBA8, level0, 5, 3);
+test('a chain of an uneven or thin texture keeps every level the size the kernel walks to, and a flat colour stays flat', () => {
+ const flat = Uint32Array.from({ length: 5 * 3 }, () => packedWord(77, 90, 200, 255));
+ const chain = buildMipChain(TEXTURE_KIND_RGBA8, flat, 5, 3);
assert.equal(chain.length, 2 * 1 + 1 * 1);
- assert.equal(chain[0] & 0xff, Math.round((0 + 10 + 50 + 60) / 4), 'first texel of level 1 averages the top left block');
- assert.equal(chain[1] & 0xff, Math.round((20 + 30 + 70 + 80) / 4), 'the fifth column has no pair and is not read');
- assert.equal(chain[2] & 0xff, Math.round(((chain[0] & 0xff) + (chain[1] & 0xff)) / 2), 'level 2 is the 1 x 1 average of the two texels of level 1');
+ for (const word of chain) {
+ assert.equal(word, packedWord(77, 90, 200, 255));
+ }
+ const thin = buildMipChain(TEXTURE_KIND_RGBA8_SRGB, Uint32Array.from({ length: 8 }, () => packedWord(77, 90, 200, 255)), 8, 1);
+ assert.equal(thin.length, 4 + 2 + 1);
+ for (const word of thin) {
+ for (let channel = 0; channel < 3; channel++) {
+ assert.ok(Math.abs(byteOf(word, channel) - [77, 90, 200][channel]) <= 1);
+ }
+ }
assert.equal(buildMipChain(TEXTURE_KIND_RGBA8, new Uint32Array(1), 1, 1).length, 0);
});
-test('a float chain averages the floats without clamping, so a bright texel keeps its energy', () => {
+test('a float chain keeps the energy of a bright texel and does not clamp', () => {
const level0 = new Float32Array([8, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1]);
const chain = buildMipChain(TEXTURE_KIND_RGBA32_FLOAT, level0, 2, 2);
assert.equal(chain.length, 4);
- assert.deepEqual(Array.from(new Float32Array(chain.buffer, chain.byteOffset, 4)), [2, 0, 0, 1]);
+ const mean = Array.from(new Float32Array(chain.buffer, chain.byteOffset, 4));
+ assert.ok(Math.abs(mean[0] - 2) < 1e-5 && mean[1] === 0 && Math.abs(mean[3] - 1) < 1e-6, `mean texel ${mean}`);
});
-test('a two-channel half chain averages each channel as a float', () => {
+test('a two-channel half chain takes the mean of each channel as a float', () => {
const pair = (red, green) => (floatToHalf(red) | (floatToHalf(green) << 16)) >>> 0;
const level0 = new Uint32Array([pair(1, 0), pair(0, 0), pair(0, 0.5), pair(0, 0)]);
const chain = buildMipChain(TEXTURE_KIND_RG16_FLOAT, level0, 2, 2);
- assert.equal(halfToFloat(chain[0] & 0xffff), 0.25);
- assert.equal(halfToFloat(chain[0] >>> 16), 0.125);
+ assert.ok(Math.abs(halfToFloat(chain[0] & 0xffff) - 0.25) < 1e-3);
+ assert.ok(Math.abs(halfToFloat(chain[0] >>> 16) - 0.125) < 1e-3);
+});
+
+test('the wrap mode reaches level 1: a clamped edge does not read the opposite side', () => {
+ const level0 = Uint32Array.from({ length: 4 * 4 }, (_, index) => (index % 4 === 0 ? packedWord(255, 0, 0, 255) : packedWord(0, 0, 0, 255)));
+ const repeated = buildMipChain(TEXTURE_KIND_RGBA8, level0, 4, 4, 0, 0);
+ const clamped = buildMipChain(TEXTURE_KIND_RGBA8, level0, 4, 4, 1, 1);
+ assert.notEqual(byteOf(repeated[1], 0), byteOf(clamped[1], 0), 'the right half sees the red column on its far side only when it repeats');
});
test('without textureMips a texture is level 0 only, the flag is clear and the pool is as it was', () => {
@@ -154,7 +179,7 @@ test('without textureMips a texture is level 0 only, the flag is clear and the p
});
test('textureMips stores the chain after level 0, counts the levels in the descriptor and sets the kernel flag', () => {
- const image = byteImage(8, 8, (x, y) => [x * 30, y * 30, 7, 255]);
+ const image = byteImage(8, 8, () => [40, 80, 120, 255]);
const off = packMaps([{ image, colorSpace: 'linear' }]);
const on = packMaps([{ image, colorSpace: 'linear' }], { textureMips: true });
assert.equal(KERNEL_FLAG_TEXTURE_MIPS, 2048);
@@ -163,24 +188,27 @@ test('textureMips stores the chain after level 0, counts the levels in the descr
assert.equal(kernelFlagsOf(on) & ~KERNEL_FLAG_TEXTURE_MIPS, kernelFlagsOf(off));
assert.equal(on.textureTexels.length, 64 + 16 + 4 + 1 + 3, 'padded once to four words at the end');
assert.deepEqual(on.textureTexels.subarray(0, 64), off.textureTexels.subarray(0, 64), 'level 0 is untouched');
- assert.equal(on.textureTexels[64] & 0xff, Math.round((0 + 30 + 0 + 30) / 4), 'level 1 starts right after level 0');
- assert.ok(Math.abs((on.textureTexels[64 + 16 + 4] & 0xff) - 105) <= 1, 'level 3 is one texel holding the mean of the red ramp');
+ for (const wordIndex of [64, 64 + 15, 64 + 16, 64 + 19, 64 + 20]) {
+ assert.equal(on.textureTexels[wordIndex], packedWord(40, 80, 120, 255), `word ${wordIndex}: every level of a flat map is that colour, stored right after level 0`);
+ }
});
-test('an sRGB chain averages in linear light and stores bytes again, alpha on its stored value', () => {
- const blackAndWhite = new Uint32Array([packedWord(0, 0, 0, 255), packedWord(255, 255, 255, 255), packedWord(255, 255, 255, 255), packedWord(0, 0, 0, 200)]);
- const chain = buildMipChain(TEXTURE_KIND_RGBA8_SRGB, blackAndWhite, 2, 2);
- assert.equal(chain[0], packedWord(188, 188, 188, 241), 'half the light is the byte 188, not the byte 128');
- assert.equal(buildMipChain(TEXTURE_KIND_RGBA8, blackAndWhite, 2, 2)[0], packedWord(128, 128, 128, 241), 'a linear map keeps the plain average');
- const grey = new Uint32Array(4).fill(packedWord(77, 77, 77, 255));
- assert.equal(buildMipChain(TEXTURE_KIND_RGBA8_SRGB, grey, 2, 2)[0], packedWord(77, 77, 77, 255), 'a flat colour survives the round trip');
+test('an sRGB chain stores bytes of the mean light: level 1 integrates the reconstruction, which is darker than a box of decoded texels', () => {
+ const chain = buildMipChain(TEXTURE_KIND_RGBA8_SRGB, BLACK_WHITE_CHECKER_4X4(), 4, 4);
+ const level1 = byteOf(chain[0], 0);
+ assert.ok(level1 >= 130 && level1 <= 145, `level 1 holds byte ${level1}: the mean of the decoded blend of black and white, near 137`);
+ assert.ok(level1 < 188, 'the box of decoded texels would give the byte 188');
+ assert.equal(byteOf(chain[0], 3), 255);
+ const grey = buildMipChain(TEXTURE_KIND_RGBA8_SRGB, new Uint32Array(4).fill(packedWord(77, 77, 77, 255)), 2, 2);
+ assert.ok(Math.abs(byteOf(grey[0], 0) - 77) <= 1, 'a flat colour survives the round trip');
});
-test('an sRGB map keeps its format at every level and its levels hold the mean of the light', () => {
- const checker = byteImage(2, 2, (x, y) => ((x + y) % 2 === 0 ? [0, 0, 0, 255] : [255, 255, 255, 255]));
+test('an sRGB map keeps its format at every level', () => {
+ const checker = byteImage(4, 4, (x, y) => ((x + y) % 2 === 0 ? [0, 0, 0, 255] : [255, 255, 255, 255]));
const input = packMaps([{ image: checker, colorSpace: 'srgb' }], { textureMips: true });
assert.equal(descriptorWord(input, 0, 3) & 0xff, FORMAT_RGBA8_SRGB);
- assert.equal(input.textureTexels[4], packedWord(188, 188, 188, 255), 'the level holds half the light of black and white, which is the stored byte 188');
+ const level1 = byteOf(input.textureTexels[16], 0);
+ assert.ok(level1 >= 130 && level1 <= 145, `level 1 byte ${level1}`);
});
test('mips are per texture too: mips true on one map, false on another, and nearest maps never take levels', () => {
@@ -229,9 +257,12 @@ test('float and half textures are packed in their own formats, with levels on re
assert.equal(mipCountOf(input, 0), 3);
const floatTexels = new Float32Array(input.textureTexels.buffer, input.textureTexels.byteOffset, 64 + 16 + 4);
assert.deepEqual(Array.from(floatTexels.subarray(0, 4)), [12, 6, 3, 1], 'an HDR texel is stored unclamped');
- assert.equal(floatTexels[64], (12 + 0.5 + 0.5 + 0.5) / 4, 'level 1 averages the unclamped floats');
+ const levelOneRed = [0, 1, 2, 3].map((texel) => floatTexels[64 + texel * 4]);
+ assert.ok(Math.max(...levelOneRed) > 1, 'the texel that sees the bright one is above one');
+ const levelOneMean = levelOneRed.reduce((sum, value) => sum + value, 0) / 4;
+ assert.ok(Math.abs(levelOneMean - (12 + 15 * 0.5) / 16) < 1e-4, `level 1 keeps the energy of level 0: ${levelOneMean}`);
const halfStart = descriptorWord(input, 1, 0);
- assert.equal(halfToFloat(input.textureTexels[halfStart + 16] & 0xffff), 0.25);
+ assert.ok(Math.abs(halfToFloat(input.textureTexels[halfStart + 16] & 0xffff) - 0.25) < 1e-3);
});
test('textureMips and mips fail at the boundary with what to pass', () => {
@@ -308,3 +339,42 @@ test('an HDR float emissive map keeps values above one through the kernel, with
assert.ok(Math.abs(result.rgba[centrePixel * 4 + 1] - texelValue * 0.5) < 0.05);
}
});
+
+test('the level follows the footprint with no half level of bias: one texel per pixel reads level 0, two texels per pixel level 1', gpuSkip, () => {
+ const size = 32;
+ const fieldOfView = 30;
+ const distance = 2 / Math.tan(fieldOfView * Math.PI / 360);
+ const camera = createCamera({ eye: [0, 0, distance], target: [0, 0, 0], fov: fieldOfView }, size, size);
+ const spread = (texelsPerSide) => {
+ const checker = new Float32Array(texelsPerSide * texelsPerSide * 4);
+ for (let texel = 0; texel < texelsPerSide * texelsPerSide; texel++) {
+ const value = ((texel % texelsPerSide) + Math.floor(texel / texelsPerSide)) % 2 === 0 ? 0 : 1;
+ checker.set([value, value, value, 1], texel * 4);
+ }
+ const options = { width: size, height: size, samples: 1, textureMips: true };
+ const input = buildNativeInputV2(
+ {
+ materials: [{ color: [0, 0, 0], emissionStrength: 1, emissionColor: [1, 1, 1], emissiveTexture: { image: { width: texelsPerSide, height: texelsPerSide, data: checker } } }],
+ instances: [{ geometry: quadGeometry(0), materialIndex: 0 }],
+ lights: {},
+ },
+ camera,
+ options,
+ );
+ const result = traceNative(input, { ...options, kernel: 'cycles' });
+ const centre = [];
+ for (let row = 14; row < 18; row++) {
+ for (let column = 14; column < 18; column++) {
+ centre.push(result.rgba[(row * size + column) * 4]);
+ }
+ }
+ return { minimum: Math.min(...centre), maximum: Math.max(...centre) };
+ };
+ // The quad is 16 pixels wide at its centre. 32 texels across it: 2 texels per pixel, level 1, the flat mean of the checker.
+ const twoTexels = spread(32);
+ assert.ok(twoTexels.maximum - twoTexels.minimum < 0.02, 'level 1 is flat: ' + JSON.stringify(twoTexels));
+ assert.ok(Math.abs(twoTexels.minimum - 0.5) < 0.02);
+ // 16 texels across it: 1 texel per pixel, level 0, the checker itself.
+ const oneTexel = spread(16);
+ assert.ok(oneTexel.maximum - oneTexel.minimum > 0.3, 'level 0 keeps the checker: ' + JSON.stringify(oneTexel));
+});