Skip to content

3D engine that AI agents drive

Add palette quantize and ordered dither to splat pixel-art output (#1744)

Nguyen Xuan An3ed3df939d50
diff --git a/changes/1744-palette.md b/changes/1744-palette.md
new file mode 100644
index 00000000..50fbfccb
--- /dev/null
+++ b/changes/1744-palette.md
@@ -0,0 +1 @@
+- `createGaussianSplats` takes `palette` (2 to 256 colours) and `dither` (`bayer4` or `bayer8`) to snap `alphaCut` splats to a palette for a pixel-art look (#1744)
diff --git a/changes/1744-palette.size.md b/changes/1744-palette.size.md
new file mode 100644
index 00000000..9959b8e3
--- /dev/null
+++ b/changes/1744-palette.size.md
@@ -0,0 +1 @@
+- entry:gaussian-splats: 1230 bytes gzip for the palette and Bayer dither option (option checks, the palette fragment shader and its program cache), the pixel-art snapping splat users otherwise do in a separate image pass after every frame (#1744).
diff --git a/docs/gaussian-splats.md b/docs/gaussian-splats.md
index 2315d1e0..76a051ef 100644
--- a/docs/gaussian-splats.md
+++ b/docs/gaussian-splats.md
@@ -33,7 +33,9 @@ A file over `maximumBytes` (default 512 MiB, for SPZ also its inflated size), or
A Z-up file (Blender, CAD) loads upright with `parseGaussianSplatPly(bytes, { upAxis: 'z' })`: positions and rotations turn by -90 degrees about x, so the file's +z comes out on +y and each disc keeps its orientation. The default is `'y'`, no change. `upAxis` also works on `parseGaussianSplatPlyAsync`; the SPZ readers do not take it, use `matrix`.
-`createGaussianSplats(data, { alphaCut: 0.5 })` (and the async version) draws the scene as hard discs instead of soft blobs. A pixel whose gaussian alpha (the falloff times the splat's opacity) is below `alphaCut`, a number from 0 to 1, is dropped; every other pixel is written opaque with depth, with no blending, so neighbouring splats stay their own colour and the result does not depend on the sort. Leave it out for the soft look, which is unchanged. Opaque scenes draw before soft ones on the same renderer, and a splat whose opacity is under the cut never shows. A full pixel-art look still needs a palette step after the frame.
+`createGaussianSplats(data, { alphaCut: 0.5 })` (and the async version) draws the scene as hard discs instead of soft blobs. A pixel whose gaussian alpha (the falloff times the splat's opacity) is below `alphaCut`, a number from 0 to 1, is dropped; every other pixel is written opaque with depth, with no blending, so neighbouring splats stay their own colour and the result does not depend on the sort. Leave it out for the soft look, which is unchanged. Opaque scenes draw before soft ones on the same renderer, and a splat whose opacity is under the cut never shows.
+
+For a pixel-art look add a palette: `createGaussianSplats(data, { alphaCut: 0.5, palette: ['#1b1b2f', '#c8553d', '#ffd166', [0.9, 0.9, 0.85]], dither: 'bayer4' })`. `palette` is 2 to 256 colours, each a hex string (`'#rgb'` or `'#rrggbb'`) or an `[r, g, b]` array of numbers from 0 to 1, and it needs `alphaCut`, because a blended pixel has no single colour to snap. Every opaque splat pixel takes the nearest palette colour by squared RGB distance (the first one on a tie), judged on the splat's display colour before any HDR exposure. `dither` is `'none'` (default), `'bayer4'` or `'bayer8'`: before the nearest colour is picked, each pixel moves by an ordered-dither threshold from its screen position (the canvas pixel, so a frame at the same size always gives the same pixels), up to 0.125 either way in each channel. The sky, parts and other splat scenes in the frame are not snapped. With no `palette` nothing changes. The outline, the upscale and baking a surface into splats are not part of this.
## Loading without freezing the page
diff --git a/src/gaussian-splats.js b/src/gaussian-splats.js
index 6d79cf4a..ee086025 100644
--- a/src/gaussian-splats.js
+++ b/src/gaussian-splats.js
@@ -4,6 +4,7 @@ import { createSplatSorter } from './gaussian-splat-sort.js';
import { runInChunks } from './gaussian-splat-chunks.js';
import { GAUSSIAN_SPLAT_HARD_COUNT_LIMIT, GAUSSIAN_SPLAT_LIMITS, parseGaussianSplatPly, parseGaussianSplatPlyAsync } from './gaussian-splat-ply.js';
import { parseGaussianSplatSpz, parseGaussianSplatSpzAsync } from './gaussian-splat-spz.js';
+import { buildPaletteFragmentSource, resolveSplatPalette } from './splat-palette.js';
export { GAUSSIAN_SPLAT_HARD_COUNT_LIMIT, GAUSSIAN_SPLAT_LIMITS, parseGaussianSplatPly, parseGaussianSplatPlyAsync, parseGaussianSplatSpz, parseGaussianSplatSpzAsync };
@@ -181,7 +182,7 @@ function checkSplatArray(data, { field, stride, types, meaning }, caller) {
function resolveSplatOptions(options, caller) {
if (options === undefined) return {};
if (options === null || typeof options !== 'object') {
- throw new TypeError(`${caller} options must be an object such as { matrix, maximumCount, alphaCut } or left out, got ${options === null ? 'null' : typeof options}`);
+ throw new TypeError(`${caller} options must be an object such as { matrix, maximumCount, alphaCut, palette, dither } or left out, got ${options === null ? 'null' : typeof options}`);
}
return options;
}
@@ -213,10 +214,15 @@ function resolveAlphaCut(alphaCut, caller) {
return alphaCut;
}
-function buildSplats(data, matrix, packed, alphaCut) {
+function resolveSplatLook(options, caller) {
+ const alphaCut = resolveAlphaCut(options.alphaCut, caller);
+ return { alphaCut, palette: resolveSplatPalette(options.palette, options.dither, alphaCut, caller) };
+}
+
+function buildSplats(data, matrix, packed, { alphaCut, palette }) {
const sorter = createSplatSorter(data.positions, data.count, data.bounds);
const statistics = { count: data.count, visibleCount: 0, sortMilliseconds: 0, gpuBytes: 0, cpuBytes: data.positions.byteLength + data.count * 8 };
- return { count: data.count, matrix: mat4.clone(matrix), bounds: data.bounds, statistics, packed, sorter, alphaCut };
+ return { count: data.count, matrix: mat4.clone(matrix), bounds: data.bounds, statistics, packed, sorter, alphaCut, palette };
}
/**
@@ -226,6 +232,8 @@ function buildSplats(data, matrix, packed, alphaCut) {
* `alphaCut` (a number from 0 to 1, default off) turns the blended look into hard opaque discs: a pixel whose gaussian alpha
* (falloff times the splat's opacity) is below it is dropped and every other pixel is written opaque, with depth, so
* neighbouring splats no longer mix their colours. These splats draw before the soft ones.
+ * `palette` (2 to 256 colours, hex strings or [r, g, b] from 0 to 1; needs `alphaCut`) snaps every opaque pixel to its nearest
+ * palette colour, and `dither` (`'none'` default, `'bayer4'`, `'bayer8'`) adds an ordered dither first. Both are off by default.
* The returned object has `count`, `matrix`, `bounds` and `statistics` (`count`, `visibleCount`, `sortMilliseconds`,
* `gpuBytes`, `cpuBytes`).
*/
@@ -234,10 +242,10 @@ export function createGaussianSplats(data, options) {
const { maximumCount = GAUSSIAN_SPLAT_LIMITS.maximumCount } = resolvedOptions;
checkSplatInput(data, maximumCount, 'createGaussianSplats');
const matrix = resolveMatrix(resolvedOptions.matrix, 'createGaussianSplats');
- const resolvedAlphaCut = resolveAlphaCut(resolvedOptions.alphaCut, 'createGaussianSplats');
+ const look = resolveSplatLook(resolvedOptions, 'createGaussianSplats');
const { packRange, packed } = createSplatPacker(data);
packRange(0, data.count);
- return buildSplats(data, matrix, packed, resolvedAlphaCut);
+ return buildSplats(data, matrix, packed, look);
}
/**
@@ -250,10 +258,10 @@ export async function createGaussianSplatsAsync(data, rawOptions) {
const { maximumCount = GAUSSIAN_SPLAT_LIMITS.maximumCount } = options;
checkSplatInput(data, maximumCount, 'createGaussianSplatsAsync');
const matrix = resolveMatrix(options.matrix, 'createGaussianSplatsAsync');
- const alphaCut = resolveAlphaCut(options.alphaCut, 'createGaussianSplatsAsync');
+ const look = resolveSplatLook(options, 'createGaussianSplatsAsync');
const { packRange, packed } = createSplatPacker(data);
await runInChunks(data.count, options, 'createGaussianSplatsAsync', packRange);
- return buildSplats(data, matrix, packed, alphaCut);
+ return buildSplats(data, matrix, packed, look);
}
function createGpuResources(context, splats) {
@@ -280,15 +288,15 @@ function createGpuResources(context, splats) {
const attachments = new WeakMap();
-function createProgramInfo(context, fragmentSource) {
+function createProgramInfo(context, fragmentSource, extraUniformNames = []) {
const program = compileProgram(context, VERTEX_SOURCE, fragmentSource);
- const uniforms = Object.fromEntries(UNIFORM_NAMES.map(name => [name, context.getUniformLocation(program, name)]));
+ const uniforms = Object.fromEntries([...UNIFORM_NAMES, ...extraUniformNames].map(name => [name, context.getUniformLocation(program, name)]));
return { program, uniforms };
}
function createAttachment(renderer) {
const context = renderer.context;
- const attachment = { blended: createProgramInfo(context, FRAGMENT_SOURCE), opaque: null, entries: new Set(), modelView: mat4.create(), original: null, disposeOriginal: null };
+ const attachment = { blended: createProgramInfo(context, FRAGMENT_SOURCE), opaque: null, palettePrograms: new Map(), entries: new Set(), modelView: mat4.create(), original: null, disposeOriginal: null };
attachment.original = renderer.drawBlendBatches;
attachment.disposeOriginal = renderer.dispose;
renderer.drawBlendBatches = function drawBlendBatchesAndSplats(frame) {
@@ -313,6 +321,7 @@ function releaseAttachment(renderer, attachment) {
attachment.entries.clear();
renderer.context.deleteProgram(attachment.blended.program);
if (attachment.opaque) renderer.context.deleteProgram(attachment.opaque.program);
+ for (const programInfo of attachment.palettePrograms.values()) renderer.context.deleteProgram(programInfo.program);
renderer.drawBlendBatches = attachment.original;
renderer.dispose = attachment.disposeOriginal;
attachments.delete(renderer);
@@ -356,6 +365,14 @@ function prepareOpaqueState(renderer, attachment, frame) {
useProgram(renderer, attachment.opaque, frame);
}
+function paletteProgramFor(renderer, attachment, palette) {
+ const key = `${palette.count}:${palette.dither}`;
+ if (!attachment.palettePrograms.has(key)) {
+ attachment.palettePrograms.set(key, createProgramInfo(renderer.context, buildPaletteFragmentSource(palette.count, palette.dither), ['paletteColors']));
+ }
+ return attachment.palettePrograms.get(key);
+}
+
function restoreState(renderer) {
const context = renderer.context;
context.depthMask(true);
@@ -380,6 +397,7 @@ function drawEntry(renderer, attachment, entry, programInfo) {
if (visibleCount === 0) return;
context.uniformMatrix4fv(programInfo.uniforms.modelView, false, attachment.modelView);
if (splats.alphaCut !== null) context.uniform1f(programInfo.uniforms.alphaCut, splats.alphaCut);
+ if (splats.palette) context.uniform3fv(programInfo.uniforms.paletteColors, splats.palette.colors);
context.activeTexture(context.TEXTURE0 + DATA_TEXTURE_UNIT);
context.bindTexture(context.TEXTURE_2D, entry.texture);
context.bindVertexArray(entry.vertexArray);
@@ -391,12 +409,19 @@ function drawEntries(renderer, attachment, frame) {
if (attachment.entries.size === 0) return;
prepareFrameState(renderer);
const entries = [...attachment.entries];
- const opaqueEntries = entries.filter(entry => entry.splats.alphaCut !== null);
+ const opaqueEntries = entries.filter(entry => entry.splats.alphaCut !== null && !entry.splats.palette);
+ const paletteEntries = entries.filter(entry => entry.splats.palette);
const blendedEntries = entries.filter(entry => entry.splats.alphaCut === null);
if (opaqueEntries.length > 0) {
prepareOpaqueState(renderer, attachment, frame);
for (const entry of opaqueEntries) drawEntry(renderer, attachment, entry, attachment.opaque);
}
+ for (const entry of paletteEntries) {
+ prepareOpaqueState(renderer, attachment, frame);
+ const programInfo = paletteProgramFor(renderer, attachment, entry.splats.palette);
+ useProgram(renderer, programInfo, frame);
+ drawEntry(renderer, attachment, entry, programInfo);
+ }
if (blendedEntries.length > 0) {
prepareBlendedState(renderer, attachment, frame);
const farToNear = blendedEntries.map(entry => ({ entry, distance: distanceToEye(entry.splats, frame.eye) })).sort((first, second) => second.distance - first.distance);
diff --git a/src/splat-palette.js b/src/splat-palette.js
new file mode 100644
index 00000000..71e230b1
--- /dev/null
+++ b/src/splat-palette.js
@@ -0,0 +1,148 @@
+// Palette snapping for gaussian splat scenes drawn with `alphaCut`: each opaque splat pixel takes the nearest palette colour,
+// after an optional ordered (Bayer) dither. The shader text and the CPU reference below read the same matrix and constants,
+// so a unit test on the reference pins what the GPU draws.
+
+export const SPLAT_PALETTE_LIMITS = Object.freeze({ minimumColors: 2, maximumColors: 256 });
+export const SPLAT_DITHER_MODES = Object.freeze(['none', 'bayer4', 'bayer8']);
+
+// How far a dither threshold (from -0.5 to 0.5) pushes each colour channel before the nearest colour is chosen.
+export const SPLAT_DITHER_SPREAD = 0.25;
+
+const DITHER_SIZES = Object.freeze({ none: 0, bayer4: 4, bayer8: 8 });
+
+/** The n x n Bayer index matrix (n a power of two), row by row, holding 0 to n*n - 1. */
+export function buildBayerMatrix(size) {
+ let matrix = [0];
+ for (let side = 1; side < size; side *= 2) {
+ const next = new Array(side * side * 4);
+ for (let row = 0; row < side * 2; row++) {
+ for (let column = 0; column < side * 2; column++) {
+ const base = 4 * matrix[(row % side) * side + (column % side)];
+ const quadrantOffset = [[0, 2], [3, 1]][Math.floor(row / side)][Math.floor(column / side)];
+ next[row * side * 2 + column] = base + quadrantOffset;
+ }
+ }
+ matrix = next;
+ }
+ return matrix;
+}
+
+function parseHexColor(text, position) {
+ const match = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(text);
+ if (!match) {
+ throw new RangeError(`palette[${position}] must be a hex colour such as '#a1b2c3' or '#abc', or an [r, g, b] array of numbers from 0 to 1, got ${JSON.stringify(text)}`);
+ }
+ const digits = match[1].length === 3 ? [...match[1]].map(digit => digit + digit).join('') : match[1];
+ return [0, 2, 4].map(offset => parseInt(digits.slice(offset, offset + 2), 16) / 255);
+}
+
+function parseArrayColor(color, position) {
+ const valid = color.length === 3 && color.every(value => typeof value === 'number' && value >= 0 && value <= 1);
+ if (!valid) {
+ throw new RangeError(`palette[${position}] must be a hex colour such as '#a1b2c3' or an [r, g, b] array of three numbers from 0 to 1, got ${JSON.stringify(color)}`);
+ }
+ return color;
+}
+
+function parsePaletteColor(color, position) {
+ if (typeof color === 'string') return parseHexColor(color, position);
+ if (Array.isArray(color)) return parseArrayColor(color, position);
+ throw new RangeError(`palette[${position}] must be a hex colour such as '#a1b2c3' or an [r, g, b] array of numbers from 0 to 1, got ${String(color)}`);
+}
+
+/**
+ * Checks the `palette` and `dither` options of createGaussianSplats and returns `{ colors, count, dither }` (colors is a
+ * Float32Array of r, g, b per colour), or null when no palette is given.
+ */
+export function resolveSplatPalette(palette, dither, alphaCut, caller) {
+ if (palette === undefined || palette === null) {
+ if (dither !== undefined && dither !== 'none') {
+ throw new TypeError(`${caller} dither needs a palette to snap to: pass palette as an array of 2 to 256 colours, or leave dither out`);
+ }
+ return null;
+ }
+ const { minimumColors, maximumColors } = SPLAT_PALETTE_LIMITS;
+ if (!Array.isArray(palette) || palette.length < minimumColors || palette.length > maximumColors) {
+ throw new RangeError(`${caller} palette must be an array of ${minimumColors} to ${maximumColors} colours (hex strings or [r, g, b] arrays from 0 to 1), got ${Array.isArray(palette) ? `${palette.length} colours` : typeof palette}`);
+ }
+ const resolvedDither = dither ?? 'none';
+ if (!SPLAT_DITHER_MODES.includes(resolvedDither)) {
+ throw new RangeError(`${caller} dither must be one of ${SPLAT_DITHER_MODES.map(mode => `'${mode}'`).join(', ')}, got ${JSON.stringify(dither)}`);
+ }
+ if (alphaCut === null) {
+ throw new TypeError(`${caller} palette needs alphaCut (a number from 0 to 1) so the splats draw as opaque discs; blended pixels cannot be snapped to a palette. Pass alphaCut: 0.5, or leave palette out`);
+ }
+ const colors = new Float32Array(palette.length * 3);
+ palette.forEach((color, position) => colors.set(parsePaletteColor(color, position), position * 3));
+ return { colors, count: palette.length, dither: resolvedDither };
+}
+
+function ditherOffset(mode, pixelX, pixelY) {
+ const size = DITHER_SIZES[mode];
+ if (size === 0) return 0;
+ const matrix = buildBayerMatrix(size);
+ const index = matrix[(pixelY % size) * size + (pixelX % size)];
+ return ((index + 0.5) / (size * size) - 0.5) * SPLAT_DITHER_SPREAD;
+}
+
+/**
+ * The palette colour the shader writes for a splat colour `rgb` (three numbers from 0 to 1) at integer pixel
+ * (`pixelX`, `pixelY`) of the canvas. The nearest colour by squared RGB distance wins, the first on a tie.
+ */
+export function snapToSplatPalette(rgb, pixelX, pixelY, palette) {
+ const offset = ditherOffset(palette.dither, pixelX, pixelY);
+ const shifted = rgb.map(value => Math.min(Math.max(value + offset, 0), 1));
+ let bestIndex = 0;
+ let bestDistance = Infinity;
+ for (let index = 0; index < palette.count; index++) {
+ const distance = [0, 1, 2].reduce((sum, channel) => sum + (shifted[channel] - palette.colors[index * 3 + channel]) ** 2, 0);
+ if (distance < bestDistance) {
+ bestDistance = distance;
+ bestIndex = index;
+ }
+ }
+ return Array.from(palette.colors.subarray(bestIndex * 3, bestIndex * 3 + 3));
+}
+
+function ditherShaderLines(mode) {
+ const size = DITHER_SIZES[mode];
+ if (size === 0) return '';
+ const matrix = buildBayerMatrix(size);
+ return `const int BAYER[${size * size}] = int[${size * size}](${matrix.join(', ')});
+ ivec2 pixel = ivec2(gl_FragCoord.xy) % ${size};
+ float threshold = (float(BAYER[pixel.y * ${size} + pixel.x]) + 0.5) / ${size * size}.0 - 0.5;
+ source = clamp(source + threshold * ${SPLAT_DITHER_SPREAD.toFixed(2)}, 0.0, 1.0);`;
+}
+
+/** The opaque fragment shader with the palette step: `count` colours in the uniform array `paletteColors`. */
+export function buildPaletteFragmentSource(count, mode) {
+ return `#version 300 es
+precision highp float;
+uniform float hdrEnabled;
+uniform float exposure;
+uniform float alphaCut;
+uniform vec3 paletteColors[${count}];
+in vec4 vertexColor;
+in vec2 vertexOffset;
+out vec4 outputColor;
+void main() {
+ float falloff = -dot(vertexOffset, vertexOffset);
+ if (falloff < -4.0) discard;
+ float alpha = exp(falloff) * vertexColor.a;
+ if (alpha < max(alphaCut, 1.0 / 255.0)) discard;
+ vec3 source = vertexColor.rgb;
+ ${ditherShaderLines(mode)}
+ vec3 snapped = paletteColors[0];
+ float bestDistance = dot(source - snapped, source - snapped);
+ for (int index = 1; index < ${count}; index++) {
+ vec3 difference = source - paletteColors[index];
+ float distanceToColor = dot(difference, difference);
+ if (distanceToColor < bestDistance) {
+ bestDistance = distanceToColor;
+ snapped = paletteColors[index];
+ }
+ }
+ vec3 color = hdrEnabled > 0.5 ? pow(snapped, vec3(2.2)) * exposure : snapped;
+ outputColor = vec4(color, 1.0);
+}`;
+}
diff --git a/tests/gaussian-splat-palette.test.js b/tests/gaussian-splat-palette.test.js
new file mode 100644
index 00000000..5991f4fa
--- /dev/null
+++ b/tests/gaussian-splat-palette.test.js
@@ -0,0 +1,142 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import test from 'node:test';
+import { mat4 } from 'gl-matrix';
+import { attachGaussianSplats, createGaussianSplats, createGaussianSplatsAsync, GAUSSIAN_SPLAT_SHADER_SOURCES } from '../src/gaussian-splats.js';
+import { buildBayerMatrix, buildPaletteFragmentSource, resolveSplatPalette, snapToSplatPalette } from '../src/splat-palette.js';
+
+const BLACK_AND_WHITE = ['#000000', '#fff'];
+
+function resolve(palette, dither, alphaCut = 0.5) {
+ return resolveSplatPalette(palette, dither, alphaCut, 'createGaussianSplats');
+}
+
+function greyGrid(value, dither, size) {
+ const palette = resolve(BLACK_AND_WHITE, dither);
+ const rows = [];
+ for (let pixelY = 0; pixelY < size; pixelY++) {
+ let row = '';
+ for (let pixelX = 0; pixelX < size; pixelX++) {
+ row += snapToSplatPalette([value, value, value], pixelX, pixelY, palette)[0] === 1 ? 'W' : 'B';
+ }
+ rows.push(row);
+ }
+ return rows;
+}
+
+const countWhite = rows => rows.join('').split('W').length - 1;
+
+test('the Bayer matrices hold each index once in the standard order', () => {
+ assert.deepEqual(buildBayerMatrix(4), [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5]);
+ assert.deepEqual([...buildBayerMatrix(8)].sort((first, second) => first - second), Array.from({ length: 64 }, (_, index) => index));
+});
+
+test('without dither each colour snaps to the nearest palette colour, first on a tie', () => {
+ const palette = resolve(['#000000', '#ffffff', [1, 0, 0]]);
+ assert.deepEqual(snapToSplatPalette([0.4, 0.4, 0.4], 0, 0, palette), [0, 0, 0]);
+ assert.deepEqual(snapToSplatPalette([0.6, 0.6, 0.6], 7, 3, palette), [1, 1, 1]);
+ assert.deepEqual(snapToSplatPalette([0.9, 0.1, 0.1], 2, 2, palette), [1, 0, 0]);
+ assert.deepEqual(snapToSplatPalette([0.5, 0.5, 0.5], 0, 0, resolve(BLACK_AND_WHITE)), [0, 0, 0]);
+ assert.deepEqual(greyGrid(0.5, 'none', 2), ['BB', 'BB']);
+});
+
+test('bayer4 turns mid grey into a checkerboard and a 0.4 grey into its two lightest cells', () => {
+ assert.deepEqual(greyGrid(0.5, 'bayer4', 4), ['BWBW', 'WBWB', 'BWBW', 'WBWB']);
+ assert.deepEqual(greyGrid(0.4, 'bayer4', 4), ['BBBB', 'BBWB', 'BBBB', 'WBBB']);
+});
+
+test('bayer8 splits mid grey into half white, and the grid repeats every 8 pixels', () => {
+ const grid = greyGrid(0.5, 'bayer8', 16);
+ assert.equal(countWhite(grid.slice(0, 8).map(row => row.slice(0, 8))), 32);
+ assert.deepEqual(grid.slice(8).map(row => row.slice(8)), grid.slice(0, 8).map(row => row.slice(0, 8)));
+});
+
+test('the palette needs alphaCut, 2 to 256 colours, a real dither name and says what to pass otherwise', () => {
+ assert.equal(resolveSplatPalette(undefined, undefined, null, 'createGaussianSplats'), null);
+ assert.equal(resolveSplatPalette(null, 'none', 0.5, 'createGaussianSplats'), null);
+ assert.throws(() => resolve(undefined, 'bayer4'), /dither needs a palette/);
+ assert.throws(() => resolve(['#000000']), /palette must be an array of 2 to 256 colours.*got 1 colours/);
+ assert.throws(() => resolve(new Array(257).fill('#000')), /2 to 256 colours.*got 257/);
+ assert.throws(() => resolve('#000000'), /palette must be an array of 2 to 256 colours.*got string/);
+ assert.throws(() => resolve(['#000000', 'red']), /palette\[1\] must be a hex colour.*"red"/);
+ assert.throws(() => resolve(['#000000', [0, 1.5, 0]]), /palette\[1\] must be a hex colour.*\[0,1\.5,0\]/);
+ assert.throws(() => resolve(['#000000', 7]), /palette\[1\] must be a hex colour.*got 7/);
+ assert.throws(() => resolve(BLACK_AND_WHITE, 'floyd'), /dither must be one of 'none', 'bayer4', 'bayer8', got "floyd"/);
+ assert.throws(() => resolve(BLACK_AND_WHITE, 'bayer4', null), /palette needs alphaCut/);
+ assert.equal(resolve(['#abc', [0, 0.5, 1]], 'bayer8').count, 2);
+ assert.deepEqual(Array.from(resolve(['#ff8000', '#000']).colors.subarray(0, 3)), [1, 128 / 255, 0].map(Math.fround));
+});
+
+function oneSplat() {
+ return {
+ count: 1,
+ positions: new Float32Array([0, 0, -3]),
+ scales: new Float32Array([0.1, 0.1, 0.1]),
+ rotations: new Float32Array([1, 0, 0, 0]),
+ colors: new Uint8Array([200, 100, 50, 255]),
+ bounds: { minimum: [-1, -1, -4], maximum: [1, 1, -2] },
+ };
+}
+
+test('createGaussianSplats and its async twin validate the palette at the boundary', async () => {
+ const data = oneSplat();
+ assert.equal(createGaussianSplats(data, { alphaCut: 0.5 }).palette, null);
+ const splats = createGaussianSplats(data, { alphaCut: 0.5, palette: BLACK_AND_WHITE, dither: 'bayer4' });
+ assert.equal(splats.palette.count, 2);
+ assert.equal(splats.palette.dither, 'bayer4');
+ assert.throws(() => createGaussianSplats(data, { palette: BLACK_AND_WHITE }), /createGaussianSplats palette needs alphaCut/);
+ await assert.rejects(createGaussianSplatsAsync(data, { alphaCut: 0.5, palette: ['#000'] }), /createGaussianSplatsAsync palette must be an array of 2 to 256/);
+});
+
+function createRecordingRenderer() {
+ const calls = [];
+ const context = new Proxy({}, {
+ get(target, name) {
+ if (typeof name !== 'string') return undefined;
+ if (name === 'getShaderParameter' || name === 'getProgramParameter') return () => true;
+ if (/^[A-Z_0-9]+$/.test(name)) return name;
+ return (...parameters) => {
+ calls.push([name, ...parameters]);
+ return { created: name };
+ };
+ },
+ });
+ const renderer = {
+ context,
+ canvas: { width: 64, height: 64 },
+ multisampleFramebuffer: {},
+ projection: mat4.perspective(mat4.create(), 1, 1, 0.1, 50),
+ view: mat4.create(),
+ hdr: false,
+ drawBlendBatches() {},
+ dispose() {},
+ };
+ return { renderer, calls };
+}
+
+function drawWith(options) {
+ const { renderer, calls } = createRecordingRenderer();
+ attachGaussianSplats(renderer, createGaussianSplats(oneSplat(), options));
+ calls.length = 0;
+ renderer.drawBlendBatches({ eye: [0, 0, 0], exposure: 1 });
+ return calls;
+}
+
+test('without a palette the shaders and draw calls are as before', () => {
+ const plain = drawWith({ alphaCut: 0.5 });
+ assert.ok(!plain.some(([name]) => name === 'uniform3fv'));
+ assert.ok(!plain.filter(([name]) => name === 'shaderSource').some(call => String(call[2]).includes('paletteColors')));
+ const digest = createHash('sha256').update(GAUSSIAN_SPLAT_SHADER_SOURCES.opaqueFragment).digest('hex');
+ assert.equal(digest, 'd86baccbe36073ee22f6df8c9a2687bb6a9c1d2e9f3046b951139e5ae536cb61');
+});
+
+test('a palette scene draws with the palette shader and uploads its colours', () => {
+ const snapped = drawWith({ alphaCut: 0.5, palette: ['#000', '#fff', '#f00'], dither: 'bayer4' });
+ const upload = snapped.find(([name]) => name === 'uniform3fv');
+ assert.deepEqual(Array.from(upload[2]), [0, 0, 0, 1, 1, 1, 1, 0, 0]);
+ const sources = snapped.filter(([name]) => name === 'shaderSource').map(call => call[2]);
+ assert.ok(sources.includes(buildPaletteFragmentSource(3, 'bayer4')));
+ assert.ok(buildPaletteFragmentSource(3, 'bayer4').includes(`int[16](${buildBayerMatrix(4).join(', ')})`));
+ assert.ok(!buildPaletteFragmentSource(3, 'none').includes('BAYER'));
+ assert.equal(snapped.filter(([name]) => name === 'drawArraysInstanced').length, 1);
+});