three-gpu-pathtracer 0.0.20 → 0.0.22

package/README.md

@@ -30,6 +30,8 @@ _More features and capabilities in progress!_
 
 [Depth of Field](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/depthOfField.html)
 
+[HDR Image](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/hdr.html)
+
 **Features**
 
 [Skinned Geometry Support](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/skinnedMesh.html)
@@ -58,9 +60,6 @@ _More features and capabilities in progress!_
 
 [Ambient Occlusion Material](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/aoRender.html)
 
-[Looking Glass Portrait Quilt Render](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/lkg.html)
-
-
 ## Running examples locally
 
 To run and modify the examples locally, make sure you have Node and NPM installed.  Check the supported versions in [the test configuration](./.github/workflows/node.js.yml).
@@ -79,82 +78,22 @@ On Debian or Ubuntu, run `sudo apt install build-essential`.  It should just wor
 
 ```js
 import * as THREE from 'three';
-import { FullScreenQuad } from 'three/examples/jsm/postprocessing/Pass.js';
-import {
-	PathTracingSceneGenerator,
-	PathTracingRenderer,
-	PhysicalPathTracingMaterial,
-} from 'three-gpu-pathtracer';
+import { WebGLPathTracer } from 'three-gpu-pathtracer';
 
-// init scene, renderer, camera, controls, etc
+// init scene, camera, controls, etc
 
-renderer.outputEncoding = THREE.sRGBEncoding;
+renderer = new THREE.WebGLRenderer();
 renderer.toneMapping = THREE.ACESFilmicToneMapping;
 
-// initialize the path tracing material and renderer
-const ptMaterial = new PhysicalPathTracingMaterial();
-const ptRenderer = new PathTracingRenderer( renderer );
-ptRenderer.setSize( window.innerWidth, window.innerHeight );
-ptRenderer.camera = camera;
-ptRenderer.material = ptMaterial;
-
-// if rendering transparent background
-ptRenderer.alpha = true;
-
-// init quad for rendering to the canvas
-const fsQuad = new FullScreenQuad( new THREE.MeshBasicMaterial( {
-	map: ptRenderer.target.texture,
-
-	// if rendering transparent background
-	blending: THREE.CustomBlending,
-} ) );
-
-// ensure scene matrices are up to date
-scene.updateMatrixWorld();
-
-// initialize the scene and update the material properties with the bvh, materials, etc
-const generator = new PathTracingSceneGenerator();
-const { bvh, textures, materials, lights } = generator.generate( scene );
-
-// update bvh and geometry attribute textures
-ptMaterial.bvh.updateFrom( bvh );
-ptMaterial.attributesArray.updateFrom(
-	geometry.attributes.normal,
-	geometry.attributes.tangent,
-	geometry.attributes.uv,
-	geometry.attributes.color,
-);
-
-// update materials and texture arrays
-ptMaterial.materialIndexAttribute.updateFrom( geometry.attributes.materialIndex );
-ptMaterial.textures.setTextures( renderer, 2048, 2048, textures );
-ptMaterial.materials.updateFrom( materials, textures );
-
-// update the lights
-ptMaterial.lights.updateFrom( lights );
-
-// set the environment map
-const texture = await new RGBELoader().setDataType( THREE.FloatType ).loadAsync( envMapUrl );
-ptRenderer.material.envMapInfo.updateFrom( texture );
+pathTracer = new WebGLPathTracer( renderer );
+pathTracer.setScene( scene, camera );
 
 animate();
 
-// ...
-
 function animate() {
 
-	// if the camera position changes call "ptRenderer.reset()"
-
-	// update the camera and render one sample
-	camera.updateMatrixWorld();
-	ptRenderer.update();
-
-	// if using alpha = true then the target texture will change every frame
-	// so we must retrieve it before render.
-	fsQuad.material.map = ptRenderer.target.texture;
-
-	// copy the current state of the path tracer to canvas to display
-	fsQuad.render( renderer );
+	requestAnimationFrame( animate );
+	pathTracer.renderSample();
 
 }
 ```
