@plasius/gpu-lighting

Advanced lighting WGSL modules and planning profiles for @plasius/gpu-worker. The package is structured around modern lighting tracks:

• Lumen-inspired hybrid realtime GI/reflections.
• Path-traced reference lighting.
• Froxel-based volumetric lighting.
• HDRI/IBL precomputation passes.

Apache-2.0. ESM + CJS builds. WGSL assets are published in dist/.

Install

npm install @plasius/gpu-lighting

Browser Demo

npm run demo

Then open http://localhost:8000/gpu-lighting/demo/.

The browser demo now mounts the shared 3D harbor validation scene from @plasius/gpu-shared instead of a catalog-only page, so lighting-band behavior is visible against GLTF ships, water, and cloth.

For browser-only serving, the demo resolves @plasius/gpu-shared through an import map so the page stays on the published package surface rather than a package-private source path.

Usage (load one technique)

import {
  loadLightingTechniqueJobs,
  loadLightingTechniqueWorkerBundle,
  getLightingTechnique,
} from "@plasius/gpu-lighting";
import { assembleWorkerWgsl, loadWorkerWgsl } from "@plasius/gpu-worker";

const workerWgsl = await loadWorkerWgsl();
const { preludeWgsl, jobs } = await loadLightingTechniqueJobs("hybrid");

const shaderCode = await assembleWorkerWgsl(workerWgsl, {
  preludeWgsl,
  jobs,
});

console.log(getLightingTechnique("hybrid").description);

Usage (worker governance bundle)

import {
  getLightingProfileWorkerManifest,
  loadLightingTechniqueWorkerBundle,
} from "@plasius/gpu-lighting";

const bundle = await loadLightingTechniqueWorkerBundle("hybrid");

// WGSL for gpu-worker assembly
console.log(bundle.preludeWgsl, bundle.jobs);

// Contract-aligned metadata for gpu-performance and gpu-debug integrations
console.log(bundle.workerManifest.jobs[0].performance.levels);
console.log(bundle.workerManifest.jobs[0].debug);
console.log(bundle.workerManifest.schedulerMode);
console.log(bundle.workerManifest.jobs[0].worker.priority);
console.log(bundle.workerManifest.jobs[0].worker.dependencies);

const profileManifest = getLightingProfileWorkerManifest("realtime");
console.log(profileManifest.jobs.map((job) => job.worker.jobType));

Distance-Banded Lighting

import { createLightingBandPlan } from "@plasius/gpu-lighting";

const bandPlan = createLightingBandPlan({
  profile: "realtime",
  importance: "high",
});

console.log(bandPlan.bands.map((band) => band.primaryShadowSource));
console.log(bandPlan.bands.find((band) => band.band === "near").rtParticipation);

Band plans make near, mid, far, and horizon shadow sources explicit, keep RT shadow/reflection/GI participation independent, and publish temporal reuse plus update cadence expectations for downstream renderer and performance packages.

Environment Lighting Presets

import {
  createEnvironmentLightingConfig,
  createWavefrontEnvironmentLightingOptions,
} from "@plasius/gpu-lighting";

const lighting = createEnvironmentLightingConfig({
  scene: "forest",
  timeOfDay: "dusk",
  intensity: 1.05,
  environmentPortals: [
    {
      id: "north-window",
      position: [0, 1.2, -2.4],
      normal: [0, 0, 1],
      tangent: [1, 0, 0],
      width: 1.8,
      height: 1.1,
      intensity: 1.4,
    },
  ],
});

const wavefrontLighting = createWavefrontEnvironmentLightingOptions({
  preset: "cavern-night",
});

console.log(lighting.environmentLightSources.map((source) => source.kind));
console.log(wavefrontLighting.environmentMissLighting.startingPoint);

createEnvironmentLightingConfig(...) owns the reusable sky/environment semantics: horizon and zenith colours, key-light direction, key-light colour, environment intensity, exposure, ambient residual colour, and optional environment-light portals.

Preset families now cover:

• grass-field-{dawn,midday,dusk,night}
• forest-{dawn,midday,dusk,night}
• warehouse-{dawn,midday,dusk,night}
• cavern-{dawn,midday,dusk,night}

Callers can pass the combined preset name directly or pass scene plus timeOfDay; scene-only aliases default to midday.

Each preset publishes scene, timeOfDay, normalized environmentLightSources, a dominantLightSource, and environmentMissLighting. Source metadata includes source kind, role, direction, position, colour, intensity, radiance, luminance, reach, and angular radius. Renderers can use environmentMissLighting when a path ray misses scene geometry: the miss has an inferred source colour/brightness and a stable startingPoint of environment-miss instead of an unbounded null/negative sky sample. Emissive material hits remain explicit light-source hits and should not be double-counted by environment inference.

