Skip to content

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

9.0 KB
Raw Blame
/**
 * Materials in the words of a shading artist, written as glTF 2.0 PBR
 * metallic-roughness plus the Khronos extensions for clearcoat, sheen,
 * specular, IOR, transmission, volume, iridescence, anisotropy, emissive
 * strength and unlit.
 */
import { type ColorInput, linearRgb, linearRgba } from "./color.js";

/** A texture added to the document (`GltfDocument.addTexture`). */
export interface TextureRef {
	readonly texture: number;
}

export interface TextureSlot {
	texture: TextureRef;
	/** UV set. Default 0. */
	texCoord?: number;
	/**
	 * Placement of the image on the UVs (KHR_texture_transform): `scale`
	 * repeats it (a tiling detail map), `offset` shifts it, `rotation` turns
	 * it (degrees, counterclockwise).
	 */
	transform?: {
		scale?: [number, number];
		offset?: [number, number];
		rotation?: number;
	};
}

export interface MaterialSpec {
	name?: string;
	/** Base color (display sRGB; alpha from #rrggbbaa or a 4th component). Default white. */
	color?: ColorInput;
	colorTexture?: TextureRef | TextureSlot;
	/** 0..1. Default 0 (glTF's default of 1 is rarely what a sculpt wants). */
	metallic?: number;
	/** 0..1. Default 0.5. */
	roughness?: number;
	/** Green = roughness, blue = metallic, as glTF packs them. */
	metallicRoughnessTexture?: TextureRef | TextureSlot;
	normalTexture?: TextureRef | (TextureSlot & { scale?: number });
	occlusionTexture?: TextureRef | (TextureSlot & { strength?: number });
	/** Emitted color (display sRGB). */
	emissive?: ColorInput;
	/** Multiplies `emissive` past 1 for bloom (KHR_materials_emissive_strength). */
	emissiveStrength?: number;
	emissiveTexture?: TextureRef | TextureSlot;
	/** Default "opaque". "mask" cuts out below `alphaCutoff` (hair cards, frayed hems). */
	alphaMode?: "opaque" | "mask" | "blend";
	/** Default 0.5. */
	alphaCutoff?: number;
	/** Render back faces (cloaks, leaves, hair cards). */
	doubleSided?: boolean;
	/** No lighting (KHR_materials_unlit). */
	unlit?: boolean;
	/** Lacquer layer: strength 0..1, or with its own roughness. */
	clearcoat?: number | { factor: number; roughness?: number };
	/** Cloth and fur retroreflection. */
	sheen?: { color: ColorInput; roughness?: number };
	/** Dielectric specular strength and tint. */
	specular?: { factor?: number; color?: ColorInput };
	/** Index of refraction. Default 1.5. */
	ior?: number;
	/** Light passing through thin surfaces, 0..1. */
	transmission?: number;
	/** Thick transmissive volume (eye lens, amber, ice). */
	volume?: {
		thickness: number;
		attenuationColor?: ColorInput;
		attenuationDistance?: number;
	};
	/** Thin-film interference: strength 0..1, or with film IOR and thickness range (nm). */
	iridescence?:
		| number
		| { factor: number; ior?: number; thickness?: [number, number] };
	/** Brushed / combed highlights: strength 0..1, rotation in degrees. */
	anisotropy?: { strength: number; rotation?: number };
	/**
	 * Light scattering under the surface (skin, wax, jade, leaves): strength
	 * 0..1 and the scattered color (display sRGB). glTF has no ratified
	 * lobe for it, so it is written to `extras.framefields.subsurface`,
	 * which framefields renders and other viewers ignore.
	 */
	subsurface?: number | { factor: number; color?: ColorInput };
	/** Free data for other tools (glTF `extras`). */
	extras?: Record<string, unknown>;
}

export interface MaterialJson {
	json: Record<string, unknown>;
	extensions: string[];
}

const slot = (t: TextureRef | TextureSlot): TextureSlot =>
	"texture" in t && typeof t.texture === "object"
		? (t as TextureSlot)
		: { texture: t as TextureRef };

function textureInfo(
	t: TextureRef | TextureSlot,
	used: Set<string>,
	extra: Record<string, number> = {},
): Record<string, unknown> {
	const s = slot(t);
	const info: Record<string, unknown> = {
		index: s.texture.texture,
		...(s.texCoord ? { texCoord: s.texCoord } : {}),
		...extra,
	};
	const tr = s.transform;
	if (tr && (tr.scale || tr.offset || tr.rotation)) {
		used.add("KHR_texture_transform");
		info.extensions = {
			KHR_texture_transform: {
				...(tr.offset ? { offset: tr.offset } : {}),
				...(tr.rotation ? { rotation: (tr.rotation * Math.PI) / 180 } : {}),
				...(tr.scale ? { scale: tr.scale } : {}),
			},
		};
	}
	return info;
}

function check(name: string, v: number | undefined, lo = 0, hi = 1) {
	if (v === undefined) return;
	if (!Number.isFinite(v) || v < lo || v > hi)
		throw new Error(`material: ${name} ${v} is outside ${lo}..${hi}`);
}