@@ -176,245 +115,227 @@ const blurredEnvMap = generator.generate( envMap, 0.35 );
 
 ```
 
-## Dynamic Scenes
+# Exports
 
-Using the dynamic scene generator the same, frequently updated scene can be converted into a single reusable geometry multiple times and BVH refit which greatly improves subsequent scene updates. See `DynamicPathTracingSceneGenerator` docs for more info.
+## WebGLPathTracer
 
-```js
-import { DynamicPathTracingSceneGenerator } from 'three-gpu-pathtracer';
+### constructor
 
-// ... initialize scene etc
+```
+constructor( renderer : WebGLRenderer )
+```
 
-const generator = new DynamicPathTracingSceneGenerator( scene );
-const { bvh, textures, materials } = generator.generate( scene );
+### .bounces
 
-// ... update path tracer and render
+```js
+bounces = 10 : Number
 ```
 
-## Asynchronous Scene Generation
+Max number of lights bounces to trace.
 
-_NOTE WebWorker syntax is inconsistently supported across bundlers and sometimes not supported at all so the PathTracingSceneWorker class is not exported from the package root. If needed the code from src/worker can be copied and modified to accomodate a particular build process._
+### .filteredGlossyFactor
 
 ```js
-import { PathTracingSceneWorker } from 'three-gpu-pathtracer/src/workers/PathTracingSceneWorker.js';
+filteredGlossyFactor = 0 : Number
+```
 
-// ...
+Factor for alleviating bright pixels from rays that hit diffuse surfaces then specular surfaces. Setting this higher alleviates fireflies but will remove some specular caustics.
 
-// initialize the scene and update the material properties with the bvh, materials, etc
-const generator = new PathTracingSceneWorker();
-const { bvh, textures, materials, lights } = await generator.generate( scene );
+### .tiles
 
-// ...
+```js
+tiles = ( 3, 3 ) : Vector2
 ```
 
-# Exports
-
-## PathTracingRenderer
-
-Utility class for tracking and rendering a path traced scene to a render target.
+Number of tiles on x and y to render to. Can be used to improve the responsiveness of a page while still rendering a high resolution target.
 
-### .samples
+### .renderDelay
 
 ```js
-readonly samples : Number
+renderDelay = 100 : Number
 ```
 
-Number of samples per pixel that have been rendered to the target.
+Number of milliseconds to delay rendering samples after the path tracer has been reset.
 
-### .target
+### .fadeDuration
 
 ```js
-readonly target : WebGLRenderTarget
+fadeDuration = 500 : Number
 ```
 
-The target being rendered to. The size of the target is updated with `setSize` and is initialized to a FloatType texture.
+How long to take to fade the fully path traced scene in in milliseconds wen rendering to the canvas.
 
-> **Note**
-> Target will swap render targets after every full sample when alpha is enabled.
-
-### .camera
+### .minSamples
 
 ```js
-camera = null : Camera
+minSamples = 5 : Number
 ```
 
-The camera to render with. The view offset of the camera will be updated every sample to enable anti aliasing.
+How many samples to render before displaying to the canvas.
 
-### .material
+### .dynamicLowRes
 
 ```js
-material = null : ShaderMaterial
+dynamicLowRes = false : Boolean
 ```
 
-The Path Tracing material to render. This is expected to be a full screen quad material that respects the "opacity" field for every pixel so samples can be accumulated over time. The material is also expected to have `cameraWorldMatrix` and `invProjectionMatrix` fields of type `Matrix4`.
+Whether to render an extra low resolution of the scene while the full resolution renders. The scale is defined by `lowResScale`.
 
-### .tiles
+### .lowResScale
 
 ```js
-tiles = ( 1, 1 ) : Vector2
+lowResScale = 0.1 : Number
 ```
 
-Number of tiles on x and y to render to. Can be used to improve the responsiveness of a page while still rendering a high resolution target.
+The scale to render the low resolution pass at.
 
-### .stableNoise
+### .synchronizeRenderSize
 
 ```js
-stableNoise = false : Boolean
+synchronizeRenderSize = true : Boolean
 ```
 
