@plasius/gpu-renderer 0.1.12 → 0.1.13

package/src/index.d.ts

@@ -151,6 +151,19 @@ export type RendererAccelerationStructureUpdateClass =
   | "rigid-dynamic"
   | "deforming"
   | "proxy";
+export type RendererWavefrontHitType =
+  | "surface"
+  | "emissive"
+  | "environment"
+  | "transparent"
+  | "miss";
+export type RendererWavefrontPassKey =
+  | "generatePrimaryRays"
+  | "intersectActiveQueue"
+  | "resolveSurfaceRecords"
+  | "accumulateTerminalRadiance"
+  | "scatterContinuations"
+  | "compactAndSwapQueues";
 
 export interface RendererInputBoundary {
   readonly type: "stable-visual-snapshot";
@@ -288,9 +301,75 @@ export interface RayTracingRenderPlan {
       }
   )[];
   readonly accelerationStructureUpdates: readonly RendererAccelerationStructureUpdatePolicy[];
+  readonly wavefront: RendererWavefrontPathTracingPlan;
   readonly workerManifest: RendererWorkerManifest;
 }
 
+export interface RendererWavefrontFieldContract {
+  readonly name: string;
+  readonly type: string;
+  readonly description: string;
+}
+
+export interface RendererWavefrontRecordContract {
+  readonly schemaVersion: typeof rendererWavefrontBufferSchemaVersion;
+  readonly recordName: string;
+  readonly fields: readonly RendererWavefrontFieldContract[];
+}
+
+export interface RendererWavefrontQueueDescriptor {
+  readonly name: "active" | "next";
+  readonly role: "current-bounce" | "next-bounce";
+}
+
+export interface RendererWavefrontBounceStep {
+  readonly bounce: number;
+  readonly readQueue: "active" | "next";
+  readonly writeQueue: "active" | "next";
+  readonly passOrder: readonly RendererWavefrontPassKey[];
+}
+
+export interface RendererWavefrontTerminationPolicy {
+  readonly terminalHitTypes: readonly RendererWavefrontHitType[];
+  readonly continuationHitTypes: readonly RendererWavefrontHitType[];
+  readonly emissive: Readonly<{
+    action: "accumulate-and-stop";
+    contributesRadiance: true;
+  }>;
+  readonly environment: Readonly<{
+    action: "accumulate-and-stop";
+    contributesRadiance: true;
+  }>;
+  readonly miss: Readonly<{
+    action: "accumulate-environment-or-dark-stop";
+    contributesRadiance: true;
+  }>;
+}
+
+export interface RendererWavefrontPathTracingPlan {
+  readonly schemaVersion: typeof rendererWavefrontBufferSchemaVersion;
+  readonly owner: typeof rendererDebugOwner;
+  readonly maxDepth: number;
+  readonly queueCapacity: number;
+  readonly explicitLightSampling: boolean;
+  readonly accumulationResetEpoch: number;
+  readonly queueLayout: Readonly<{
+    strategy: typeof rendererWavefrontQueuePairStrategy;
+    compactAfterScatter: true;
+    queues: readonly RendererWavefrontQueueDescriptor[];
+  }>;
+  readonly bufferContracts: Readonly<{
+    ray: RendererWavefrontRecordContract;
+    hit: RendererWavefrontRecordContract;
+    surface: RendererWavefrontRecordContract;
+    materialReference: RendererWavefrontRecordContract;
+    mediumReference: RendererWavefrontRecordContract;
+    accumulation: RendererWavefrontRecordContract;
+  }>;
+  readonly bounceSchedule: readonly RendererWavefrontBounceStep[];
+  readonly terminationPolicy: RendererWavefrontTerminationPolicy;
+}
+
 export function getRendererWorkerProfile(
   name?: RendererWorkerProfileName
 ): RendererWorkerProfile;
@@ -309,11 +388,28 @@ export function createRayTracingRenderPlan(options: {
         readonly [key: string]: unknown;
       }
   )[];
