three-gpu-pathtracer 0.0.1 → 0.0.2

package/README.md

@@ -1,29 +1,50 @@
 # three-gpu-pathtracer
 
+[![npm version](https://img.shields.io/npm/v/three-gpu-pathtracer.svg?style=flat-square)](https://www.npmjs.com/package/three-gpu-pathtracer)
 [![lgtm code quality](https://img.shields.io/lgtm/grade/javascript/g/gkjohnson/three-gpu-pathtracer.svg?style=flat-square&label=code-quality)](https://lgtm.com/projects/g/gkjohnson/three-gpu-pathtracer/)
 [![build](https://img.shields.io/github/workflow/status/gkjohnson/three-gpu-pathtracer/Node.js%20CI?style=flat-square&label=build)](https://github.com/gkjohnson/three-gpu-pathtracer/actions)
+[![github](https://flat.badgen.net/badge/icon/github?icon=github&label)](https://github.com/gkjohnson/three-gpu-pathtracer/)
+[![twitter](https://flat.badgen.net/twitter/follow/garrettkjohnson)](https://twitter.com/garrettkjohnson)
+[![sponsors](https://img.shields.io/github/sponsors/gkjohnson?style=flat-square&color=1da1f2)](https://github.com/sponsors/gkjohnson/)
 
 ![](https://user-images.githubusercontent.com/734200/162287477-96696b18-890b-4c1b-8a73-d662e577cc48.png)
 
-Path tracing project using [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh) to accelerate high quality, physically based rendering on the GPU. Features include support for GGX surface model, material information, textures, normal maps, emission, environment maps, tiled rendering, and more!
+Path tracing project using [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh) and WebGL 2 to accelerate high quality, physically based rendering on the GPU. Features include support for GGX surface model, material information, textures, normal maps, emission, environment maps, tiled rendering, and more!
 
 _More features and capabilities in progress!_
 
 # Examples
 
-[PBR demo here](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/index.html)!
+**Beauty Demos**
 
-[Lego demo here](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/lego.html)!
+[Physically Based Materials](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/index.html)
 
-[Material demo here](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/materialBall.html)!
+[Lego Models](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/lego.html)
 
-[Transmission preset demo here](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/materialBall.html#transmission)!
+[Interior Scene](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/interior.html)
 
-[Ambient Occlusion Material demo here](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/aoRender.html)!
+[Depth of Field](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/depthOfField.html)
+
+**Features**
+
+[Skinned Geometry Support](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/skinnedMesh.html)
+
+[Morph Target Support](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/skinnedMesh.html#morphtarget)
+
+**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)
+
+**Light Baking**
+
+[Ambient Occlusion Material](https://gkjohnson.github.io/three-gpu-pathtracer/example/bundle/aoRender.html)
 
 # Use
 
 ```js
+import * as THREE from 'three';
 import { FullScreenQuad } from 'three/examples/jsm/postprocessing/Pass.js';
 import {
 	PathTracingSceneGenerator,
@@ -46,7 +67,7 @@ const fsQuad = new FullScreenQuad( new THREE.MeshBasicMaterial( {
 
 // initialize the scene and update the material properties with the bvh, materials, etc
 const generator = new PathTracingSceneGenerator();
-const { bvh, textures, materials } = await generator.generate( scene );
+const { bvh, textures, materials } = generator.generate( scene );
 
 // update bvh and geometry attribute textures
 ptMaterial.bvh.updateFrom( bvh );
@@ -63,8 +84,6 @@ ptMaterial.setDefine( 'MATERIAL_LENGTH', materials.length );
 // set the environment map
 const texture = await new RGBELoader().loadAsync( envMapUrl );
 const pmremGenerator = new THREE.PMREMGenerator( renderer );
-pmremGenerator.compileCubemapShader();
-
 const envMap = pmremGenerator.fromEquirectangular( texture );
 ptRenderer.material.environmentMap = envMap.texture;
 
@@ -89,6 +108,37 @@ function animate() {
 }
 ```
 
+## Dynamic Scenes
+
+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.
+
+```js
+import { DynamicPathTracingSceneGenerator } from 'three-gpu-pathtracer';
+
+// ... initialize scene etc
+
+const generator = new DynamicPathTracingSceneGenerator( scene );
+const { bvh, textures, materials } = generator.generate( scene );
+
+// ... update path tracer and render
+```
+
+## Asynchronous Scene Generation
+
+_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._
+
+```js
+import { PathTracingSceneWorker } from 'three-gpu-pathtracer/src/workers/PathTracingSceneWorker.js';
+
+// ...
+
+// 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 );
+
+// ...
+```
+
 # Exports
 
 ## PathTracingRenderer
@@ -180,7 +230,7 @@ Utility class for generating the set of data required for initializing the path
 ### .generate
 
 ```js
-async generate( scene : Object3D ) : {
+generate( scene : Object3D, options = {} : Object ) : {
 	bvh : MeshBVH,
 	materials : Array<Material>,
 	textures : Array<Texture>
@@ -189,6 +239,118 @@ async generate( scene : Object3D ) : {
 
 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.
 
+## PathTracingSceneWorker
+
+_extends PathTracingSceneGenerator_
+
+See note in [Asyncronous Generation](#asynchronous-generation) use snippet.
+
+### .generate
+
+```js
+async generate( scene : Object3D, options = {} : Object ) : {
+	bvh : MeshBVH,
+	materials : Array<Material>,
+	textures : Array<Texture>
+}
+```
+
+### .dispose
+
+```js
+dispose() : void
+```
+
+## PhysicalCamera
+
+_extends THREE.PerspectiveCamera_
+
+An extension of the three.js PerspectiveCamera with some other parameters associated with depth of field. These parameters otherwise do not affect the camera behavior are are for convenience of use with the PhysicalCameraUniform and pathtracer.
+
+### .focusDistance
+
+```js
+focusDistance = 25 : Number
+```
+
+The distance from the camera in meters that everything is is perfect focus.
+
+### .fStop
+
+```js
+fStop = 1.4 : Number
+```
+
+The fstop value of the camera. If this is changed then the `bokehSize` field is implicitly updated.
+
+### .bokehSize
+
+```js
+bokehSize : Number
+```
+
+The bokeh size as derived from the fStop and focal length in millimeters. If this is set then the fStop is implicitly updated.
+
+### .apertureBlades
+
+```js
+apertureBlades = 0 : Number
+```
+
+The number of sides / blades on the aperture.
+
+### .apertureRotation
+
+```js
+apertureRotation = 0 : Number
+```
+
+The rotation of the aperture shape in radians.
+
+### .anamorphicRatio
+
+```js
+anamorphicRatio = 1 : Number
+```
+
+The anamorphic ratio of the lens. A higher value will stretch the bokeh effect horizontally.
+
+## 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 )
+```
+
+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.
+
 ## MaterialBase
 
 _extends THREE.ShaderMaterial_
@@ -211,6 +373,12 @@ _extends MaterialBase_
 
 ```js
 {
+	// The number of ray bounces to test. Higher is better quality but slower performance.
+	bounces = 3 : Number,
+	
+	// The physical camera parameters to use
+	physicalCamera : PhysicalCameraUniform,
+	
 	// Geometry and BVH information,
 	bvh: MeshBVHUniformStruct,
 	normalAttribute: FloatVertexAttributeTexture,
@@ -225,13 +393,13 @@ _extends MaterialBase_
 	environmentRotaton: Matrix3,
 
 	// Environment Map information,
-	environmentBlur: Number,
-	environmentIntensity: Number,
+	environmentBlur = 0: Number,
+	environmentIntensity = 1: 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: Number,
+	filterGlossyFactor = 0: Number,
 
 	// The colors to use for the gradient env lighting when no environment map is provided.
 	gradientTop: Color,
@@ -247,8 +415,8 @@ _extends MaterialBase_
 
 ```js
 {
-	// The number of ray bounces to test. Higher is better quality but slower performance.
-	BOUNCES = 3 : Number,
+	// Whether the shader should include logic for physical camera and depth of field
+	DOF_SUPPORT = 1 : Number,
 
 	// The number of transparent pixels to allow on top of existing bounces for object transparency.
 	TRANSPARENT_TRAVERSALS = 5 : Number,
@@ -259,7 +427,6 @@ _extends MaterialBase_
 	// The number of materials provided in the "materials" uniform.
 	MATERIAL_LENGTH : Number,
 
-
 }
 ```
 
@@ -282,6 +449,18 @@ setTextures(
 
 Takes the rendering context to updateh 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.
+
 ## MaterialStructArrayUniform
 
 _extends Array_
@@ -300,6 +479,20 @@ Updates the value of the uniform to align with the provided set of materials and
 
 Struct definiton for representing material information as a uniform. See the [implementation](https://github.com/gkjohnson/three-gpu-pathtracer/blob/main/src/shader/shaderStructs.js) for full struct definition information.
 
+### .side
+
+```js
+side = 0 : Number
+```
+
+This is the only field that needs to be set explicitly and is not derived from the Material setting. It defaults to rendering double sided triangles since transmissive volumes require solid, double sided geometry. The possible options are as follows:
+
+```js
+ 0   // Double Sided
+ 1   // Front Sided
+-1   // Back Sided
+```
+
 ### .updateFrom
 
 ```js
@@ -336,12 +529,28 @@ Material struct definition for use with uniforms. See the [implementation](https
 
 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.
 
-# Caveats
+# 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.
 
 # Screenshots
 
+![](https://user-images.githubusercontent.com/734200/162584469-68e6df38-92da-4a13-b352-ca0bdea14548.png)
+
+<p align="center">
+<i>Sample materials</i>
+</p>
+
+![](https://user-images.githubusercontent.com/734200/163835927-be75d2c0-f27b-4e4b-a3eb-2371043fa5e1.png)
+
+![](https://user-images.githubusercontent.com/734200/163839431-ed75e64d-9ae4-4423-afca-55162a44873e.png)
+
+<p align="center">
+<i>"SD Macross City Standoff Diorama" scene by <a href="https://sketchfab.com/3d-models/sd-macross-city-standoff-diorama-b154220f7e7441799d6be2f7ff9658c7">tipatat</a></i>
+</p>
+
 ![](./docs/interior-scene-cropped.png)
 
 <p align="center">
@@ -350,8 +559,10 @@ Set of randomness and other light transmport utilities for use in a shader. See
 
 ![](https://user-images.githubusercontent.com/734200/161820794-df0da371-ee5c-4368-9e7b-5e7daf6cf3c7.png)
 
+![](https://user-images.githubusercontent.com/734200/162550315-3cdabf40-3dea-4d7d-bcfc-eb543eea2d93.png)
+
 <p align="center">
-<i>Perseverance Rover model by <a href="https://mars.nasa.gov/resources/25042/mars-perseverance-rover-3d-model/">NASA / JPL-Caltech</a></i>
+<i>Perseverance Rover, Ingenuity Helicopter models by <a href="https://mars.nasa.gov/resources/25042/mars-perseverance-rover-3d-model/">NASA / JPL-Caltech</a></i>
 </p>
 
 ![](https://user-images.githubusercontent.com/734200/161877900-566652e4-c799-4940-bccb-0c8f4cea5387.png)