Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

WebXR: Add docs page for XREstimatedLight #27041

Merged
merged 3 commits into from
Oct 27, 2023
Merged

WebXR: Add docs page for XREstimatedLight #27041

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c74400e
Add docs page for XREstimatedLight
snowzurfer Oct 24, 2023
dbcef6b
Fix link in list json and copy in docs page
snowzurfer Oct 24, 2023
6d8073d
Update XREstimatedLight.html
Mugen87 Oct 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
122 changes: 122 additions & 0 deletions docs/examples/en/webxr/XREstimatedLight.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
4 changes: 4 additions & 0 deletions docs/list.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}

},
Expand Down
2 changes: 1 addition & 1 deletion examples/jsm/webxr/XREstimatedLight.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down