+  wavefront?: {
+    maxDepth?: number;
+    queueCapacity?: number;
+    explicitLightSampling?: boolean;
+    accumulationResetEpoch?: number;
+  };
 }): RayTracingRenderPlan;
 
+export function createWavefrontPathTracingPlan(options?: {
+  maxDepth?: number;
+  queueCapacity?: number;
+  explicitLightSampling?: boolean;
+  accumulationResetEpoch?: number;
+}): RendererWavefrontPathTracingPlan;
+
 export const rendererRepresentationBands: readonly RendererRepresentationBand[];
 export const rendererAccelerationStructureUpdateClasses: readonly RendererAccelerationStructureUpdateClass[];
 export const rendererRayTracingStageOrder: readonly RendererRenderStage["key"][];
+export const rendererWavefrontBufferSchemaVersion: 1;
+export const rendererWavefrontQueuePairStrategy: "ping-pong-active-next";
+export const rendererWavefrontHitTypes: readonly RendererWavefrontHitType[];
+export const rendererWavefrontPassOrder: readonly RendererWavefrontPassKey[];
 
 export const defaultRendererClearColor: readonly [number, number, number, number];
 export const rendererDebugOwner: "renderer";

package/src/index.js

@@ -27,6 +27,23 @@ export const rendererRayTracingStageOrder = Object.freeze([
   "composition",
   "present",
 ]);
