@plasius/gpu-renderer 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-renderer",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Framework-agnostic WebGPU renderer runtime for Plasius projects.",
   "type": "module",
   "sideEffects": false,
@@ -27,7 +27,7 @@
   "scripts": {
     "build": "tsup",
     "demo": "python3 -m http.server --directory ..",
-    "typecheck": "node --check src/index.js && node --check src/wavefront-compute.js",
+    "typecheck": "node --check src/index.js && node --check src/wavefront-frame-runtime.js && node --check src/wavefront-compute.js",
     "audit:eslint": "eslint . --max-warnings=0",
     "audit:deps": "npm ls --all --omit=optional --omit=peer > /dev/null 2>&1 || true",
     "audit:npm": "npm audit --audit-level=high --omit=dev",

package/src/index.d.ts

@@ -13,6 +13,56 @@ export type WavefrontMaterialKind =
   | "light"
   | number;
 
+export interface WavefrontAdaptiveSamplingLevelConfig {
+  readonly samplesPerPixel: number;
+  readonly frameTimeBudgetMs: number;
+  readonly minimumSamplesPerPixel: number;
+}
+
+export interface WavefrontAdaptiveSamplingLevel {
+  readonly id: string;
+  readonly label: string;
+  readonly estimatedCostMs: number;
+  readonly config: WavefrontAdaptiveSamplingLevelConfig;
+}
+
+export interface CreateWavefrontAdaptiveSamplingLevelsResult {
+  readonly requestedSamplesPerPixel: number;
+  readonly minimumSamplesPerPixel: number;
+  readonly frameTimeBudgetMs: number;
+  readonly levels: readonly WavefrontAdaptiveSamplingLevel[];
+}
+
+export interface WavefrontTextureSampleInput {
+  readonly texCoord?: number;
+  readonly scale?: number;
+  readonly strength?: number;
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8ClampedArray | Uint8Array | readonly number[];
+}
+
+export interface WavefrontMediumInput {
+  readonly id?: number;
+  readonly mediumId?: number;
+  readonly phaseModel?: number | "isotropic";
+  readonly density?: number;
+  readonly attenuationColor?: RendererColor | readonly number[];
+  readonly attenuationDistance?: number;
+  readonly absorption?: readonly [number, number, number] | readonly number[];
+  readonly scattering?: readonly [number, number, number] | readonly number[];
+}
+
+export interface WavefrontVolumeInput {
+  readonly thickness?: number;
+  readonly phaseModel?: number | "isotropic";
+  readonly density?: number;
+  readonly attenuationColor?: RendererColor | readonly number[];
+  readonly attenuationDistance?: number;
+  readonly absorption?: readonly [number, number, number] | readonly number[];
+  readonly scattering?: readonly [number, number, number] | readonly number[];
+}
+
 export interface WavefrontCameraOptions {
   readonly position?: readonly [number, number, number] | readonly number[];
   readonly target?: readonly [number, number, number] | readonly number[];
@@ -21,12 +71,21 @@ export interface WavefrontCameraOptions {
   readonly fov?: number;
 }
 
+export function createWavefrontAdaptiveSamplingLevels(options?: {
+  readonly samplesPerPixel?: number;
+  readonly frameTimeBudgetMs?: number;
+  readonly minimumSamplesPerPixel?: number;
+}): CreateWavefrontAdaptiveSamplingLevelsResult;
+
 export interface WavefrontSceneObjectInput {
   readonly id?: number;
   readonly kind?: WavefrontSceneObjectKind;
   readonly type?: WavefrontSceneObjectKind;
   readonly materialKind?: WavefrontMaterialKind;
   readonly flags?: number;
+  readonly mediumRefId?: number;
+  readonly mediumId?: number;
+  readonly medium?: WavefrontMediumInput | null;
   readonly center?: readonly [number, number, number] | readonly number[];
   readonly position?: readonly [number, number, number] | readonly number[];
   readonly radius?: number;
@@ -48,6 +107,16 @@ export interface WavefrontSceneObjectInput {
   readonly metallic?: number;
   readonly opacity?: number;
   readonly ior?: number;
+  readonly sheen?: number;
+  readonly sheenTint?: number;
+  readonly sheenColor?: RendererColor | readonly number[];
+  readonly clearcoat?: number;
+  readonly clearcoatRoughness?: number;
+  readonly specular?: number;
+  readonly specularColor?: RendererColor | readonly number[];
+  readonly thickness?: number;
+  readonly transmission?: number;
+  readonly volume?: WavefrontVolumeInput | null;
   readonly material?: {
     readonly kind?: WavefrontMaterialKind;
     readonly color?: RendererColor | readonly number[];
@@ -58,6 +127,18 @@ export interface WavefrontSceneObjectInput {
     readonly metallic?: number;
     readonly opacity?: number;
     readonly ior?: number;
+    readonly sheen?: number;
+    readonly sheenTint?: number;
+    readonly sheenColor?: RendererColor | readonly number[];
+    readonly clearcoat?: number;
+    readonly clearcoatRoughness?: number;
+    readonly specular?: number;
+    readonly specularColor?: RendererColor | readonly number[];
+    readonly thickness?: number;
+    readonly transmission?: number;
+    readonly medium?: WavefrontMediumInput | null;
+    readonly mediumId?: number;
+    readonly volume?: WavefrontVolumeInput | null;
   };
 }
 
@@ -66,6 +147,8 @@ export interface WavefrontSceneObject {
   readonly kind: number;
   readonly materialKind: number;
   readonly flags: number;
+  readonly mediumRefId: number;
+  readonly medium: WavefrontMediumInput | null;
   readonly center: readonly [number, number, number] | readonly number[];
   readonly halfExtent: readonly [number, number, number] | readonly number[];
   readonly color: readonly [number, number, number, number] | readonly number[];
@@ -74,6 +157,15 @@ export interface WavefrontSceneObject {
   readonly metallic: number;
   readonly opacity: number;
   readonly ior: number;
+  readonly sheen: number;
+  readonly sheenTint: number;
+  readonly sheenColor: readonly [number, number, number, number] | readonly number[];
+  readonly clearcoat: number;
+  readonly clearcoatRoughness: number;
+  readonly specular: number;
+  readonly specularColor: readonly [number, number, number, number] | readonly number[];
+  readonly thickness: number;
+  readonly transmission: number;
 }
 
 export interface WavefrontMeshInput {
@@ -99,6 +191,16 @@ export interface WavefrontMeshInput {
   readonly metallic?: number;
   readonly opacity?: number;
   readonly ior?: number;
+  readonly sheen?: number;
+  readonly sheenTint?: number;
+  readonly sheenColor?: RendererColor | readonly number[];
+  readonly clearcoat?: number;
+  readonly clearcoatRoughness?: number;
+  readonly specular?: number;
+  readonly specularColor?: RendererColor | readonly number[];
+  readonly thickness?: number;
+  readonly transmission?: number;
+  readonly volume?: WavefrontVolumeInput | null;
   readonly material?: {
     readonly kind?: WavefrontMaterialKind;
     readonly color?: RendererColor | readonly number[];
@@ -109,11 +211,31 @@ export interface WavefrontMeshInput {
     readonly metallic?: number;
     readonly opacity?: number;
     readonly ior?: number;
+    readonly sheen?: number;
+    readonly sheenTint?: number;
+    readonly sheenColor?: RendererColor | readonly number[];
+    readonly clearcoat?: number;
+    readonly clearcoatRoughness?: number;
+    readonly specular?: number;
+    readonly specularColor?: RendererColor | readonly number[];
+    readonly thickness?: number;
+    readonly transmission?: number;
     readonly id?: number;
+    readonly medium?: WavefrontMediumInput | null;
+    readonly mediumId?: number;
+    readonly volume?: WavefrontVolumeInput | null;
+    readonly baseColorTexture?: WavefrontTextureSampleInput | null;
+    readonly metallicRoughnessTexture?: WavefrontTextureSampleInput | null;
+    readonly normalTexture?: WavefrontTextureSampleInput | null;
+    readonly occlusionTexture?: WavefrontTextureSampleInput | null;
+    readonly emissiveTexture?: WavefrontTextureSampleInput | null;
   };
-  readonly medium?: {
-    readonly id?: number;
-  };
+  readonly baseColorTexture?: WavefrontTextureSampleInput | null;
+  readonly metallicRoughnessTexture?: WavefrontTextureSampleInput | null;
+  readonly normalTexture?: WavefrontTextureSampleInput | null;
+  readonly occlusionTexture?: WavefrontTextureSampleInput | null;
+  readonly emissiveTexture?: WavefrontTextureSampleInput | null;
+  readonly medium?: WavefrontMediumInput | null;
 }
 
 export interface WavefrontTriangleRecord {
@@ -123,6 +245,7 @@ export interface WavefrontTriangleRecord {
   readonly flags: number;
   readonly materialRefId: number;
   readonly mediumRefId: number;
+  readonly materialSlot?: number;
   readonly v0: readonly number[];
   readonly v1: readonly number[];
   readonly v2: readonly number[];
@@ -135,6 +258,15 @@ export interface WavefrontTriangleRecord {
   readonly color: readonly number[];
   readonly emission: readonly number[];
   readonly material: readonly number[];
+  readonly materialResponse: readonly number[];
+  readonly materialExtension?: readonly number[];
+  readonly specularColor?: readonly number[];
+  readonly baseColorAtlas?: readonly number[];
+  readonly metallicRoughnessAtlas?: readonly number[];
+  readonly normalAtlas?: readonly number[];
+  readonly occlusionAtlas?: readonly number[];
+  readonly emissiveAtlas?: readonly number[];
+  readonly textureSettings?: readonly number[];
   readonly bounds: Readonly<{ min: readonly number[]; max: readonly number[] }>;
   readonly centroid: readonly number[];
 }
@@ -214,6 +346,7 @@ export interface WavefrontReferenceHit {
   readonly color: readonly number[];
   readonly emission: readonly number[];
   readonly material: readonly number[];
+  readonly materialResponse: readonly number[];
 }
 
 export interface IntersectWavefrontReferenceTriangleOptions {
@@ -250,12 +383,27 @@ export interface WavefrontGpuMeshSource {
       readonly flags: number;
       readonly materialRefId: number;
       readonly mediumRefId: number;
+      readonly medium: WavefrontMediumInput | null;
       readonly color: readonly number[];
       readonly emission: readonly number[];
       readonly roughness: number;
       readonly metallic: number;
       readonly opacity: number;
       readonly ior: number;
+      readonly sheen: number;
+      readonly sheenTint: number;
+      readonly sheenColor: readonly [number, number, number, number] | readonly number[];
+      readonly clearcoat: number;
+      readonly clearcoatRoughness: number;
+      readonly specular: number;
+      readonly specularColor: readonly [number, number, number, number] | readonly number[];
+      readonly thickness: number;
+      readonly transmission: number;
+      readonly baseColorTexture: WavefrontTextureSampleInput | null;
+      readonly metallicRoughnessTexture: WavefrontTextureSampleInput | null;
+      readonly normalTexture: WavefrontTextureSampleInput | null;
+      readonly occlusionTexture: WavefrontTextureSampleInput | null;
+      readonly emissiveTexture: WavefrontTextureSampleInput | null;
     }>[];
     readonly count: number;
     readonly recordBytes: number;
@@ -264,6 +412,24 @@ export interface WavefrontGpuMeshSource {
   readonly bvhNodeCapacity: number;
 }
 
+export interface WavefrontGpuTextureAtlasSource {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8Array;
+  readonly defaultRect: readonly [number, number, number, number] | readonly number[];
+}
+
+export interface WavefrontGpuMaterialSource {
+  readonly buffer: ArrayBuffer;
+  readonly count: number;
+  readonly recordBytes: number;
+  readonly baseColorAtlas: WavefrontGpuTextureAtlasSource;
+  readonly metallicRoughnessAtlas: WavefrontGpuTextureAtlasSource;
+  readonly normalAtlas: WavefrontGpuTextureAtlasSource;
+  readonly occlusionAtlas: WavefrontGpuTextureAtlasSource;
+  readonly emissiveAtlas: WavefrontGpuTextureAtlasSource;
+}
+
 export interface WavefrontEmissiveTriangleIndexSource {
   readonly buffer: ArrayBuffer;
   readonly indices: readonly number[];
@@ -312,6 +478,7 @@ export interface WavefrontEnvironmentMapInput {
   readonly enabled?: boolean;
   readonly width?: number;
   readonly height?: number;
+  readonly mipLevelCount?: number;
   readonly projection?: "equirectangular" | string;
   readonly format?: GPUTextureFormat | "rgba16float";
   readonly texture?: GPUTexture;
@@ -323,16 +490,19 @@ export interface WavefrontEnvironmentMapInput {
   readonly rotationRadians?: number;
   readonly rotation?: number;
   readonly ambientStrength?: number;
+  readonly hasImportanceData?: boolean;
 }
 
 export interface WavefrontEnvironmentMapSnapshot {
   readonly enabled: boolean;
   readonly width: number;
   readonly height: number;
+  readonly mipLevelCount: number;
   readonly projection: string;
   readonly intensity: number;
   readonly rotationRadians: number;
   readonly ambientStrength: number;
+  readonly hasImportanceData: boolean;
 }
 
 export interface WavefrontPathTracingComputeConfig {
@@ -347,9 +517,20 @@ export interface WavefrontPathTracingComputeConfig {
   readonly sceneObjects: readonly WavefrontSceneObject[];
   readonly sceneObjectCount: number;
   readonly sceneObjectCapacity: number;
+  readonly mediums: readonly Readonly<{
+    readonly id: number;
+    readonly phaseModel: number;
+    readonly density: number;
+    readonly attenuationColor: readonly [number, number, number, number] | readonly number[];
+    readonly attenuationDistance: number;
+    readonly absorption: readonly [number, number, number] | readonly number[];
+    readonly scattering: readonly [number, number, number] | readonly number[];
+  }>[];
+  readonly mediumCount: number;
   readonly accelerationBuildMode: WavefrontAccelerationBuildMode;
   readonly gpuAccelerationBuildRequired: boolean;
   readonly gpuMeshSource: WavefrontGpuMeshSource;
+  readonly gpuMaterialSource: WavefrontGpuMaterialSource;
   readonly meshAcceleration: WavefrontMeshAcceleration;
   readonly emissiveTriangleIndices: WavefrontEmissiveTriangleIndexSource;
   readonly emissiveTriangleCount: number;
@@ -424,6 +605,7 @@ export interface WavefrontPathTracingMemoryEstimate {
   readonly pathVertexBytes: number;
   readonly sceneObjectBytes: number;
   readonly triangleBytes: number;
+  readonly materialTableBytes: number;
   readonly bvhNodeBytes: number;
   readonly bvhLeafReferenceBytes: number;
   readonly emissiveTriangleMetadataBytes: number;
@@ -489,6 +671,7 @@ export interface CreateWavefrontPathTracingComputeRendererOptions {
   readonly tilePixelCapacity?: number;
   readonly sceneObjectCapacity?: number;
   readonly sceneObjects?: readonly WavefrontSceneObjectInput[];
+  readonly mediums?: readonly WavefrontMediumInput[];
   readonly mesh?: WavefrontMeshInput;
   readonly meshes?: readonly WavefrontMeshInput[];
   readonly triangleCapacity?: number;
@@ -525,6 +708,11 @@ export interface WavefrontPathTracingComputeRenderer {
   renderFrame(options?: {
     readStats?: boolean;
     readOutputProbe?: boolean;
+    awaitGPUCompletion?: boolean;
+    submittedWorkTimeoutMs?: number;
+    samplesPerPixel?: number;
+    minimumSamplesPerPixel?: number;
+    frameTimeBudgetMs?: number;
     probe?: { x?: number; y?: number };
   }): Promise<WavefrontPathTracingComputeFrameStats>;
   readOutputProbe(options?: { x?: number; y?: number }): Promise<
@@ -551,6 +739,7 @@ export interface WavefrontPathTracingComputeRenderer {
     emissiveTriangleCount: number;
     environmentPortalCount: number;
     environmentPortalMode: 0 | 1 | 2;
+    mediumCount: number;
     environmentMap: WavefrontEnvironmentMapSnapshot;
     deferredPathResolve: boolean;
     bvhNodeCount: number;
@@ -574,6 +763,9 @@ export interface WavefrontPathTracingComputeFrameStats {
   readonly tiles: number;
   readonly tileSize: number;
   readonly samplesPerPixel: number;
+  readonly renderedSamplesPerPixel: number;
+  readonly frameTimeBudgetMs: number | null;
+  readonly budgetConstrained: boolean;
   readonly maxFramePassesPerSubmission: number;
   readonly screenRays: number;
   readonly primaryRays: number;
@@ -582,6 +774,7 @@ export interface WavefrontPathTracingComputeFrameStats {
   readonly emissiveTriangleCount: number;
   readonly environmentPortalCount: number;
   readonly environmentPortalMode: 0 | 1 | 2;
+  readonly mediumCount: number;
   readonly environmentMap: WavefrontEnvironmentMapSnapshot;
   readonly deferredPathResolve: boolean;
   readonly bvhNodeCount: number;
@@ -592,6 +785,15 @@ export interface WavefrontPathTracingComputeFrameStats {
   readonly accelerationBuilt: boolean;
   readonly accelerationBuildCount: number;
   readonly commandSubmissions: number;
+  readonly gpuWorkerJobs: Readonly<{
+    completedPerFrame: number;
+    completedPerSecond: number | null;
+    completedPerSubmission: number;
+    directDispatchesCompleted: number;
+    indirectDispatchesCompleted: number;
+    frameTimeMs: number;
+    awaitedGpuCompletion: boolean;
+  }>;
   readonly frameConfigSlots: number;
   readonly gpuParallelism: WavefrontGpuParallelismDiagnostics;
   readonly memory: WavefrontPathTracingMemoryEstimate;
@@ -618,6 +820,9 @@ export function normalizeWavefrontSceneObject(
   input?: WavefrontSceneObjectInput,
   index?: number
 ): WavefrontSceneObject;
+export function createWavefrontGpuMaterialSource(
+  meshes?: readonly WavefrontMeshInput[] | WavefrontMeshInput
+): WavefrontGpuMaterialSource;
 export function createDefaultWavefrontSceneObjects(): readonly WavefrontSceneObject[];
 export function estimateWavefrontPathTracingMemory(options?: {
   tilePixelCapacity?: number;
@@ -646,12 +851,25 @@ export function normalizeWavefrontMesh(
   metallic: number;
   opacity: number;
   ior: number;
+  sheen: number;
+  sheenTint: number;
+  sheenColor: readonly [number, number, number, number] | readonly number[];
+  clearcoat: number;
+  clearcoatRoughness: number;
+  specular: number;
+  specularColor: readonly [number, number, number, number] | readonly number[];
+  transmission: number;
+  baseColorTexture: WavefrontTextureSampleInput | null;
+  metallicRoughnessTexture: WavefrontTextureSampleInput | null;
+  normalTexture: WavefrontTextureSampleInput | null;
+  occlusionTexture: WavefrontTextureSampleInput | null;
 }>;
 export function createWavefrontMeshAcceleration(
   meshes?: readonly WavefrontMeshInput[] | WavefrontMeshInput
 ): WavefrontMeshAcceleration;
 export function createWavefrontGpuMeshSource(
-  meshes?: readonly WavefrontMeshInput[] | WavefrontMeshInput
+  meshes?: readonly WavefrontMeshInput[] | WavefrontMeshInput,
+  gpuMaterialSource?: WavefrontGpuMaterialSource | null
 ): WavefrontGpuMeshSource;
 export function createWavefrontEmissiveTriangleIndexSource(
   meshes?: readonly WavefrontMeshInput[] | WavefrontMeshInput,
@@ -731,12 +949,14 @@ export const rendererWavefrontComputeStatsStride: 8;
 
 export const wavefrontPathTracingComputeLimits: Readonly<{
   workgroupSize: 64;
+  traceStorageBufferBindings: number;
   rayRecordBytes: 80;
-  hitRecordBytes: 208;
-  sceneObjectRecordBytes: 96;
+  hitRecordBytes: 256;
+  sceneObjectRecordBytes: 160;
   meshVertexRecordBytes: 48;
-  meshRangeRecordBytes: 96;
-  triangleRecordBytes: 208;
+  meshRangeRecordBytes: 240;
+  triangleRecordBytes: 352;
+  materialRecordBytes: 192;
   bvhNodeRecordBytes: 48;
   bvhLeafReferenceRecordBytes: 16;
   emissiveTriangleIndexBytes: 4;

package/src/index.js

@@ -5,6 +5,7 @@ export {
   createWavefrontBvhBuildLevels,
   createWavefrontBvhSortStages,
   createWavefrontEmissiveTriangleIndexSource,
+  createWavefrontGpuMaterialSource,
   createWavefrontGpuMeshSource,
   createWavefrontMeshAcceleration,
   createWavefrontPathTracingComputeConfig,
@@ -149,6 +150,57 @@ const rendererAccelerationStructurePolicies = Object.freeze(
   )
 );
 
+function clampWavefrontAdaptiveSamplesPerPixel(value) {
+  if (!Number.isFinite(value)) {
+    return 1;
+  }
+  return Math.max(1, Math.min(256, Math.round(value)));
+}
+
+export function createWavefrontAdaptiveSamplingLevels(options = {}) {
+  const requestedSamplesPerPixel = clampWavefrontAdaptiveSamplesPerPixel(
+    options.samplesPerPixel ?? 1
+  );
+  const minimumSamplesPerPixel = Math.min(
+    requestedSamplesPerPixel,
+    clampWavefrontAdaptiveSamplesPerPixel(options.minimumSamplesPerPixel ?? 1)
+  );
+  const frameTimeBudgetMs = Number.isFinite(options.frameTimeBudgetMs)
+    ? Math.max(0, Number(options.frameTimeBudgetMs))
+    : 0;
+  const levels = new Set([minimumSamplesPerPixel, requestedSamplesPerPixel]);
+  let currentSamplesPerPixel = minimumSamplesPerPixel;
+
+  while (currentSamplesPerPixel < requestedSamplesPerPixel) {
+    levels.add(currentSamplesPerPixel);
+    currentSamplesPerPixel *= 2;
+  }
+
+  levels.add(Math.min(currentSamplesPerPixel, requestedSamplesPerPixel));
+
+  return Object.freeze({
+    requestedSamplesPerPixel,
+    minimumSamplesPerPixel,
+    frameTimeBudgetMs,
+    levels: Object.freeze(
+      [...levels]
+        .sort((left, right) => left - right)
+        .map((samplesPerPixel) =>
+          Object.freeze({
+            id: `${samplesPerPixel}spp`,
+            label: `${samplesPerPixel} spp`,
+            estimatedCostMs: samplesPerPixel,
+            config: Object.freeze({
+              samplesPerPixel,
+              frameTimeBudgetMs,
+              minimumSamplesPerPixel,
+            }),
+          })
+        )
+    ),
+  });
+}
+
 function createWavefrontField(name, type, description) {
   return Object.freeze({
     name,