3D engine that AI agents drive
Give every part of a repeated name its position in the pass objects list (#707)
Nguyen Xuan An7b10b8c8122a
diff --git a/docs/mcp.md b/docs/mcp.mdindex 3e82687c..d6e01387 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -197,7 +197,7 @@ Nested `volumeFog` and `bloom` fields merge. `pointLights` replaces the complete`environment.lines` turns on outlines, toon light and polylines, and `lines: null` removes them. A material takes `toon` for its own light steps. The code loads only for a recipe that uses either. See [line art](line-art.md).-`postPasses` (set with `set-post-passes`, `null` clears) adds full-screen GLSL passes after the finished frame. See [user passes](user-passes.md) for the rules. A compile failure comes back as `renderError` with the log mapped to the snippet's lines, and the session stays usable.+`postPasses` (set with `set-post-passes`, `null` clears) adds full-screen GLSL passes after the finished frame. A pass may list `objects` (part names) to read which part is under a pixel with `objectSlotAt`. See [user passes](user-passes.md) for the rules. A compile failure comes back as `renderError` with the log mapped to the snippet's lines, and the session stays usable.The preview allocates depth support at creation so enabling fog does not recreate render targets.Active volume fog requires HDR support. Unsupported previews reject that edit before committing.diff --git a/docs/user-passes.md b/docs/user-passes.mdindex 3e55cbb2..811fdd3d 100644--- a/docs/user-passes.md+++ b/docs/user-passes.md@@ -32,7 +32,7 @@ You do not declare uniforms or the version line; the engine writes them. A snipp| `time` | `float` | Frame time in seconds. || `depthAt(uv)`, `worldPointAt(uv)` | functions | Raw depth, and the world position of the pixel. || `worldNormalAt(uv)` | function | The surface normal, found from neighbouring depth samples. It is exact on flat faces and wrong at silhouettes and in the sky. |-| `objectSlotAt(uv)` | function | The position in the pass's `objects` list of the part under `uv`, or -1 for the background, any other part, and a pass with no `objects`. Edges are hard: an object ID cannot be antialiased. A name that is not a part in the frame fails the render and lists part names to use. |+| `objectSlotAt(uv)` | function | The position in the pass's `objects` list of the part under `uv`, or -1 for the background, any other part, and a pass with no `objects`. A name that matches several parts gives all of them its one position. Edges are hard: an object ID cannot be antialiased. A name that is not a part in the frame fails the render and lists part names to use. || `gl_FragCoord` | `vec4` | The pixel position inside this pass. |## Limits and rulesdiff --git a/src/post-mask.js b/src/post-mask.jsindex 93dc4ad3..a1b73634 100644--- a/src/post-mask.js+++ b/src/post-mask.js@@ -89,19 +89,28 @@ float maskAt(vec2 coordinate) {}`;-export function objectIdentifiers(renderer, names) {+/** Resolves each name to its part IDs. `slots[i]` is the index in `names` of the name that produced `identifiers[i]`, so a name that matches several parts keeps one slot. */+export function objectIdentifierSlots(renderer, names) {if (!renderer.passSupport) throw new Error('A mask by objects needs installRenderPasses(renderer) and the object ID pass drawn first.');const known = renderer.passSupport.objectNames();const identifiers = [];- for (const name of names) {+ const slots = [];+ names.forEach((name, slot) => {const matches = known.flatMap((candidate, index) => (candidate === name ? [index + 1] : []));if (matches.length === 0) {throw new Error(`Mask object "${name}" is not a part in the frame. Fix: use a part name such as ${known.slice(0, 8).map(part => `"${part}"`).join(', ') || '(the scene has no opaque parts)'}.`);}- identifiers.push(...matches);- }+ for (const identifier of matches) {+ identifiers.push(identifier);+ slots.push(slot);+ }+ });if (identifiers.length > MAXIMUM_MASK_OBJECTS) throw new RangeError(`The mask names ${identifiers.length} parts; the limit is ${MAXIMUM_MASK_OBJECTS}. Fix: name fewer parts.`);- return identifiers;+ return { identifiers, slots };+}++export function objectIdentifiers(renderer, names) {+ return objectIdentifierSlots(renderer, names).identifiers;}/** Sets the mask uniforms of a stage. A step with no mask gets a mask of one everywhere. Leaves texture unit 1 active. */diff --git a/src/user-pass.js b/src/user-pass.jsindex 32d9aea6..5a7ef8fe 100644--- a/src/user-pass.js+++ b/src/user-pass.js@@ -2,7 +2,7 @@ import { compileProgram, fullscreenVertex } from './gl-program.js';import {SNIPPET_LIMITS, requireKnownFields, validateShaderSnippet, validateSnippetUniforms, snippetUniformDeclarations, mapShaderInfoLog,} from './shader-snippet-validator.js';-import { MAXIMUM_MASK_OBJECTS, resolveObjectNames, objectIdentifiers, unbindMask } from './post-mask.js';+import { MAXIMUM_MASK_OBJECTS, resolveObjectNames, objectIdentifierSlots, unbindMask } from './post-mask.js';// User post-process passes: fragment snippets that run on the finished frame, after the stock effects, the grade and the// view transform, as the last step before the canvas. The core renderer carries nothing for them. installUserPasses wraps@@ -78,6 +78,7 @@ uniform float time;uniform sampler2D sceneObjectIds;uniform int u67_objectCount;uniform int u67_objectIds[${MAXIMUM_MASK_OBJECTS}];+uniform int u67_objectSlots[${MAXIMUM_MASK_OBJECTS}];out vec4 u67_output;float depthAt(vec2 uv) { return texture(sceneDepth, uv).r; }vec3 worldPointAt(vec2 uv) {@@ -91,7 +92,7 @@ int objectSlotAt(vec2 uv) {int identifier = int(idBytes.r + idBytes.g * 256.0 + idBytes.b * 65536.0);for (int slot = 0; slot < ${MAXIMUM_MASK_OBJECTS}; slot++) {if (slot >= u67_objectCount) break;- if (u67_objectIds[slot] == identifier) return slot;+ if (u67_objectIds[slot] == identifier) return u67_objectSlots[slot];}return -1;}@@ -218,7 +219,7 @@ export function installUserPasses(renderer) {throw compilationError(pass, error, built);}if (entry) releaseEntry(context, entry);- const names = ['sceneColor', 'sceneDepth', 'sceneObjectIds', 'u67_objectCount', 'u67_objectIds', 'u67_inverseViewProjection', 'resolution', 'time', ...Object.keys(pass.uniforms)];+ const names = ['sceneColor', 'sceneDepth', 'sceneObjectIds', 'u67_objectCount', 'u67_objectIds', 'u67_objectSlots', 'u67_inverseViewProjection', 'resolution', 'time', ...Object.keys(pass.uniforms)];state.entries[index] = {pass, source: built.source, program, target: null,locations: Object.fromEntries(names.map(name => [name, context.getUniformLocation(program, name)])),@@ -263,12 +264,15 @@ export function installUserPasses(renderer) {context.uniform2f(locations.resolution, width, height);context.uniform1f(locations.time, frame.time ?? 0);for (const [name, uniform] of Object.entries(pass.uniforms)) setUniformValue(context, locations[name], uniform);- const identifiers = pass.objects ? objectIdentifiers(renderer, pass.objects) : [];+ const { identifiers, slots } = pass.objects ? objectIdentifierSlots(renderer, pass.objects) : { identifiers: [], slots: [] };context.uniform1i(locations.u67_objectCount, identifiers.length);if (identifiers.length > 0) {const padded = new Int32Array(MAXIMUM_MASK_OBJECTS);padded.set(identifiers);context.uniform1iv(locations.u67_objectIds, padded);+ const paddedSlots = new Int32Array(MAXIMUM_MASK_OBJECTS);+ paddedSlots.set(slots);+ context.uniform1iv(locations.u67_objectSlots, paddedSlots);context.activeTexture(context.TEXTURE2);context.bindTexture(context.TEXTURE_2D, renderer.passSupport.texture);context.uniform1i(locations.sceneObjectIds, 2);diff --git a/tests/post-steps.test.js b/tests/post-steps.test.jsindex 8b4904db..ac4d8f9f 100644--- a/tests/post-steps.test.js+++ b/tests/post-steps.test.js@@ -218,6 +218,29 @@ test('a user pass binds the object ID pass for its parts and unbinds it after thassert.throws(() => renderer.resolveFrame({ time: 0 }), /Mask object "missing" is not a part in the frame/);});+test('a user pass slot is the position in its objects list, also when a name matches several parts', () => {+ const calls = [];+ const context = recordingContext(calls);+ const renderer = {+ context, canvas: { width: 16, height: 9 }, postStages: [], depthTexture: 'depth', whiteTexture: 'white',+ inverseViewProjection: mat4.create(), resolveFrame() {}, benchmark: false,+ passSupport: { texture: 'ids', objectNames: () => ['hero', 'hero', 'floor'] },+ };+ installUserPasses(renderer);+ renderer.userPasses.set([{ name: 'tint', fragment: PASS_FRAGMENT, objects: ['hero', 'floor'] }]);+ renderer.resolveFrame({ time: 0 });+ const [identifiers, slots] = calls.filter(call => call[0] === 'uniform1iv').map(call => Array.from(call[2]));+ assert.deepEqual(identifiers.slice(0, 4), [1, 2, 3, 0], 'both hero parts and the floor are uploaded');+ assert.deepEqual(slots.slice(0, 3), [0, 0, 1], 'both hero parts report slot 0 and the floor reports slot 1');+ // The shader walks the uploaded IDs and returns the matching slot entry; the same walk in JavaScript.+ const slotOf = identifier => {+ const index = identifiers.slice(0, 3).indexOf(identifier);+ return index === -1 ? -1 : slots[index];+ };+ assert.deepEqual([1, 2, 3, 4].map(slotOf), [0, 0, 1, -1]);+ assert.match(buildPassFragment(normalizeUserPasses([{ name: 'tint', fragment: PASS_FRAGMENT, objects: ['hero'] }])[0]).source, /return u67_objectSlots\[slot\]/);+});+test('the shaders keep their fixed sample patterns and read no history', () => {for (const fragment of [glareFragment, lensDistortionFragment, colorBalanceFragment, stylizeFragment, compositeFragment]) {assert.match(fragment, /^#version 300 es/);