+export const rendererWavefrontBufferSchemaVersion = 1;
+export const rendererWavefrontQueuePairStrategy = "ping-pong-active-next";
+export const rendererWavefrontHitTypes = Object.freeze([
+  "surface",
+  "emissive",
+  "environment",
+  "transparent",
+  "miss",
+]);
+export const rendererWavefrontPassOrder = Object.freeze([
+  "generatePrimaryRays",
+  "intersectActiveQueue",
+  "resolveSurfaceRecords",
+  "accumulateTerminalRadiance",
+  "scatterContinuations",
+  "compactAndSwapQueues",
+]);
 
 const rendererRayTracingStageDefinitions = Object.freeze(
   rendererRayTracingStageOrder.map((key, index) =>
@@ -104,6 +121,167 @@ const rendererAccelerationStructurePolicies = Object.freeze(
   )
 );
 
+function createWavefrontField(name, type, description) {
+  return Object.freeze({
+    name,
+    type,
+    description,
+  });
+}
+
+const rendererWavefrontBufferContracts = Object.freeze({
+  ray: Object.freeze({
+    schemaVersion: rendererWavefrontBufferSchemaVersion,
+    recordName: "RayRecord",
+    fields: Object.freeze([
+      createWavefrontField("rayId", "u32", "Stable ray identifier for correlation and debugging."),
+      createWavefrontField("parentRayId", "u32", "Parent ray identifier for continuation lineage."),
+      createWavefrontField("sourcePixelId", "u32", "Screen pixel or texel that owns the sample."),
+      createWavefrontField("sampleId", "u32", "Per-pixel sample slot for accumulation."),
+      createWavefrontField("bounce", "u32", "Breadth-first bounce depth for the queue entry."),
+      createWavefrontField("origin", "vec3<f32>", "Ray origin in renderer world space."),
+      createWavefrontField("direction", "vec3<f32>", "Normalized ray direction in renderer world space."),
+      createWavefrontField("throughput", "vec3<f32>", "Current path throughput before the next event."),
+      createWavefrontField("mediumRefId", "u32", "Active medium reference identifier for the ray."),
+      createWavefrontField("flags", "u32", "Bit flags for front-face state, debug, and quality toggles."),
+    ]),
+  }),
+  hit: Object.freeze({
+    schemaVersion: rendererWavefrontBufferSchemaVersion,
+    recordName: "HitRecord",
+    fields: Object.freeze([
+      createWavefrontField("rayId", "u32", "Ray identifier copied from the active queue."),
+      createWavefrontField("sourcePixelId", "u32", "Pixel/texel owner for the ray sample."),
+      createWavefrontField("hitType", rendererWavefrontHitTypes.join(" | "), "Resolved hit classification for termination or continuation."),
+      createWavefrontField("distance", "f32", "Nearest-hit distance or miss sentinel."),
+      createWavefrontField("entityId", "u32", "Stable scene entity identifier."),
+      createWavefrontField("instanceId", "u32", "Renderer instance identifier."),
+      createWavefrontField("primitiveId", "u32", "Primitive or triangle identifier."),
+      createWavefrontField("materialId", "u32", "Surface material identifier."),
+      createWavefrontField("barycentrics", "vec3<f32>", "Triangle barycentric coordinates for interpolation."),
+      createWavefrontField("uv", "vec2<f32>", "Resolved surface UV when available."),
+      createWavefrontField("geometricNormal", "vec3<f32>", "True geometric face normal."),
+      createWavefrontField("shadingNormal", "vec3<f32>", "Interpolated or repaired shading normal."),
+      createWavefrontField("frontFace", "bool", "Front-face classification for shading and medium transitions."),
+    ]),
+  }),
+  surface: Object.freeze({
+    schemaVersion: rendererWavefrontBufferSchemaVersion,
+    recordName: "SurfaceRecord",
+    fields: Object.freeze([
+      createWavefrontField("rayId", "u32", "Ray identifier matched to the resolved hit."),
+      createWavefrontField("entityId", "u32", "Stable scene entity identifier."),
+      createWavefrontField("materialRefId", "u32", "Material-reference indirection for shading lookup tables."),
+      createWavefrontField("mediumRefId", "u32", "Resolved medium transition/reference identifier."),
+      createWavefrontField("geometricNormal", "vec3<f32>", "Preserved geometric normal for hemisphere checks."),
+      createWavefrontField("shadingNormal", "vec3<f32>", "Normal used for BSDF/BTDF evaluation."),
+      createWavefrontField("uv", "vec2<f32>", "Resolved texture coordinate."),
+      createWavefrontField("tangentFrame", "mat3x3<f32>", "Optional tangent basis for normal-map transforms."),
+    ]),
+  }),
+  materialReference: Object.freeze({
+    schemaVersion: rendererWavefrontBufferSchemaVersion,
+    recordName: "MaterialReferenceRecord",
+    fields: Object.freeze([
+      createWavefrontField("materialRefId", "u32", "Stable material lookup identifier."),
+      createWavefrontField("materialId", "u32", "Authoritative material id from scene submission."),
+      createWavefrontField("shadingModel", "u32", "Renderer-owned shading model enum."),
+      createWavefrontField("textureSetId", "u32", "Texture indirection set for the material."),
+      createWavefrontField("flags", "u32", "Alpha, emissive, transmission, and debug flags."),
+    ]),
+  }),
+  mediumReference: Object.freeze({
+    schemaVersion: rendererWavefrontBufferSchemaVersion,
+    recordName: "MediumReferenceRecord",
+    fields: Object.freeze([
+      createWavefrontField("mediumRefId", "u32", "Stable medium lookup identifier."),
+      createWavefrontField("mediumId", "u32", "Authoritative medium or fluid descriptor id."),
+      createWavefrontField("phaseModel", "u32", "Medium phase-function selector."),
+      createWavefrontField("absorption", "vec3<f32>", "Absorption coefficients for the active medium."),
+      createWavefrontField("scattering", "vec3<f32>", "Scattering coefficients for the active medium."),
+    ]),
+  }),
+  accumulation: Object.freeze({
+    schemaVersion: rendererWavefrontBufferSchemaVersion,
+    recordName: "AccumulationRecord",
+    fields: Object.freeze([
+      createWavefrontField("sourcePixelId", "u32", "Screen pixel or texel accumulator owner."),
+      createWavefrontField("sampleCount", "u32", "Committed sample count for the pixel."),
+      createWavefrontField("radiance", "vec3<f32>", "Accumulated radiance before tone-map/output resolve."),
+      createWavefrontField("throughput", "vec3<f32>", "Last surviving throughput for debug and variance tracking."),
+      createWavefrontField("resetEpoch", "u32", "Accumulation reset generation for history invalidation."),
+    ]),
+  }),
+});
+
+function buildWavefrontTerminationPolicy() {
+  return Object.freeze({
+    terminalHitTypes: Object.freeze(["emissive", "environment", "miss"]),
+    continuationHitTypes: Object.freeze(["surface", "transparent"]),
+    emissive: Object.freeze({
+      action: "accumulate-and-stop",
+      contributesRadiance: true,
+    }),
+    environment: Object.freeze({
+      action: "accumulate-and-stop",
+      contributesRadiance: true,
+    }),
+    miss: Object.freeze({
+      action: "accumulate-environment-or-dark-stop",
+      contributesRadiance: true,
+    }),
+  });
+}
+
+function buildWavefrontBounceSchedule(maxDepth) {
+  return Object.freeze(
+    Array.from({ length: maxDepth }, (_, index) =>
+      Object.freeze({
+        bounce: index,
+        readQueue: index % 2 === 0 ? "active" : "next",
+        writeQueue: index % 2 === 0 ? "next" : "active",
+        passOrder: rendererWavefrontPassOrder,
+      })
+    )
+  );
+}
+
+export function createWavefrontPathTracingPlan(options = {}) {
+  const maxDepth =
+    options.maxDepth === undefined
+      ? 6
+      : readPositiveInteger("maxDepth", options.maxDepth);
+  const queueCapacity =
+    options.queueCapacity === undefined
+      ? 8192
+      : readPositiveInteger("queueCapacity", options.queueCapacity);
+  const accumulationResetEpoch =
+    options.accumulationResetEpoch === undefined
+      ? 0
+      : readNonNegativeInteger("accumulationResetEpoch", options.accumulationResetEpoch);
+  const explicitLightSampling = options.explicitLightSampling === true;
+
+  return Object.freeze({
+    schemaVersion: rendererWavefrontBufferSchemaVersion,
+    owner: rendererDebugOwner,
+    maxDepth,
+    queueCapacity,
+    explicitLightSampling,
+    accumulationResetEpoch,
+    queueLayout: Object.freeze({
+      strategy: rendererWavefrontQueuePairStrategy,
+      compactAfterScatter: true,
+      queues: Object.freeze([
+        Object.freeze({ name: "active", role: "current-bounce" }),
+        Object.freeze({ name: "next", role: "next-bounce" }),
+      ]),
+    }),
+    bufferContracts: rendererWavefrontBufferContracts,
+    bounceSchedule: buildWavefrontBounceSchedule(maxDepth),
+    terminationPolicy: buildWavefrontTerminationPolicy(),
+  });
+}
+
 function buildRendererWorkerBudgetLevels(jobType, queueClass, levels) {
   return Object.freeze(
     levels.map((level) =>
@@ -678,6 +856,7 @@ export function createRayTracingRenderPlan(options = {}) {
     renderStages: workerManifest.renderStages,
     representationBands: representations,
     accelerationStructureUpdates: workerManifest.accelerationStructureUpdates,
+    wavefront: createWavefrontPathTracingPlan(options.wavefront),
     workerManifest,
   });
 }
@@ -732,6 +911,20 @@ function readPositiveNumber(name, value) {
   return value;
 }
 
+function readPositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer.`);
+  }
+  return value;
+}
+
+function readNonNegativeInteger(name, value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative integer.`);
+  }
+  return value;
+}
+
 function now() {
   if (typeof performance !== "undefined" && typeof performance.now === "function") {
     return performance.now();