Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Carry a coat or sheen map only when it cannot change the roughness, and check record fields (#1036)

Nguyen Xuan Anba2df41642e4
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 2d2df908..11268afd 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -1090,6 +1090,7 @@ Same scene, same 4096 samples, 192 x 128, box filter, 8 bounces, seed 1, against
- `absorption` improves by a factor of 11 in relMSE but does not pass the 2 percent mean gate (red 0.9649, blue 0.9715) and has 9 tiles outside 5 percent, in the job export and the bench packing alike. The kernel applies the glTF attenuation exactly (transmittance equals `attenuationColor` after `attenuationDistance`); `render-cycles.py` gives Blender one grey density from the mean log of the colour `[inferred]`, so part of the gap is likely the reference, not the kernel. This was not separated.
- The v1 tables are still what the legacy kernel and light bakes read. Not carried: `doubleSided` (a job traces every surface two sided, and carrying the 67js default `false` would cull the backs of every material), the `liquid` tag, `occlusionMap`, `lightMap`, `moss` and splat layers, the coat and sheen roughness maps (the record has one slot for each pair), and `thickness`.
- A scene whose materials cannot be exported whole is traced from the v1 tables for that frame, with the reason in `materialsReason`.
+- Known limits of the carried layers. The kernel reads a coat's weight and roughness from one map and a sheen's tint and roughness from one map, so a clearcoat or sheen colour map is carried only when the layer's roughness is 0 or its roughness map is the same image; otherwise the factor alone is used and the job report says so. An iridescence factor below 1 thins the film (the record holds thickness times the factor) where the rasteriser weights the effect, so the hue differs from a full-strength film; the parity row is at factor 1. An anisotropy map scales the converted Cycles strength, which is not the conversion of the scaled glTF strength, so the lobe shape is approximate where the map is below 1. The record-name fields (`coatTint`, `coatIor`, `thinWalled` and the rest of `RECORD_FIELDS`) are for callers that build parts in code; no MCP material sets them, and a value that is not a finite number, a boolean or an array of finite numbers is refused.
![Opaque pane before, blend pane after, Cycles 5.3 (left to right) for a blend pane over a sheen sphere](native-job-materials.jpg)
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index a6d57e50..de377a4e 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -64,7 +64,7 @@ Also checked before any ray is traced: samples times pixels times bounces at mos
- Limits: 400,000 triangles counted once per shared geometry, 1,024 distinct geometries (the part limit, counted on geometries) and 65,536 instances. An instanced scene has no world-space triangle arrays or CPU BVH, so only `buildNativeInputV2` reads it.
- A part's material is its own entry in `materials`, so copies may differ in material; a multi-material mesh stays one geometry with the materials the part names.
- `buildNativeInput` (the `legacy` kernel) refuses an instanced scene with an error; build the scene without `instancing` for that kernel. `traceNative` with `kernel: "legacy"` refuses a FORMAT-v2 input the same way.
-- Render jobs with `renderer.backend: "native"` keep repeated geometry as instances when the job traces with the `cycles` kernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input for `traceNative`, and the report names the `instances` and counts `triangles` once per shared geometry. With `JS67_NATIVE_KERNEL=legacy`, `JS67_NATIVE_INSTANCING=off` (flattened triangles on the `cycles` kernel, to compare the two), or a scene where no geometry is shared, the job exports flattened tables exactly as before.
+- Render jobs with `renderer.backend: "native"` keep repeated geometry as instances when the job traces with the `cycles` kernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input for `traceNative`, and the report names the `instances` and counts `triangles` once per shared geometry. With `JS67_NATIVE_KERNEL=legacy`, `JS67_NATIVE_INSTANCING=off` (flattened triangles on the `cycles` kernel, to compare the two), or a scene where no geometry is shared, the job exports flattened geometry as before; on the `cycles` kernel the materials are still sent whole (next point), and only the legacy kernel reads the v1 tables.
- A job sends the materials of an instanced scene and of a flattened one the same way (`buildJobNativeInput` and `buildFlattenedJobNativeInput` in `packages/render-native/job-input.mjs`): what the v1 material tables carry is read from them, and `carriedMaterialFields` lays blend opacity, sheen, specular, anisotropy, iridescence, attenuation and the layer textures over it. A part looks the same whether or not other geometry in the scene is shared, and a material that sets none of those fields packs to the record the v1 tables gave. Every job on the `cycles` kernel is exported as FORMAT-v2; the legacy kernel and light bakes keep the v1 tables.
- When the instanced packer refuses a scene (copies of an emissive mesh that emit different triangles, a singular matrix), the job exports it flattened as before and the report says `instancing: "flattened"` and `instancingReason`. A scene that fails to export no longer marks the native tracer unusable for the process; only a tracer or adapter failure does.
- A part with `shadowOnly: true` becomes an instance that camera rays skip (visibility bits for every other ray kind stay set). An instance whose material differs from the first copy's emits light by its own material: a copy made emissive by its material is sampled as a light, and a copy made non-emissive is not. Triangles of a shared mesh that are emissive keep one `local_emissive_offset` for all copies, so a copy scaled to a size that drops an emissive triangle the other copies keep is refused with its index.
diff --git a/packages/render-native/job-input.mjs b/packages/render-native/job-input.mjs
index 76040df3..055f6fb2 100644
--- a/packages/render-native/job-input.mjs
+++ b/packages/render-native/job-input.mjs
@@ -68,11 +68,38 @@ function layerFields(material, resolved) {
fields.attenuationColor = material.attenuationColor ?? [1, 1, 1];
}
for (const name of RECORD_FIELDS) {
- if (material[name] !== undefined) fields[name] = material[name];
+ if (material[name] === undefined) continue;
+ if (!isRecordValue(material[name])) {
+ throw new TypeError(`Material field ${name} must be a finite number, a boolean or an array of finite numbers; got ${String(material[name])}.`);
+ }
+ fields[name] = material[name];
}
return fields;
}
+function isRecordValue(value) {
+ if (typeof value === 'boolean') return true;
+ if (typeof value === 'number') return Number.isFinite(value);
+ if (!Array.isArray(value) && !ArrayBuffer.isView(value)) return false;
+ return Array.from(value).every(channel => typeof channel === 'number' && Number.isFinite(channel));
+}
+
+function sharesImage(firstDescriptor, secondDescriptor) {
+ return Boolean(firstDescriptor?.image) && firstDescriptor.image === secondDescriptor?.image;
+}
+
+// The kernel reads a coat's weight and roughness from the red and green channels of one map, and a sheen's tint and
+// roughness from the colour and alpha of one map. A 67js material (glTF) keeps each roughness in a map of its own. So the
+// weight or tint map is carried only when its other channel cannot change the roughness: the roughness factor is 0, or the
+// material's roughness map is the same image.
+function coatMapFitsTheSlot(material, resolved) {
+ return !(resolved.clearcoatRoughness > 0) || sharesImage(material.layerMaps?.clearcoatTexture, material.layerMaps?.clearcoatRoughnessTexture);
+}
+
+function sheenMapFitsTheSlot(material) {
+ return !(material.sheenRoughness > 0) || sharesImage(material.layerMaps?.sheenColorTexture, material.layerMaps?.sheenRoughnessTexture);
+}
+
// A layer texture only matters while its layer is on, so a texture on a layer that is off stays out of the record.
function layerTextures(material, resolved, resolveTexture) {
const textures = {};
@@ -81,11 +108,11 @@ function layerTextures(material, resolved, resolveTexture) {
};
if (resolved.transmission > 0) keep('transmission', resolved.transmissionTexture);
if (resolved.clearcoat > 0) {
- keep('coatWeightRoughness', resolved.clearcoatTexture);
+ if (coatMapFitsTheSlot(material, resolved)) keep('coatWeightRoughness', resolved.clearcoatTexture);
keep('coatNormal', resolveTexture(material.layerMaps?.clearcoatNormalTexture));
}
if (material.anisotropy > 0) keep('anisotropy', resolveTexture(material.layerMaps?.anisotropyTexture));
- if (hasColor(material.sheenColor)) keep('sheenColorRoughness', resolveTexture(material.layerMaps?.sheenColorTexture));
+ if (hasColor(material.sheenColor) && sheenMapFitsTheSlot(material)) keep('sheenColorRoughness', resolveTexture(material.layerMaps?.sheenColorTexture));
if (material.bumpDistance > 0) keep('bump', resolveTexture(material.bumpMap));
return textures;
}
diff --git a/src/path-tracer.js b/src/path-tracer.js
index ef849071..0684afef 100644
--- a/src/path-tracer.js
+++ b/src/path-tracer.js
@@ -55,6 +55,15 @@ const IGNORED_LAYERS = [
// The layer maps the native "cycles" kernel reads with its whole materials (the roughness maps of the coat and the sheen have no slot).
const KERNEL_LAYER_MAPS = ['clearcoatTexture', 'clearcoatNormalTexture', 'anisotropyTexture', 'sheenColorTexture'];
+// The native kernel reads a coat's weight and roughness, and a sheen's tint and roughness, from one map each
+// (packages/render-native/job-input.mjs carries the map only when it cannot change the roughness).
+function hasSplitLayerMap(material) {
+ const maps = material.layerMaps ?? {};
+ const coatIsSplit = Boolean(maps.clearcoatTexture) && material.clearcoatRoughness > 0 && maps.clearcoatTexture.image !== maps.clearcoatRoughnessTexture?.image;
+ const sheenIsSplit = Boolean(maps.sheenColorTexture) && material.sheenRoughness > 0 && maps.sheenColorTexture.image !== maps.sheenRoughnessTexture?.image;
+ return coatIsSplit || sheenIsSplit;
+}
+
function hasGraphOpacity(material) {
return material.pattern?.type === 'graph' && Object.hasOwn(material.pattern.graph ?? {}, 'opacity');
}
@@ -989,6 +998,7 @@ export function describeIgnoredFeatures(parts, environment, backend = 'cpu', { k
if (material.alphaMode === 'blend' && hasGraphOpacity(material)) notes.add('A graph opacity output is traced as a cutout at 0.5.');
else if (material.alphaMode === 'blend' && !kernelMaterials) notes.add('Blended transparency is traced as opaque.');
if (!kernelMaterials && (material.layerMaps?.clearcoatTexture || material.transmissionMap)) notes.add('Graph clearcoat and transmission masks are read by the CPU tracer; the GPU tracers use the factors.');
+ if (kernelMaterials && hasSplitLayerMap(material)) notes.add('A clearcoat or sheen colour map is ignored when the layer has a roughness above 0 kept in another map.');
if (material.emissionFresnel > 0 && backend !== 'cpu') notes.add('emission fresnel is ignored by the GPU path tracers; the cpu backend applies it.');
for (const [name, isUsed, kernelShades] of IGNORED_LAYERS) if (!(kernelMaterials && kernelShades) && isUsed(material, kernelMaterials)) notes.add(`${name} is ignored.`);
}
diff --git a/tests/native-instancing-fallback.test.js b/tests/native-instancing-fallback.test.js
index 1de1076e..ed4f35c2 100644
--- a/tests/native-instancing-fallback.test.js
+++ b/tests/native-instancing-fallback.test.js
@@ -59,7 +59,7 @@ for (const [name, scene] of Object.entries(scenes)) {
assert.equal(exported.wholeMaterials, true);
const main = mainsExport(matrices);
for (const [tableName, table] of Object.entries(main)) {
- if (!ArrayBuffer.isView(table) || tableName === 'kernelParams') continue;
+ if (!ArrayBuffer.isView(table)) continue;
assert.equal(exported.tables[tableName], Buffer.from(table.buffer, table.byteOffset, table.byteLength).toString('base64'), tableName);
}
});
diff --git a/tests/native-job-materials.test.js b/tests/native-job-materials.test.js
index d90ee7ce..824aed3e 100644
--- a/tests/native-job-materials.test.js
+++ b/tests/native-job-materials.test.js
@@ -313,3 +313,31 @@ test('a job frame with a blend pane differs from the same scene traced from the
const direct = traceNative(buildNativeInput(buildTraceScene(parts, environment), camera, packOptions, pack), { width: WIDTH, height: HEIGHT, samples: 8, kernel: 'cycles' });
assert.notDeepEqual(viaV2, Buffer.from(direct.rgba.buffer, direct.rgba.byteOffset, direct.rgba.byteLength));
});
+
+// The kernel reads the green channel of the coat map as a roughness scale and the alpha of the sheen map as one; a 67js
+// material keeps those in other maps, so a weight or tint map is carried only when it cannot change the roughness (#1036).
+test('a coat or sheen map is carried only when its other channel cannot change the roughness', () => {
+ const coatMask = checker(2, 9);
+ const sheenTint = checker(2, 11);
+ const resolvedCoat = roughness => ({ clearcoat: 1, clearcoatRoughness: roughness, clearcoatTexture: resolveTexture(coatMask), transmission: 0 });
+ const smoothCoat = carriedMaterialFields({ layerMaps: { clearcoatTexture: coatMask } }, resolvedCoat(0), resolveTexture);
+ assert.ok(smoothCoat.textures.coatWeightRoughness, 'a coat without roughness keeps its mask');
+ const roughCoat = carriedMaterialFields({ layerMaps: { clearcoatTexture: coatMask } }, resolvedCoat(0.3), resolveTexture);
+ assert.equal(roughCoat.textures, undefined, 'the green channel of a mask would scale the roughness');
+ const packedCoat = carriedMaterialFields({ layerMaps: { clearcoatTexture: coatMask, clearcoatRoughnessTexture: { ...coatMask } } }, resolvedCoat(0.3), resolveTexture);
+ assert.ok(packedCoat.textures.coatWeightRoughness, 'one image for weight and roughness is what the slot holds');
+
+ const sheen = roughness => ({ sheenColor: [1, 1, 1], sheenRoughness: roughness, layerMaps: { sheenColorTexture: sheenTint } });
+ assert.ok(carriedMaterialFields(sheen(0), { transmission: 0, clearcoat: 0 }, resolveTexture).textures.sheenColorRoughness);
+ assert.equal(carriedMaterialFields(sheen(0.5), { transmission: 0, clearcoat: 0 }, resolveTexture).textures, undefined);
+
+ const notes = describeIgnoredFeatures([{ material: { clearcoat: 1, clearcoatRoughness: 0.3, layerMaps: { clearcoatTexture: coatMask } } }], { map: {} }, 'cpu', { kernelMaterials: true });
+ assert.deepEqual(notes, ['A clearcoat or sheen colour map is ignored when the layer has a roughness above 0 kept in another map.']);
+});
+
+test('a record field that is not a finite number, a boolean or an array of finite numbers is refused', () => {
+ const resolved = { transmission: 0, clearcoat: 0 };
+ assert.throws(() => carriedMaterialFields({ coatIor: 'glass' }, resolved, resolveTexture), /Material field coatIor must be a finite number/);
+ assert.throws(() => carriedMaterialFields({ coatTint: [1, Number.NaN, 1] }, resolved, resolveTexture), /Material field coatTint/);
+ assert.deepEqual(carriedMaterialFields({ coatIor: 1.6, thinWalled: true, coatTint: [0.5, 0.9, 0.5] }, resolved, resolveTexture), { coatIor: 1.6, thinWalled: true, coatTint: [0.5, 0.9, 0.5] });
+});