A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(pipeline): a cut-out chain holds the share its cut keeps, and a cut-out takes its colour into its clear texels
yhh0a285d995e80
diff --git a/pipeline/src/assets/ktx2Mips.ts b/pipeline/src/assets/ktx2Mips.tsindex 566a8e43d..272f9e810 100644--- a/pipeline/src/assets/ktx2Mips.ts+++ b/pipeline/src/assets/ktx2Mips.ts@@ -135,6 +135,42 @@ export function halveRgba(rgba: Uint8Array, width: number, height: number, srgb:return { rgba: out, width: w, height: h };}+/**+ * The next level down of a cut-out's chain, whose alpha is COVERAGE: the share of the texels under each new texel that the cut keeps.+ * Read at the first step from the image itself (`cutoff` given: a texel counts when its alpha reaches it), and from there on by averaging+ * shares, which is exact. Colour is weighted the same way, so a level is the colour of what the cut keeps and not of what it throws away.+ *+ * A plain average of alpha is the share only for a mask that is 0 or 1; a soft one (a painted band of lashes fading out, a strand's+ * antialiased edge) averages to more than the cut keeps, and a shader taking the minified alpha as coverage drew the faint parts the+ * source never shows. Coverage-preserving rescaling (preserveAlphaCoverage) is the answer for a shader that cuts every level at the+ * cutoff; the engine's cut-out shaders read a minified level as the share it is (cutoutCoverage), so this chain gives them the share.+ */+export function halveCoverage(rgba: Uint8Array, width: number, height: number, srgb: boolean, cutoff: number | null): {+ rgba: Uint8Array; width: number; height: number;+} {+ const w = Math.max(1, width >> 1), h = Math.max(1, height >> 1);+ const out = new Uint8Array(w * h * 4);+ const threshold = cutoff === null ? 0 : cutoff * 255;+ for (let y = 0; y < h; y++) {+ const y0 = Math.min(height - 1, y * 2), y1 = Math.min(height - 1, y * 2 + 1);+ for (let x = 0; x < w; x++) {+ const x0 = Math.min(width - 1, x * 2), x1 = Math.min(width - 1, x * 2 + 1);+ const taps = [(y0 * width + x0) * 4, (y0 * width + x1) * 4, (y1 * width + x0) * 4, (y1 * width + x1) * 4];+ const weights = taps.map(t => (cutoff === null ? rgba[t + 3]! / 255 : (rgba[t + 3]! >= threshold ? 1 : 0)));+ const total = weights.reduce((n, v) => n + v, 0);+ const o = (y * w + x) * 4;+ for (let c = 0; c < 3; c++) {+ const mean = (f: (t: number) => number) => (total > 0+ ? taps.reduce((n, t, i) => n + f(t) * weights[i]!, 0) / total+ : taps.reduce((n, t) => n + f(t), 0) / 4);+ out[o + c] = srgb ? toSrgbByte(mean(t => toLinear[rgba[t + c]!]!)) : Math.round(mean(t => rgba[t + c]!));+ }+ out[o + 3] = Math.round(total / 4 * 255);+ }+ }+ return { rgba: out, width: w, height: h };+}+/*** `base`'s level 0 over every level of `below` (encoded from the half-size* image, so its level 0 is the base's level 1), as one KTX2 with `base`'sdiff --git a/pipeline/src/assets/modelImages.ts b/pipeline/src/assets/modelImages.tsindex 480eb00f0..2cf2e1f55 100644--- a/pipeline/src/assets/modelImages.ts+++ b/pipeline/src/assets/modelImages.ts@@ -67,6 +67,65 @@ function constantColor(p: Pixels): number[] | null {return [d[0] ?? 0, d[1] ?? 0, d[2] ?? 0, d[3] ?? 0];}+/**+ * A cut-out's colour carried into its clear texels: each texel's colour is pulled toward that of the solid texels nearest it, as far as it is+ * clear (push-pull over a pyramid of alpha-weighted colour). What a painter leaves under alpha 0 is usually whatever was behind the strokes,+ * a skin tone under eyelashes, white under a leaf; a mip averages it in with the strands, and seen from a distance the card drew a veil of+ * that colour over what it covers (the render lab's probe eye came out pink). A texel that is solid keeps its colour exactly.+ */+export function bleedCutoutColor(p: Pixels): Uint8Array {+ const levels: { w: number; h: number; c: Float32Array; a: Float32Array }[] = [];+ let w = p.width, h = p.height;+ let c = new Float32Array(w * h * 3), a = new Float32Array(w * h);+ for (let i = 0; i < w * h; i++) {+ const alpha = p.rgba[i * 4 + 3]! / 255;+ a[i] = alpha;+ for (let k = 0; k < 3; k++) c[i * 3 + k] = p.rgba[i * 4 + k]! * alpha;+ }+ levels.push({ w, h, c, a });+ while (w > 1 || h > 1) {+ const nw = Math.max(1, w >> 1), nh = Math.max(1, h >> 1);+ const nc = new Float32Array(nw * nh * 3), na = new Float32Array(nw * nh);+ for (let y = 0; y < nh; y++) {+ for (let x = 0; x < nw; x++) {+ const o = y * nw + x;+ for (const [dx, dy] of [[0, 0], [1, 0], [0, 1], [1, 1]] as const) {+ const sx = Math.min(w - 1, x * 2 + dx), sy = Math.min(h - 1, y * 2 + dy);+ const i = sy * w + sx;+ na[o] += a[i]!;+ for (let k = 0; k < 3; k++) nc[o * 3 + k] += c[i * 3 + k]!;+ }+ }+ }+ w = nw; h = nh; c = nc; a = na;+ levels.push({ w, h, c, a });+ }+ const out = new Uint8Array(p.rgba);+ for (let y = 0; y < p.height; y++) {+ for (let x = 0; x < p.width; x++) {+ const i = y * p.width + x;+ const alpha = p.rgba[i * 4 + 3]! / 255;+ if (alpha >= 1) continue;+ // The colour of the nearest solid neighbourhood: the first level up whose cell holds any.+ let fill: [number, number, number] | null = null;+ for (let l = 1; l < levels.length; l++) {+ const L = levels[l]!;+ const lx = Math.min(L.w - 1, x >> l), ly = Math.min(L.h - 1, y >> l);+ const o = ly * L.w + lx;+ if (L.a[o]! > 1e-3) {+ fill = [L.c[o * 3]! / L.a[o]!, L.c[o * 3 + 1]! / L.a[o]!, L.c[o * 3 + 2]! / L.a[o]!];+ break;+ }+ }+ if (!fill) continue;+ for (let k = 0; k < 3; k++) {+ out[i * 4 + k] = Math.round(p.rgba[i * 4 + k]! * alpha + fill[k]! * (1 - alpha));+ }+ }+ }+ return out;+}+function redIsZero(p: Pixels): boolean {for (let i = 0; i < p.rgba.length; i += 4) if (p.rgba[i] !== 0) return false;return true;@@ -164,6 +223,8 @@ export function prepareModelImages(result: ModelImportResult,};const noticed = new Set<string>();+ // Base colours by file: whether every material that reads one cuts it out (only then is its clear colour never seen up close).+ const bases = new Map<string, { pixels: Pixels; ref: ImportedImageRef; cutoutOnly: boolean; users: ImportedMaterial[] }>();const materials = new Set<ImportedMaterial>();for (const mesh of result.meshes) if (mesh.material) materials.add(mesh.material);for (const material of materials) {@@ -181,6 +242,11 @@ export function prepareModelImages(result: ModelImportResult,const settings = DATA_SLOTS.has(slot) ? { ...ref.settings, sRGB: false } : ref.settings;material[slot] = settings ? { ...converted, settings } : converted;if (!pixels) continue;+ if (slot === 'baseColorTexture' && converted.external === false) {+ const entry = bases.get(converted.file) ?? { pixels, ref: converted, cutoutOnly: true, users: [] };+ entry.users.push(material);+ bases.set(converted.file, entry);+ }// A format with no alpha mode (FBX) leaves the base colour's alpha to say it.if (slot === 'baseColorTexture' && options.alphaFromBaseColor&& material.opaque && material.alphaCutoff === undefined) {@@ -204,12 +270,20 @@ export function prepareModelImages(result: ModelImportResult,+ ` ${pixels.width}x${pixels.height} — a material constant would say the same`);}}- // A cutout's mips keep its coverage at the cutoff it tests, or it thins with distance.+ // A cutout's mips hold the share of texels its cut keeps (mipCoverage: see halveCoverage), which is what its shaders read as the+ // coverage of a minified pixel.const base = material.baseColorTexture;if (base && material.alphaCutoff !== undefined && material.alphaCutoff > 0) {material.baseColorTexture = { ...base, settings: { ...base.settings, mipCoverage: material.alphaCutoff } };}}+ for (const entry of bases.values()) {+ entry.cutoutOnly = entry.users.every(m => m.alphaCutoff !== undefined && m.alphaCutoff > 0);+ if (!entry.cutoutOnly) continue;+ const texture = embedded.get(entry.ref.file);+ if (!texture) continue;+ texture.bytes = encodeRgbaPng(entry.pixels.width, entry.pixels.height, bleedCutoutColor(entry.pixels));+ }const converted = new Set([...seen.entries()].filter(([k]) => k.startsWith('x:') && isDdsName(k.slice(2))).map(([k]) => k.slice(2)));diff --git a/pipeline/src/assets/textureCook.ts b/pipeline/src/assets/textureCook.tsindex 6c584d466..f65dcdedc 100644--- a/pipeline/src/assets/textureCook.ts+++ b/pipeline/src/assets/textureCook.ts@@ -14,7 +14,7 @@ import {decideTextureCook, cookIntentDefeated, explainTextureCook, downscaledSize,type TextureCookDecision,} from './textureCookDecision';-import { halveRgba, joinMipLevels, alphaCoverage, preserveAlphaCoverage } from './ktx2Mips';+import { joinMipLevels, halveCoverage } from './ktx2Mips';import { cookCachedAt, cookCacheFile, cookCacheHitAt, encoderIdentity } from './cookCache';/** Targets the KTX2 the cook emits can transcode to at runtime (UASTC + ETC1S). */@@ -39,22 +39,20 @@ export interface BasisEncoderModule {}/**- * A cutout's UASTC chain, each level halved here from the one above with its alpha- * rescaled to the full image's coverage at @p cutoff — plain averaging thins a- * sparse cutout, such as a railing, until nothing of it passes the cut.+ * A cutout's UASTC chain: level 0 as authored, and each level below it holding as alpha the share of the image's texels the cut at+ * @p cutoff keeps (halveCoverage), the coverage a minified cut-out is drawn with.*/async function encodeCoverageChain(enc: BasisEncoderModule, img: { rgba: Uint8Array; width: number; height: number },srgb: boolean, cutoff: number): Promise<Uint8Array> {- const coverage = alphaCoverage(img.rgba, cutoff);const parts: Uint8Array[] = [];let level = img;+ let first = true;for (;;) {parts.push(await enc.encodeToKtx2({ type: enc.ImageType.RGBA, data: level.rgba, width: level.width, height: level.height },{ mode: 'uastc', srgb, mipmaps: false, supercompress: true }));if (level.width === 1 && level.height === 1) break;- const half = halveRgba(level.rgba, level.width, level.height, srgb);- preserveAlphaCoverage(half.rgba, cutoff, coverage);- level = half;+ level = halveCoverage(level.rgba, level.width, level.height, srgb, first ? cutoff : null);+ first = false;}return joinMipLevels(parts);}@@ -182,7 +180,8 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO// before this existed is re-encoded rather than reused.const supercompress = mode === 'uastc';const key = [source, JSON.stringify({ mode, srgb: tex.srgb, maxSize: tex.maxSize, scaled: scaled ? [size!.width, size!.height] : null,- ...(coverage ? { mipCoverage: coverage } : {}), ...(supercompress ? { supercompress } : {}), ...mips }), input.encoder!.id];+ // `chain: 2` marks the coverage chain (halveCoverage) that replaced the rescaled one: an entry cooked before it is re-encoded.+ ...(coverage ? { mipCoverage: coverage, chain: 2 } : {}), ...(supercompress ? { supercompress } : {}), ...mips }), input.encoder!.id];const produce = (): Promise<Uint8Array> => {const image = scaled ? scaledImage() : null;return coveragediff --git a/pipeline/tests/ktx2-mips.test.ts b/pipeline/tests/ktx2-mips.test.tsindex 1db6b2e5a..6d2defb4e 100644--- a/pipeline/tests/ktx2-mips.test.ts+++ b/pipeline/tests/ktx2-mips.test.ts@@ -12,7 +12,7 @@ import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSynimport { tmpdir } from 'node:os';import path from 'node:path';import {- readKtx2Layout, wantsMipChain, halveRgba, spliceMipChain, joinMipLevels, alphaCoverage, preserveAlphaCoverage,+ readKtx2Layout, wantsMipChain, halveRgba, spliceMipChain, joinMipLevels, alphaCoverage, preserveAlphaCoverage, halveCoverage,} from '../src/assets/ktx2Mips';import { cookCached } from '../src/assets/cookCache';import { cookAssets } from '../src/assets/cookAssets';@@ -143,3 +143,19 @@ describe('a cutout\'s mips keep its coverage', () => {expect(() => joinMipLevels([chainParts[0]!, chainParts[2]!])).toThrow(/not the level under/);});});++describe('a cut-out chain whose alpha is coverage', () => {+ it('gives a soft band the share its cut keeps, not its average alpha', () => {+ // Four texels at alpha 0.3 (a faint painted band) and nothing above the cutoff: the cut keeps none of them.+ const faint = new Uint8Array([90, 60, 50, 77, 90, 60, 50, 77, 90, 60, 50, 77, 90, 60, 50, 77]);+ expect(halveCoverage(faint, 2, 2, false, 0.45).rgba[3]).toBe(0);+ // One solid strand of four: a quarter, and the colour is the strand's.+ const strand = new Uint8Array([20, 10, 5, 255, 200, 120, 110, 60, 200, 120, 110, 60, 200, 120, 110, 60]);+ expect(Array.from(halveCoverage(strand, 2, 2, false, 0.45).rgba)).toEqual([20, 10, 5, 64]);+ });++ it('averages shares below the first level, which is exact', () => {+ const shares = new Uint8Array([255, 255, 255, 255, 255, 255, 255, 0, 255, 255, 255, 128, 255, 255, 255, 128]);+ expect(halveCoverage(shares, 2, 2, false, null).rgba[3]).toBe(128);+ });+});diff --git a/sdk/src/foliage/foliageShader.ts b/sdk/src/foliage/foliageShader.tsindex cd4504780..5bb6fd69e 100644--- a/sdk/src/foliage/foliageShader.ts+++ b/sdk/src/foliage/foliageShader.ts@@ -105,12 +105,16 @@ void main() {float height = clamp(v_color.r, 0.0, 1.0);float light = v_color.b;vec4 tex = texture(u_albedo, v_texCoord);+ // Before the branch: a derivative needs every fragment of its quad. How many texels of the map a pixel spans, for cutoutCoverage.+ vec2 mapSize = vec2(textureSize(u_albedo, 0));+ float texels = max(length(dFdx(v_texCoord) * mapSize), length(dFdy(v_texCoord) * mapSize));+ float edgeA = fwidth(tex.a);vec3 albedo = mix(u_baseColor.rgb, u_tipColor.rgb, height);float alpha = 1.0;if (u_useTexture > 0.5) {albedo *= tex.rgb;alpha = tex.a;- alpha = (alpha - u_alphaCutoff) / max(fwidth(alpha), 1e-4) + 0.5;+ alpha = cutoutCoverage(alpha, u_alphaCutoff, edgeA, texels, gl_FragCoord.xy, u_time.w);if (alpha <= 0.0) discard;alpha = min(alpha, 1.0);}@@ -157,6 +161,8 @@ fn packNormal(n : vec3f) -> vec2f {#endiflet tex = textureSampleGrad(u_albedo, u_albedo_s, v.v_texCoord, duvx, duvy);let edge = max(fwidth(tex.a), 1e-4);+ let mapSize = vec2f(textureDimensions(u_albedo));+ let texels = max(length(duvx * mapSize), length(duvy * mapSize));#ifdef MESH_NORMALSlet P = v.v_worldXYZ;var N = normalize(v.v_worldNormal);@@ -171,7 +177,7 @@ fn packNormal(n : vec3f) -> vec2f {var alpha = 1.0;if (mc.u_useTexture > 0.5) {albedo = albedo * tex.rgb;- alpha = (tex.a - mc.u_alphaCutoff) / edge + 0.5;+ alpha = cutoutCoverage(tex.a, mc.u_alphaCutoff, edge, texels, v.pos.xy, tc.u_time.w);if (alpha <= 0.0) { discard; }alpha = min(alpha, 1.0);}