material-designer-runtime 0.1.0 → 0.1.2

package/README.md

@@ -13,19 +13,94 @@ supported version alongside it.
 
 ## Usage
 
+There are two ways to put a document's material on a mesh: let the runtime hand you a
+**ready-made material** (all config loaded for you), or bake the **channel textures** and assign
+them to a material you build yourself. Everything bakes on a `WebGPURenderer`, which must be
+initialized (`await renderer.init()`) first.
+
+### Get a ready-made material
+
+`getNodeMaterial()` and `getMeshMaterial()` both load the document's family and every setting
+(metalness, roughness, the physical lobes, phong shininess, toon gradient, …) — you never copy
+config by hand. Pick based on what you need:
+
+- **`getNodeMaterial()`** — the TSL node material (`MeshStandardNodeMaterial`, `MeshPhysicalNodeMaterial`, …)
+  with full procedural fidelity: triplanar projection, parallax-occlusion, per-vertex AO, and
+  procedurally-driven lobes. WebGPU only.
+- **`getMeshMaterial()`** — a plain Three.js material (`MeshStandardMaterial`, `MeshPhysicalMaterial`,
+  `MeshLambertMaterial`, `MeshToonMaterial`, `MeshPhongMaterial`, `MeshMatcapMaterial`) with the baked
+  maps in the standard slots. Drops the node-only features above.
+
 ```ts
 import { MaterialGraphRuntime } from "material-designer-runtime";
+import { WebGPURenderer } from "three/webgpu";
+import { Mesh, SphereGeometry } from "three";
+
+const renderer = new WebGPURenderer();
+await renderer.init();
 
 const runtime = new MaterialGraphRuntime()
   .setRenderer(renderer)
-  .setBackend("offline")
   .fromDocument(document);
+await runtime.refresh(); // bake the graph to channel textures
 
-await runtime.refresh();
-mesh.material = runtime.material;
+const geometry = new SphereGeometry(1, 128, 64);
 
-runtime.setOutputResolution(1024);
+// (a) TSL node material — full fidelity (triplanar, parallax, procedural lobes), WebGPU only:
+const mesh = new Mesh(geometry, runtime.getNodeMaterial());
+// The node material object can change on a re-bake (e.g. a family switch) — keep the mesh current:
+runtime.surface.onRebuilt(() => { mesh.material = runtime.getNodeMaterial(); });
+
+// (b) …or a plain Three.js material with the baked maps + settings loaded in (pick one path):
+//   geometry.setAttribute("uv1", geometry.getAttribute("uv")); // .aoMap samples the 2nd UV set
+//   const mesh = new Mesh(geometry, runtime.getMeshMaterial());
+
+// Live edits re-bake implicitly — await whenIdle() before reading back:
 runtime.setNodeParam("noise", "scale", 18);
+runtime.setOutputResolution(1024);
+await runtime.whenIdle();
+
+runtime.dispose(); // release GPU resources when done
 ```
 
+### Bring your own material
+
+Bake just the PBR channel maps with the shared `bakeService` (no material surface is created) and
+assign them to your own material. The baked textures already carry the correct `.colorSpace`
+(base color / emission are sRGB, data channels linear), so you assign them as-is:
+
+```ts
+import { bakeService, MaterialGraphSession, defaultRegistry } from "material-designer-runtime";
+import { WebGPURenderer } from "three/webgpu";
+import { Mesh, BoxGeometry, MeshStandardMaterial } from "three";
+
+const renderer = new WebGPURenderer();
+await renderer.init();
+bakeService.attachRenderer(renderer);
+
+const session = new MaterialGraphSession(document, defaultRegistry);
+const set = await bakeService.bake(session, { size: 1024 }); // set.present = the channels actually baked
+
+const material = new MeshStandardMaterial();
+material.map = set.texture("baseColor"); // THREE.Texture | null, keyed by channel
+material.roughnessMap = set.texture("roughness");
+material.metalnessMap = set.texture("metallic");
+material.normalMap = set.texture("normal");
+material.aoMap = set.texture("ambientOcclusion");
+material.emissiveMap = set.texture("emission");
+material.emissive.set(0xffffff);
+material.roughness = 1;
+material.metalness = 1; // the maps carry the values — keep the multipliers at 1
+
+const geometry = new BoxGeometry(1, 1, 1);
+geometry.setAttribute("uv1", geometry.getAttribute("uv")); // aoMap samples the 2nd UV set
+const mesh = new Mesh(geometry, material);
+// Keep `set` alive while the material is in use — set.dispose() frees the render targets (and the textures).
+```
+
+`height` is baked separately (`set.heightTarget?.texture`). To read a channel back as CPU pixels
+for PNG export, use `bakeService.readImage(session, channel, 1024)` → `ImageData` (size must be a
+multiple of 64). If you keep a live `MaterialGraphRuntime`, the same baked textures are also
+reachable via `runtime.surface.getChannelTexture(channel)` and `runtime.surface.getHeightTexture()`.
+
 The editor owns UI state, selection, storage, presets, and undo history. This package owns only graph document loading, compilation, baking, direct parameter updates, and the material surface.

