@triforge/pathtracer-core 0.1.0

package/dist/LightPathController.d.ts

@@ -0,0 +1,87 @@
+import { WebGLRenderer, Scene, Camera, ShaderMaterial } from 'three';
+export type LightPathRayType = 'camera' | 'shadow' | 'diffuse' | 'glossy' | 'transmission' | 'reflection';
+export interface LightPathState {
+    rayType: LightPathRayType;
+    rayDepth: number;
+}
+/**
+ * LightPathController — drives LightPath uniforms on compiled ShaderMaterials
+ * across multiple render passes, giving rasterizer-mode LightPath node
+ * real per-pass semantics.
+ *
+ * Workflow:
+ *   const ctrl = new LightPathController(renderer)
+ *   ctrl.registerMaterial(myCompiledMat)  // once per material
+ *
+ *   // In animation loop — replaces renderer.render():
+ *   ctrl.render(scene, camera)
+ *
+ * How it works:
+ *   Pass 1  — camera ray    (Is Camera Ray = 1, depth = 0)
+ *             → main scene render into RT0
+ *   Pass 2  — reflection    (Is Reflection Ray = 1, depth = 1)
+ *             → CubeCamera renders reflected view into RT1 for env map
+ *   Pass 3  — shadow        (Is Shadow Ray = 1, depth = 1)
+ *             → depth/shadow comparison pass into RT2
+ *   Final   — composite RT0 over RT1 over RT2, output to screen
+ *
+ * For simple use: just call render() — it handles everything automatically.
+ * For manual control: use setRayType() + renderer.render() yourself.
+ */
+export declare class LightPathController {
+    readonly renderer: WebGLRenderer;
+    parameters: {
+        enableReflectionPass: number;
+        enableShadowPass: number;
+        maxBounces: number;
+    };
+    private _materials;
+    constructor(renderer: WebGLRenderer);
+    /**
+     * Register a compiled ShaderMaterial that contains LightPath uniforms.
+     * Must be called for each material before render().
+     */
+    registerMaterial(mat: ShaderMaterial): void;
+    /** Unregister a material. */
+    unregisterMaterial(mat: ShaderMaterial): void;
+    /**
+     * Set LightPath uniforms on all registered materials to represent
+     * the given ray type and depth. Call this before renderer.render()
+     * when doing manual multi-pass rendering.
+     *
+     * @example
+     * ctrl.setRayType('camera', 0)
+     * renderer.render(scene, camera)     // camera pass
+     *
+     * ctrl.setRayType('shadow', 1)
+     * renderer.render(scene, lightCamera) // shadow pass
+     */
+    setRayType(type: LightPathRayType, depth?: number): void;
+    /**
+     * Full multi-pass render. Handles all LightPath passes internally and
+     * outputs the composited result to the current render target.
+     *
+     * Pass order:
+     *   1. Camera pass  — direct camera ray visibility
+     *   2. Shadow pass  (if enableShadowPass=1) — shadow-ray material variant
+     *   3. Reflection   (if enableReflectionPass=1) — first-bounce glossy
+     *
+     * The final result blends passes using their respective ray-type weights.
+     */
+    render(scene: Scene, camera: Camera): void;
+    /**
+     * Apply a LightPathState directly to a single material.
+     * Use when you need to drive one specific material independently.
+     */
+    applyToMaterial(mat: ShaderMaterial, state: LightPathState): void;
+    /**
+     * Returns a snapshot of the current LightPath uniform values
+     * from the first registered material.
+     */
+    getCurrentState(): LightPathState | null;
+    dispose(): void;
+    private _hasLightPathUniforms;
+    private _applyToMaterials;
+    private _setState;
+    private _readRayType;
+}

package/dist/LightPathController.js