-Whether to reset the random seed to `0` when restarting the render. If true then a consistent random sample pattern will appear when moving the camera, for example.
+Whether to automatically update the sie of the path traced buffer when the canvas size changes.
 
-### .stableTiles
+### .renderScale
 
 ```js
-stableTiles = true : Boolean
+renderScale = 1 : Number
 ```
 
-Whether the initial tile is reset to the top left tile when moving the camera or if it should continue to shift every frame.
+The scale to render the path traced image at. Only relevant if `synchronizeRenderSize` is true.
 
-### .alpha
+### .renderToCanvas
 
 ```js
-alpha = false : Boolean
+renderToCanvas = true : Boolean
 ```
 
-Whether to support rendering scenes with transparent backgrounds. When transparent backgrounds are used two extra render targets are used, custom blending is performed, and PathTracingRenderer.target will change on every completed sample.
+Whether to automatically render the path traced buffer to the canvas when `renderSample` is called.
 
-> **Note**
-> When a transparent background is used the material used for the final render to the canvas must use the same "premultipliedAlpha" setting as the canvas otherwise the final image may look incorrect.
-
-### constructor
+### .rasterizeScene
 
 ```js
-constructor( renderer : WebGLRenderer )
+rasterizeScene = true : Boolean
 ```
 
-### .setSize
+Whether to automatically rasterize the scene with the three.js renderer while the path traced buffer is rendering.
+
+### .textureSize
 
 ```js
-setSize( size : Vector2 ) : void
+textureSize = ( 1024, 1024 ) : Vector2
 ```
 
-Sets the size of the target to render to.
+The dimensions to expand or shrink all textures to so all scene textures can be packed into a single texture array.
 
-### .update
+### .samples
 
 ```js
-update()
+readonly samples : Number
 ```
 
-Renders a single sample to the target.
+The number of samples that have been rendered.
 
-### .reset
+### .target
 
 ```js
-reset() : void
+readonly target : WebGLRenderTarget
 ```
 
-Resets and restarts the render from scratch.
-
-## QuiltPathTracingRenderer
-
-Renderer that supports rendering to a quilt renderer to rendering on displays such as the Looking Glass display.
+The path traced render target. This potentially changes every call to `renderSample`.
 
-### .viewCount
+### .setScene
 
 ```js
-viewCount = 48 : Number
+setScene( scene : Scene, camera : Camera ) : void
 ```
 
-The number of views to be rendered. If this is less than the product of the quiltDimensions then there will be gaps at the end of the quilt.
+Sets the scene and camera to render. Must be called again when the camera object changes, the geometry in the scene changes, or new materials are assigned.
 
-### .quiltDimensions
-```js
-quiltDimensions = Vector2( 8, 6 ) : Vector2
-```
+While only changed data is updated it is still a relatively expensive function. Prefer to use the other "update" functions where possible.
 
-The number of quilt patches in each dimension.
+### .setSceneAsync
 
-### .viewCone
 ```js
-viewCone = 35 * DEG2RAD : Number
+setSceneAsync(
+	scene : Scene,
+	camera : Camera,
+	options = {
+		onProgress = null : value => void,
+	} : Object
+) : void
 ```
 
-The total angle sweep for the camera views rendered across the quilt.
+Asynchronous version of `setScene`. Requires calling `setBVHWorker` first.
 
-### .viewFoV
+### .updateCamera
 
 ```js
-viewFoV = 14 * DEG2RAD : Number
+updateCamera() : void
 ```
 
-The camera field of view to render.
+Updates the camera parameters. Must be called if any of the parameters on the previously set camera change.
 
-### .displayDistance
+### .updateMaterials
 
 ```js
-displayDistance = 1 : Number
+updateMaterials() : void
 ```
 
-The distance of the viewer to the display.
+Updates the material properties. Must be called when properties change for any materials already being used.
 
-### .displayAspect
+Note that materials used with WebGLPathTracer support the following additional properties:
 
 ```js
-displayAspect = 0.75 : Number
-```
+// Whether to render the object as completely transparent against the rest
+// of the environment so other objects can be composited later
+matte = false : Boolean;
 