package/dist/document.d.ts

@@ -1,6 +1,6 @@
 import { type NodeRegistry } from "./graph/registry";
 import { type GraphChange, type MaterialGraphDocument, type MaterialGraphSource } from "./graph/types";
-export declare const MATERIAL_DOCUMENT_VERSION = 2;
+export declare const MATERIAL_DOCUMENT_VERSION = 4;
 export declare function cloneMaterialDocument(doc: MaterialGraphDocument): MaterialGraphDocument;
 export declare function createDefaultMaterialDocument(): MaterialGraphDocument;
 export declare function migrateMaterialDocument(doc: MaterialGraphDocument): MaterialGraphDocument;

package/dist/graph/bake-service.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from "three";
 import { RenderTarget, type WebGPURenderer, type MeshBasicNodeMaterial } from "three/webgpu";
-import { type CacheEntry } from "./compiler";
+import { type CacheEntry, type ParamUsage } from "./compiler";
 import type { MaterialGraphSource, MaterialValue, PbrSocket } from "./types";
 export declare const SURFACE_CHANNELS: PbrSocket[];
 export interface BakeOptions {
@@ -27,9 +27,11 @@ export declare class BakedTextureSet {
     private readonly cacheMats;
     cachePlan: CacheEntry[];
     uniforms: Map<string, Record<string, MaterialValue>>;
+    paramUsage: ParamUsage;
+    private readonly constArrays;
     heightTarget: RenderTarget | null;
     hasHeight: boolean;
-    present: Set<"roughness" | "normal" | "baseColor" | "metallic" | "emission" | "ambientOcclusion">;
+    present: Set<"roughness" | "normal" | "baseColor" | "metallic" | "ambientOcclusion" | "emission">;
     signature: string;
     size: number;
     constructor(size: number, channels: PbrSocket[]);
@@ -39,9 +41,11 @@ export declare class BakedTextureSet {
     cacheTarget(cacheId: string, size?: number, mips?: boolean): RenderTarget;
     cacheMaterial(cacheId: string): MeshBasicNodeMaterial;
     cacheTexture(cacheId: string, size?: number, mips?: boolean): THREE.Texture;
+    pruneCaches(liveIds: ReadonlySet<string>): void;
     firstTarget(): RenderTarget | null;
     ensureHeightTarget(): RenderTarget;
     texture(ch: PbrSocket): THREE.Texture | null;
+    allocConstantArray(nodeId: string, key: string, data: ArrayLike<number>, elementType: "float" | "vec3"): MaterialValue;
     flushCaches(): void;
     dispose(): void;
 }

package/dist/graph/channel-baker.d.ts

@@ -4,7 +4,7 @@ export declare const FIELD_CHANNELS: PbrSocket[];
 export declare const COLOR_CHANNELS: PbrSocket[];
 export declare function encodeChannel(node: MaterialValue, channel: PbrSocket): MaterialValue;
 export declare function makeChannelMaterial(): MeshBasicNodeMaterial;
-export declare function compileMaterialsAsync(renderer: WebGPURenderer, materials: MeshBasicNodeMaterial[]): Promise<void>;
+export declare function compileMaterialsAsync(renderer: WebGPURenderer, materials: MeshBasicNodeMaterial[], destSize: number): Promise<void>;
 export declare function renderCacheToTarget(renderer: WebGPURenderer, material: MeshBasicNodeMaterial, rt: RenderTarget): void;
 export declare function renderMaterialToTarget(renderer: WebGPURenderer, material: MeshBasicNodeMaterial, rt: RenderTarget, isNormal?: boolean): void;
 export declare function renderColorNodeToTarget(renderer: WebGPURenderer, colorNode: MaterialValue, rt: RenderTarget, isNormal?: boolean): void;

package/dist/graph/compiler.d.ts

@@ -1,9 +1,11 @@
 import * as THREE from "three";
-import { MeshStandardNodeMaterial, MeshPhysicalNodeMaterial } from "three/webgpu";
-import { type MaterialBackend, type MaterialBundle, type MaterialGraphDocument, type MaterialValue, type PortKind } from "./types";
+import { type NodeMaterial } from "three/webgpu";
+import { type MaterialBackend, type MaterialBundle, type MaterialGraphDocument, type MaterialType, type MaterialTypeSettings, type MaterialValue, type PortKind } from "./types";
 import { type NodeRegistry } from "./registry";
+import { gradientMapFor, matcapFor } from "./material-textures";
+export { gradientMapFor, matcapFor };
 export interface CompiledMaterial {
-    material: MeshStandardNodeMaterial;
+    material: NodeMaterial;
     uniforms: Map<string, Record<string, MaterialValue>>;
 }
 export interface CacheSizing {
@@ -11,6 +13,8 @@ export interface CacheSizing {
     size?: number;
 }
 export type CacheAlloc = (cacheId: string, kind: PortKind, sizing?: CacheSizing) => THREE.Texture;
+export type ParamUsage = Map<string, Record<string, "live" | "constant">>;
+export type ConstantArrayAlloc = (nodeId: string, key: string, data: ArrayLike<number>, elementType: "float" | "vec3") => MaterialValue;
 export interface CacheEntry {
     cacheId: string;
     kind: PortKind;
@@ -21,16 +25,42 @@ export interface CompileOptions {
     backend: MaterialBackend;
     soloNodeId?: string;
     allocCache?: CacheAlloc;
+    allocConstantArray?: ConstantArrayAlloc;
     outputResolution?: number;
 }
 export interface CompiledSockets {
     bundle: MaterialBundle;
     uniforms: Map<string, Record<string, MaterialValue>>;
     cachePlan: CacheEntry[];
+    paramUsage: ParamUsage;
 }
 export declare function readOutputResolution(doc: MaterialGraphDocument): number;
+export declare function readMaterialSurface(doc: MaterialGraphDocument): {
+    type: MaterialType;
+    settings: MaterialTypeSettings;
+};
+export interface MaterialConfig {
+    type: MaterialType;
+    baseColor: string;
+    metallic: number;
+    roughness: number;
+    ior: number;
+    alpha: number;
+    coat: number;
+    coatRoughness: number;
+    sheen: number;
+    sheenRoughness: number;
+    transmission: number;
+    emission: string;
+    emissionStrength: number;
+    shininess: number;
+    specular: string;
+    gradientSteps: number;
+    matcap: string;
+}
+export declare function readMaterialConfig(doc: MaterialGraphDocument): MaterialConfig;
 export declare function countGraphNodes(doc: MaterialGraphDocument): number;
 export declare function compileSockets(doc: MaterialGraphDocument, registry: NodeRegistry, optsIn: CompileOptions): CompiledSockets;
-export declare function newSurfaceMaterial(): MeshPhysicalNodeMaterial;
-export declare function applyBundle(material: MeshPhysicalNodeMaterial, bundle: MaterialBundle): void;
+export declare function newSurfaceMaterial(type?: MaterialType, settings?: MaterialTypeSettings): NodeMaterial;
+export declare function applyBundle(material: NodeMaterial, bundle: MaterialBundle, type: MaterialType): void;
 export declare function compileGraph(doc: MaterialGraphDocument, registry: NodeRegistry, opts: CompileOptions): CompiledMaterial;

package/dist/graph/material-textures.d.ts

@@ -0,0 +1,3 @@
+import * as THREE from "three";
+export declare function gradientMapFor(steps: number | undefined): THREE.DataTexture;
+export declare function matcapFor(_id: string | undefined): THREE.Texture | null;

package/dist/graph/mesh-material.d.ts

@@ -0,0 +1,6 @@
+import * as THREE from "three";
+import { type MaterialGraphDocument, type PbrSocket } from "./types";
+export interface ChannelTextures {
+    get(channel: PbrSocket): THREE.Texture | null;
+}
+export declare function buildMeshMaterial(doc: MaterialGraphDocument, textures: ChannelTextures): THREE.Material;

package/dist/graph/nodes/shader/shader-material.d.ts

@@ -0,0 +1,2 @@
+import { type MaterialNodeDef } from "../../types";
+export declare const shaderMaterialNode: MaterialNodeDef;

package/dist/graph/nodes/vector/vector-rotate.d.ts

@@ -0,0 +1,2 @@
+import type { MaterialNodeDef } from "../../types";
+export declare const vectorRotateNode: MaterialNodeDef;

package/dist/graph/textured-surface.d.ts

@@ -1,12 +1,14 @@
 import * as THREE from "three";
-import type { MeshStandardNodeMaterial } from "three/webgpu";
-import { type MaterialBackend, type MaterialGraphSource } from "./types";
+import type { NodeMaterial } from "three/webgpu";
+import { type MaterialBackend, type MaterialGraphSource, type PbrSocket } from "./types";
 import { type MaterialBakeService } from "./bake-service";
 export declare class TexturedSurface {
     private readonly graph;
     private readonly service;
     private readonly source?;
-    private readonly offlineMat;
+    private offlineMat;
+    private matType;
+    private matSig;
     private liveUniforms;
     private material_;
     readonly scaleUniform: import("three/webgpu").UniformNode<"float", number>;
@@ -26,13 +28,25 @@ export declare class TexturedSurface {
     private pendingKind;
     private flushRequested;
     private readonly listeners;
+    private readonly textureListeners;
     private lastError_;
+    private processingDepth;
+    private idleWaiters;
     constructor(graph: MaterialGraphSource, service: MaterialBakeService, source?: string | undefined);
-    get material(): MeshStandardNodeMaterial;
+    get material(): NodeMaterial;
     get lastError(): string | null;
+    get busy(): boolean;
+    whenIdle(): Promise<void>;
+    private enterProcessing;
+    private exitProcessing;
     getLastBakeMs(): number;
     onRebuilt(fn: () => void): () => void;
     private notify;
+    onTexturesUpdated(fn: () => void): () => void;
+    private notifyTexturesUpdated;
+    getChannelTexture(ch: PbrSocket): THREE.Texture | null;
+    getHeightTexture(): THREE.Texture | null;
+    presentChannels(): ReadonlySet<PbrSocket>;
     refresh(): Promise<void>;
     regenerate(): void;
     setScale(value: number): void;

package/dist/graph/types.d.ts

@@ -31,8 +31,25 @@ export interface ParamDef {
     options?: string[];
     default: unknown;
     bakeStructural?: boolean;
+    structural?: boolean;
 }
 export type MaterialBackend = "live" | "offline";
+export type MaterialType = "standard" | "physical" | "lambert" | "toon" | "phong" | "matcap";
+export declare const MATERIAL_TYPES: MaterialType[];
+export interface MaterialTypeSettings {
+    shininess?: number;
+    specular?: string;
+    gradientSteps?: number;
+    matcap?: string;
+}
+export interface MaterialTypeCaps {
+    roughMetal: boolean;
+    physicalLobes: boolean;
+    ao: boolean;
+    emissive: boolean;
+}
+export declare const MATERIAL_TYPE_CAPS: Record<MaterialType, MaterialTypeCaps>;
+export declare function normalizeMaterialType(raw: unknown): MaterialType;
 export type GraphChange = {
     kind: "structural";
 } | {
@@ -47,8 +64,9 @@ export type GraphChange = {
 };
 export interface BuildCtx {
     inputs: Record<string, MaterialValue | undefined>;
-    uniforms: Record<string, MaterialValue>;
-    params: Record<string, unknown>;
+    live(key: string): MaterialValue;
+    constant(key: string): unknown;
+    constantArray(key: string, compute: () => ArrayLike<number>, elementType?: "float" | "vec3"): MaterialValue;
     coord: MaterialValue;
     backend: MaterialBackend;
     tileRepeat?: number;
@@ -130,6 +148,7 @@ export interface MaterialGraphSource {
     onChange(fn: (change: GraphChange) => void): () => void;
 }
 export declare const MATERIAL_OUTPUT_TYPE = "material-output";
+export declare const SHADER_MATERIAL_TYPE = "shader-material";
 export declare const PBR_SOCKETS: readonly ["baseColor", "normal", "emission", "roughness", "metallic", "ambientOcclusion"];
 export type PbrSocket = (typeof PBR_SOCKETS)[number];
 export interface MaterialBundle {

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { MaterialGraphRuntime, type MaterialGraphRuntimeOptions } from "./runtim
 export { MATERIAL_DOCUMENT_VERSION, MaterialGraphSession, cloneMaterialDocument, createDefaultMaterialDocument, migrateMaterialDocument, } from "./document";
 export { createMaterialTopologyKey } from "./topology";
 export { MaterialBakeService, BakedTextureSet, SURFACE_CHANNELS, bakeService, type BakeOptions, type BakeReport, } from "./graph/bake-service";
-export { compileGraph, compileSockets, countGraphNodes, newSurfaceMaterial, readOutputResolution, type CompileOptions, type CompiledSockets, } from "./graph/compiler";
+export { compileGraph, compileSockets, countGraphNodes, newSurfaceMaterial, readMaterialSurface, readMaterialConfig, readOutputResolution, type CompileOptions, type CompiledSockets, type MaterialConfig, } from "./graph/compiler";
+export { buildMeshMaterial, type ChannelTextures } from "./graph/mesh-material";
 export { NodeRegistry, createDefaultRegistry, defaultRegistry, nodeParamDefs, nodePorts, } from "./graph/registry";
 export { TexturedSurface } from "./graph/textured-surface";
 export { runTilingTest } from "./graph/tiling-test";