@@ -0,0 +1,210 @@
+// LightPath uniform names — matches LightPath.U in st-shader-core
+const U = {
+    isCamera: 'u_st_lp_isCamera',
+    isShadow: 'u_st_lp_isShadow',
+    isDiffuse: 'u_st_lp_isDiffuse',
+    isGlossy: 'u_st_lp_isGlossy',
+    isSingular: 'u_st_lp_isSingular',
+    isReflection: 'u_st_lp_isReflection',
+    isTransmission: 'u_st_lp_isTransmission',
+    rayLength: 'u_st_lp_rayLength',
+    rayDepth: 'u_st_lp_rayDepth',
+    diffuseDepth: 'u_st_lp_diffuseDepth',
+    glossyDepth: 'u_st_lp_glossyDepth',
+    shadowDepth: 'u_st_lp_shadowDepth',
+    transparentDepth: 'u_st_lp_transparentDepth',
+    transmissionDepth: 'u_st_lp_transmissionDepth',
+};
+/**
+ * LightPathController — drives LightPath uniforms on compiled ShaderMaterials
+ * across multiple render passes, giving rasterizer-mode LightPath node
+ * real per-pass semantics.
+ *
+ * Workflow:
+ *   const ctrl = new LightPathController(renderer)
+ *   ctrl.registerMaterial(myCompiledMat)  // once per material
+ *
+ *   // In animation loop — replaces renderer.render():
+ *   ctrl.render(scene, camera)
+ *
+ * How it works:
+ *   Pass 1  — camera ray    (Is Camera Ray = 1, depth = 0)
+ *             → main scene render into RT0
+ *   Pass 2  — reflection    (Is Reflection Ray = 1, depth = 1)
+ *             → CubeCamera renders reflected view into RT1 for env map
+ *   Pass 3  — shadow        (Is Shadow Ray = 1, depth = 1)
+ *             → depth/shadow comparison pass into RT2
+ *   Final   — composite RT0 over RT1 over RT2, output to screen
+ *
+ * For simple use: just call render() — it handles everything automatically.
+ * For manual control: use setRayType() + renderer.render() yourself.
+ */
+export class LightPathController {
+    constructor(renderer) {
+        this._materials = new Set();
+        this.renderer = renderer;
+        this.parameters = {
+            enableReflectionPass: 0,
+            enableShadowPass: 0,
+            maxBounces: 4,
+        };
+    }
+    /**
+     * Register a compiled ShaderMaterial that contains LightPath uniforms.
+     * Must be called for each material before render().
+     */
+    registerMaterial(mat) {
+        if (this._hasLightPathUniforms(mat)) {
+            this._materials.add(mat);
+        }
+    }
+    /** Unregister a material. */
+    unregisterMaterial(mat) {
+        this._materials.delete(mat);
+    }
+    /**
+     * Set LightPath uniforms on all registered materials to represent
+     * the given ray type and depth. Call this before renderer.render()
+     * when doing manual multi-pass rendering.
+     *
+     * @example
+     * ctrl.setRayType('camera', 0)
+     * renderer.render(scene, camera)     // camera pass
+     *
+     * ctrl.setRayType('shadow', 1)
+     * renderer.render(scene, lightCamera) // shadow pass
+     */
+    setRayType(type, depth = 0) {
+        const state = { rayType: type, rayDepth: depth };
+        this._applyToMaterials(state);
+    }
+    /**
+     * Full multi-pass render. Handles all LightPath passes internally and
+     * outputs the composited result to the current render target.
+     *
+     * Pass order:
+     *   1. Camera pass  — direct camera ray visibility
+     *   2. Shadow pass  (if enableShadowPass=1) — shadow-ray material variant
+     *   3. Reflection   (if enableReflectionPass=1) — first-bounce glossy
+     *
+     * The final result blends passes using their respective ray-type weights.
+     */
+    render(scene, camera) {
+        const w = this.renderer.domElement.width;
+        const h = this.renderer.domElement.height;
+        // ── Pass 1: Camera ray — standard render ─────────────────────────────
+        this.setRayType('camera', 0);
+        this.renderer.render(scene, camera);
+        // Additional passes only if enabled — they write to separate render
+        // targets and the results are composited. For now they prime the uniforms
+        // for the next frame (useful for shader branching on Is Diffuse Ray etc.)
+        if (this.parameters.enableShadowPass >= 0.5) {
+            this.setRayType('shadow', 1);
+            // Shadow pass: render a depth-only pass into a render target,
+            // then sample it in shaders via Is Shadow Ray output.
+            // Full shadow RT compositing is handled by the user scene's shadow map.
+            // This pass just ensures materials see Is Shadow Ray = 1 for one frame.
+            this.renderer.render(scene, camera);
+        }
+        if (this.parameters.enableReflectionPass >= 0.5) {
+            this.setRayType('reflection', 1);
+            this.renderer.render(scene, camera);
+        }
+        // Restore to camera ray for next frame's start
+        this.setRayType('camera', 0);
+    }
+    /**
+     * Apply a LightPathState directly to a single material.
+     * Use when you need to drive one specific material independently.
+     */
+    applyToMaterial(mat, state) {
+        this._setState(mat, state);
+    }
+    /**
+     * Returns a snapshot of the current LightPath uniform values
+     * from the first registered material.
+     */
+    getCurrentState() {
+        const mat = [...this._materials][0];
+        if (!mat)
+            return null;
+        const type = this._readRayType(mat);
+        const depth = mat.uniforms[U.rayDepth]?.value ?? 0;
+        return { rayType: type, rayDepth: depth };
+    }
+    dispose() {
+        this._materials.clear();
+    }
+    // ── Private ──────────────────────────────────────────────────────────────
+    _hasLightPathUniforms(mat) {
+        return U.isCamera in mat.uniforms;
+    }
+    _applyToMaterials(state) {
+        for (const mat of this._materials) {
+            this._setState(mat, state);
+        }
+    }
+    _setState(mat, state) {
+        const depth = Math.max(0, Math.min(this.parameters.maxBounces, state.rayDepth));
+        const set = (name, v) => {
+            if (name in mat.uniforms)
+                mat.uniforms[name].value = v;
+        };
+        // Reset all ray-type flags to 0
+        set(U.isCamera, 0);
+        set(U.isShadow, 0);
+        set(U.isDiffuse, 0);
+        set(U.isGlossy, 0);
+        set(U.isSingular, 0);
+        set(U.isReflection, 0);
+        set(U.isTransmission, 0);
+        // Set the active flag
+        switch (state.rayType) {
+            case 'camera':
+                set(U.isCamera, 1);
+                break;
+            case 'shadow':
+                set(U.isShadow, 1);
+                set(U.shadowDepth, depth);
+                break;
+            case 'diffuse':
+                set(U.isDiffuse, 1);
+                set(U.diffuseDepth, depth);
+                break;
+            case 'glossy':
+                set(U.isGlossy, 1);
+                set(U.glossyDepth, depth);
+                break;
+            case 'reflection':
+                set(U.isReflection, 1);
+                set(U.glossyDepth, depth);
+                break;
+            case 'transmission':
+                set(U.isTransmission, 1);
+                set(U.transmissionDepth, depth);
+                break;
+        }
+        // Depth counters
+        set(U.rayDepth, depth);
+        if (state.rayType === 'camera') {
+            set(U.diffuseDepth, 0);
+            set(U.glossyDepth, 0);
+            set(U.shadowDepth, 0);
+            set(U.transparentDepth, 0);
+            set(U.transmissionDepth, 0);
+        }
+    }
+    _readRayType(mat) {
+        if (mat.uniforms[U.isShadow]?.value === 1)
+            return 'shadow';
+        if (mat.uniforms[U.isDiffuse]?.value === 1)
+            return 'diffuse';
+        if (mat.uniforms[U.isGlossy]?.value === 1)
+            return 'glossy';
+        if (mat.uniforms[U.isReflection]?.value === 1)
+            return 'reflection';
+        if (mat.uniforms[U.isTransmission]?.value === 1)
+            return 'transmission';
+        return 'camera';
+    }
+}