/** The material's glTF JSON and the extensions it uses. */
export function materialJson(m: MaterialSpec): MaterialJson {
	check("metallic", m.metallic);
	check("roughness", m.roughness);
	check("alphaCutoff", m.alphaCutoff);
	check("transmission", m.transmission);
	check("ior", m.ior, 1, 4);
	check("emissiveStrength", m.emissiveStrength, 0, 1e6);

	const used = new Set<string>();
	const info = (t: TextureRef | TextureSlot, extra?: Record<string, number>) =>
		textureInfo(t, used, extra);
	const pbr: Record<string, unknown> = {
		baseColorFactor: linearRgba(m.color ?? "#ffffff"),
		metallicFactor: m.metallic ?? 0,
		roughnessFactor: m.roughness ?? 0.5,
	};
	if (m.colorTexture) pbr.baseColorTexture = info(m.colorTexture);
	if (m.metallicRoughnessTexture)
		pbr.metallicRoughnessTexture = info(m.metallicRoughnessTexture);

	const json: Record<string, unknown> = { pbrMetallicRoughness: pbr };
	if (m.name) json.name = m.name;
	if (m.normalTexture) {
		const scale =
			"scale" in m.normalTexture ? m.normalTexture.scale : undefined;
		json.normalTexture = info(
			m.normalTexture,
			scale === undefined ? {} : { scale },
		);
	}
	if (m.occlusionTexture) {
		const strength =
			"strength" in m.occlusionTexture
				? m.occlusionTexture.strength
				: undefined;
		json.occlusionTexture = info(
			m.occlusionTexture,
			strength === undefined ? {} : { strength },
		);
	}
	if (m.emissive) json.emissiveFactor = linearRgb(m.emissive);
	if (m.emissiveTexture) {
		json.emissiveTexture = info(m.emissiveTexture);
		json.emissiveFactor ??= [1, 1, 1];
	}
	if (m.alphaMode && m.alphaMode !== "opaque") {
		json.alphaMode = m.alphaMode.toUpperCase();
		if (m.alphaMode === "mask" && m.alphaCutoff !== undefined)
			json.alphaCutoff = m.alphaCutoff;
	}
	if (m.doubleSided) json.doubleSided = true;
	const extras: Record<string, unknown> = { ...(m.extras ?? {}) };
	if (m.subsurface !== undefined) {
		const ss =
			typeof m.subsurface === "number"
				? { factor: m.subsurface }
				: m.subsurface;
		check("subsurface", ss.factor);
		const own =
			(extras.framefields as Record<string, unknown> | undefined) ?? {};
		extras.framefields = {
			...own,
			subsurface: {
				factor: ss.factor,
				color: linearRgb(ss.color ?? "#ff6a4a"),
			},
		};
	}
	if (Object.keys(extras).length) json.extras = extras;

	const ext: Record<string, Record<string, unknown>> = {};
	if (m.unlit) ext.KHR_materials_unlit = {};
	if (m.emissiveStrength !== undefined && m.emissiveStrength !== 1)
		ext.KHR_materials_emissive_strength = {
			emissiveStrength: m.emissiveStrength,
		};
	if (m.clearcoat !== undefined) {
		const c =
			typeof m.clearcoat === "number" ? { factor: m.clearcoat } : m.clearcoat;
		check("clearcoat", c.factor);
		check("clearcoat roughness", c.roughness);
		ext.KHR_materials_clearcoat = {
			clearcoatFactor: c.factor,
			...(c.roughness === undefined
				? {}
				: { clearcoatRoughnessFactor: c.roughness }),
		};
	}
	if (m.sheen) {
		check("sheen roughness", m.sheen.roughness);
		ext.KHR_materials_sheen = {
			sheenColorFactor: linearRgb(m.sheen.color),
			sheenRoughnessFactor: m.sheen.roughness ?? 0.5,
		};
	}
	if (m.specular) {
		check("specular", m.specular.factor);
		ext.KHR_materials_specular = {
			...(m.specular.factor === undefined
				? {}
				: { specularFactor: m.specular.factor }),
			...(m.specular.color
				? { specularColorFactor: linearRgb(m.specular.color) }
				: {}),
		};
	}
	if (m.ior !== undefined) ext.KHR_materials_ior = { ior: m.ior };
	if (m.transmission !== undefined)
		ext.KHR_materials_transmission = { transmissionFactor: m.transmission };
	if (m.volume) {
		ext.KHR_materials_volume = {
			thicknessFactor: m.volume.thickness,
			...(m.volume.attenuationColor
				? { attenuationColor: linearRgb(m.volume.attenuationColor) }
				: {}),
			...(m.volume.attenuationDistance === undefined
				? {}
				: { attenuationDistance: m.volume.attenuationDistance }),
		};
	}
	if (m.iridescence !== undefined) {
		const i =
			typeof m.iridescence === "number"
				? { factor: m.iridescence }
				: m.iridescence;
		check("iridescence", i.factor);
		ext.KHR_materials_iridescence = {
			iridescenceFactor: i.factor,
			...(i.ior === undefined ? {} : { iridescenceIor: i.ior }),
			...(i.thickness
				? {
						iridescenceThicknessMinimum: i.thickness[0],
						iridescenceThicknessMaximum: i.thickness[1],
					}
				: {}),
		};
	}
	if (m.anisotropy) {
		check("anisotropy", m.anisotropy.strength);
		ext.KHR_materials_anisotropy = {
			anisotropyStrength: m.anisotropy.strength,
			...(m.anisotropy.rotation
				? { anisotropyRotation: (m.anisotropy.rotation * Math.PI) / 180 }
				: {}),
		};
	}
	if (Object.keys(ext).length) json.extensions = ext;
	return { json, extensions: [...Object.keys(ext), ...used] };
}