Portals describe physical openings such as windows where outside radiance can enter an interior. They are normalized as rectangle apertures with position, normal, tangent, dimensions, colour, and radiance scale. createWavefrontEnvironmentLightingOptions(...) projects that contract into the current @plasius/gpu-renderer wavefront renderer options without making the renderer depend on this package directly.

DAG Scheduling

Lighting worker manifests now publish schedulerMode: "dag" plus per-job priority and dependencies so downstream runtimes can preserve stage order.

• hybrid: directLighting and screenTrace are roots; radianceCache, finalGather, and reflectionResolve unlock as upstream work finishes.
• pathtracer: pathTrace -> accumulate -> denoise
• volumetrics: volumetricShadow -> froxelIntegrate
• hdri: irradianceConvolution and specularPrefilter are roots; brdfLut joins after both finish.

Usage (profile planning)

import {
  createLightingProfileModeLadder,
  getLightingProfile,
  loadLightingProfile,
} from "@plasius/gpu-lighting";

const profile = getLightingProfile("realtime");
// profile.techniques -> ["hybrid", "volumetrics", "hdri"]

const plan = await loadLightingProfile("realtime");
// plan.techniques is an array of loaded prelude+job WGSL bundles.

const modeLadder = createLightingProfileModeLadder();
// modeLadder exposes reference -> hybrid -> realtime ordering for gpu-performance.

Usage (reference-first performance ladder)

import {
  createGpuPerformanceGovernor,
  createQualityLadderAdapter,
} from "@plasius/gpu-performance";
import {
  createLightingProfileModeLadder,
} from "@plasius/gpu-lighting";

const lightingModePlan = createLightingProfileModeLadder({
  initialProfile: "reference",
});
const lightingMode = createQualityLadderAdapter(lightingModePlan);

const governor = createGpuPerformanceGovernor({
  device,
  modules: [lightingMode],
  target: lightingModePlan.target,
  adaptation: lightingModePlan.adaptation,
});

createLightingProfileModeLadder() publishes the policy contract for the reference-first mode you described:

• start from reference
• keep a 4-frame adaptation window
• hold the premium mode while the negotiated average remains at or above 30 FPS
• degrade the whole lighting profile to hybrid, then realtime, only when that window can no longer sustain the budget

The package now ships concrete WGSL contracts for:

• hybrid.directLighting: direct sun/sky resolve with roughness-aware specular shaping
• hybrid.screenTrace: first-hit reflection tracing over the shared hybrid scene contracts
• hybrid.radianceCache: irradiance history updates for cache-backed indirect reuse
• hybrid.finalGather: cache + trace composition with temporal reuse for the hybrid GI path
• pathtracer.pathTrace: analytic scene tracing, bounce integration, and sky fallback
• pathtracer.accumulate: progressive history resolve with reset handling
• pathtracer.denoise: spatial-temporal bilateral filtering for reference previews
• hybrid.reflectionResolve: surface-aware reflection shading with roughness/fresnel shaping

This is still a catalog/planning package rather than proof of a finished end-to-end renderer. Downstream runtimes such as @plasius/gpu-renderer still need to bind real scene buffers and execute these kernels on the live frame graph.

Profiles

• realtime: Lumen-inspired hybrid GI/reflections + volumetrics + HDRI/IBL.
• hybrid: hybrid GI/reflections with HDRI/IBL support.
• reference: path tracing + volumetrics + HDRI/IBL for validation and lookdev.

Techniques

• hybrid
  • directLighting
  • screenTrace
  • radianceCache
  • finalGather
  • reflectionResolve
• pathtracer
  • pathTrace
  • accumulate
  • denoise
• volumetrics
  • froxelIntegrate
  • volumetricShadow
• hdri
  • irradianceConvolution
  • specularPrefilter
  • brdfLut

Demo

Run the demo server from the repo root:

cd gpu-lighting
npm run demo

Then open http://localhost:8000/gpu-lighting/demo/. The mounted 3D scene keeps the lighting profile, band-policy, and worker-state catalog visible while rendering the shared harbor validation surface.

Development Checks

npm run lint
npm run typecheck
npm run test:coverage
npm run build
npm run pack:check

Files

• src/index.js: technique/profile catalogs, loader APIs, validation.
• src/techniques/hybrid/*: realtime hybrid GI/reflections WGSL modules.
• src/techniques/pathtracer/*: path tracing reference WGSL modules.
• src/techniques/volumetrics/*: volumetric lighting WGSL modules.
• src/techniques/hdri/*: HDRI/IBL precompute WGSL modules.
• docs/adrs/*: architecture decisions for the lighting stack.
• docs/tdrs/*: technical design records for worker manifests and debug hooks.
• docs/design/*: integration guidance for worker budgets, DAG metadata, and debug instrumentation.