Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Material graphs: opacity, clearcoat and transmission outputs, layer, hue and curve nodes (issue #609)

Nguyen Xuan Ana9d0f21aceec
diff --git a/changes/609-material-graph-outputs.md b/changes/609-material-graph-outputs.md
new file mode 100644
index 00000000..04514fc6
--- /dev/null
+++ b/changes/609-material-graph-outputs.md
@@ -0,0 +1 @@
+- Material graphs: new outputs `opacity` (base texture alpha), `clearcoat` and `transmission` (per-pixel masks), and mixing nodes `layer` (mask-blended layers such as paint over rust), `hue` and `curve`. The rasterizer reads opacity and clearcoat, the CPU path tracer all three. Graphs without them bake the same (#609)
diff --git a/changes/609-material-graph-outputs.size.md b/changes/609-material-graph-outputs.size.md
new file mode 100644
index 00000000..1fb4cc6f
--- /dev/null
+++ b/changes/609-material-graph-outputs.size.md
@@ -0,0 +1,2 @@
+- scene:agent-scene: three graph outputs and three mixing nodes add about 2 KB source to the already loaded graph baker, and the clearcoat texture now reads through the box projection.
+- goal:capable: the path tracer reads two more textures per hit; the graph language gains what paint-over-rust needs.
diff --git a/docs/agent-scene.md b/docs/agent-scene.md
index ba395b74..f1f643e4 100644
--- a/docs/agent-scene.md
+++ b/docs/agent-scene.md
@@ -172,11 +172,14 @@ texture images, so no text from a recipe ever reaches the shader. The language s
| `roughness`, `metallic` | The metallic-roughness map. A material that has either output defaults the matching factor to 1 |
| `emission` | The emissive map. The material `emission` defaults to 1 when the graph has it |
| `height` | A normal map, so it gives bump. `bump` (0 to 4, default 1) scales the relief |
+| `opacity` | The alpha of the base colour map. The material blends unless `alphaMode` says otherwise. The path tracer cuts it out at 0.5 |
+| `clearcoat` | A per-pixel mask of the clear coat (the red channel of `layerMaps.clearcoatTexture`). The material `clearcoat` defaults to 1. The rasterizer and the CPU path tracer read it |
+| `transmission` | A per-pixel mask of transmission (`transmissionMap`). The material `transmission` defaults to 1. Only the CPU path tracer reads the mask; the rasterizer and GPU tracers use the factor |
Nodes: `uv` (`"u"`, `"v"` or `"both"`), `noise`, `voronoi` (`output`: `distance`, `edge` or `cell`, a random value per cell),
`wave` (`sine`, `saw` or `triangle` along `u`, `v` or `diagonal`), `checker`, `gradient` (`u`, `v` or `radial`), `ramp`
(2 to 8 stops of numbers or colours), `vec`, and the maths nodes `add`, `sub`, `mul`, `div`, `min`, `max`, `pow`, `abs`, `floor`,
-`fract`, `sqrt`, `invert`, `clamp`, `smoothstep` and `mix`. Maths nodes work on each component of a vector. Every texture
+`fract`, `sqrt`, `invert`, `clamp`, `smoothstep` and `mix`. Mixing nodes: `layer` (`base`, `top`, `mask`, `edge` 0.5, `softness` 0.1) puts `top` over `base` where the mask passes the edge, so `{ "layer": { "base": [0.45, 0.18, 0.06], "top": [0.1, 0.35, 0.7], "mask": chipMask } }` is paint over rust; `hue` (`color`, `shift` in turns, `saturation`, `value`) and `curve` (`value`, 2 to 8 `points` `[x, y]` with rising x, straight segments). Maths nodes work on each component of a vector. Every texture
node takes `at`, a vector expression such as `{ "add": [{ "uv": "both" }, { "mul": [{ "vec": [0.1, 0, 0] }, 1] }] }`, to warp
it. Scales and counts are whole numbers (1 to 64, even for `checker`), so every texture node tiles. `noise` is Blender's Noise Texture
(2D, detail `octaves - 1`, roughness 0.5, lacunarity 2, normalized; `seed` moves the lattice by whole cells) with the lattice
diff --git a/docs/material-maps.md b/docs/material-maps.md
index 3e733cc6..1703bd1b 100644
--- a/docs/material-maps.md
+++ b/docs/material-maps.md
@@ -168,7 +168,7 @@ glTF import and export carry these layers through `KHR_materials_clearcoat`, `tr
## Baked graphs and UV patterns
A recipe material `pattern` of type `graph` bakes a bounded node graph into `map`, `normalMap` (from the graph's height),
-`metallicRoughnessMap` and `emissiveMap`, each only when the graph has that output. With `mapping: "uv"` the descriptors carry
+`metallicRoughnessMap` and `emissiveMap`, each only when the graph has that output; `opacity` goes into the alpha of `map`, `clearcoat` into `layerMaps.clearcoatTexture` and `transmission` into `transmissionMap`. With `mapping: "uv"` the descriptors carry
`boxMapScale: 0`, so the renderer samples every map, the emissive map included, with the geometry's UV channel 0, and GLB
export writes the maps with the authored UVs. With the default `box` mapping the maps are projected along the object axes.
The graph never becomes shader source: the shader gains no code per graph. See "Material graphs" in agent-scene.md.
diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.js
index efc33124..7abbe355 100644
--- a/src/agent-scene-capabilities.js
+++ b/src/agent-scene-capabilities.js
@@ -50,10 +50,11 @@ export const MATERIAL_PATTERN_TYPES =Object.freeze(['noise', 'wood', 'planks', '
export const MAX_MATERIAL_PATTERNS = 16;
// A material graph bakes to textures on the CPU and never becomes shader text. Its node and depth limits are the field
// expression limits; maxWork is work units per pixel times pixels, so a costly graph needs a smaller texture.
-export const MATERIAL_GRAPH_OUTPUTS = Object.freeze(['color', 'roughness', 'metallic', 'emission', 'height']);
+export const MATERIAL_GRAPH_OUTPUTS = Object.freeze(['color', 'roughness', 'metallic', 'emission', 'height', 'opacity', 'clearcoat', 'transmission']);
export const MATERIAL_GRAPH_OPERATORS = Object.freeze([
'uv', 'vec', 'ramp', 'noise', 'voronoi', 'wave', 'checker', 'gradient',
'add', 'sub', 'mul', 'div', 'min', 'max', 'pow', 'abs', 'floor', 'fract', 'sqrt', 'invert', 'clamp', 'smoothstep', 'mix',
+ 'layer', 'hue', 'curve',
]);
export const MATERIAL_GRAPH_LIMITS = Object.freeze({ maxNodes: MAX_FIELD_NODES, maxDepth: MAX_FIELD_DEPTH, maxStops: 8, maxWork: 30_000_000 });
// Curve and text geometry. A text geometry is bounded by vertices per curve segment: the bundled font stays under
@@ -68,7 +69,7 @@ export const CURVE_TEXT_DETAILS = Object.freeze({
});
export const MATERIAL_MAPPINGS = Object.freeze(['box', 'uv']);
export const MATERIAL_GRAPH_NODES = Object.freeze({
- outputs: 'color (linear RGB; a number is grey), roughness, metallic, emission (colour; defaults to 1), height (becomes a normal map).',
+ outputs: 'color (linear RGB; a number is grey), roughness, metallic, emission (colour; defaults to 1), height (becomes a normal map), opacity (base texture alpha; the material blends unless alphaMode says otherwise), clearcoat and transmission (per-pixel masks of the material factors, which default to 1; the path tracer reads both, the rasterizer reads clearcoat only).',
node: 'A number, [x, y, z], or an object with exactly one operator.',
textures: Object.freeze({
noise: '{"noise":{"scale":8,"seed":1,"octaves":4}}',
@@ -80,6 +81,7 @@ export const MATERIAL_GRAPH_NODES = Object.freeze({
}),
uv: '{"uv":"u"|"v"|"both"} are the coordinates.',
ramp: '{"ramp":{"value":node,"stops":[[0,[r,g,b]],[1,[r,g,b]]]}} maps a number to colours, 2 to 8 stops rising from 0 to 1.',
+ mixing: '{"layer":{"base":node,"top":node,"mask":number node,"edge":0.5,"softness":0.1}} puts top over base where mask passes edge (paint over rust); {"hue":{"color":node,"shift":number node (turns),"saturation":1,"value":1}}; {"curve":{"value":node,"points":[[x,y],...]}} remaps by 2 to 8 points with rising x.',
maths: 'add sub mul div min max pow take [a,b]; abs floor fract sqrt invert take one node; clamp smoothstep mix take [a,b,c]; {"vec":[r,g,b]}. Numbers combine with vectors per component.',
example: '{"color":{"ramp":{"value":{"noise":{"scale":8}},"stops":[[0,[0.1,0.05,0.02]],[1,[0.6,0.4,0.2]]]}},"height":{"noise":{"scale":8}}}',
mapping: 'box (default) projects along the object axes and needs no UVs; uv follows geometry UVs, so the mesh needs a uv_unwrap node or geometry.uvs. size and axis only apply to box.',
diff --git a/src/agent-scene.js b/src/agent-scene.js
index 703c4931..0fd4bc1d 100644
--- a/src/agent-scene.js
+++ b/src/agent-scene.js
@@ -28,7 +28,7 @@ const RENDER_FLAG_FIELDS = ['visible', 'castShadow', 'receiveShadow', 'holdout',
const PART_FLAG_FIELDS = RENDER_FLAG_FIELDS.slice(1);
const NODE_FIELDS = ['translation', 'rotation', 'scale', 'parent', 'label', 'geometry', 'material', 'skin', 'relations', 'asset', 'vegetation', 'decal', 'depthLayer', 'blend', ...RENDER_FLAG_FIELDS];
const MATERIAL_FIELDS = ['color', 'metallic', 'roughness', 'emission', 'emissiveColor', 'opacity', 'alphaMode', 'doubleSided', 'pattern', 'map', 'subsurface', 'snippet', 'waterPreset', 'absorption', 'turbidity', ...MATERIAL_LAYER_FIELDS];
-const PATTERN_TEXTURE_FIELDS = ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap', 'boxMapScale', 'boxMapAxis'];
+const PATTERN_TEXTURE_FIELDS = ['map', 'normalMap', 'metallicRoughnessMap', 'emissiveMap', 'layerMaps', 'transmissionMap', 'boxMapScale', 'boxMapAxis'];
const CAMERA_FIELDS = [...Object.keys(CAMERA_DEFAULTS), ...CAMERA_LENS_FIELDS];
const LOOK_OPERATION_FIELDS = Object.freeze({
'set-environment': 'environment',
@@ -200,6 +200,11 @@ function copyMaterialLayers(value, result) {
if (value[field] === undefined) continue;
result[field] = Array.isArray(value[field]) ? vector(value[field], 3, field) : value[field];
}
+ // A graph that outputs clearcoat or transmission is the per-pixel mask, so the factor defaults to 1 (full strength).
+ const graph = value.pattern?.type === 'graph' ? value.pattern.graph : null;
+ for (const field of ['clearcoat', 'transmission']) {
+ if (value[field] === undefined && graph && Object.hasOwn(graph, field)) result[field] = 1;
+ }
validateMaterialLayers(result);
if (value.subsurface !== undefined) result.subsurface = agentSceneModule('subsurfaceShader').copySubsurface(value.subsurface, result.tag);
if (value.snippet) result.snippet = agentSceneModule('materialSnippet').normalizeMaterialSnippet(value.snippet, { hasMap: Boolean(value.map || value.pattern) });
@@ -234,7 +239,9 @@ function materialFrom(value) {
throw new RangeError(`alphaMode must be one of ${RECIPE_ALPHA_MODES.join(', ')}.`);
}
// The renderer ignores opacity on opaque surfaces, so any opacity below one means blending (additive stays additive).
- result.alphaMode = result.opacity < 1 && requestedAlphaMode === 'opaque' ? 'blend' : requestedAlphaMode;
+ // A graph that outputs opacity writes it into the base texture alpha, which only blend, add and mask read.
+ const graphHasOpacity = value.pattern?.type === 'graph' && Object.hasOwn(value.pattern.graph ?? {}, 'opacity');
+ result.alphaMode = (result.opacity < 1 || graphHasOpacity) && requestedAlphaMode === 'opaque' ? 'blend' : requestedAlphaMode;
result.doubleSided = defaultValue(value.doubleSided, false);
if (typeof result.doubleSided !== 'boolean') {
throw new TypeError('doubleSided must be boolean.');
diff --git a/src/material-graph.js b/src/material-graph.js
index 96b81a1e..71b1c9bd 100644
--- a/src/material-graph.js
+++ b/src/material-graph.js
@@ -334,6 +334,105 @@ function compileMath(name, node, state, depth) {
return liftComponentwise(operands.map(operand => compileNode(operand, state, depth + 1)), compute);
}
+// ---------------------------------------------------------------------------------------------------------------
+// Mixing nodes: a layer put over another where a mask passes, a hue shift and a curve.
+
+function compileScalarInput(node, state, depth, label) {
+ const compiled = compileNode(node, state, depth + 1);
+ if (compiled.kind !== 'scalar') throw graphError(`${label} needs a number.`);
+ return compiled;
+}
+
+function compileLayer(node, state, depth) {
+ const settings = textureSettings(node, 'layer', ['base', 'top', 'mask', 'edge', 'softness']);
+ for (const required of ['base', 'top', 'mask']) {
+ if (settings[required] === undefined) throw graphError(`layer needs "${required}".`);
+ }
+ const edge = settings.edge ?? 0.5;
+ const softness = settings.softness ?? 0.1;
+ if (!finiteLiteral(edge) || !finiteLiteral(softness) || softness < 0) throw graphError('layer edge is a number and softness a number from 0.');
+ const base = compileNode(settings.base, state, depth + 1);
+ const top = compileNode(settings.top, state, depth + 1);
+ const mask = compileScalarInput(settings.mask, state, depth, 'layer "mask"');
+ const coverage = scalarValue((u, v) => {
+ const value = mask.evaluate(u, v);
+ return softness === 0 ? (value >= edge ? 1 : 0) : smoothStep(edge - softness, edge + softness, value);
+ });
+ return liftComponentwise([base, top, coverage], mixNumbers);
+}
+
+function rgbToHsv(red, green, blue) {
+ const high = Math.max(red, green, blue);
+ const spread = high - Math.min(red, green, blue);
+ let hue = 0;
+ if (spread > 0) {
+ if (high === red) hue = ((green - blue) / spread + 6) % 6;
+ else if (high === green) hue = (blue - red) / spread + 2;
+ else hue = (red - green) / spread + 4;
+ }
+ return [hue / 6, high === 0 ? 0 : spread / high, high];
+}
+
+function hsvToRgb(hue, saturation, value) {
+ const channel = offset => {
+ const sector = (offset + hue * 6) % 6;
+ return value * (1 - saturation * Math.max(0, Math.min(sector, 4 - sector, 1)));
+ };
+ return [channel(5), channel(3), channel(1)];
+}
+
+function compileHue(node, state, depth) {
+ const settings = textureSettings(node, 'hue', ['color', 'shift', 'saturation', 'value']);
+ const saturation = settings.saturation ?? 1;
+ const brightness = settings.value ?? 1;
+ for (const factor of [saturation, brightness]) {
+ if (typeof factor !== 'number' || !Number.isFinite(factor) || factor < 0 || factor > 4) throw graphError('hue saturation and value are numbers from 0 to 4.');
+ }
+ const color = compileNode(settings.color, state, depth + 1);
+ if (color.kind !== 'vector') throw graphError('hue "color" needs a colour such as [r, g, b].');
+ const shift = compileScalarInput(settings.shift ?? 0, state, depth, 'hue "shift"');
+ state.cost += 4;
+ const [red, green, blue] = color.parts;
+ // The three channels read the same pixel in a row, so the last result is kept instead of converting three times.
+ let lastU = NaN;
+ let lastV = NaN;
+ let lastResult = [0, 0, 0];
+ const shifted = (u, v) => {
+ if (u !== lastU || v !== lastV) {
+ const [hue, sourceSaturation, sourceValue] = rgbToHsv(finiteOrZero(red(u, v)), finiteOrZero(green(u, v)), finiteOrZero(blue(u, v)));
+ lastResult = hsvToRgb(fract(hue + finiteOrZero(shift.evaluate(u, v))), clampUnit(sourceSaturation * saturation), sourceValue * brightness);
+ lastU = u;
+ lastV = v;
+ }
+ return lastResult;
+ };
+ return vectorValue((u, v) => shifted(u, v)[0], (u, v) => shifted(u, v)[1], (u, v) => shifted(u, v)[2]);
+}
+
+function compileCurve(node, state, depth) {
+ const settings = textureSettings(node, 'curve', ['value', 'points']);
+ const { points } = settings;
+ if (!Array.isArray(points) || points.length < 2 || points.length > MATERIAL_GRAPH_LIMITS.maxStops) throw graphError(`curve needs 2 to ${MATERIAL_GRAPH_LIMITS.maxStops} points.`);
+ let previousX = -Infinity;
+ for (const point of points) {
+ if (!Array.isArray(point) || point.length !== 2 || !point.every(finiteLiteral) || point[0] <= previousX) throw graphError('curve points are [x, y] with x rising.');
+ previousX = point[0];
+ }
+ const remap = input => {
+ if (input <= points[0][0]) return points[0][1];
+ for (let index = 1; index < points.length; index++) {
+ if (input <= points[index][0]) {
+ const [fromX, fromY] = points[index - 1];
+ const [toX, toY] = points[index];
+ return mixNumbers(fromY, toY, (input - fromX) / (toX - fromX));
+ }
+ }
+ return points[points.length - 1][1];
+ };
+ state.cost += 2;
+ return liftComponentwise([compileNode(settings.value, state, depth + 1)], remap);
+}
+
const TEXTURE_COMPILERS = new Map([
['noise', compileNoise], ['voronoi', compileVoronoi], ['wave', compileWave], ['checker', compileChecker], ['gradient', compileGradient],
]);
@@ -359,12 +458,15 @@ function compileNode(node, state, depth) {
if (name === 'uv') return compileCoordinates(node);
if (name === 'vec') return compileVector(node, state, depth);
if (name === 'ramp') return compileRamp(node, state, depth);
+ if (name === 'layer') return compileLayer(node, state, depth);
+ if (name === 'hue') return compileHue(node, state, depth);
+ if (name === 'curve') return compileCurve(node, state, depth);
if (TEXTURE_COMPILERS.has(name)) return TEXTURE_COMPILERS.get(name)(node, state, depth);
if (MATH_OPERATORS.has(name)) return compileMath(name, node, state, depth);
throw graphError(`unknown operator ${describeKey(name)}. Use one of ${MATERIAL_GRAPH_OPERATORS.join(', ')}.`);
}
-const SCALAR_OUTPUTS = ['roughness', 'metallic', 'height'];
+const SCALAR_OUTPUTS = ['roughness', 'metallic', 'height', 'opacity', 'clearcoat', 'transmission'];
/**
* Check a graph and compile each output. Limits on nodes, depth and work per pixel are enforced here, before any
@@ -410,6 +512,14 @@ function sampleChannels(compiled, u, v) {
return [finiteOrZero(compiled.parts[0](u, v)), finiteOrZero(compiled.parts[1](u, v)), finiteOrZero(compiled.parts[2](u, v))];
}
+const unitByte = value => Math.round(clampUnit(finiteOrZero(value)) * 255);
+
+// A mask is read from the red channel, as glTF reads clearcoatTexture and transmissionTexture.
+function writeMask(data, offset, value) {
+ data[offset] = unitByte(value);
+ data[offset + 3] = 255;
+}
+
function writeColor(data, offset, channels) {
for (let channel = 0; channel < 3; channel++) data[offset + channel] = linearToSrgbByte(channels[channel]);
data[offset + 3] = 255;
@@ -419,9 +529,12 @@ function writeColor(data, offset, channels) {
export function bakeMaterialGraph(graph, { resolution, bump }) {
const compiled = compileMaterialGraph(graph);
checkMaterialGraphWork(compiled, resolution);
- const { color, roughness, metallic, emission, height } = compiled.outputs;
+ const { color, roughness, metallic, emission, height, opacity, clearcoat, transmission } = compiled.outputs;
const pixelCount = resolution * resolution;
- const colorData = color ? new Uint8ClampedArray(pixelCount * 4) : null;
+ // Opacity travels in the alpha of the base texture, so an opacity-only graph still gets a (white) base texture.
+ const colorData = color || opacity ? new Uint8ClampedArray(pixelCount * 4).fill(255) : null;
+ const clearcoatData = clearcoat ? new Uint8ClampedArray(pixelCount * 4) : null;
+ const transmissionData = transmission ? new Uint8ClampedArray(pixelCount * 4) : null;
const emissionData = emission ? new Uint8ClampedArray(pixelCount * 4) : null;
const surfaceData = roughness || metallic ? new Uint8ClampedArray(pixelCount * 4) : null;
for (let row = 0; row < resolution; row++) {
@@ -431,6 +544,9 @@ export function bakeMaterialGraph(graph, { resolution, bump }) {
const v = (row + 0.5) / resolution;
const offset = pixel * 4;
if (color) writeColor(colorData, offset, sampleChannels(color, u, v));
+ if (opacity) colorData[offset + 3] = unitByte(opacity.evaluate(u, v));
+ if (clearcoat) writeMask(clearcoatData, offset, clearcoat.evaluate(u, v));
+ if (transmission) writeMask(transmissionData, offset, transmission.evaluate(u, v));
if (emission) writeColor(emissionData, offset, sampleChannels(emission, u, v));
if (surfaceData) {
surfaceData[offset] = 255;
@@ -445,6 +561,9 @@ export function bakeMaterialGraph(graph, { resolution, bump }) {
map: descriptor(colorData, 'srgb'),
emissiveMap: descriptor(emissionData, 'srgb'),
metallicRoughnessMap: descriptor(surfaceData, 'linear'),
+ // The rasterizer binds clearcoatTexture from layerMaps; transmission has no layer slot, so the tracer reads transmissionMap.
+ layerMaps: clearcoatData ? { clearcoatTexture: descriptor(clearcoatData, 'linear') } : undefined,
+ transmissionMap: descriptor(transmissionData, 'linear'),
normalMap: descriptor(height ? normalMapFromHeightFunction((u, v) => finiteOrZero(height.evaluate(u, v)), resolution, bump) : null, 'linear'),
};
}
diff --git a/src/material-layer-shaders.js b/src/material-layer-shaders.js
index 6b4909e1..4e9220ab 100644
--- a/src/material-layer-shaders.js
+++ b/src/material-layer-shaders.js
@@ -216,7 +216,7 @@ uniform float ${name}On;
registerShaderFeatureCode('clearcoatTexture', Object.freeze({
declarations: textureUniforms('clearcoatTexture') + COAT_STATE_DECLARATIONS,
- mainSetup: COAT_STATE_SETUP + ` if (clearcoatTextureOn > 0.5) coatState.x *= texture(clearcoatTexture, textureUV).r;
+ mainSetup: COAT_STATE_SETUP + ` if (clearcoatTextureOn > 0.5) coatState.x *= (BOX_MAPPED ? sampleBox(clearcoatTexture) : texture(clearcoatTexture, textureUV)).r;
`,
}));
diff --git a/src/path-tracer-scene.js b/src/path-tracer-scene.js
index 4259f572..314c5728 100644
--- a/src/path-tracer-scene.js
+++ b/src/path-tracer-scene.js
@@ -115,6 +115,12 @@ function resolveTexture(descriptor) {
// A part without a mask is lit by every light.
const ALL_LIGHTS = -1;
+// A graph opacity output is texture alpha on a blended material. The tracer has no blending, so it cuts out at half.
+function graphOpacityCutoff(material) {
+ const graph = material.pattern?.type === 'graph' ? material.pattern.graph : null;
+ return material.alphaMode === 'blend' && graph && Object.hasOwn(graph, 'opacity') ? 0.5 : 0;
+}
+
function resolveMaterial(material) {
const emissionColor = material.emissiveColor ?? material.color;
const emissionStrength = material.emission ?? 0;
@@ -125,6 +131,8 @@ function resolveMaterial(material) {
emission: emissionColor.map(channel => channel * emissionStrength),
emissiveTexture: emissionStrength > 0 ? resolveTexture(material.emissiveMap) : null,
clearcoat: material.clearcoat ?? 0,
+ clearcoatTexture: resolveTexture(material.layerMaps?.clearcoatTexture),
+ transmissionTexture: resolveTexture(material.transmissionMap),
clearcoatRoughness: material.clearcoatRoughness ?? 0,
transmission: material.transmission ?? 0,
subsurface: resolveTraceSubsurface(material.subsurface),
@@ -134,7 +142,7 @@ function resolveMaterial(material) {
normalScale: material.normalScale ?? [1, 1],
surfaceTexture: resolveTexture(material.metallicRoughnessMap),
lightMask: material.lightMask ?? ALL_LIGHTS,
- alphaCutoff: material.alphaMode === 'mask' ? material.alphaCutoff ?? 0.5 : 0,
+ alphaCutoff: material.alphaMode === 'mask' ? material.alphaCutoff ?? 0.5 : graphOpacityCutoff(material),
};
}
diff --git a/src/path-tracer-shading.js b/src/path-tracer-shading.js
index 8346fdc6..34a27533 100644
--- a/src/path-tracer-shading.js
+++ b/src/path-tracer-shading.js
@@ -224,7 +224,7 @@ function dielectricSpecularAlbedo(normalReflectance, roughness, viewCosine) {
* the light its reflection did not take, so the diffuse colour shrinks with the Fresnel term, and a clear coat takes
* its share from both lobes below it.
*/
-export function prepareSurface(surface, material, metallic, roughness, baseColor, normal, viewX, viewY, viewZ) {
+export function prepareSurface(surface, material, metallic, roughness, baseColor, normal, viewX, viewY, viewZ, clearcoat = material.clearcoat) {
buildFrame(normal, surface.frame);
surface.view[0] = viewX;
surface.view[1] = viewY;
@@ -234,7 +234,7 @@ export function prepareSurface(surface, material, metallic, roughness, baseColor
const ratio = (material.ior - 1) / (material.ior + 1);
const dielectricNormalReflectance = ratio * ratio;
const dielectricFresnel = dielectricSpecularAlbedo(dielectricNormalReflectance, roughness, viewCosine);
- surface.coatWeight = material.clearcoat > 0 ? material.clearcoat * schlick(DIELECTRIC_COAT_REFLECTANCE, viewCosine) : 0;
+ surface.coatWeight = clearcoat > 0 ? clearcoat * schlick(DIELECTRIC_COAT_REFLECTANCE, viewCosine) : 0;
const underCoat = 1 - surface.coatWeight;
const diffuseShare = (1 - metallic) * (1 - dielectricFresnel) * underCoat;
for (let channel = 0; channel < 3; channel++) {
diff --git a/src/path-tracer.js b/src/path-tracer.js
index f5721f48..ca0c81ea 100644
--- a/src/path-tracer.js
+++ b/src/path-tracer.js
@@ -47,10 +47,14 @@ const IGNORED_LAYERS = [
['iridescence', material => material.iridescence > 0],
['sheen', material => (material.sheenColor ?? []).some(channel => channel !== 0)],
['moss', material => material.moss > 0],
- ['splat layers', material => Boolean(material.layers || material.layerMaps)],
+ ['splat layers', material => Boolean(material.layers || Object.keys(material.layerMaps ?? {}).some(name => name !== 'clearcoatTexture'))],
['lightMap', material => Boolean(material.lightMap)],
];
+function hasGraphOpacity(material) {
+ return material.pattern?.type === 'graph' && Object.hasOwn(material.pattern.graph ?? {}, 'opacity');
+}
+
function boundedInteger(options, name) {
const limit = PATH_TRACER_LIMITS[name];
const value = options[name] ?? limit.fallback;
@@ -183,7 +187,7 @@ function createHit() {
distance: 0, material: null,
point: new Float64Array(3), normal: new Float64Array(3), color: new Float64Array(3),
texel: new Float64Array(4), mapTexel: new Float64Array(4), emission: new Float64Array(3),
- metallic: 0, roughness: 0,
+ metallic: 0, roughness: 0, clearcoat: 0, transmission: 0,
};
}
@@ -358,6 +362,16 @@ function fillHit(scene, triangleId, originX, originY, originZ, directionX, direc
}
hit.metallic = material.metallic;
hit.roughness = material.roughness;
+ hit.clearcoat = material.clearcoat;
+ hit.transmission = material.transmission;
+ if (material.clearcoatTexture) {
+ sampleTexture(material.clearcoatTexture, u, v, hit.mapTexel);
+ hit.clearcoat *= hit.mapTexel[0];
+ }
+ if (material.transmissionTexture) {
+ sampleTexture(material.transmissionTexture, u, v, hit.mapTexel);
+ hit.transmission *= hit.mapTexel[0];
+ }
if (material.surfaceTexture) {
sampleTexture(material.surfaceTexture, u, v, hit.mapTexel);
hit.roughness *= hit.mapTexel[1];
@@ -836,7 +850,7 @@ function createPathTracer(scene, options) {
normal[0] = hit.normal[0] * facing;
normal[1] = hit.normal[1] * facing;
normal[2] = hit.normal[2] * facing;
- const isGlass = material.transmission > 0 && random.next() < material.transmission;
+ const isGlass = hit.transmission > 0 && random.next() < hit.transmission;
if (!featuresRecorded) {
recordFeatures(normal, isGlass);
featuresRecorded = true;
@@ -856,7 +870,7 @@ function createPathTracer(scene, options) {
}
afterMirror = true;
} else {
- prepareSurface(surface, material, hit.metallic, hit.roughness, hit.color, normal, viewX, viewY, viewZ);
+ prepareSurface(surface, material, hit.metallic, hit.roughness, hit.color, normal, viewX, viewY, viewZ, hit.clearcoat);
const subsurface = material.subsurface;
if (subsurface) splitSubsurface(surface, subsurface.weight);
addLights(depth, normal);
@@ -921,7 +935,8 @@ export function describeIgnoredFeatures(parts, environment) {
const material = part.material ?? {};
for (const field of IGNORED_MAP_FIELDS) if (material[field]) notes.add(`${field} is ignored.`);
if (material.tag && material.tag !== 'surface') notes.add(`${material.tag} materials are traced as plain surfaces.`);
- if (material.alphaMode === 'blend') notes.add('Blended transparency is traced as opaque.');
+ if (material.alphaMode === 'blend') notes.add(hasGraphOpacity(material) ? 'A graph opacity output is traced as a cutout at 0.5.' : 'Blended transparency is traced as opaque.');
+ if (material.layerMaps?.clearcoatTexture || material.transmissionMap) notes.add('Graph clearcoat and transmission masks are read by the CPU tracer; the GPU tracers use the factors.');
for (const [name, isUsed] of IGNORED_LAYERS) if (isUsed(material)) notes.add(`${name} is ignored.`);
}
return [...notes];
diff --git a/tests/material-graph-mixing.test.js b/tests/material-graph-mixing.test.js
new file mode 100644
index 00000000..c200b537
--- /dev/null
+++ b/tests/material-graph-mixing.test.js
@@ -0,0 +1,117 @@
+import './support/load-agent-scene-modules.mjs';
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { bakeMaterialPattern, normalizeMaterialPattern } from '../src/material-patterns.js';
+import { compileMaterialGraph } from '../src/material-graph.js';
+import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene-capabilities.js';
+import { createAgentScene } from '../src/agent-scene.js';
+import { describeIgnoredFeatures } from '../src/path-tracer.js';
+
+const RUST = [0.45, 0.18, 0.06];
+const PAINT = [0.1, 0.35, 0.7];
+const chippedPaint = { curve: { value: { noise: { scale: 6, seed: 4 } }, points: [[0.2, 0], [0.8, 1]] } };
+
+// Blue paint over rust: the paint covers where the chip mask is high, rust shows through where it chipped.
+const paintedOverRust = {
+ color: { layer: { base: RUST, top: PAINT, mask: chippedPaint, edge: 0.5, softness: 0.05 } },
+ roughness: { layer: { base: 0.95, top: 0.3, mask: chippedPaint, edge: 0.5, softness: 0.05 } },
+ clearcoat: { layer: { base: 0, top: 1, mask: chippedPaint, edge: 0.5, softness: 0.05 } },
+};
+
+function evaluate(graph, output, u = 0.3, v = 0.6) {
+ const compiled = compileMaterialGraph(graph).outputs[output];
+ return compiled.kind === 'vector' ? compiled.parts.map(part => part(u, v)) : compiled.evaluate(u, v);
+}
+
+test('layer puts the top over the base where the mask passes the edge', () => {
+ const graph = mask => ({ color: { layer: { base: [1, 0, 0], top: [0, 0, 1], mask, edge: 0.5, softness: 0 } } });
+ assert.deepEqual(evaluate(graph(0.2), 'color'), [1, 0, 0]);
+ assert.deepEqual(evaluate(graph(0.9), 'color'), [0, 0, 1]);
+ assert.throws(() => compileMaterialGraph({ color: { layer: { base: 1, top: 0 } } }), /needs "mask"/);
+ assert.throws(() => compileMaterialGraph({ color: { layer: { base: 1, top: 0, mask: [1, 1, 1] } } }), /mask" needs a number/);
+});
+
+test('hue shifts a colour around the wheel and curve remaps with straight segments', () => {
+ const [red, green, blue] = evaluate({ color: { hue: { color: [1, 0, 0], shift: 1 / 3 } } }, 'color');
+ assert.ok(green > 0.99 && red < 0.01 && blue < 0.01);
+ assert.deepEqual(evaluate({ color: { hue: { color: [0.5, 0.5, 0.5], shift: 0.4 } } }, 'color'), [0.5, 0.5, 0.5]);
+ const curve = value => evaluate({ height: { curve: { value, points: [[0, 0], [0.5, 1], [1, 0.5]] } } }, 'height');
+ assert.equal(curve(0.25), 0.5);
+ assert.equal(curve(0.75), 0.75);
+ assert.equal(curve(-3), 0);
+ assert.throws(() => compileMaterialGraph({ height: { curve: { value: 0.5, points: [[0, 0], [0, 1]] } } }), /x rising/);
+});
+
+test('opacity bakes into base texture alpha, clearcoat and transmission into red channel masks', () => {
+ const baked = bakeMaterialPattern(normalizeMaterialPattern({
+ type: 'graph', resolution: 256,
+ graph: { color: PAINT, opacity: { uv: 'u' }, clearcoat: { uv: 'v' }, transmission: 0.5 },
+ }));
+ const pixel = (descriptor, column, row) => descriptor.image.data.slice((row * 256 + column) * 4, (row * 256 + column) * 4 + 4);
+ assert.equal(pixel(baked.map, 0, 100)[3], 0);
+ assert.ok(pixel(baked.map, 255, 100)[3] >= 254);
+ assert.equal(pixel(baked.layerMaps.clearcoatTexture, 10, 0)[0], 0);
+ assert.ok(pixel(baked.layerMaps.clearcoatTexture, 10, 255)[0] >= 254);
+ assert.equal(pixel(baked.transmissionMap, 10, 10)[0], 128);
+ assert.equal(baked.layerMaps.clearcoatTexture.colorSpace, 'linear');
+ const opacityOnly = bakeMaterialPattern(normalizeMaterialPattern({ type: 'graph', resolution: 256, graph: { opacity: 0.5 } }));
+ assert.deepEqual([...pixel(opacityOnly.map, 3, 3)], [255, 255, 255, 128]);
+ assert.equal(opacityOnly.layerMaps, undefined);
+});
+
+test('a painted-over-rust material renders from one recipe', () => {
+ const recipe = {
+ format: '67js.scene', schemaVersion: 1,
+ materials: [{ id: 'worn-paint', pattern: { type: 'graph', graph: paintedOverRust, resolution: 256 } }],
+ geometries: [{ id: 'panel', type: 'mesh', base: { type: 'box', bevel: 0 } }],
+ nodes: [{ id: 'panel', geometry: 'panel', material: 'worn-paint' }],
+ };
+ const { material } = createAgentScene(recipe).parts[0];
+ assert.equal(material.clearcoat, 1);
+ assert.equal(material.roughness, 1);
+ assert.ok(material.layerMaps.clearcoatTexture.image);
+ const data = material.map.image.data;
+ let rustPixels = 0;
+ let paintPixels = 0;
+ for (let index = 0; index < data.length; index += 4) {
+ if (data[index] > data[index + 2]) rustPixels++;
+ else paintPixels++;
+ }
+ assert.ok(rustPixels > 1000 && paintPixels > 1000, `both layers show: rust ${rustPixels}, paint ${paintPixels}`);
+ const coat = material.layerMaps.clearcoatTexture.image.data;
+ const roughness = material.metallicRoughnessMap.image.data;
+ let checked = 0;
+ for (let index = 0; index < coat.length; index += 4 * 97) {
+ // Pixels inside the soft edge blend both layers, so only fully covered or fully chipped ones are compared.
+ if (coat[index] !== 0 && coat[index] !== 255) continue;
+ const painted = coat[index] === 255;
+ assert.equal(data[index] < data[index + 2], painted, 'paint is blue, rust is red');
+ assert.equal(roughness[index + 1] < 128, painted, 'the paint is smoother than the rust');
+ checked++;
+ }
+ assert.ok(checked > 100);
+});
+
+test('opacity blends the material, and the tracer cuts it out and says what it ignores', () => {
+ const recipe = {
+ format: '67js.scene', schemaVersion: 1,
+ materials: [{ id: 'veil', pattern: { type: 'graph', graph: { color: PAINT, opacity: { uv: 'u' }, transmission: 0.5 }, resolution: 256 } }],
+ geometries: [{ id: 'panel', type: 'mesh', base: { type: 'box', bevel: 0 } }],
+ nodes: [{ id: 'panel', geometry: 'panel', material: 'veil' }],
+ };
+ const { parts } = createAgentScene(recipe);
+ assert.equal(parts[0].material.alphaMode, 'blend');
+ assert.equal(parts[0].material.transmission, 1);
+ const notes = describeIgnoredFeatures(parts, {});
+ assert.ok(notes.some(note => /graph opacity output is traced as a cutout/.test(note)));
+ assert.ok(notes.some(note => /clearcoat and transmission masks are read by the CPU tracer/.test(note)));
+});
+
+test('scene_capabilities lists the new outputs and mixing nodes', () => {
+ const { outputs, operators, nodes } = AGENT_SCENE_CAPABILITIES.materialGraph;
+ for (const name of ['opacity', 'clearcoat', 'transmission']) assert.ok(outputs.includes(name), name);
+ for (const name of ['layer', 'hue', 'curve']) {
+ assert.ok(operators.includes(name), name);
+ assert.ok(nodes.mixing.includes(`"${name}"`), name);
+ }
+});
diff --git a/tests/material-graph.test.js b/tests/material-graph.test.js
index 388c58e1..54d293f6 100644
--- a/tests/material-graph.test.js
+++ b/tests/material-graph.test.js
@@ -179,6 +179,7 @@ test('every capability operator compiles, and no other operator does', () => {
const samples = {
uv: { uv: 'u' }, vec: { vec: [1, 2, 3] }, ramp: { ramp: { value: 0.5, stops: [[0, 0], [1, 1]] } },
noise: { noise: {} }, voronoi: { voronoi: {} }, wave: { wave: {} }, checker: { checker: {} }, gradient: { gradient: {} },
+ layer: { layer: { base: [0, 0, 0], top: [1, 1, 1], mask: 0.5 } }, hue: { hue: { color: [1, 0, 0], shift: 0.1 } }, curve: { curve: { value: 0.5, points: [[0, 0], [1, 1]] } },
};
for (const name of MATERIAL_GRAPH_OPERATORS) {
const node = samples[name] ?? (['abs', 'floor', 'fract', 'sqrt', 'invert'].includes(name) ? { [name]: 0.5 } : { [name]: [0.2, 0.4, 0.6].slice(0, ['clamp', 'smoothstep', 'mix'].includes(name) ? 3 : 2) });