three-gpu-pathtracer 0.0.4 → 0.0.5

package/README.md

@@ -31,12 +31,16 @@ _More features and capabilities in progress!_
 
 [Morph Target Support](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/skinnedMesh.html#morphtarget)
 
+[Area Light Support](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/areaLight.html)
+
 **Test Scenes**
 
 [Material Test Orb](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/materialBall.html)
 
 [Transmission Preset Orb](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/materialBall.html#transmission)
 
+[Model Viewer Fidelity Scene Comparisons](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/viewerTest.html#khronos-DragonAttenuation)
+
 **Light Baking**
 
 [Ambient Occlusion Material](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/aoRender.html)
@@ -56,6 +60,9 @@ import {
 
 // init scene, renderer, camera, controls, etc
 
+renderer.outputEncoding = THREE.sRGBEncoding;
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+
 // initialize the path tracing material and renderer
 const ptMaterial = new PhysicalPathTracingMaterial();
 const ptRenderer = new PathTracingRenderer( renderer );
@@ -79,7 +86,7 @@ scene.updateMatrixWorld();
 
 // initialize the scene and update the material properties with the bvh, materials, etc
 const generator = new PathTracingSceneGenerator();
-const { bvh, textures, materials } = generator.generate( scene );
+const { bvh, textures, materials, lights } = generator.generate( scene );
 
 // update bvh and geometry attribute textures
 ptMaterial.bvh.updateFrom( bvh );
@@ -92,6 +99,10 @@ 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 );
+ptMaterial.lightCount = lights.length;
+
 // set the environment map
 const texture = await new RGBELoader().loadAsync( envMapUrl );
 ptRenderer.material.envMapInfo.updateFrom( texture );
@@ -161,7 +172,7 @@ import { PathTracingSceneWorker } from 'three-gpu-pathtracer/src/workers/PathTra
 
 // initialize the scene and update the material properties with the bvh, materials, etc
 const generator = new PathTracingSceneWorker();
-const { bvh, textures, materials } = await generator.generate( scene );
+const { bvh, textures, materials, lights } = await generator.generate( scene );
 
 // ...
 ```
@@ -265,10 +276,11 @@ Utility class for generating the set of data required for initializing the path
 ### .generate
 
 ```js
-generate( scene : Object3D, options = {} : Object ) : {
+generate( scene : Object3D | Array<Object3D>, options = {} : Object ) : {
 	bvh : MeshBVH,
 	materials : Array<Material>,
-	textures : Array<Texture>
+	textures : Array<Texture>,
+	lights : Array<Light>
 }
 ```
 
@@ -283,10 +295,11 @@ See note in [Asyncronous Generation](#asynchronous-generation) use snippet.
 ### .generate
 
 ```js
-async generate( scene : Object3D, options = {} : Object ) : {
+async generate( scene : Object3D | Array<Object3D>, options = {} : Object ) : {
 	bvh : MeshBVH,
 	materials : Array<Material>,
-	textures : Array<Texture>
+	textures : Array<Texture>,
+	lights : Array<Light>
 }
 ```
 
@@ -350,6 +363,12 @@ anamorphicRatio = 1 : Number
 
 The anamorphic ratio of the lens. A higher value will stretch the bokeh effect horizontally.
 
+## EquirectCamera
+
+_extends THREE.Camera_
+
+A class indicating that the path tracer should render an equirectangular view. Does not work with three.js raster rendering.
+
 ## 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.
@@ -361,7 +380,7 @@ If geometry or materials are added or removed from the scene then `reset` must b
 ### constructor
 
 ```js
-constructor( scene : Object3D )
+constructor( scene : Object3D | Array<Object3D> )
 ```
 
 Takes the scene to convert.
@@ -449,6 +468,10 @@ _extends MaterialBase_
 	materials: MaterialsTexture,
 	textures: RenderTarget2DArray,
 
+	// Light information
+	lights: LightsTexture,
+	lightCount = 0: Number,
+
 	// Environment Map information
 	envMapInfo: EquirectHdrInfoUniform,
 	environmentRotation: Matrix3,
@@ -486,7 +509,6 @@ _extends MaterialBase_
 	// The number of transparent pixels to allow on top of existing bounces for object transparency.
 	TRANSPARENT_TRAVERSALS = 5 : Number,
 
-
 }
 ```
 
@@ -527,6 +549,16 @@ _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).
+
 ### .setSide
 
 ```js
@@ -561,6 +593,20 @@ Updates the size and values of the texture to align with the provided set of mat
 
 The "matte" and "side" values must be updated explicitly.
 
+## LightsTexture
+
+_extends DataTexture_
+
+Helper texture uniform for encoding lights as texture data.
+
+### .updateFrom
+
+```js
+updateFrom( lights : Array<Light> ) : void
+```
+
+Updates the size and values of the texture to align with the provided set of lights.
+
 ## EquirectHdrInfoUniform
 
 Stores the environment map contents along with the intensity distribution information to support multiple importance sampling.
@@ -593,13 +639,17 @@ Merges the set of meshes into a single geometry with a `materialIndex` vertex at
 
 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 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.
+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 transmport 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.
+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