# three-gpu-pathtracer/webgpu ## Random Strategies ### RANDOM_PCG ```js RANDOM_PCG: Object ``` Uncorrelated pseudo random samples. Converges slowest but never shows structured artifacts. ### RANDOM_SOBOL ```js RANDOM_SOBOL: Object ``` Sobol low discrepancy samples, scrambled per pixel. Converges faster than `RANDOM_PCG`. The default. ### RANDOM_BLUE_DITHER ```js RANDOM_BLUE_DITHER: Object ``` The same Sobol sequence for every pixel, offset by a blue noise dither so early frames read as smooth grain rather than clumped noise. ## Transmissive Background Modes ### TRANSMISSIVE_BACKGROUND_ENVIRONMENT ```js TRANSMISSIVE_BACKGROUND_ENVIRONMENT: number ``` Sample the environment map, so glass shows what is behind it. ### TRANSMISSIVE_BACKGROUND_OVERLAY ```js TRANSMISSIVE_BACKGROUND_OVERLAY: number ``` Set the opacity from the transmitted light intensity, tinted by the environment lighting. ### TRANSMISSIVE_BACKGROUND_TRANSPARENT ```js TRANSMISSIVE_BACKGROUND_TRANSPARENT: number ``` Attenuate the background by the transmitted light, so glass renders against transparency. ## BlurredEnvMapGenerator Produces a PMREM prefiltered, optionally downsampled equirectangular copy of an environment map. Blurring removes the small bright details that make an environment slow to converge. ### .constructor ```js constructor( renderer: WebGPURenderer ) ``` ### .dispose ```js dispose(): void ``` Frees every GPU resource held by the generator. ### .generate ```js async generate( texture: Texture, blur = 0: number, width = null: number, height = null: number ): Promise ``` Renders a blurred copy of the given environment map. The source texture is left untouched. > [!NOTE] > The returned texture is owned by the caller and must be disposed. ## FSRUpscaler Upscales a path traced image to the drawing buffer size with FSR. Pass one to "WebGPUPathTracer.setUpscaler". The "Upscaler" class is passed in rather than imported so it does not become a dependency. ```js import { Upscaler } from '@pmndrs/upscaler'; pathTracer.setUpscaler( new FSRUpscaler( { Upscaler } ) ); ``` ### .constructor ```js constructor( { // The `Upscaler` class from `@pmndrs/upscaler`. Upscaler: function, sharpness?: number, } ) ``` Every field below can also be assigned after construction. ### .init ```js init( renderer: WebGPURenderer ): void ``` ### .upscale ```js upscale( source: Texture, camera: Camera ): Texture ``` Upscales a texture to the renderer's drawing buffer size. ## OIDNDenoiser Runs Open Image Denoise over a path traced image. Pass one to "WebGPUPathTracer.setDenoiser", or drive it directly with "denoise". "initUNetFromURL" and the weights are passed in rather than imported so neither the library nor the network files become a dependency. ```js import { initUNetFromURL } from 'oidn-webgpu'; pathTracer.setDenoiser( new OIDNDenoiser( { initUNetFromURL, auxWeightsUrl } ) ); ``` Weights come from the oidn-weights repository, where the "_small" and "_large" variants trade quality against download size and per tile cost. ### events ```js // Fired when a pass started by `update` fails, such as the weights failing to download, with the // failure as the event's `error`. No other pass starts until a reset. { type: 'error' } // Fired as each tile of a pass finishes, with the fraction of the pass done as `progress`. { type: 'progress' } ``` ### .texture ```js texture: ExternalTexture | null ``` The denoised result, or null until the first tile has been produced. ### .complete ```js complete: boolean ``` Whether a pass has finished. Stays true until reset. ### .running ```js running: boolean ``` Whether a pass is running. The work is spread over several frames. ### .constructor ```js constructor( { initUNetFromURL: function, // Weights for the guided model. auxWeightsUrl: string, // Weights for the color only model, needed only when // `useAuxiliaryBuffers` is `false`. colorWeightsUrl?: string, useAuxiliaryBuffers?: boolean, maxTileSize?: number | null, // `false` pins every tile to `maxTileSize`. An object tunes // the adaptive sizing. dynamicTile?: DynamicTileSetting | null, } ) ``` Every field below can also be assigned after construction. ### .init ```js init( renderer: WebGPURenderer ): void ``` ### .update ```js update( target: Texture, aux = null: StorageArrayTexture | null ): Texture | null ``` Unpacks the auxiliary buffers the path tracer accumulated and starts a pass. Safe to call every frame. ### .denoise ```js async denoise( color: Texture, albedo = null: Texture | null, normal = null: Texture | null ): void ``` Runs a pass unless one is already running or finished. The optional albedo and normal buffers guide the filter and select the guided model. Both hold [0,1] values, with normals mapped so a flat normal is (0.5, 0.5, 1). ### .reset ```js reset(): void ``` Drops any running pass and the last result. Call it whenever the image changes, such as when the camera moves. ## WebGPUPathTracer Progressive path tracer running on WebGPU. Call [WebGPUPathTracer#setScene](WebGPUPathTracer#setScene) once, then [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) every frame to accumulate samples into the canvas. The scene is captured when `setScene` is called, so changes to geometry, materials, lights, or the environment afterward require the matching `update*` function. Any change that invalidates the accumulated image restarts it. ### events ```js // Fired once every pixel has reached `maxSamples` and an attached denoiser has finished. Fires // again after a reset, or after `maxSamples` is raised, once the render has caught up. { type: 'complete' } // Fired as the render advances. `stage` is "building", "compiling", "rendering" or "denoising", and // `progress` is the fraction of it done, or null when unknown. "rendering" also gives the sample // counts as `samples`, reported a few times a second. { type: 'progress' } ``` ### .maxBounces ```js maxBounces: number = 15 ``` Maximum number of times a ray can scatter before the path is terminated. Higher values resolve more indirect light at the cost of speed. ### .frameBudget ```js frameBudget: number = 250000 ``` Number of path steps dispatched per [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) call, independent of resolution. Raising it trades frame rate for convergence speed. ### .frameTime ```js readonly frameTime: number ``` GPU time in milliseconds of a recent [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) call. Only measured when the renderer is created with `trackTimestamp: true`. ### .maxTransparentBounces ```js maxTransparentBounces: number = 15 ``` Maximum number of alpha tested surfaces a ray can pass through. Counted separately from [WebGPUPathTracer#maxBounces](WebGPUPathTracer#maxBounces) so foliage and cutouts cannot exhaust the bounce budget. ### .maxSubsurfaceBounces ```js maxSubsurfaceBounces: number = 256 ``` Maximum number of scatter events a path can take inside a subsurface scattering volume. Counted separately from [WebGPUPathTracer#maxBounces](WebGPUPathTracer#maxBounces). Paths that reach it end, darkening dense volumes. ### .maxSamples ```js maxSamples: number = 0 ``` Stops accumulating once every pixel reaches this many samples. A denoiser only runs once the render has stopped, so it has no effect while this is `0`. > [!NOTE] > `0` renders indefinitely. ### .complete ```js complete: boolean ``` Whether every pixel has reached [WebGPUPathTracer#maxSamples](WebGPUPathTracer#maxSamples) and an attached denoiser has finished, as of the last measurement. Always false while rendering indefinitely. ### .transmissiveBackground ```js transmissiveBackground: number = TRANSMISSIVE_BACKGROUND_OVERLAY ``` How the background is treated behind transmissive surfaces. One of `TRANSMISSIVE_BACKGROUND_OVERLAY`, `TRANSMISSIVE_BACKGROUND_ENVIRONMENT`, or `TRANSMISSIVE_BACKGROUND_TRANSPARENT`. ### .filterGlossyFactor ```js filterGlossyFactor: number = 1 ``` Blurs sharp reflections seen through rough surfaces to suppress fireflies. Higher values remove more noise and more detail. > [!NOTE] > `0` disables the filter. ### .multipleImportanceSampling ```js multipleImportanceSampling: boolean = true ``` Whether to combine light sampling and bsdf sampling with MIS. Disabling it makes lights noticeably noisier. ### .clampDirect ```js clampDirect: number = 0 ``` Upper bound on the contribution of a directly lit path segment, for suppressing fireflies. > [!NOTE] > `0` disables the clamp. Clamping darkens the image and biases the result. ### .clampIndirect ```js clampIndirect: number = 10 ``` Upper bound on the contribution of an indirectly lit path segment, for suppressing fireflies. > [!NOTE] > `0` disables the clamp. Clamping darkens the image and biases the result. ### .target ```js readonly target: Texture | null ``` The render target the accumulated samples are written into. ### .fadeState ```js readonly fadeState: number ``` Progress of the fade from the low resolution preview to the full render, from 0 to 1. ### .lowResTarget ```js readonly lowResTarget: Texture ``` The low resolution preview rendered while [WebGPUPathTracer#renderDelay](WebGPUPathTracer#renderDelay) elapses. ### .lowResMode ```js readonly lowResMode: boolean ``` Whether the tracer is currently rendering the low resolution preview. ### .compiling ```js readonly compiling: boolean ``` Whether the kernels are compiling, such as after the scene or material changes. Nothing new renders until they finish and the canvas keeps the last frame, so an app may draw its own preview in the meantime. ### .textureAtlas ```js readonly textureAtlas: AtlasTexture ``` The atlas every scene texture is packed into for the kernels to sample. ### .minSamples ```js minSamples: number = 1 ``` Average samples per pixel the full resolution render must reach before it is faded in. ### .renderDelay ```js renderDelay: number = 16 ``` Milliseconds to show the low resolution preview for after a reset. ### .fadeDuration ```js fadeDuration: number = 250 ``` Milliseconds taken to cross fade from the preview to the full render. ### .dynamicLowRes ```js dynamicLowRes: boolean = true ``` Whether to render a low resolution preview while the camera is moving. ### .lowResScale ```js lowResScale: number = 0.1 ``` Resolution of the low resolution preview, as a fraction of the render size. Adjusted when [WebGPUPathTracer#adaptiveDynamicRes](WebGPUPathTracer#adaptiveDynamicRes) is set. The preview never has more pixels than a frame of [WebGPUPathTracer#frameBudget](WebGPUPathTracer#frameBudget) can render. ### .adaptiveDynamicRes ```js adaptiveDynamicRes: boolean = true ``` Whether [WebGPUPathTracer#lowResScale](WebGPUPathTracer#lowResScale) is adjusted to the pixels a frame of [WebGPUPathTracer#frameBudget](WebGPUPathTracer#frameBudget) can render. ### .adaptiveFrameBudget ```js adaptiveFrameBudget: boolean = true ``` Whether [WebGPUPathTracer#frameBudget](WebGPUPathTracer#frameBudget) is adjusted to keep each [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) call near [WebGPUPathTracer#targetFrameTime](WebGPUPathTracer#targetFrameTime) of GPU time. Requires a renderer created with `trackTimestamp: true`. ### .targetFrameTime ```js targetFrameTime: number = 16 ``` GPU time in milliseconds per frame targeted by [WebGPUPathTracer#adaptiveFrameBudget](WebGPUPathTracer#adaptiveFrameBudget). ### .renderScale ```js renderScale: number = 1 ``` Resolution the path tracer renders at, as a fraction of the canvas size. Lowering it converges faster at the cost of detail, and pairs with an upscaler. ### .synchronizeRenderSize ```js synchronizeRenderSize: boolean = true ``` Whether to track the canvas size automatically. Set to `false` to drive the render size with [WebGPUPathTracer#setSize](WebGPUPathTracer#setSize). ### .renderToCanvas ```js renderToCanvas: boolean = true ``` Whether [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) draws the result to the current render target, the canvas by default. Set to `false` to only accumulate, as when baking to a texture read through [WebGPUPathTracer#target](WebGPUPathTracer#target). ### .asyncCompile ```js asyncCompile: boolean = false ``` Whether to compile the kernels asynchronously so a compile doesn't stall the page. Nothing new renders while [WebGPUPathTracer#compiling](WebGPUPathTracer#compiling) is true. ### .generateMissingAttributes ```js generateMissingAttributes: boolean = true ``` Whether to generate the attributes in [WebGPUPathTracer#commonAttributes](WebGPUPathTracer#commonAttributes) on geometry that is missing them when the scene is set. ### .commonAttributes ```js commonAttributes: Array = [ 'normal', 'tangent' ] ``` Vertex attributes every geometry is expected to provide. ### .stableNoise ```js stableNoise: boolean = true ``` Whether to restart the random sequence on reset so a given camera always produces the same image. ### .pause ```js pause: boolean = false ``` Whether to stop accumulating samples. The last image keeps being presented. ### .constructor ```js constructor( renderer: WebGPURenderer ) ``` ### .getSampleCountsAsync ```js async getSampleCountsAsync(): Promise ``` Measures the per pixel sample counts. Use `min` for convergence checks and `avg` to display. > [!NOTE] > The wavefront backend reduces the counts on the GPU and reads them back, so only call > this when the numbers are needed. ### .setMultipleImportanceSampling ```js setMultipleImportanceSampling( value: boolean ): void ``` ### .setDenoiser ```js setDenoiser( denoiser: OIDNDenoiser | null ): void ``` Attaches a denoiser, run once the render settles and displayed in place of the raw image. Settings live on the instance. Pass null to remove it. The render restarts when the auxiliary buffers it needs are added or dropped. ### .setUpscaler ```js setUpscaler( upscaler: FSRUpscaler | null ): void ``` Attaches an upscaler, run before the image is presented so the render can happen below the canvas resolution. Settings live on the instance. Pass null to remove it. ### .setScene ```js setScene( scene: Scene, camera: Camera ): void ``` Captures the scene and camera and builds the acceleration structures the kernels trace against. Call this once, then use the `update*` functions for later changes. > [!NOTE] > Geometry BVHs are built synchronously, so this blocks for large scenes. ### .setBVHWorker ```js setBVHWorker( WorkerConstructor: function ): void ``` Sets the worker class [WebGPUPathTracer#setSceneAsync](WebGPUPathTracer#setSceneAsync) builds the mesh geometry BVHs with, such as `GenerateMeshBVHWorker` from three-mesh-bvh. Several are created and disposed per call so geometries build in parallel. ### .setSceneAsync ```js async setSceneAsync( scene: Scene, camera: Camera ): Promise ``` Like [WebGPUPathTracer#setScene](WebGPUPathTracer#setScene) but builds the mesh geometry BVHs in the workers set with [WebGPUPathTracer#setBVHWorker](WebGPUPathTracer#setBVHWorker) so the page is not blocked. Skinned meshes are still built synchronously. ### .setRandom ```js setRandom( random: Object ): void ``` Replaces the random number generator and recompiles the kernels. ### .setCamera ```js setCamera( camera: Camera ): void ``` Replaces the camera the rays are generated from. Cameras with a `getCameraRayFn`, such as `PhysicalCamera` and `EquirectCamera`, provide their own ray generation. ### .updateMaterials ```js updateMaterials(): void ``` Re-reads the material properties and textures from the scene. Call after changing any material. ### .updateTransforms ```js updateTransforms(): void ``` Re-reads the world matrices from the scene. Call after moving any object. > [!NOTE] > Changing geometry requires [WebGPUPathTracer#setScene](WebGPUPathTracer#setScene) instead, since the BVH > must be rebuilt. ### .updateCamera ```js updateCamera(): void ``` Re-reads the camera transform and projection. Call after moving the camera. ### .updateEnvironment ```js updateEnvironment(): void ``` Re-reads `scene.environment` and `scene.background`, along with their intensity, rotation, and blur. ### .updateLights ```js updateLights(): void ``` Re-collects the lights in the scene. Call after adding, removing, or changing one. ### .setSize ```js setSize( x: number, y: number ): void ``` Sets the resolution the path tracer renders at. Only used when [WebGPUPathTracer#synchronizeRenderSize](WebGPUPathTracer#synchronizeRenderSize) is `false`. ### .reset ```js reset(): void ``` Discards the accumulated image and starts over. The `update*` functions call this for you. ### .renderSample ```js renderSample(): void ``` Accumulates one round of samples and presents the result to the canvas. Call once per frame. ### .renderDebugBounds ```js renderDebugBounds( { // Count the top level object bounding boxes. displayTLAS = true: boolean, // Count the per object geometry bounding boxes. displayBLAS = true: boolean, // Only count boxes in front of the nearest hit, so occluded // boxes do not contribute. Culling and material transparency // are honored. stopAtSurface = false: boolean, // Node count that saturates to full heat. saturationCount = 64: number, } ): void ``` Draws a heatmap of how many BVH bounding boxes each camera ray intersects, for diagnosing box overlap and traversal cost. Hotter pixels traverse more nodes. ### .renderTextureAtlas ```js renderTextureAtlas( layer = 0: number ): void ``` Draws one layer of the texture atlas to the canvas, for debugging texture packing. ### .renderSampleDensity ```js renderSampleDensity(): void ``` Draws a heatmap of the per pixel sample counts, for spotting pixels that converge slowly. > [!NOTE] > Measures on every call and draws with the previous result, since the readback lands a > frame later. ### .renderAuxBuffer ```js renderAuxBuffer( buffer = 'albedo': 'albedo' | 'normal' ): void ``` Draws the albedo or normal auxiliary buffer accumulated for the denoiser, for checking what it is given. Nothing is drawn until a denoiser that uses them is attached. ### .dispose ```js dispose(): void ``` Frees every GPU resource held by the tracer, including any attached denoiser and upscaler. ### .getRenderTime ```js getRenderTime(): number ``` Milliseconds elapsed since the last reset. ## SampleCounts ### .min ```js min: number ``` Lowest sample count of any pixel. ### .max ```js max: number ``` Highest sample count of any pixel. ### .avg ```js avg: number ``` Mean sample count across the image. ### .samplesPerSecond ```js samplesPerSecond: number ``` Mean samples accumulated per second since the last reset.