Skip to content

Code-first video & image, rendered natively on WebGPU.

13.5 KB
Raw Blame
/**
 * The fixture writer's output is standard glTF: the Khronos validator finds no errors or
 * warnings, and the engine's own loader reads back exactly what was written
 * (geometry, 32-bit indices, skins, named morph targets, materials, clips).
 */
import { denseMorphDeltas, parseGLB } from "@framefields/webgpu-renderers";
import { validateBytes } from "gltf-validator";
import { describe, expect, it } from "vitest";
import { encodePng, GltfDocument, linearRgba, Skeleton } from "./index.js";
import { readPng } from "./read-png.test-util.js";

async function validate(glb: Uint8Array) {
	const report = await validateBytes(glb, { maxIssues: 50 });
	const issues = report.issues.messages
		.filter((m: { severity: number }) => m.severity <= 1)
		.map(
			(m: { code: string; message: string; pointer?: string }) =>
				`${m.code} ${m.pointer ?? ""}: ${m.message}`,
		);
	return {
		errors: report.issues.numErrors,
		warnings: report.issues.numWarnings,
		issues,
	};
}

/** A quad strip of `rows` segments along +y, two vertices wide. */
function strip(rows: number, height: number) {
	const positions: number[] = [];
	const normals: number[] = [];
	const indices: number[] = [];
	for (let r = 0; r <= rows; r++) {
		const y = (r / rows) * height;
		positions.push(-5, y, 0, 5, y, 0);
		normals.push(0, 0, 1, 0, 0, 1);
		if (r < rows) {
			const a = r * 2;
			indices.push(a, a + 1, a + 3, a, a + 3, a + 2);
		}
	}
	return { positions, normals, indices };
}

