Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add the opt-in compact colour addon: R11F_G11F_B10F frame and multisample colour (closes #287)

Nguyen Xuan An35e115518674
diff --git a/bench/reference/harness.js b/bench/reference/harness.js
index df4de4de..35f4c2f8 100644
--- a/bench/reference/harness.js
+++ b/bench/reference/harness.js
@@ -1,4 +1,5 @@
// Runs in the page: draws one reference scene, and describes it as plain data for Blender.
+import { useCompactColor } from '/src/compact-color.js';
import { Renderer67 } from '/src/renderer.js';
import { REFERENCE_SCENES, KHRONOS_SCENES, KTX2_SCENES, loadBarnLampVariant, CLOTH_SCENES } from './scenes.js';
import { GRAND_SCENES } from './grand-scenes.js';
@@ -30,6 +31,7 @@ function withDerivedGroundBounce(scene, drawnParts) {
}
// ?reversedDepth=on draws with reversed-Z (issue #310); the scenes draw with the standard depth buffer otherwise.
+const COMPACT_COLOR = new URLSearchParams(location.search).get('compactColor') === 'on';
const REVERSED_DEPTH = new URLSearchParams(location.search).get('reversedDepth') === 'on';
const WATER_REFLECTION = { off: false, ssr: 'ssr' }[new URLSearchParams(location.search).get('water')] ?? 'planar';
@@ -172,6 +174,7 @@ function createSceneRenderer(parts, scene, cascades, { water = WATER_REFLECTION
ground: false, hdr: true, depth: true, samples: 4, pixelRatio: 1, memoryBudgetMiB: 1024, world: true,
environment: scene.environment, shadowBounds: scene.shadow, shadowCascades: cascades ? createCascadedShadows({ count: cascades }) : null, skyOpenness, fogSkyVisibility,
});
+ if (COMPACT_COLOR) useCompactColor(renderer);
if (REVERSED_DEPTH) installReversedDepth(renderer, true);
attachWaterReflection(renderer, reflecting.surface);
if (water === 'ssr') {
diff --git a/bench/runtime/README.md b/bench/runtime/README.md
index dfd4cdfb..1b321c14 100644
--- a/bench/runtime/README.md
+++ b/bench/runtime/README.md
@@ -65,7 +65,7 @@ Measured twice on 2026-11-04 at 960 by 540 with 4 MSAA samples, against three.js
Each 67js result in `report.json` lists its render targets (`renderTargets`: name, size, format, samples, bytes). The same list comes from `renderer.memoryReport()`. At 960 by 540 with 4 samples, for `instanced-objects` and `large-outdoor` alike: `shadowMap` 16 MB (2048 by 2048 depth), `multisampleColor` 15.82 MB (RGBA16F), `multisampleDepth` 3.96 MB (16 bits, it was 7.91 MB with 24 bits) and `frameColor` 3.96 MB. The counter totals 41.36 MB and 43.58 MB, so 1.4 to 3.6 MB is geometry and textures.
-**At 1920 by 1080** (4 samples, no depth texture; measured with `renderer.memoryReport()`, the same for all seven scenes) a plain lit scene holds 110.92 MB of render targets: `multisampleColor` 63.28 MB (RGBA16F, 4 samples), `shadowMap` 16 MB, `multisampleDepth` 15.82 MB and `frameColor` 15.82 MB. The multisampled colour is 57 percent of it, so only a smaller colour format or fewer samples can halve the total, and both change pixels. With `shadowCascades` on, a scene also holds the cascade array (48 MB for three 2048 slices); the single map used to stay beside it, and now it is one texel unless volume fog or a `subsurface` material reads it. At 960 by 540 that takes 20 of the 26 reference scenes 16 MB lower (a plain scene from 93.66 MB to 77.66 MB; the 6 scenes with volume fog or subsurface keep the map), with byte-identical pictures.
+**At 1920 by 1080** (4 samples, no depth texture; measured with `renderer.memoryReport()`, the same for all seven scenes) a plain lit scene holds 110.92 MB of render targets: `multisampleColor` 63.28 MB (RGBA16F, 4 samples), `shadowMap` 16 MB, `multisampleDepth` 15.82 MB and `frameColor` 15.82 MB. The multisampled colour is 57 percent of it, so only a smaller colour format or fewer samples can halve the total, and both change pixels. The opt-in addon `useCompactColor(renderer)` (`addons/compact-color`) stores the frame and the multisample colour as R11F_G11F_B10F: 110.92 MB becomes 71.37 MB (39.55 MB less; `multisampleColor` 31.64, `frameColor` 7.91), and the 26 reference pictures differ from the default by mean FLIP 0.002 to 0.030 (median 0.021). Without it the default stays RGBA16F and draws the same pictures as before (3 scenes compared, max diff 0). With `shadowCascades` on, a scene also holds the cascade array (48 MB for three 2048 slices); the single map used to stay beside it, and now it is one texel unless volume fog or a `subsurface` material reads it. At 960 by 540 that takes 20 of the 26 reference scenes 16 MB lower (a plain scene from 93.66 MB to 77.66 MB; the 6 scenes with volume fog or subsurface keep the map), with byte-identical pictures.
Issue 287 asked for at most 23.25 MB, half of the 46.5 MB the first run showed. It is not met: 41.36 MB is the most the pictures allow today. Each step was scored by FLIP of the new 67js picture against the old one, over the 25 reference scenes, and the limit was 0.002. The 16-bit multisampled depth scored 0.0000 everywhere and is in. Left out: an R11G11B10F colour target (saves 9.9 MB; 0.002 to 0.034, about 0.02 on most scenes, because the packed format truncates), a 1024 shadow map for small views (saves 12 MB; `subsurface` 0.006) and a 16-bit sun shadow map (saves 8 MB; `brick-flat` 0.0023 and `brick-graph` 0.0031). A renderer that needs the alpha of the colour target would also have to keep RGBA16F, so the packed format would need a flag for such an addon.
diff --git a/changes/287-compact-color.md b/changes/287-compact-color.md
new file mode 100644
index 00000000..3ee34caf
--- /dev/null
+++ b/changes/287-compact-color.md
@@ -0,0 +1 @@
+- Add the opt-in addon `useCompactColor(renderer)` (`@codepawlhq/67js/addons/compact-color`, issue #287). It stores the frame and its multisample colour in 4 bytes a pixel (R11F_G11F_B10F) instead of 8: at 1920 x 1080 with 4 samples the render targets go from 110.92 to 71.37 MB. It has no alpha, so it needs `hdr: true` and an opaque canvas and throws otherwise, and it throws when the device lacks the renderer's sample count in that format. Mean FLIP against the default over the 26 reference scenes is 0.002 to 0.030 (median 0.021). Without the call the core keeps RGBA16F and draws byte-identical pictures.
diff --git a/changes/287-compact-color.size.md b/changes/287-compact-color.size.md
new file mode 100644
index 00000000..6ee4ded6
--- /dev/null
+++ b/changes/287-compact-color.size.md
@@ -0,0 +1,3 @@
+- scene:lit-box: +22 B gzip (50070 to 50092) for the R11F_G11F_B10F entry in the render target ledger that the compact colour addon records.
+- goal:lit-box: +22 B gzip (50070 to 50092) for the ledger entry above. Approved by the lead under An's rule for goal scenes on 2026-11-04.
+- goal:agent-scene: +16 B gzip (102939 to 102955) for the same ledger entry. Approved by the lead under An's rule for goal scenes on 2026-11-04.
diff --git a/docs/guide.md b/docs/guide.md
index baebf462..33b44303 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -334,6 +334,7 @@ Tags select specialized behavior: `armor` allows studio finish overrides. `floor
| world | false | Enable outdoor rendering and world clipping defaults |
| samples | 4 | Requested MSAA count. Negotiated against hardware |
| hdr | false | Request floating-point color targets |
+| (compact colour) | off | `useCompactColor(renderer)` from `@codepawlhq/67js/addons/compact-color` stores the HDR frame and its multisample colour as R11F_G11F_B10F instead of RGBA16F: 39.55 MB less at 1920 x 1080 with 4 samples (110.92 to 71.37 MB). The format has no alpha, so it needs `hdr: true` and an opaque canvas and throws otherwise; it also throws when the device does not support the renderer's sample count in that format. Mean FLIP against the default is 0.002 to 0.030 (median 0.021) over the 26 reference scenes. Without the call nothing changes. `renderer.memoryReport()` lists the formats |
| memoryBudgetMiB | 256 | Estimated render allocation budget |
| environment | {} | Sky, light and fog settings |
| shadowBounds | {} | Custom extent, eye and target for shadow framing |
diff --git a/package.json b/package.json
index bf7ab383..771ad685 100644
--- a/package.json
+++ b/package.json
@@ -100,6 +100,7 @@
"./addons/subsurface-shader": "./build/subsurface-shader.js",
"./addons/light-linking": "./build/light-linking.js",
"./addons/cascaded-shadows": "./build/cascaded-shadows.js",
+ "./addons/compact-color": "./build/compact-color.js",
"./addons/gaussian-splats": "./build/gaussian-splats.js",
"./addons/texture-update": "./build/texture-update.js",
"./package.json": "./package.json"
diff --git a/src/compact-color.js b/src/compact-color.js
new file mode 100644
index 00000000..e5d9c755
--- /dev/null
+++ b/src/compact-color.js
@@ -0,0 +1,38 @@
+// Opt-in addon (issue #287): stores the HDR frame and its multisample colour as R11F_G11F_B10F, 4 bytes a pixel instead of 8.
+// At 1920 x 1080 with 4 samples that is 39.55 MB less. The format has no alpha, drops negative values and keeps 6 or 5 mantissa
+// bits, so pictures differ from the default by a small amount (docs/guide.md). Without this addon the core keeps RGBA16F.
+const COMPACT_FORMAT = 'R11F_G11F_B10F';
+
+function respecifyColorTargets(renderer) {
+ const context = renderer.context;
+ if (!renderer.multisampleFramebuffer) return;
+ const { width, height } = renderer.canvas;
+ context.bindRenderbuffer(context.RENDERBUFFER, renderer.multisampleColor);
+ context.renderbufferStorageMultisample(context.RENDERBUFFER, renderer.multisampleSamples, context[COMPACT_FORMAT], width, height);
+ context.bindTexture(context.TEXTURE_2D, renderer.frameTexture);
+ context.texImage2D(context.TEXTURE_2D, 0, context[COMPACT_FORMAT], width, height, 0, context.RGB, context.HALF_FLOAT, null);
+ for (const framebuffer of [renderer.multisampleFramebuffer, renderer.resolveFramebuffer]) {
+ context.bindFramebuffer(context.FRAMEBUFFER, framebuffer);
+ if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) throw new Error('Compact colour targets failed to allocate. Do not install compact colour on this device.');
+ }
+ context.bindFramebuffer(context.FRAMEBUFFER, null);
+ renderer.renderTargets.record('multisampleColor', { width, height, format: COMPACT_FORMAT, samples: renderer.multisampleSamples });
+ renderer.renderTargets.record('frameColor', { width, height, format: COMPACT_FORMAT });
+}
+
+/** Switches the frame and multisample colour to R11F_G11F_B10F. Needs `hdr: true` and an opaque canvas. Returns the renderer. */
+export function useCompactColor(renderer) {
+ if (!renderer.hdr || renderer.transparent) throw new Error('Compact colour needs hdr: true with negotiated HDR support and an opaque canvas, because it has no alpha.');
+ if (renderer.colorFormat === COMPACT_FORMAT) return renderer;
+ const context = renderer.context;
+ const supported = context.getInternalformatParameter(context.RENDERBUFFER, context[COMPACT_FORMAT], context.SAMPLES);
+ if (renderer.multisampleSamples > 0 && !Array.from(supported).includes(renderer.multisampleSamples)) throw new Error(`Compact colour does not support ${renderer.multisampleSamples} samples on this device.`);
+ const allocateFrameTargets = renderer.allocateFrameTargets;
+ renderer.allocateFrameTargets = function allocateCompactColorTargets(width, height) {
+ allocateFrameTargets.call(this, width, height);
+ respecifyColorTargets(this);
+ };
+ renderer.colorFormat = COMPACT_FORMAT;
+ respecifyColorTargets(renderer);
+ return renderer;
+}
diff --git a/src/render-target-ledger.js b/src/render-target-ledger.js
index 23bf3309..060642b0 100644
--- a/src/render-target-ledger.js
+++ b/src/render-target-ledger.js
@@ -1,6 +1,6 @@
// Lists the GPU render targets a renderer owns, so an agent can read what each one costs.
// Sizes follow the texel format, so they are the same on every machine, whatever padding a driver adds.
-const BYTES_PER_PIXEL = { R8: 1, RGBA8: 4, RGBA16F: 8, DEPTH_COMPONENT16: 2, DEPTH_COMPONENT24: 4 };
+const BYTES_PER_PIXEL = { R8: 1, RGBA8: 4, RGBA16F: 8, R11F_G11F_B10F: 4, R11F_G11F_B10F: 4, DEPTH_COMPONENT16: 2, DEPTH_COMPONENT24: 4 };
const BYTES_PER_MEGABYTE = 1048576;
export class RenderTargetLedger {
diff --git a/tests/render-target-memory.test.js b/tests/render-target-memory.test.js
index e12610de..4111fdc6 100644
--- a/tests/render-target-memory.test.js
+++ b/tests/render-target-memory.test.js
@@ -2,6 +2,7 @@ import test from 'node:test';
import assert from 'node:assert/strict';
import { Renderer67 } from '../src/renderer.js';
import { RenderTargetLedger } from '../src/render-target-ledger.js';
+import { useCompactColor } from '../src/compact-color.js';
import { CascadedShadows } from '../src/cascaded-shadows.js';
const BYTES_PER_MEGABYTE = 1048576;
@@ -119,3 +120,39 @@ test('with cascades the single shadow map stays one texel unless volume fog or s
subsurface.renderer.createShadowMap();
assert.equal(subsurface.sizes[0][0], 2048);
});
+
+function supportingSamples(renderer, samples) {
+ const base = renderer.context;
+ renderer.context = new Proxy(base, { get: (target, name) => (name === 'getInternalformatParameter' ? () => samples : target[name]) });
+}
+
+test('without the compact colour addon the frame and multisample colour stay RGBA16F', () => {
+ const renderer = frameTargetRenderer(false);
+ renderer.allocateFrameTargets(1920, 1080);
+ const byName = Object.fromEntries(renderer.memoryReport().targets.map(target => [target.name, target]));
+ assert.equal(byName.multisampleColor.format, 'RGBA16F');
+ assert.equal(byName.frameColor.format, 'RGBA16F');
+});
+
+test('compact colour halves the frame and multisample colour and keeps the other targets', () => {
+ const renderer = frameTargetRenderer(false);
+ renderer.canvas = { width: 1920, height: 1080 };
+ supportingSamples(renderer, [4, 8]);
+ renderer.allocateFrameTargets(1920, 1080);
+ const before = Object.fromEntries(renderer.memoryReport().targets.map(target => [target.name, target]));
+ useCompactColor(renderer);
+ const after = Object.fromEntries(renderer.memoryReport().targets.map(target => [target.name, target]));
+ assert.equal(after.multisampleColor.format, 'R11F_G11F_B10F');
+ assert.equal(after.frameColor.format, 'R11F_G11F_B10F');
+ assert.equal(after.multisampleColor.bytes * 2, before.multisampleColor.bytes);
+ assert.equal(after.frameColor.bytes * 2, before.frameColor.bytes);
+ assert.equal(after.multisampleDepth.bytes, before.multisampleDepth.bytes);
+});
+
+test('compact colour needs HDR, an opaque canvas and a sample count the format supports', () => {
+ assert.throws(() => useCompactColor({ hdr: false }), /needs hdr: true/);
+ assert.throws(() => useCompactColor({ hdr: true, transparent: true }), /needs hdr: true/);
+ const unsupported = frameTargetRenderer(false);
+ supportingSamples(unsupported, [2]);
+ assert.throws(() => useCompactColor(unsupported), /does not support 4 samples/);
+});
diff --git a/vite.lib.config.js b/vite.lib.config.js
index b2519364..10087ee3 100644
--- a/vite.lib.config.js
+++ b/vite.lib.config.js
@@ -94,6 +94,7 @@ export default defineConfig({
'subsurface-shader': 'src/subsurface-shader.js',
'light-linking': 'src/light-linking.js',
'cascaded-shadows': 'src/cascaded-shadows.js',
+ 'compact-color': 'src/compact-color.js',
'gaussian-splats': 'src/gaussian-splats.js',
'texture-update': 'src/texture-update.js',
// Page of the MCP preview. It imports the engine chunks above instead of bundling its own copy.