-The aspect ratio of the display.
+// Whether the object should cast a shadow
+castShadow = true : Boolean;
+```
 
-### .setFromDisplayView
+### .updateEnvironment
 
 ```js
-setFromDisplayView(
-	displayDistance : Number,
-	displayWidth : Number,
-	displayHeight : Number,
-) : void
+updateEnvironment() : void
 ```
 
-Updates the `displayDistance`, `displayAspect`, and the `viewFoV` from viewer and display information.
-
-## PathTracingSceneGenerator
+Updates lighting from the scene environment and background properties. Must be called if any associated scene settings change on the set scene object.
 
-Utility class for generating the set of data required for initializing the path tracing material with a bvh, geometry, materials, and textures.
-
-### .generate
+### .updateLights
 
 ```js
-generate( scene : Object3D | Array<Object3D>, options = {} : Object ) : {
-	bvh : MeshBVH,
-	materials : Array<Material>,
-	textures : Array<Texture>,
-	lights : Array<Light>
-}
+updateLights() : void
 ```
 
-Merges the geometry in the given scene with an additional "materialIndex" attribute that references the associated material array. Also produces a set of textures referenced by the scene materials.
+Updates lights used in path tracing. Must be called if any lights are added or removed or properties change.
 
-## PathTracingSceneWorker
+### .renderSample
 
-_extends PathTracingSceneGenerator_
+```js
+renderSample() : void
+```
 
-See note in [Asyncronous Generation](#asynchronous-generation) use snippet.
+Render a single sample to the path tracer target. If `renderToCanvas` is true then the image is rendered to the canvas.
 
-### .generate
+### .reset
 
 ```js
-async generate( scene : Object3D | Array<Object3D>, options = {} : Object ) : {
-	bvh : MeshBVH,
-	materials : Array<Material>,
-	textures : Array<Texture>,
-	lights : Array<Light>
-}
+reset() : void
 ```
 
+Restart the rendering.
+
 ### .dispose
 
 ```js
 dispose() : void
 ```
 
+Dispose the path tracer assets. Any materials or textures used must be disposed separately.
+
 ## PhysicalCamera
 
 _extends THREE.PerspectiveCamera_
@@ -487,10 +408,10 @@ radius = 0 : Number
 
 The radius of the spotlight surface. Increase this value to add softness to shadows.
 
-### .iesTexture
+### .iesMap
 
 ```js