describe("GltfDocument", () => {
	it("writes a skinned, morphing, animated character that validates and loads back", async () => {
		const skel = new Skeleton()
			.add("Root", { at: [0, 0, 0] })
			.add("Mid", { at: [0, 50, 0], parent: "Root" })
			.add("Tip", { at: [0, 100, 0], parent: "Mid" });
		const doc = new GltfDocument();
		const rig = doc.addSkeleton(skel);
		const s = strip(4, 100);
		const n = s.positions.length / 3;
		const joints: number[] = [];
		const weights: number[] = [];
		for (let v = 0; v < n; v++) {
			const y = s.positions[v * 3 + 1] as number;
			joints.push(y < 50 ? 0 : 1, y < 50 ? 1 : 2, 0, 0);
			weights.push(3, 1, 0, 0); // normalized on write
		}
		const bulge = s.positions.map((_, i) =>
			i % 3 === 0 ? s.positions[i]! * 0.5 : 0,
		);
		const material = doc.addMaterial({
			name: "Lacquer",
			color: "#d99a2b",
			roughness: 0.35,
			clearcoat: { factor: 1, roughness: 0.05 },
			sheen: { color: "#ffd9c0", roughness: 0.4 },
			doubleSided: true,
		});
		const mesh = doc.addMesh({
			name: "Strip",
			primitives: [
				{
					...s,
					joints,
					weights,
					material,
					targets: [
						{ name: "wide", positions: bulge },
						{ name: "flat", positions: new Array(n * 3).fill(0) },
					],
				},
			],
			weights: [0, 0],
		});
		const body = doc.addNode({ name: "Body", mesh, skin: rig.skin });
		const t = [0, 1];
		doc.addAnimation({
			name: "Bend",
			channels: [
				{
					node: rig.joints.get("Mid")!,
					path: "rotation",
					times: t,
					values: [0, 0, 0, 1, 0, 0, Math.SQRT1_2, Math.SQRT1_2],
				},
				{ node: body, path: "weights", times: t, values: [0, 0, 1, 0] },
			],
		});
		const glb = doc.toGlb();

		const report = await validate(glb);
		expect(report.issues).toEqual([]);
		expect(report.errors).toBe(0);

		const model = parseGLB(glb);
		const m = model.meshes[0]!;
		expect(Array.from(m.positions)).toEqual(s.positions);
		expect(Array.from(m.indices)).toEqual(s.indices);
		expect(m.morphTargets).toHaveLength(2);
		expect(Array.from(m.morphTargets![0]!.positions!)).toEqual(bulge);
		expect(Array.from(m.jointWeights!.slice(0, 4))).toEqual([0.75, 0.25, 0, 0]);
		const skin = model.skins![0]!;
		expect(skin.joints.map((j) => model.nodes![j]!.name)).toEqual([
			"Root",
			"Mid",
			"Tip",
		]);
		// Inverse bind matrices undo each joint's rest position.
		expect(
			Array.from(skin.inverseBindMatrices.slice(16 + 12, 16 + 15)),
		).toEqual([0, -50, 0]);
		expect(model.nodes![skin.joints[2]!]!.translation).toEqual([0, 50, 0]);
		const clip = model.animations.find((a) => a.name === "Bend")!;
		expect(clip.duration).toBeCloseTo(1);
		expect(clip.tracks.some((k) => k.weights)).toBe(true);
		const mat = Object.values(model.materials)[0]!;
		expect(mat.roughness).toBeCloseTo(0.35);
		expect(mat.twoSided).toBe(true);
		// Factors are linear in the file; the loader hands back display color.
		const [r] = linearRgba("#d99a2b");
		expect(r).toBeLessThan(0.75);
		expect(mat.diffuseColor?.[0]).toBeCloseTo(0xd9 / 255, 2);
		const json = doc.json() as {
			meshes: { extras: { targetNames: string[] } }[];
			extensionsUsed: string[];
		};
		expect(json.meshes[0]!.extras.targetNames).toEqual(["wide", "flat"]);
		expect(json.extensionsUsed).toEqual([
			"KHR_materials_clearcoat",
			"KHR_materials_sheen",
		]);
	});

	it("switches to 32-bit indices past 65,535 vertices", async () => {
		const s = strip(40000, 1000);
		const doc = new GltfDocument();
		doc.addNode({ mesh: doc.addMesh({ primitives: [s] }) });
		const glb = doc.toGlb();
		expect((await validate(glb)).errors).toBe(0);
		const m = parseGLB(glb).meshes[0]!;
		expect(m.indices).toBeInstanceOf(Uint32Array);
		expect(m.indices[m.indices.length - 1]).toBe(
			s.indices[s.indices.length - 1],
		);
	});

	it("stores morph targets that move few vertices as sparse accessors", async () => {
		const s = strip(20, 100);
		const n = s.positions.length / 3;
		const poke = new Array<number>(n * 3).fill(0);
		poke[7 * 3 + 2] = 4; // one vertex out along +z
		const doc = new GltfDocument();
		doc.addNode({
			mesh: doc.addMesh({
				primitives: [
					{
						...s,
						targets: [
							{
								name: "poke",
								positions: poke,
								normals: new Array(n * 3).fill(0),
							},
						],
					},
				],
			}),
		});
		const glb = doc.toGlb();
		const report = await validate(glb);
		expect(report.issues).toEqual([]);
		const jsonLength = new DataView(glb.buffer, glb.byteOffset).getUint32(
			12,
			true,
		);
		const json = JSON.parse(
			new TextDecoder().decode(glb.subarray(20, 20 + jsonLength)),
		) as {
			meshes: { primitives: { targets: { POSITION: number }[] }[] }[];
			accessors: { sparse?: { count: number }; max?: number[] }[];
		};
		const acc =
			json.accessors[json.meshes[0]!.primitives[0]!.targets[0]!.POSITION]!;
		expect(acc.sparse?.count).toBe(1);
		expect(acc.max).toEqual([0, 0, 4]);
		const m = parseGLB(glb).meshes[0]!;
		expect(Array.from(denseMorphDeltas(m.morphTargets![0]!, n))).toEqual(poke);
		// Kept sparse in memory: only the moved vertex.
		expect(Array.from(m.morphTargets![0]!.indices!)).toEqual([7]);
		expect(m.morphTargetNames).toEqual(["poke"]);
	});

	it("encodes PNGs that decode to the same pixels", () => {
		const w = 7;
		const h = 5;
		const rgba = Uint8Array.from(
			{ length: w * h * 4 },
			(_, i) => (i * 37 + (i >> 3) * 11) & 0xff,
		);
		const png = encodePng(rgba, w, h);
		expect(Array.from(png.subarray(1, 4))).toEqual([0x50, 0x4e, 0x47]);
		const back = readPng(png);
		expect([back.width, back.height]).toEqual([w, h]);
		expect(Array.from(back.rgba)).toEqual(Array.from(rgba));
	});

	it("writes texture transforms that tile a map, and the loader applies them to that map alone", async () => {
		const s = strip(1, 10);
		const uvs = [0, 1, 1, 1, 0, 0, 1, 0];
		const doc = new GltfDocument();
		const png = encodePng(new Uint8Array(4 * 4 * 4).fill(200), 4, 4);
		const material = doc.addMaterial({
			colorTexture: doc.addTexture({ image: png, mimeType: "image/png" }),
			normalTexture: {
				texture: doc.addTexture({ image: png, mimeType: "image/png" }),
				scale: 0.5,
				transform: { scale: [8, 8] },
			},
		});
		doc.addNode({
			mesh: doc.addMesh({ primitives: [{ ...s, uvs, material }] }),
		});
		const glb = doc.toGlb();
		const report = await validate(glb);
		expect(report.issues).toEqual([]);
		expect(
			(doc.json() as { extensionsUsed: string[] }).extensionsUsed,
		).toContain("KHR_texture_transform");
		const m = parseGLB(glb).meshes[0]!;
		expect(Array.from(m.uvs ?? [])).toEqual(uvs);
		expect(Array.from(m.mapUvs?.normal ?? [])).toEqual(uvs.map((x) => x * 8));
	});

	it("writes every material extension in a valid form", async () => {
		const doc = new GltfDocument();
		const material = doc.addMaterial({
			color: "#ffffffcc",
			alphaMode: "mask",
			alphaCutoff: 0.4,
			emissive: "#ff7a2e",
			emissiveStrength: 6,
			specular: { factor: 0.6, color: "#fff4e0" },
			ior: 1.38,
			transmission: 0.3,
			volume: {
				thickness: 2,
				attenuationColor: "#d99a2b",
				attenuationDistance: 5,
			},
			iridescence: { factor: 0.8, ior: 1.4, thickness: [120, 420] },
			anisotropy: { strength: 0.6, rotation: 90 },
		});
		doc.addNode({
			mesh: doc.addMesh({ primitives: [{ ...strip(1, 10), material }] }),
		});
		const report = await validate(doc.toGlb());
		expect(report.issues).toEqual([]);
		expect(report.errors).toBe(0);
	});

	it("writes layered lobes the engine loader reads back", () => {
		const doc = new GltfDocument();
		const material = doc.addMaterial({
			color: "#e8cfb0",
			clearcoat: { factor: 0.6, roughness: 0.1 },
			sheen: { color: "#ffd9c0", roughness: 0.4 },
			anisotropy: { strength: 0.5, rotation: 30 },
			iridescence: { factor: 0.7, ior: 1.4, thickness: [100, 380] },
			subsurface: { factor: 0.8, color: "#ff5040" },
		});
		doc.addNode({
			mesh: doc.addMesh({ primitives: [{ ...strip(1, 10), material }] }),
		});
		const surface = Object.values(parseGLB(doc.toGlb()).materials)[0]?.surface;
		expect(surface?.clearcoat).toBeCloseTo(0.6);
		expect(surface?.clearcoatRoughness).toBeCloseTo(0.1);
		expect(surface?.sheen).toBeCloseTo(1);
		// Display colors come back as written.
		expect(surface?.sheenColor?.[0]).toBeCloseTo(1, 2);
		expect(surface?.sheenColor?.[1]).toBeCloseTo(0xd9 / 0xff, 2);
		expect(surface?.anisotropyRotation).toBeCloseTo(30);
		expect(surface?.iridescenceThickness).toBeCloseTo(380);
		expect(surface?.subsurface).toBeCloseTo(0.8);
		expect(surface?.subsurfaceColor?.[1]).toBeCloseTo(0x50 / 0xff, 2);
	});

	it("writes rig drivers and transmissive glass the loader reads", () => {
		const doc = new GltfDocument();
		const glass = doc.addMaterial({
			transmission: 1,
			ior: 1.376,
			volume: { thickness: 0.3 },
		});
		doc.addNode({
			mesh: doc.addMesh({ primitives: [{ ...strip(1, 10), material: glass }] }),
		});
		doc.addDriver({ joint: "lid", from: "eye", rotate: { x: 0.65 } });
		const model = parseGLB(doc.toGlb());
		expect(model.drivers).toEqual([
			{ joint: "lid", from: "eye", rotate: { x: 0.65 } },
		]);
		const m = Object.values(model.materials)[0];
		expect(m?.shading).toBe("glass");
		expect(m?.ior).toBeCloseTo(1.376);
		expect(m?.thickness).toBeCloseTo(0.3);
		expect(() => doc.addDriver({ joint: "a", from: "b", rotate: {} })).toThrow(
			/finite share/,
		);
	});

	it("refuses inconsistent input where it is given", () => {
		const doc = new GltfDocument();
		expect(() =>
			doc.addMesh({
				primitives: [{ positions: [0, 0, 0, 1, 0, 0], normals: [0, 0, 1] }],
			}),
		).toThrow(/1 entries for 2 vertices/);
		expect(() =>
			doc.addMesh({ primitives: [{ ...strip(1, 1), indices: [0, 1, 9] }] }),
		).toThrow(/outside 0\.\.3/);
		const skinned = doc.addMesh({
			primitives: [
				{
					...strip(1, 1),
					joints: new Array(16).fill(0).map((_, i) => (i % 4 ? 0 : 3)),
					weights: new Array(16).fill(0).map((_, i) => (i % 4 ? 0 : 1)),
				},
			],
		});
		const rig = doc.addSkeleton(new Skeleton().add("A", { at: [0, 0, 0] }));
		expect(() => doc.addNode({ mesh: skinned, skin: rig.skin })).toThrow(
			/joint 3 but the skin has 1/,
		);
		expect(() => doc.addMaterial({ roughness: 2 })).toThrow(/outside 0\.\.1/);
	});
});