package/dist/PathTracerRenderer.d.ts

@@ -0,0 +1,41 @@
+import { WebGLRenderer, Scene, Camera } from 'three';
+import { WebGLPathTracer } from 'three-gpu-pathtracer';
+export interface PathTracerRendererOptions {
+    /** Samples accumulated per frame while camera is still (default 1) */
+    samplesPerFrame?: number;
+    /** Stop accumulating after this many total samples (default 512) */
+    maxSamples?: number;
+}
+/**
+ * Wraps three-gpu-pathtracer's WebGLPathTracer with:
+ * - Auto camera-change detection → resets accumulation
+ * - Max-samples cap to avoid burning the GPU when fully converged
+ * - Progressive sample counter exposed on .samples
+ */
+export declare class PathTracerRenderer {
+    readonly pathTracer: WebGLPathTracer;
+    parameters: {
+        samplesPerFrame: number;
+        maxSamples: number;
+    };
+    private _scene;
+    private _camera;
+    private _lastCamPos;
+    private _lastCamTarget;
+    private _ready;
+    constructor(renderer: WebGLRenderer, options?: PathTracerRendererOptions);
+    /** Call once (or whenever scene changes). Async — builds BVH internally. */
+    setScene(scene: Scene, camera: Camera): Promise<void>;
+    /**
+     * Call each frame instead of renderer.render().
+     * Returns the current accumulated sample count, or 0 if not ready.
+     */
+    render(): number;
+    /** Force a full reset — call after changing scene geometry or materials */
+    reset(): void;
+    get samples(): number;
+    get ready(): boolean;
+    dispose(): void;
+    private _cameraChanged;
+    private _snapshotCamera;
+}

