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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 texturenode takes `at`, a vector expression such as `{ "add": [{ "uv": "both" }, { "mul": [{ "vec": [0.1, 0, 0] }, 1] }] }`, to warpit. 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 latticediff --git a/docs/material-maps.md b/docs/material-maps.mdindex 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 patternsA 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 GLBexport 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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, baseColorconst 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.jsindex 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.jsnew file mode 100644index 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.jsindex 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) });