describe("Skeleton", () => {
	it("mirrors left joints to the right, under mirrored parents", () => {
		const s = new Skeleton()
			.add("Spine", { at: [0, 100, 0] })
			.add("LeftShoulder", { at: [5, 140, 0], parent: "Spine" })
			.add("LeftArm", { at: [20, 140, 0], parent: "LeftShoulder" })
			.mirror();
		expect(s.joint("RightArm").at).toEqual([-20, 140, 0]);
		expect(s.joint("RightArm").parent).toBe("RightShoulder");
		expect(s.joint("RightShoulder").parent).toBe("Spine");
	});

	it("keeps rest orientations: node rotations, inverse bind matrices, mirrored copies", async () => {
		// A forearm turned 90° about z at rest: its local x points up.
		const turn: [number, number, number, number] = [
			0,
			0,
			Math.SQRT1_2,
			Math.SQRT1_2,
		];
		const s = new Skeleton()
			.add("Root", { at: [0, 0, 0] })
			.add("LeftArm", { at: [10, 0, 0], parent: "Root", orient: turn })
			.add("LeftHand", { at: [10, 8, 0], parent: "LeftArm", orient: turn })
			.mirror();
		expect(s.local("LeftHand")).toEqual([
			expect.closeTo(8, 9),
			expect.closeTo(0, 9),
			expect.closeTo(0, 9),
		]);
		const r = s.joint("RightArm").orient!;
		expect(
			[r[0], r[1], r[2], r[3]].map((x) => Math.round(x * 1e6) / 1e6 + 0),
		).toEqual([0, 0, -0.707107, 0.707107]);
		const doc = new GltfDocument();
		doc.addSkeleton(s);
		const glb = doc.toGlb();
		expect((await validate(glb)).issues).toEqual([]);
		const model = parseGLB(glb);
		const skin = model.skins![0]!;
		const names = skin.joints.map((j) => model.nodes![j]!.name);
		// Each inverse bind matrix takes its joint's rest position to the origin.
		names.forEach((n, i) => {
			const at = s.joint(n).at;
			const m = skin.inverseBindMatrices;
			for (let r = 0; r < 3; r++)
				expect(
					m[i * 16 + r]! * at[0] +
						m[i * 16 + 4 + r]! * at[1] +
						m[i * 16 + 8 + r]! * at[2] +
						m[i * 16 + 12 + r]!,
				).toBeCloseTo(0, 5);
		});
		// The hand's node holds no extra turn: it rests as its parent does.
		const hand = model.nodes![skin.joints[names.indexOf("LeftHand")]!]!;
		expect(hand.rotation ?? [0, 0, 0, 1]).toEqual(
			[0, 0, 0, 1].map((v) => expect.closeTo(v, 9)),
		);
		expect(hand.translation?.[0]).toBeCloseTo(8, 6);
	});
});