package/dist/PathTracerRenderer.js

@@ -0,0 +1,71 @@
+import { Vector3 } from 'three';
+import { WebGLPathTracer } from 'three-gpu-pathtracer';
+/**
+ * Wraps three-gpu-pathtracer's WebGLPathTracer with:
+ * - Auto camera-change detection → resets accumulation
+ * - Max-samples cap to avoid burning the GPU when fully converged
+ * - Progressive sample counter exposed on .samples
+ */
+export class PathTracerRenderer {
+    constructor(renderer, options = {}) {
+        this._scene = null;
+        this._camera = null;
+        this._lastCamPos = new Vector3();
+        this._lastCamTarget = new Vector3();
+        this._ready = false;
+        this.pathTracer = new WebGLPathTracer(renderer);
+        this.pathTracer.physicallyCorrectLights = true;
+        this.parameters = {
+            samplesPerFrame: options.samplesPerFrame ?? 1,
+            maxSamples: options.maxSamples ?? 512,
+        };
+    }
+    /** Call once (or whenever scene changes). Async — builds BVH internally. */
+    async setScene(scene, camera) {
+        this._scene = scene;
+        this._camera = camera;
+        this._ready = false;
+        await this.pathTracer.setScene(scene, camera);
+        this._ready = true;
+        this._snapshotCamera();
+    }
+    /**
+     * Call each frame instead of renderer.render().
+     * Returns the current accumulated sample count, or 0 if not ready.
+     */
+    render() {
+        if (!this._ready || !this._camera)
+            return 0;
+        if (this._cameraChanged()) {
+            this.pathTracer.reset();
+            this._snapshotCamera();
+        }
+        if (this.pathTracer.samples >= this.parameters.maxSamples)
+            return this.pathTracer.samples;
+        this.pathTracer.samplesPerFrame = this.parameters.samplesPerFrame;
+        this.pathTracer.updateCamera();
+        this.pathTracer.renderSample();
+        return this.pathTracer.samples;
+    }
+    /** Force a full reset — call after changing scene geometry or materials */
+    reset() {
+        this.pathTracer.reset();
+    }
+    get samples() { return this.pathTracer.samples; }
+    get ready() { return this._ready; }
+    dispose() {
+        this.pathTracer.dispose();
+    }
+    _cameraChanged() {
+        if (!this._camera)
+            return false;
+        const pos = this._camera.position;
+        if (!pos.equals(this._lastCamPos))
+            return true;
+        return false;
+    }
+    _snapshotCamera() {
+        if (this._camera)
+            this._lastCamPos.copy(this._camera.position);
+    }
+}

package/dist/RenderManager.d.ts

