Skip to content

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

11.5 KB
Raw Blame
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { MeshoptEncoder } from "meshoptimizer/encoder";
import { afterEach, describe, expect, it, vi } from "vitest";
import { GltfLoader, loadGLTF } from "./gltf-loader.js";

const IMAGE = "data:image/png;base64,iVBORw0KGgo=";

/** A one-quad glTF with two UV sets (TEXCOORD_1 = TEXCOORD_0 + 10) and the given material. */
function quadGltf(
	material: Record<string, unknown>,
	extra: Record<string, unknown> = {},
): Record<string, unknown> {
	const pos = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0]);
	const uv0 = new Float32Array([0, 0, 1, 0, 0, 1, 1, 1]);
	const uv1 = uv0.map((v) => v + 10);
	const bin = Buffer.concat([pos, uv0, uv1].map((a) => Buffer.from(a.buffer)));
	return {
		asset: { version: "2.0" },
		buffers: [
			{
				byteLength: bin.length,
				uri: `data:application/octet-stream;base64,${bin.toString("base64")}`,
			},
		],
		bufferViews: [
			{ buffer: 0, byteOffset: 0, byteLength: 48 },
			{ buffer: 0, byteOffset: 48, byteLength: 32 },
			{ buffer: 0, byteOffset: 80, byteLength: 32 },
		],
		accessors: [
			{ bufferView: 0, componentType: 5126, count: 4, type: "VEC3" },
			{ bufferView: 1, componentType: 5126, count: 4, type: "VEC2" },
			{ bufferView: 2, componentType: 5126, count: 4, type: "VEC2" },
		],
		meshes: [
			{
				primitives: [
					{
						attributes: { POSITION: 0, TEXCOORD_0: 1, TEXCOORD_1: 2 },
						material: 0,
					},
				],
			},
		],
		images: [{ uri: IMAGE }, { uri: "data:image/webp;base64,UklGRg==" }],
		textures: [{ source: 0, sampler: 0 }],
		samplers: [{}],
		materials: [{ name: "M", ...material }],
		...extra,
	};
}

const parse = (doc: Record<string, unknown>) =>
	GltfLoader.parse(JSON.stringify(doc));

