Skip to content

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.

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.ts
index 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`'s
diff --git a/pipeline/src/assets/modelImages.ts b/pipeline/src/assets/modelImages.ts
index 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.ts
index 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 coverage
diff --git a/pipeline/tests/ktx2-mips.test.ts b/pipeline/tests/ktx2-mips.test.ts
index 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, writeFileSyn
import { 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.ts
index 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 {
#endif
let 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_NORMALS
let 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);
}