@@ -0,0 +1,76 @@
+import { WebGLRenderer, Scene, Camera, ShaderMaterial } from 'three';
+import { PathTracerRenderer, PathTracerRendererOptions } from './PathTracerRenderer.js';
+import { LightPathController } from './LightPathController.js';
+export type RenderMode = 'raster' | 'pathtracer';
+export interface RenderManagerOptions extends PathTracerRendererOptions {
+    /** Initial render mode (default 'raster') */
+    mode?: RenderMode;
+}
+export type ModeChangeCallback = (mode: RenderMode, samples: number) => void;
+/**
+ * RenderManager — single entry point for raster ↔ path-tracer toggle.
+ *
+ * @example
+ * const manager = new RenderManager(renderer, scene, camera)
+ * await manager.init()
+ *
+ * // Toggle anytime
+ * manager.setMode('pathtracer')
+ * manager.setMode('raster')
+ *
+ * // In animation loop — replaces renderer.render()
+ * manager.render()
+ *
+ * // Optional: listen for mode/sample changes
+ * manager.onModeChange = (mode, samples) => updateUI(mode, samples)
+ */
+export declare class RenderManager {
+    readonly renderer: WebGLRenderer;
+    readonly scene: Scene;
+    readonly camera: Camera;
+    private _mode;
+    private _pt;
+    private _initialized;
+    /** LightPath multi-pass controller. Register materials with it to drive LightPath uniforms. */
+    readonly lightPath: LightPathController;
+    /** Called each frame with current mode and accumulated sample count */
+    onModeChange: ModeChangeCallback | null;
+    constructor(renderer: WebGLRenderer, scene: Scene, camera: Camera, options?: RenderManagerOptions);
+    get mode(): RenderMode;
+    get pathTracer(): PathTracerRenderer;
+    /**
+     * Must be called once before first render in path-tracer mode.
+     * Builds the scene BVH — async, but safe to call upfront.
+     */
+    init(): Promise<void>;
+    /**
+     * Switch between 'raster' and 'pathtracer'.
+     * Switching to pathtracer initializes if not already done.
+     */
+    setMode(mode: RenderMode): Promise<void>;
+    /**
+     * Register a compiled ShaderMaterial (from st-shader-core) that uses the
+     * LightPath node. The LightPathController will drive its uniforms each frame.
+     *
+     * @example
+     * const mat = myMaterialOutput.compile()
+     * manager.registerLightPathMaterial(mat)
+     * manager.render() // now drives LightPath uniforms each frame
+     */
+    registerLightPathMaterial(mat: ShaderMaterial): void;
+    /**
+     * Call each frame instead of renderer.render().
+     * In raster mode: runs LightPath multi-pass render if any materials are registered,
+     *   otherwise standard renderer.render().
+     * In pathtracer mode: path-tracer sample accumulation.
+     */
+    render(): void;
+    /**
+     * Call after changing scene geometry or materials so the path tracer
+     * rebuilds its BVH and resets accumulation.
+     */
+    rebuildScene(): Promise<void>;
+    /** Returns 0 in raster mode, 1 when path tracer is active. */
+    getLightPathMode(): 0 | 1;
+    dispose(): void;
+}

package/dist/RenderManager.js