describe("glTF texture features", () => {
	afterEach(() => vi.restoreAllMocks());

	it("bakes KHR_texture_transform into the mesh UVs", () => {
		const model = parse(
			quadGltf({
				pbrMetallicRoughness: {
					baseColorTexture: {
						index: 0,
						extensions: {
							KHR_texture_transform: {
								offset: [0.5, 0.25],
								scale: [2, 4],
								rotation: Math.PI / 2,
							},
						},
					},
				},
			}),
		);
		const uvs = Array.from(model.meshes[0]!.uvs);
		// uv (1, 0): scaled to (2, 0), rotated to (0, 2), offset to (0.5, 2.25).
		expect(uvs[2]).toBeCloseTo(0.5, 5);
		expect(uvs[3]).toBeCloseTo(2.25, 5);
		// uv (0, 1): scaled to (0, 4), rotated to (-4, 0), offset to (-3.5, 0.25).
		expect(uvs[4]).toBeCloseTo(-3.5, 5);
		expect(uvs[5]).toBeCloseTo(0.25, 5);
	});

	it("keeps each map's UV set and texture transform", () => {
		const model = parse(
			quadGltf({
				pbrMetallicRoughness: { baseColorTexture: { index: 0, texCoord: 1 } },
				occlusionTexture: {
					index: 0,
					extensions: { KHR_texture_transform: { offset: [0.25, 0.5] } },
				},
			}),
		);
		expect(Array.from(model.meshes[0]!.uvs.slice(0, 4))).toEqual([
			10, 10, 11, 10,
		]);
		expect(model.materials.M?.diffuseTextureBuffer).toBeDefined();
		expect(model.materials.M?.occlusionTextureBuffer).toBeDefined();
		expect(Array.from(model.meshes[0]!.mapUvs!.occlusion!.slice(0, 4))).toEqual(
			[0.25, 0.5, 1.25, 0.5],
		);
	});

	it("reads the sampler's NEAREST magnification and clamp wrap", () => {
		const doc = quadGltf({
			pbrMetallicRoughness: { baseColorTexture: { index: 0 } },
		});
		doc.samplers = [{ magFilter: 9728, wrapS: 33071 }];
		const mat = parse(doc).materials.M!;
		expect(mat.textureFilter).toBe("nearest");
		expect(mat.textureWrap).toBe("clamp");
	});

	it("reads each map's own sampler, so a detail map can tile under a clamped base color", () => {
		const doc = quadGltf({
			pbrMetallicRoughness: { baseColorTexture: { index: 0 } },
			normalTexture: { index: 1 },
			occlusionTexture: { index: 2 },
		});
		doc.textures = [
			{ source: 0, sampler: 0 },
			{ source: 0, sampler: 1 },
			{ source: 0 },
		];
		doc.samplers = [
			{ wrapS: 33071, wrapT: 33071 },
			{ wrapS: 10497, wrapT: 33648, magFilter: 9728 },
		];
		const mat = parse(doc).materials.M!;
		expect(mat.textureWrap).toBe("clamp");
		expect(mat.mapSampling?.normal).toEqual({
			wrapU: "repeat",
			wrapV: "mirror",
			filter: "nearest",
		});
		// No sampler: glTF's default, repeat and linear.
		expect(mat.mapSampling?.occlusion).toEqual({
			wrapU: "repeat",
			wrapV: "repeat",
			filter: "linear",
		});
		expect(mat.mapSampling?.metallicRoughness).toBeUndefined();
	});

	it("prefers WebP and Basis extension sources", () => {
		const doc = quadGltf({
			pbrMetallicRoughness: { baseColorTexture: { index: 0 } },
			normalTexture: { index: 1 },
		});
		doc.textures = [
			{ source: 0, extensions: { EXT_texture_webp: { source: 1 } } },
			{ extensions: { KHR_texture_basisu: { source: 0 } } },
		];
		const mat = parse(doc).materials.M!;
		expect(mat.diffuseTextureMime).toBe("image/webp");
		expect(mat.normalTextureBuffer).toBeDefined();
	});

	it("fails clearly on required mesh compression", () => {
		expect(() =>
			parse(
				quadGltf({}, { extensionsRequired: ["KHR_draco_mesh_compression"] }),
			),
		).toThrow(/KHR_draco_mesh_compression.*cannot decode/);
		expect(() =>
			parse(quadGltf({}, { extensionsRequired: ["EXT_meshopt_compression"] })),
		).toThrow(/EXT_meshopt_compression/);
	});

	it("decodes Draco positions and per-map UV attributes", async () => {
		const encoded = Buffer.from(
			"RFJBQ08CAgEBAAAAAwEBAQAAAQf/AREBAQAC/wAAAAAAAQAJAwAAAAEDCQIAAQAAAIA/AAAAAAAAAAAAAAAAAACAPwAAAAAAAAAAAAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAA=",
			"base64",
		);
		const doc = quadGltf(
			{ normalTexture: { index: 0 } },
			{
				extensionsRequired: ["KHR_draco_mesh_compression"],
				buffers: [
					{
						byteLength: encoded.length,
						uri: `data:application/octet-stream;base64,${encoded.toString("base64")}`,
					},
				],
				bufferViews: [{ buffer: 0, byteLength: encoded.length }],
				accessors: [
					{ componentType: 5126, count: 3, type: "VEC3" },
					{ componentType: 5126, count: 3, type: "VEC2" },
				],
				meshes: [
					{
						primitives: [
							{
								attributes: { POSITION: 0, TEXCOORD_0: 1 },
								material: 0,
								extensions: {
									KHR_draco_mesh_compression: {
										bufferView: 0,
										attributes: { POSITION: 0, TEXCOORD_0: 1 },
									},
								},
							},
						],
					},
				],
			},
		);
		const result = await GltfLoader.parseAsync(JSON.stringify(doc));
		const mesh = result.meshes[0]!;
		expect(Array.from(mesh.positions)).toEqual([0, 0, 0, 1, 0, 0, 0, 1, 0]);
		expect(Array.from(mesh.mapUvs!.normal!)).toEqual([0, 0, 1, 0, 0, 1]);
		doc.extensionsRequired = [];
		expect(() => parse(doc)).toThrow(/requires GltfLoader.parseAsync/);
	});

	it("decodes a required Draco-compressed mesh asynchronously", async () => {
		const dracoRoot = path.dirname(
			fileURLToPath(import.meta.resolve("draco3dgltf")),
		);
		const encoded = fs.readFileSync(path.join(dracoRoot, "bunny.drc"));
		const doc = quadGltf(
			{},
			{
				extensionsUsed: ["KHR_draco_mesh_compression"],
				extensionsRequired: ["KHR_draco_mesh_compression"],
				buffers: [
					{
						byteLength: encoded.length,
						uri: `data:application/octet-stream;base64,${encoded.toString("base64")}`,
					},
				],
				bufferViews: [{ buffer: 0, byteLength: encoded.length }],
				accessors: [
					{ componentType: 5126, count: 34834, type: "VEC3" },
					{ componentType: 5125, count: 69451 * 3, type: "SCALAR" },
				],
				meshes: [
					{
						primitives: [
							{
								attributes: { POSITION: 0 },
								indices: 1,
								extensions: {
									KHR_draco_mesh_compression: {
										bufferView: 0,
										attributes: { POSITION: 0 },
									},
								},
							},
						],
					},
				],
			},
		);
		const result = await GltfLoader.parseAsync(JSON.stringify(doc));
		expect(result.meshes[0]!.positions.length).toBe(34834 * 3);
		expect(result.meshes[0]!.indices.length).toBe(69451 * 3);
		expect(result.bounds.size.every((v) => v > 0)).toBe(true);
	});

	it.each([
		"EXT_meshopt_compression",
		"KHR_meshopt_compression",
	])("decodes required %s vertex buffers asynchronously", async (extension) => {
		await MeshoptEncoder.ready;
		const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
		const compressed = MeshoptEncoder.encodeGltfBuffer(
			new Uint8Array(positions.buffer),
			3,
			12,
			"ATTRIBUTES",
			extension.startsWith("KHR_") ? 1 : 0,
		);
		const doc = quadGltf(
			{},
			{
				extensionsUsed: [extension],
				extensionsRequired: [extension],
				buffers: [
					{
						byteLength: compressed.length,
						uri: `data:application/octet-stream;base64,${Buffer.from(compressed).toString("base64")}`,
					},
				],
				bufferViews: [
					{
						buffer: 0,
						byteLength: positions.byteLength,
						byteStride: 12,
						extensions: {
							[extension]: {
								buffer: 0,
								byteOffset: 0,
								byteLength: compressed.length,
								byteStride: 12,
								count: 3,
								mode: "ATTRIBUTES",
							},
						},
					},
				],
				accessors: [
					{ bufferView: 0, componentType: 5126, count: 3, type: "VEC3" },
				],
				meshes: [{ primitives: [{ attributes: { POSITION: 0 } }] }],
			},
		);
		const result = await GltfLoader.parseAsync(JSON.stringify(doc));
		expect(Array.from(result.meshes[0]!.positions)).toEqual(
			Array.from(positions),
		);
	});

	it("applies sparse accessor values over an implicit zero base", () => {
		const position = new Float32Array([7, 8, 9]);
		const bytes = Buffer.concat([
			Buffer.from([1, 0, 0, 0]),
			Buffer.from(position.buffer),
		]);
		const doc = quadGltf(
			{},
			{
				buffers: [
					{
						byteLength: bytes.length,
						uri: `data:application/octet-stream;base64,${bytes.toString("base64")}`,
					},
				],
				bufferViews: [
					{ buffer: 0, byteOffset: 0, byteLength: 1 },
					{ buffer: 0, byteOffset: 4, byteLength: 12 },
				],
				accessors: [
					{
						componentType: 5126,
						count: 3,
						type: "VEC3",
						sparse: {
							count: 1,
							indices: { bufferView: 0, componentType: 5121 },
							values: { bufferView: 1 },
						},
					},
				],
				meshes: [{ primitives: [{ attributes: { POSITION: 0 } }] }],
			},
		);
		expect(Array.from(parse(doc).meshes[0]!.positions)).toEqual([
			0, 0, 0, 7, 8, 9, 0, 0, 0,
		]);
	});

	it("rejects unknown required extensions", () => {
		for (const ext of ["VENDOR_unknown", "KHR_materials_dispersion"]) {
			expect(() => parse(quadGltf({}, { extensionsRequired: [ext] }))).toThrow(
				ext,
			);
		}
	});

	it.each([
		[5, [0, 1, 2, 2, 1, 3]],
		[6, [0, 1, 2, 0, 2, 3]],
	])("expands triangle primitive mode %i", (mode, expected) => {
		const doc = quadGltf(
			{},
			{ meshes: [{ primitives: [{ attributes: { POSITION: 0 }, mode }] }] },
		);
		expect(Array.from(parse(doc).meshes[0]!.indices)).toEqual(expected);
	});

	it.each([
		[0, "point-list", [0, 1, 2, 3]],
		[1, "line-list", [0, 1, 2, 3]],
		[2, "line-list", [0, 1, 1, 2, 2, 3, 3, 0]],
		[3, "line-list", [0, 1, 1, 2, 2, 3]],
	] as const)("converts glTF primitive mode %i", (mode, topology, expected) => {
		const doc = quadGltf(
			{},
			{ meshes: [{ primitives: [{ attributes: { POSITION: 0 }, mode }] }] },
		);
		const mesh = parse(doc).meshes[0]!;
		expect(mesh.topology).toBe(topology);
		expect(Array.from(mesh.indices)).toEqual(expected);
	});

	it("loads a model from a bare relative path", () => {
		const dir = fs.mkdtempSync(path.join(process.cwd(), "tmp-gltf-rel-"));
		try {
			fs.writeFileSync(
				path.join(dir, "quad.gltf"),
				JSON.stringify(quadGltf({})),
			);
			// No "./" prefix, as in Layer.glb("models/robot.glb").
			const bare = `${path.basename(dir)}/quad.gltf`;
			expect(loadGLTF(bare).meshes).toHaveLength(1);
		} finally {
			fs.rmSync(dir, { recursive: true, force: true });
		}
	});
});