Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.mjs
index 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.js
index 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_A
const 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.js
index 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.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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/);
+ }
+});