three-gpu-pathtracer 0.0.3 → 0.0.6

package/README.md

@@ -31,16 +31,35 @@ _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)
+
+[Spot Light Support](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/spotLights.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)
 
+
+## 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).
+
+In order to install dependencies, you will need `make` and a C++ compiler available.
+
+On Debian or Ubuntu, run `sudo apt install build-essential`.  It should just work on MacOS.
+
+- To install dependencies, run `npm install`
+- To start the demos run `npm start`
+- Visit `http://localhost:1234/<demo-name.html>`
+
 # Use
 
 **Basic Renderer**
@@ -56,6 +75,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 );
@@ -69,7 +91,7 @@ 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,
 } ) );
@@ -79,7 +101,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 +114,9 @@ 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().loadAsync( envMapUrl );
 ptRenderer.material.envMapInfo.updateFrom( texture );
@@ -108,11 +133,12 @@ function animate() {
 	camera.updateMatrixWorld();
 	ptRenderer.update();
 
-	// copy the current state of the path tracer to canvas to display
-	renderer.autoClear = false;
+	// 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 );
-	renderer.autoClear = true;
 
 }
 ```
@@ -160,7 +186,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 );
 
 // ...
 ```
@@ -264,10 +290,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>
 }
 ```
 
@@ -282,10 +309,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>
 }
 ```
 
@@ -349,6 +377,46 @@ 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.
+
+## PhysicalSpotLight
+
+_extends THREE.SpotLight_
+
+### .radius
+
+```js
+radius = 0 : Number
+```
+
+The radius of the spotlight surface. Increase this value to add softness to shadows.
+
+### .iesTexture
+
+```js
+iesTexture = null : Texture
+```
+
+The loaded IES texture describing directional light intensity. These can be loaded with the `IESLoader`.
+
+Premade IES profiles can be downloaded from [ieslibrary.com]. And custom profiles can be generated using [CNDL](https://cndl.io/).
+
+## ShapedAreaLight
+
+_extends THREE.RectAreaLight_
+
+### .isCircular
+
+```js
+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.
@@ -360,7 +428,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.
@@ -385,6 +453,12 @@ 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_
+
+Loader for loading and parsing IES profile data. Load and parse functions return a `DataTexture` with the profile contents.
+
 ## BlurredEnvMapGenerator
 
 Utility for generating a PMREM blurred environment map that can be used with the path tracer.
@@ -448,6 +522,10 @@ _extends MaterialBase_
 	materials: MaterialsTexture,
 	textures: RenderTarget2DArray,
 
+	// Light information
+	lights: LightsInfoUniformStruct,
+	iesProfiles: IESProfilesTexture,
+
 	// Environment Map information
 	envMapInfo: EquirectHdrInfoUniform,
 	environmentRotation: Matrix3,
@@ -485,7 +563,6 @@ _extends MaterialBase_
 	// The number of transparent pixels to allow on top of existing bounces for object transparency.
 	TRANSPARENT_TRAVERSALS = 5 : Number,
 
-
 }
 ```
 
@@ -526,6 +603,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
@@ -542,6 +629,14 @@ 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
@@ -552,6 +647,18 @@ 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.
 
+## 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.
@@ -584,19 +691,23 @@ 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
 
 - The project requires use of WebGL2.
 - All textures must use the same wrap and interpolation flags.
-- Texture repeat, rotation, and center properties are not supported.
+- Spotlights are not supported in non-MIS rendering currently.
 
 # Screenshots
 
@@ -649,6 +760,16 @@ Set of randomness and other light transmport utilities for use in a shader. See
 ">AzTiZ</a></i>
 </p>
 
+![](https://user-images.githubusercontent.com/734200/173212652-de6a83e5-dd2c-49b5-8ed7-484ff8969b5b.png)
+<p align="center">
+<i>Botanists Study model by <a href="https://sketchfab.com/3d-models/the-botanists-study-8b7b5743b1c848ed8ea58f5518c44e7e">riikkakilpelainen</a></i>
+</p>
+
+![](https://user-images.githubusercontent.com/734200/173170459-849b9343-efe3-4635-8719-346511472965.png)
+<p align="center">
+<i>Japanese Bridge Garden model by <a href="https://sketchfab.com/3d-models/japanese-bridge-garden-d122e17593eb4012913cde927486d15a">kristenlee</a></i>
+</p>
+
 ### Resources
 
 [Raytracing in One Weekend Book](https://raytracing.github.io/)