WebXR: Add docs page for XREstimatedLight (#27041)

* Add docs page for XREstimatedLight * Fix link in list json and copy in docs page * Update XREstimatedLight.html Fix indentations. --------- Co-authored-by: Michael Herzog <[email protected]>
mrdoob · Oct 27, 2023 · 3c21783 · 3c21783
1 parent 43a993f
commit 3c21783
Show file tree

Hide file tree

Showing 3 changed files with 127 additions and 1 deletion.
diff --git a/docs/examples/en/webxr/XREstimatedLight.html b/docs/examples/en/webxr/XREstimatedLight.html
@@ -0,0 +1,122 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		[page:Group] &rarr;
+
+		<h1>[name]</h1>
+
+		<p class="desc">
+			XREstimatedLight uses WebXR's light estimation to create
+			a light probe, a directional light, and (optionally) an environment map
+			that model the user's real-world environment and lighting.<br>
+			As WebXR updates the light and environment estimation, XREstimatedLight
+			automatically updates the light probe, directional light, and environment map.<br><br>
+
+			It's important to specify `light-estimation` as an optional or required
+			feature when creating the WebXR session, otherwise the light estimation
+			can't work.<br><br> 
+
+			See <a href="https://developer.mozilla.org/en-US/docs/Web/API/XRLightProbe#browser_compatibility">here</a>
+			for browser compatibility information, as this is still an experimental feature in WebXR.<br><br>
+
+
+			To use this, as with all files in the /examples directory, you will have to
+			include the file separately in your HTML.
+		</p>
+
+		<h2>Import</h2>
+
+		<p>
+			[name] is an add-on, and must be imported explicitly.
+			See [link:#manual/introduction/Installation Installation / Addons].
+		</p>
+
+		<code>
+		import { XREstimatedLight } from 'three/addons/webxr/XREstimatedLight.js';
+		</code>
+
+		<h2>Code Example</h2>
+
+		<code>
+		renderer.xr.enabled = true;
+
+		// Don't add the XREstimatedLight to the scene initially.
+		// It doesn't have any estimated lighting values until an AR session starts.
+		const xrLight = new XREstimatedLight( renderer );
+
+		xrLight.addEventListener( 'estimationstart' , () => {
+
+			scene.add( xrLight );
+
+			if ( xrLight.environment ) {
+
+				scene.environment = xrLight.environment;
+
+			}
+
+		} );
+
+		xrLight.addEventListener( 'estimationend', () => {
+
+			scene.remove( xrLight );
+
+			scene.environment = null;
+
+		} );
+
+		// In order for lighting estimation to work, 'light-estimation' must be included as either
+		// an optional or required feature.
+		document.body.appendChild( XRButton.createButton( renderer, {
+			optionalFeatures: [ 'light-estimation' ]
+		} ) );
+		</code>
+
+		<h2>Examples</h2>
+
+		<p>[example:webxr_ar_lighting webxr / light estimation]</p>
+
+		<h2>Constructor</h2>
+
+		<h3>[name]( [param:WebGLRenderer renderer], [param:Boolean environmentEstimation] )</h3>
+		<p>
+			[page:WebGLRenderer renderer]: (required) The renderer used to render the Scene. Mainly used to interact with WebXRManager.<br><br>
+
+			environmentEstimation: If `true`, use WebXR to estimate an environment map.
+		</p>
+
+		<h2>Events</h2>
+
+		<h3>estimationstart</h3>
+		<p>
+			Fires when the estimated lighting values start being updated.
+		</p>
+
+		<h3>estimationend</h3>
+		<p>
+			Fires when the estimated lighting values stop being updated.
+		</p>
+
+		<h2>Properties</h2>
+
+		<h3>[property:Texture environment]</h3>
+		<p>
+			The environment map estimated by WebXR. This is only available if environmentEstimation is `true`.<br><br>
+
+			It can be used as the [page:Scene.environment], for
+			[page:MeshStandardMaterial.envMap], or
+			as the [page:Scene.background].
+		</p>
+
+		<h2>Source</h2>
+
+		<p>
+			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/webxr/XREstimatedLight.js examples/jsm/webxr/XREstimatedLight.js]
+		</p>
+	</body>
+</html>
diff --git a/docs/list.json b/docs/list.json
@@ -419,6 +419,10 @@
 				"CameraUtils": "examples/en/utils/CameraUtils",
 				"SceneUtils": "examples/en/utils/SceneUtils",
 				"SkeletonUtils": "examples/en/utils/SkeletonUtils"
+			},
+
+			"WebXR": {
+				"XREstimatedLight": "examples/en/webxr/XREstimatedLight"
 			}
 
 		},

diff --git a/examples/jsm/webxr/XREstimatedLight.js b/examples/jsm/webxr/XREstimatedLight.js
@@ -147,7 +147,7 @@ export class XREstimatedLight extends Group {
 		this.directionalLight.intensity = 0;
 		this.add( this.directionalLight );
 
-		// Will be set to a cube map in the SessionLightProbe is environment estimation is
+		// Will be set to a cube map in the SessionLightProbe if environment estimation is
 		// available and requested.
 		this.environment = null;