three-gpu-pathtracer 0.0.2 → 0.0.3

package/README.md

@@ -43,6 +43,8 @@ _More features and capabilities in progress!_
 
 # Use
 
+**Basic Renderer**
+
 ```js
 import * as THREE from 'three';
 import { FullScreenQuad } from 'three/examples/jsm/postprocessing/Pass.js';
@@ -57,14 +59,24 @@ import {
 // 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 } = generator.generate( scene );
@@ -79,13 +91,10 @@ ptMaterial.uvAttribute.updateFrom( geometry.attributes.uv );
 ptMaterial.materialIndexAttribute.updateFrom( geometry.attributes.materialIndex );
 ptMaterial.textures.setTextures( renderer, 2048, 2048, textures );
 ptMaterial.materials.updateFrom( materials, textures );
-ptMaterial.setDefine( 'MATERIAL_LENGTH', materials.length );
 
 // set the environment map
 const texture = await new RGBELoader().loadAsync( envMapUrl );
-const pmremGenerator = new THREE.PMREMGenerator( renderer );
-const envMap = pmremGenerator.fromEquirectangular( texture );
-ptRenderer.material.environmentMap = envMap.texture;
+ptRenderer.material.envMapInfo.updateFrom( texture );
 
 animate();
 
@@ -108,6 +117,23 @@ function animate() {
 }
 ```
 
+**Blurred Environment Map**
+
+Using a pre blurred envioronment map can help improve frame convergence time at the cost of sharp environment reflections. If performance is concern then multiple importance sampling can be disabled and blurred environment map used.
+
+```js
+import { BlurredEnvMapGenerator } from 'three-gpu-pathtracer';
+
+// ...
+
+const envMap = await new RGBELoader().loadAsync( envMapUrl );
+const generator = new BlurredEnvMapGenerator( renderer );
+const blurredEnvMap = generator.generate( envMap, 0.35 );
+
+// render!
+
+```
+
 ## 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.
@@ -188,11 +214,19 @@ Number of tiles on x and y to render to. Can be used to improve the responsivene
 ### .stableNoise
 
 ```js
-stableNoise = false
+stableNoise = false : 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.
 
+### .alpha
+
+```js
+alpha = false : 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.
+
 ### constructor
 
 ```js
@@ -351,6 +385,32 @@ 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.
 
+## BlurredEnvMapGenerator
+
+Utility for generating a PMREM blurred environment map that can be used with the path tracer.
+
+### constructor
+
+```js
+constructor( renderer : WebGLRenderer )
+```
+
+### .generate
+
+```js
+generate( texture : Texture, blur : Number ) : DataTexture
+```
+
+Takes a texture to blur and the amount to blur it. Returns a new `DataTexture` that has been PMREM blurred environment map that can have distribution data generated for importance sampling.
+
+### .dispose
+
+```js
+dispose() : void
+```
+
+Disposes of the temporary files and textures for generation.
+
 ## MaterialBase
 
 _extends THREE.ShaderMaterial_
@@ -375,39 +435,39 @@ _extends MaterialBase_
 {
 	// 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,
+
+	// Geometry and BVH information
 	bvh: MeshBVHUniformStruct,
 	normalAttribute: FloatVertexAttributeTexture,
 	tangentAttribute: FloatVertexAttributeTexture,
 	uvAttribute: FloatVertexAttributeTexture,
 	materialIndexAttribute: UIntVertexAttributeTexture,
-	materials: MaterialStructArrayUniform,
+	materials: MaterialsTexture,
 	textures: RenderTarget2DArray,
 
-	// PMREM-processed Environment Map,
-	environmentMap: Texture,
-	environmentRotaton: Matrix3,
-
-	// Environment Map information,
-	environmentBlur = 0: Number,
+	// Environment Map information
+	envMapInfo: EquirectHdrInfoUniform,
+	environmentRotation: Matrix3,
 	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 colors to use for the gradient env lighting when no environment map is provided.
-	gradientTop: Color,
-	gradientBottom: Color,
-
 	// The colors to use for the gradient background when enabled.
 	bgGradientTop: Color,
 	bgGradientBottom: Color,
+
+	// 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,
 }
 ```
 
@@ -415,17 +475,16 @@ _extends MaterialBase_
 
 ```js
 {
-	// Whether the shader should include logic for physical camera and depth of field
-	DOF_SUPPORT = 1 : Number,
+
+	// Whether to use multiple importance sampling to help the image converge more quickly
+	FEATURE_MIS = 1 : Number,
+
+	// Whether to use the "bg" gradient fields to sample for the background
+	FEATURE_GRADIENT_BG = 0 : Number
 
 	// The number of transparent pixels to allow on top of existing bounces for object transparency.
 	TRANSPARENT_TRAVERSALS = 5 : Number,
 
-	// Whether to use the "bg" gradient fields to sample for the backround
-	GRADIENT_BG = 0 : Number
-
-	// The number of materials provided in the "materials" uniform.
-	MATERIAL_LENGTH : Number,
 
 }
 ```
@@ -461,45 +520,49 @@ updateFrom( camera : PerspectiveCamera | PhysicalCamera ) : void
 
 Copies all fields from the passed PhysicalCamera if available otherwise the defaults are used.
 
-## MaterialStructArrayUniform
+## MaterialsTexture
 
-_extends Array_
+_extends DataTexture_
 
-Array of `MaterialStructUniform` definitions for use as a Shader uniform.
+Helper texture uniform for encoding materials as texture data.
 
-### .updateFrom
+### .setSide
 
 ```js
-updateFrom( materials : Array<Material>, textures : Array<Texture> ) : void
+setSide( index : Number, side : FrontSide | BackSide | DoubleSide ) : void
 ```
 
-Updates the value of the uniform to align with the provided set of materials and textures.
-
-## MaterialStructUniform
-
-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.
+Sets the side to render for the given material.
 
-### .side
+### .setMatte
 
 ```js
-side = 0 : Number
+setMatte( index : Number, matte : Boolean ) : void
 ```
 
-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:
+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.
+
+### .updateFrom
 
 ```js
- 0   // Double Sided
- 1   // Front Sided
--1   // Back Sided
+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.
+
+## EquirectHdrInfoUniform
+
+Stores the environment map contents along with the intensity distribution information to support multiple importance sampling.
+
 ### .updateFrom
 
 ```js
-updateFrame( material : Material, textures : Array<Texture> ) : void
+updateFrom( environmentMap : Texture ) : void
 ```
 
-Updates the uniform with the information from the passed material. Texture fields are set to the index of the texture in the provided textures array.
+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