-iesTexture = null : Texture
+iesMap = null : Texture
 ```
 
 The loaded IES texture describing directional light intensity. These can be loaded with the `IESLoader`.
@@ -509,42 +430,6 @@ isCircular = false : Boolean
 
 Whether the area light should be rendered as a circle or a rectangle.
 
-## DynamicPathTracingSceneGenerator
-
-A variation of the path tracing scene generator intended for quickly regenerating a scene BVH representation that updates frequently. Ie those with animated objects or animated skinned geometry.
-
-In order to quickly update a dynamic scene the same BVH is reused across updates by refitting rather than regenerating. This is significantly faster but also results in a less optimal BVH after significant changes.
-
-If geometry or materials are added or removed from the scene then `reset` must be called.
-
-### constructor
-
-```js
-constructor( scene : Object3D | Array<Object3D> )
-```
-
-Takes the scene to convert.
-
-### .generate
-
-```js
-generate() : {
-	bvh : MeshBVH,
-	materials : Array<Material>,
-	textures : Array<Texture>
-}
-```
-
-Generates and refits the bvh to the current scene state. The same bvh, materials, and textures objects are returns after the initial call until `reset` is called.
-
-### .reset
-
-```js
-reset() : void
-```
-
-Resets the generator so a new BVH is generated. This must be called when geometry, objects, or materials are added or removed from the scene.
-
 ## IESLoader
 
 _extends Loader_
@@ -623,74 +508,6 @@ setDefine( name : string, value = undefined : any ) : void
 
 Sets the define of the given name to the provided value. If the value is set to null or undefined then it is deleted from the defines of the material. If the define changed from the previous value then `Material.needsUpdate` is set to `true`.
 
-## PhysicalPathTracingMaterial
-
-_extends MaterialBase_
-
-**Uniforms**
-
-```js
-{
-	// The number of ray bounces to test. Higher is better quality but slower performance.
-	// TransmissiveBounces indicates the number of additional transparent or translucent surfaces
-	// the ray can pass through.
-	bounces = 3 : Number,
-	transmissiveBounces = 10 : Number,
-
-	// The number of additional transmissive ray bounces to allow on top of existing bounces for object opacity / transmission.
-	transmissiveBounces = 5 : Number,
-
-	// The physical camera parameters to use
-	physicalCamera : PhysicalCameraUniform,
-
-	// Geometry and BVH information
-	bvh: MeshBVHUniformStruct,
-	attributesArray: AttributesTextureArray,
-	materialIndexAttribute: UIntVertexAttributeTexture,
-	materials: MaterialsTexture,
-	textures: RenderTarget2DArray,
-
-	// Light information
-	lights: LightsInfoUniformStruct,
-	iesProfiles: IESProfilesTexture,
-
-	// Environment Map information
-	envMapInfo: EquirectHdrInfoUniform,
-	environmentRotation: Matrix4,
-	environmentIntensity = 1: Number,
-
-	// background blur
-	backgroundBlur = 0: Number,
-
-	// Factor for alleviating bright pixels from rays that hit diffuse surfaces then
-	// specular surfaces. Setting this higher alleviates fireflies but will remove some
-	// specular caustics.
-	filterGlossyFactor = 0: Number,
-
-	// The equirectangular map to render as the background.
-	backgroundMap = null: Texture,
-
-	// The transparency to render the background with. Note that the "alpha" option
-	// must be set to true on PathTracingRenderer for this field to work properly.
-	backgroundAlpha: 1.0,
-}
-```
-
-**Defines**
-
-```js
-{
-
-	// Whether to use multiple importance sampling to help the image converge more quickly.
-	FEATURE_MIS = 1 : Number,
-
-	// Whether to use russian roulette path termination. Path termination will kick in after
-	// a minimum three bounces have been performed.
-	FEATURE_RUSSIAN_ROULETTE = 1 : Number,
-
-}
-```
-
 ## FogVolumeMaterial
 
 _extends MeshStandardMaterial_
@@ -726,161 +543,7 @@ Denoise material based on [BrutPitt/glslSmartDeNoise](https://github.com/BrutPit
 
 }
 ```