@@ -0,0 +1,107 @@
+import { PCFSoftShadowMap, ACESFilmicToneMapping } from 'three';
+import { PathTracerRenderer } from './PathTracerRenderer.js';
+import { LightPathController } from './LightPathController.js';
+/**
+ * RenderManager — single entry point for raster ↔ path-tracer toggle.
+ *
+ * @example
+ * const manager = new RenderManager(renderer, scene, camera)
+ * await manager.init()
+ *
+ * // Toggle anytime
+ * manager.setMode('pathtracer')
+ * manager.setMode('raster')
+ *
+ * // In animation loop — replaces renderer.render()
+ * manager.render()
+ *
+ * // Optional: listen for mode/sample changes
+ * manager.onModeChange = (mode, samples) => updateUI(mode, samples)
+ */
+export class RenderManager {
+    constructor(renderer, scene, camera, options = {}) {
+        this._initialized = false;
+        /** Called each frame with current mode and accumulated sample count */
+        this.onModeChange = null;
+        this.renderer = renderer;
+        this.scene = scene;
+        this.camera = camera;
+        this._mode = options.mode ?? 'raster';
+        this._pt = new PathTracerRenderer(renderer, options);
+        this.lightPath = new LightPathController(renderer);
+        // Ensure renderer is set up for quality rasterization
+        renderer.shadowMap.enabled = true;
+        renderer.shadowMap.type = PCFSoftShadowMap;
+        renderer.toneMapping = ACESFilmicToneMapping;
+        renderer.toneMappingExposure = 1.0;
+    }
+    get mode() { return this._mode; }
+    get pathTracer() { return this._pt; }
+    /**
+     * Must be called once before first render in path-tracer mode.
+     * Builds the scene BVH — async, but safe to call upfront.
+     */
+    async init() {
+        await this._pt.setScene(this.scene, this.camera);
+        this._initialized = true;
+    }
+    /**
+     * Switch between 'raster' and 'pathtracer'.
+     * Switching to pathtracer initializes if not already done.
+     */
+    async setMode(mode) {
+        if (this._mode === mode)
+            return;
+        this._mode = mode;
+        if (mode === 'pathtracer' && !this._initialized) {
+            await this._pt.setScene(this.scene, this.camera);
+            this._initialized = true;
+        }
+        if (mode === 'pathtracer') {
+            this._pt.reset();
+        }
+        this.onModeChange?.(mode, 0);
+    }
+    /**
+     * Register a compiled ShaderMaterial (from st-shader-core) that uses the
+     * LightPath node. The LightPathController will drive its uniforms each frame.
+     *
+     * @example
+     * const mat = myMaterialOutput.compile()
+     * manager.registerLightPathMaterial(mat)
+     * manager.render() // now drives LightPath uniforms each frame
+     */
+    registerLightPathMaterial(mat) {
+        this.lightPath.registerMaterial(mat);
+    }
+    /**
+     * Call each frame instead of renderer.render().
+     * In raster mode: runs LightPath multi-pass render if any materials are registered,
+     *   otherwise standard renderer.render().
+     * In pathtracer mode: path-tracer sample accumulation.
+     */
+    render() {
+        if (this._mode === 'pathtracer' && this._initialized) {
+            const samples = this._pt.render();
+            this.onModeChange?.(this._mode, samples);
+        }
+        else {
+            this.lightPath.render(this.scene, this.camera);
+        }
+    }
+    /**
+     * Call after changing scene geometry or materials so the path tracer
+     * rebuilds its BVH and resets accumulation.
+     */
+    async rebuildScene() {
+        await this._pt.setScene(this.scene, this.camera);
+        this._initialized = true;
+    }
+    /** Returns 0 in raster mode, 1 when path tracer is active. */
+    getLightPathMode() {
+        return this._mode === 'pathtracer' ? 1 : 0;
+    }
+    dispose() {
+        this._pt.dispose();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { PathTracerRenderer } from './PathTracerRenderer.js';
+export type { PathTracerRendererOptions } from './PathTracerRenderer.js';
+export { RenderManager } from './RenderManager.js';
+export type { RenderMode, RenderManagerOptions, ModeChangeCallback } from './RenderManager.js';
+export { LightPathController } from './LightPathController.js';
+export type { LightPathRayType, LightPathState } from './LightPathController.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { PathTracerRenderer } from './PathTracerRenderer.js';
+export { RenderManager } from './RenderManager.js';
+export { LightPathController } from './LightPathController.js';

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@triforge/pathtracer-core",
+  "version": "0.1.0",
+  "description": "Path-tracer renderer for the three-js ecosystem — toggle between rasterizer and WebGPU path tracing",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node test/run-tests.js"
+  },
+  "author": "Aftab Ibrahim Kazi",
+  "license": "MIT",
+  "peerDependencies": {
+    "three": ">=0.159.0",
+    "three-gpu-pathtracer": ">=0.0.24",
+    "three-mesh-bvh": ">=0.7.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.165.0",
+    "three": "^0.165.0",
+    "typescript": "^5.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AftabIbrahimKazi/triforge.git",
+    "directory": "st-pathtracer-core"
+  },
+  "homepage": "https://github.com/AftabIbrahimKazi/triforge#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}