3D engine that AI agents drive
Widen specular highlights from normal-map detail to stop sparkle (#588)
Nguyen Xuan Ane3cd4e442fe0
diff --git a/changes/588.md b/changes/588.mdnew file mode 100644index 00000000..3d66d73f--- /dev/null+++ b/changes/588.md@@ -0,0 +1 @@+Metal with detailed normal and roughness maps no longer sparkles from frame to frame at grazing angles; `environment.specularAntiAliasing` sets the strength (#588)diff --git a/changes/588.size.md b/changes/588.size.mdnew file mode 100644index 00000000..194a85e6--- /dev/null+++ b/changes/588.size.md@@ -0,0 +1,9 @@+- entry:core: the Kaplanyan-Hoffman and Toksvig terms in the lit fragment shader plus the strength uniform and its validation; fixes visible frame-to-frame sparkle on normal-mapped metal (flips over 40/255 fell by 73 percent), accepted under the trade-off rule.+- scene:lit-box: the same shader and uniform code, about 215 bytes.+- scene:gltf-box: the same shader and uniform code, about 217 bytes.+- scene:gltf-box+lazy: same code as scene:gltf-box.+- scene:agent-scene: the same shader code plus the environment field, about 242 bytes.+- scene:agent-scene+lazy: same code as scene:agent-scene.+- goal:lit-box: about 215 bytes for a visible specular anti-aliasing fix, accepted by the lead under the trade-off rule.+- goal:gltf-box: about 217 bytes for the same fix.+- goal:agent-scene: about 242 bytes for the same fix and its recipe field.diff --git a/docs/agent-look.md b/docs/agent-look.mdindex 32feeb55..a816b290 100644--- a/docs/agent-look.md+++ b/docs/agent-look.md@@ -110,6 +110,7 @@ Sky colors use display RGB, matching the renderer's existing environment contrac| `resolveCoplanar` | off | `'offset'` puts the smaller part of each coplanar pair (see the `coplanar-overlap` warning) on the next depth layer, drawn with a polygon offset; `false` or absent leaves parts as authored. Geometry never moves. Parts that set `decal` or `depthLayer` keep their own || `objectReflections` | on | Absent unless set. Each smooth metal part (`metallic` 0.5 or more, `roughness` 0.6 or less; at most 8 such parts) gets a reflection probe of the scene around it, so a chrome sphere shows the floor and its neighbours. `false` turns it off. Probes are traced at rest, so a part that moves reflects the scene as it started. `scene_inspect` names them in `reflections` || `floorSkyTrace` | on | Absent unless set. A closed room a sun lights gets the sky each floor texel sees traced into its floor (`applyFloorSkyVisibility`, strength 0.2), so shadowed floors under a roof or between walls get less world and sky light; it makes the dark end of halls closer to Cycles. Open scenes and rooms lit by lamps alone are left as they are. `false` turns it off; a value that is not a boolean is refused. It loads lazily with a recipe that names its sun (`keyColor` or `keyIntensity`), costs about 1 s of trace when the scene is built and adds triangles to the floor (0.1 to 0.4 ms per frame in the reference halls). |+| `specularAntiAliasing` | `1` | Absent unless set. `0` to `4`. Widens highlights where the shading normal or normal map detail changes within a pixel (geometric specular anti-aliasing plus a Toksvig term read from the filtered normal map length), so grainy or scanned metal stops sparkling from frame to frame at grazing angles. `0` gives a highlight that follows every texel; above `1` is softer. || `sunBounce` | `1` | Absent unless set. A number of 0 or more. A closed room a sun lights gets a few point lights at its sunlit patches (`withSunBounce`, found when the scene is prepared), so the floor, walls and pillars around a patch are lit by the light it bounces and the far end of the room less. `0` turns it off and gives the look without it; `1` is fitted to Cycles; above `1` is stronger. A value that is not a number of 0 or more is refused. Open scenes and rooms with no sun are left as they are. It loads lazily with the sun, and the lights take up to 6 of the 16 point light slots. || `setup` | `daylight` | `daylight`, `overcast`, `sunset` or `studio`. See Lighting setups || `environmentIntensity` | `1` | `0` to `100`. Scales the setup's environment light and reflections |diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex c78266a0..3fcf00c8 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -231,6 +231,7 @@ const environment = z.strictObject({objectReflections: z.boolean().optional().describe("false turns off reflection probes on smooth metal parts."),floorSkyTrace: z.boolean().optional().describe('false turns off the sky traced into floors of sun-lit closed rooms.'),sunBounce: z.number().min(0).optional().describe('Sun bounce in a closed room: 0 off, 1 default.'),+ specularAntiAliasing: z.number().min(0).max(4).optional().describe('Specular anti-aliasing: 0 off, 1 default; widens highlights that sparkle on grainy normal-mapped metal.'),resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),look: z.enum(LOOK_NAMES).nullable().optional().describe('Named look preset; null clears.'),diff --git a/src/agent-look.js b/src/agent-look.jsindex a9e504f8..072e06e3 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -1,5 +1,5 @@import { mat4 } from 'gl-matrix';-import { createLightingState, updateLightingState, MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from './lighting.js';+import { createLightingState, updateLightingState, MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS, MAXIMUM_SPECULAR_ANTI_ALIASING } from './lighting.js';import { resolveEffects } from './effects.js';import { resolveVolumeFog } from './volumetric.js';import { LIQUID_OPTICS, resolveLiquidOptics } from './liquid-optics.js';@@ -13,7 +13,7 @@ const MAX_LOOK_ARRAY_ENTRIES = Math.max(MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_Aconst ENVIRONMENT_FIELDS = ['world', 'ground', 'setup', 'environmentIntensity', 'environmentRotation', 'lightDirection', 'keyColor', 'keyIntensity', 'fillIntensity', 'ambientIntensity',- 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',+ 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',];const EFFECT_FIELDS = ['exposure', 'saturation', 'contrast', 'temperature', 'vignette', 'grain', 'ambientOcclusion', 'ambientOcclusionRadius', 'bloom', 'depthOfField', 'motionBlur'];const SHADOW_FIELDS = ['target', 'extent', 'distance', 'near', 'far'];@@ -286,6 +286,10 @@ function environmentFrom(input = {}) {}environment.sunBounce = input.sunBounce;}+ // Strength of the specular anti-aliasing that widens highlights where normals or normal map detail change within a pixel (src/lighting.js); 0 turns it off.+ if (input.specularAntiAliasing !== undefined) {+ environment.specularAntiAliasing = numberInRange(input.specularAntiAliasing, 0, MAXIMUM_SPECULAR_ANTI_ALIASING, 'specularAntiAliasing');+ }// Outlines and line geometry; null clears them. The module checks the fields and loads on demand.if (input.lines !== undefined && input.lines !== null) {environment.lines = copiedJson(agentSceneModule('lineArt').resolveLineArt(input.lines));diff --git a/src/agent-scene.js b/src/agent-scene.jsindex 736cf89b..0723ec62 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -1424,7 +1424,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {knownKeys(operation, ['type', lookField], 'operation');const patch = operation[lookField];// Spot and area lights, cascades and sun links are absent from a recipe until it sets them.- const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];+ const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'specularAntiAliasing', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];knownKeys(patch, [...Object.keys(candidate[lookField]), ...optionalFields], lookField);const nestedField = lookField === 'environment' ? 'volumeFog' : lookField === 'effects' ? 'bloom' : null;const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };diff --git a/src/lighting.js b/src/lighting.jsindex 56b6fde8..17fd32ce 100644--- a/src/lighting.js+++ b/src/lighting.js@@ -1,6 +1,9 @@import { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from './light-limits.js';export { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS };+export const DEFAULT_SPECULAR_ANTI_ALIASING = 1;+export const MAXIMUM_SPECULAR_ANTI_ALIASING = 4;+// One 2048 x 3072 depth atlas holds 24 tiles of 512 x 512 (24 MiB). A shadowed spot light uses one tile and a shadowed point// light uses six, one for each cube face.export const SHADOW_ATLAS_TILES = 24;@@ -122,6 +125,7 @@ export function createLightingState() {areaCount: 0,fillIntensity: 1,ambientIntensity: 1,+ specularAntiAliasing: DEFAULT_SPECULAR_ANTI_ALIASING,};}@@ -203,6 +207,7 @@ export function updateLightingState(state, environment, { world = false } = {})const fillIntensity = numberInRange(environment.fillIntensity ?? 1, 0, 100, 'Fill intensity');const ambientIntensity = numberInRange(environment.ambientIntensity ?? 1, 0, 100, 'Ambient intensity');const daylight = numberInRange(environment.daylight ?? 1, 0, 100, 'Daylight');+ const specularAntiAliasing = numberInRange(environment.specularAntiAliasing ?? DEFAULT_SPECULAR_ANTI_ALIASING, 0, MAXIMUM_SPECULAR_ANTI_ALIASING, 'Specular anti-aliasing');const keyColor = environment.keyColor ?? (world ? [3.7 * daylight, 3.4 * daylight, 2.9 * daylight] : [5.2, 4.7, 4.1]);vectorInRange(keyColor, 0, 1000, 'Key color');pointLights.forEach(validatePointLight);@@ -219,5 +224,6 @@ export function updateLightingState(state, environment, { world = false } = {})state.areaCount = areaLights.length;state.fillIntensity = fillIntensity;state.ambientIntensity = ambientIntensity;+ state.specularAntiAliasing = specularAntiAliasing;return state;}diff --git a/src/renderer.js b/src/renderer.jsindex 857509e4..7154d183 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -127,7 +127,7 @@ const LOCAL_SHADOW_UNIT = 15;const LIGHT_UNIFORMS = ['pointLightCount', 'pointLightPositions[0]', 'pointLightColors[0]', 'pointLightRadii[0]', 'pointLightShadowTiles[0]','spotLightCount', 'spotLightPositions[0]', 'spotLightColors[0]', 'spotLightDirections[0]', 'spotLightParameters[0]','areaLightCount', 'areaLightPositions[0]', 'areaLightColors[0]', 'areaLightNormals[0]', 'areaLightTangents[0]',- 'localShadowAtlas', 'localShadowMatrices[0]', 'localShadowTexelAngles[0]', 'keyColor', 'fillIntensity', 'ambientIntensity'];+ 'localShadowAtlas', 'localShadowMatrices[0]', 'localShadowTexelAngles[0]', 'keyColor', 'fillIntensity', 'ambientIntensity', 'specularAntiAliasing'];const SPLAT_UNIFORMS = ['splatEnabled', 'splatColor', 'splatNormal', 'splatPacked', 'splatMask', 'splatLayer[0]', 'splatTint[0]', 'splatSlope[0]', 'splatHeightRange[0]', 'splatMaskChannel[0]', 'splatMaskInvert[0]', 'splatBlend', 'splatOptions', 'splatMaskBounds', 'splatVariation'];function validateMaterialMaps(material) {@@ -2194,6 +2194,7 @@ export class Renderer67 {context.uniform3fv(this.uniforms.keyColor, this.lighting.keyColor);context.uniform1f(this.uniforms.fillIntensity, this.lighting.fillIntensity);context.uniform1f(this.uniforms.ambientIntensity, this.lighting.ambientIntensity);+ context.uniform1f(this.uniforms.specularAntiAliasing, this.lighting.specularAntiAliasing);context.uniform1f(this.uniforms.time, frame.time ?? 0);context.uniform1f(this.uniforms.wind, frame.wind ?? 0.3);context.uniform1f(this.uniforms.worldMode, this.world ? 1 : 0);diff --git a/src/shaders.js b/src/shaders.jsindex a0effe95..e4e9ae99 100644--- a/src/shaders.js+++ b/src/shaders.js@@ -265,6 +265,8 @@ uniform float localShadowTexelAngles[24];uniform vec3 keyColor;uniform float fillIntensity;uniform float ambientIntensity;+uniform float specularAntiAliasing;+const float MAXIMUM_SPECULAR_WIDENING = 0.25;uniform vec3 fogColor;uniform float fogDensity;uniform vec3 waterRipple;@@ -451,6 +453,10 @@ vec2 mapUV(float flag) {return flag > 1.5 ? lightmapUV : textureUV;}+// Toksvig variance: a normal map mip averages texels that disagree, so the filtered normal is shorter than 1.+// The shortfall is the detail the pixel can no longer resolve, and it widens the highlight instead of sparkling.+float normalMapVariance = 0.0;+vec3 mappedNormal(vec3 normal) {vec3 positionX = dFdx(worldPosition);vec3 positionY = dFdy(worldPosition);@@ -473,6 +479,8 @@ vec3 mappedNormal(vec3 normal) {float handedness = dot(cross(normal, tangent), bitangent) < 0.0 ? -1.0 : 1.0;bitangent = normalize(cross(normal, tangent)) * handedness;vec3 sampled = texture(normalMap, textureUV${featureCode("normalUv")}).xyz * 2.0 - 1.0;+ float filteredLength = clamp(length(sampled), 0.05, 1.0);+ normalMapVariance = (1.0 - filteredLength) / filteredLength;sampled.xy *= normalScale;vec3 mapped = mat3(tangent, bitangent, normal) * sampled;return dot(mapped, mapped) > 1e-12 ? normalize(mapped) : normal;@@ -589,8 +597,15 @@ ${featureCode("surfaceHook")} float alpha = surfaceAlpha(textureAlpha);float splatCavity = 1.0;if (USES_SPLAT) applySplat(color, normal, roughness, splatCavity);roughness = clamp(roughness, 0.075, 1.0);- vec3 normalChange = max(abs(dFdx(normal)), abs(dFdy(normal)));- roughness = clamp(sqrt(roughness * roughness + dot(normalChange, normalChange) * 0.3), 0.075, 1.0);+ if (specularAntiAliasing > 0.0) {+ // Kaplanyan-Hoffman: the variance of the shading normal across the pixel footprint, clamped by a kernel threshold,+ // plus the Toksvig variance of the normal map. Both add to the squared roughness.+ vec3 normalX = dFdx(normal);+ vec3 normalY = dFdy(normal);+ float screenVariance = 0.25 * (dot(normalX, normalX) + dot(normalY, normalY));+ float widening = min(2.0 * screenVariance + 0.5 * normalMapVariance, MAXIMUM_SPECULAR_WIDENING);+ roughness = clamp(sqrt(roughness * roughness + specularAntiAliasing * widening), 0.075, 1.0);+ }float mossCover = 0.0;vec3 mossTone = vec3(0.0);${featureCode("worldSurface")} vec3 specularNormal = normal;diff --git a/tests/specular-anti-aliasing.test.js b/tests/specular-anti-aliasing.test.jsnew file mode 100644index 00000000..5a481e5a--- /dev/null+++ b/tests/specular-anti-aliasing.test.js@@ -0,0 +1,31 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { createLightingState, updateLightingState, DEFAULT_SPECULAR_ANTI_ALIASING, MAXIMUM_SPECULAR_ANTI_ALIASING } from '../src/lighting.js';+import { normalizeAgentLook } from '../src/agent-look.js';++test('specular anti-aliasing is on by default and a lighting update sets or clears it', () => {+ const state = createLightingState();+ assert.equal(state.specularAntiAliasing, DEFAULT_SPECULAR_ANTI_ALIASING);+ updateLightingState(state, { specularAntiAliasing: 2.5 });+ assert.equal(state.specularAntiAliasing, 2.5);+ updateLightingState(state, { specularAntiAliasing: 0 });+ assert.equal(state.specularAntiAliasing, 0);+ updateLightingState(state, {});+ assert.equal(state.specularAntiAliasing, DEFAULT_SPECULAR_ANTI_ALIASING);+});++test('specular anti-aliasing outside zero to the maximum is refused', () => {+ const state = createLightingState();+ for (const value of [-0.1, MAXIMUM_SPECULAR_ANTI_ALIASING + 0.1, Infinity, NaN]) {+ assert.throws(() => updateLightingState(state, { specularAntiAliasing: value }), /Specular anti-aliasing/);+ }+});++test('a look keeps specularAntiAliasing only when it is set, and bounds it', () => {+ assert.equal('specularAntiAliasing' in normalizeAgentLook({ environment: {} }).environment, false);+ assert.equal(normalizeAgentLook({ environment: { specularAntiAliasing: 0 } }).environment.specularAntiAliasing, 0);+ assert.equal(normalizeAgentLook({ environment: { specularAntiAliasing: 3 } }).environment.specularAntiAliasing, 3);+ for (const specularAntiAliasing of [-1, 5, 'high', null]) {+ assert.throws(() => normalizeAgentLook({ environment: { specularAntiAliasing } }), /specularAntiAliasing/);+ }+});