-
-## RenderTarget2DArray
-
-_extends WebGLArrayRenderTarget_
-
-A convenience extension from `WebGLArrayRenderTarget` that affords easily creating a uniform texture array from an array of textures.
-
-### .setTextures
-
-```js
-setTextures(
-	renderer : WebGLRenderer,
-	width : Number,
-	height : Number,
-	textures : Array<Texture>
-) : void
-```
-
-Takes the rendering context to update the target for, the target dimensions of the texture array, and the array of textures to render into the 2D texture array. Every texture is stretched to the dimensions of the texture array at the same index they are provided in.
-
-## PhysicalCameraUniform
-
-Uniform for storing the camera parameters for use with the shader.
-
-### .updateFrom
-
-```js
-updateFrom( camera : PerspectiveCamera | PhysicalCamera ) : void
-```
-
-Copies all fields from the passed PhysicalCamera if available otherwise the defaults are used.
-
-## AttributesTextureArray
-
-A combined texture array used to store normal, tangent, uv, and color attributes in the same texture sampler array rather than separate samplers. Necessary to save texture slots.
-
-Normals, tangents, uvs, and color attribute data are stored in the 1st, 2nd, 3rd, and 4th layers of the array respectively.
-
-### .updateNormalAttribute
-
-```js
-updateNormalAttribute( attr : BufferAttribute ) : void
-```
-
-### .updateTangentAttribute
-
-```js
-updateTangentAttribute( attr : BufferAttribute ) : void
-```
-
-### .updateUvAttribute
-
-```js
-updateUvAttribute( attr : BufferAttribute ) : void
-```
-
-### .updateColorAttribute
-
-```js
-updateColorAttribute( attr : BufferAttribute ) : void
-```
-
-### .updateFrom
-
-```js
-updateFrom(
-	normal : BufferAttribute,
-	tangent : BufferAttribute,
-	uv : BufferAttribute,
-	color : BufferAttribute
-) : void
-```
-
-## MaterialsTexture
-
-_extends DataTexture_
-
-Helper texture uniform for encoding materials as texture data.
-
-### .threeCompatibilityTransforms
-
-```js
-threeCompatibilityTransforms = false : Boolean
-```
-
-Three.js materials support only a single set of UV transforms in a certain fallback priority while the pathtracer supports a unique set of transforms per texture. Set this field to true in order to use the same uv transform handling as three.js materials.
-
-See fallback order documentation [here](https://threejs.org/docs/#api/en/textures/Texture.offset).
-
-### .setMatte
-
-```js
-setMatte( index : Number, matte : Boolean ) : void
-```
-
-Sets whether or not the material of the given index is matte or not. When "true" the background is rendered in place of the material.
-
-### .setCastShadow
-
-```js
-setCastShadow( index : Number, enabled : Boolean ) : void
-```
-
-Sets whether or not the material of the given index will cast shadows. When "false" materials will not cast shadows on diffuse surfaces but will still be reflected. This is a good setting for lighting enclosed interiors with environment lighting.
-
-### .updateFrom
-
-```js
-updateFrom( materials : Array<Material>, textures : Array<Texture> ) : void
-```
-
-Updates the size and values of the texture to align with the provided set of materials and textures.
-
-The "matte" and "side" values must be updated explicitly.
-
-> **Note**
-> In order for volume transmission to work the "attenuationDistance" must be set to a value less than Infinity or "thickness" must be set to a value greater than 0.
-
-## LightsInfoUniformStruct
-
-Helper uniform for encoding lights as texture data with count.
-
-### .updateFrom
-
-```js
-updateFrom( lights : Array<Light>, iesTextures = [] : Array<Texture> ) : void
-```
-
-Updates the size and values of the texture to align with the provided set of lights and IES textures.
-
-## EquirectHdrInfoUniform
-
-Stores the environment map contents along with the intensity distribution information to support multiple importance sampling.
-
-### .updateFrom
-
-```js
-updateFrom( environmentMap : Texture ) : void
-```
-
-Takes an environment map to process into something usable by the path tracer. Is expected to be a DataTexture so the data can be read.
-
-## Functions
-
-### mergeMeshes
-
-```js
-mergeMeshes( meshes : Array<Mesh> ) : {
-	materials : Array<Material>,
-	textures : Array<Textures>,
-	geometry : BufferGeometry
-}
-```
-
-Merges the set of meshes into a single geometry with a `materialIndex` vertex attribute included on the geometry identifying the associated material in the returned `materials` array.
+<!--
 
 ## CompatibilityDetector
 
@@ -905,23 +568,7 @@ detect() : {
 
 Returns `pass === true` if the path tracer can run. If it cannot run then a message is returned indicating why.
 
-## Shader Chunks
-
-**shaderMaterialSampling**
-
-Set of functions for performing material scatter and PDF sampling. See the [implementation](https://github.com/gkjohnson/three-gpu-pathtracer/blob/main/src/shader/shaderMaterialSampling.js) for full list of functions.
-
-**shaderLightSampling**
-
-Set of functions for performing light sampling. See the [implementation](https://github.com/gkjohnson/three-gpu-pathtracer/blob/main/src/shader/shaderLightSampling.js) for full list of functions.
-
-**shaderStructs**
-
-Material and light struct definition for use with uniforms. See the [implementation](https://github.com/gkjohnson/three-gpu-pathtracer/blob/main/src/shader/shaderStructs.js) for full list of functions.
-
-**shaderUtils**
-
-Set of randomness and other light transport utilities for use in a shader. See the [implementation](https://github.com/gkjohnson/three-gpu-pathtracer/blob/main/src/shader/shaderUtils.js) for full list of functions.
+-->
 
 # Gotchas