recursal/MDN huggingface dataset:
XRSession: renderState property
===============================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The
 *read-only* **`renderState`** property of an
 `XRSession` object indicates the returns a `XRRenderState`
 object describing how the user's environment which should be rendered. The
 information provided covers the minimum and maximum distance at which to render objects,
 the vertical field of view to use when rendering the in the `inline` session
 mode, and the `XRWebGLLayer` to render into for inline composition.

 While this property is read only, you can call the `XRSession` method
 `updateRenderState()` to make changes.

Value
-----

An `XRRenderState` object describing how to render the scene.

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # dom-xrsession-renderstate |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRSession: visibilitychange event
=================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`visibilitychange`** event is sent to an `XRSession` to inform it when it becomes visible or hidden, or when it becomes visible but not currently focused. Upon receiving the event, you can check the value of the session's `visibilityState` property to determine the new visibility state.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("visibilitychange", (event) => {});

onvisibilitychange = (event) => {};
```

Event type
----------

An `XRSessionEvent`. Inherits from `Event`.

Event

XRSessionEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`session` Read only 

The `XRSession` to which the event refers.

Description
-----------

### Trigger

Triggered when an `XRSession` becomes visible or hidden, or when it becomes visible but not currently focused.

When the `XRSession` receives this event, the visibility state has already been changed.

### Use cases

Upon receiving the event, you can check the value of the session's `visibilityState` property to determine the new visibility state.

Examples
--------

This example demonstrates how to listen for a `visibilitychange` event on a WebXR session, using `addEventListener()` to begin listening for the event:


```js
navigator.xr.requestSession("inline").then((xrSession) => {
  xrSession.addEventListener("visibilitychange", (e) => {
    switch (e.session.visibilityState) {
      case "visible":
      case "visible-blurred":
        mySessionVisible(true);
        break;
      case "hidden":
        mySessionVisible(false);
        break;
    }
  });
});
```


When a visibility state change occurs, the event is received and dispatched to a function `mySessionVisible()`, with a Boolean parameter indicating whether or not the session is presently being displayed to the user.

You can also create the event handler by assigning it to the `XRSession`'s `onvisibilitychange` event handler property, like this:


```js
xrSession.onvisibilitychange = (e) => {
  /\* event handled here \*/
};
```

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # eventdef-xrsession-visibilitychange |
| WebXR Device API # dom-xrsession-onvisibilitychange |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRSession: selectend event
==========================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The WebXR event **`selectend`** is sent to an `XRSession` when one of its input sources ends its primary action or when an input source that's in the process of handling an ongoing primary action is disconnected without successfully completing the action.

The `beforexrselect` is fired before this event and can prevent this event from being raised.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("selectend", (event) => {});

onselectend = (event) => {};
```

Event type
----------

An `XRInputSourceEvent`. Inherits from `Event`.

Event

XRInputSourceEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`frame` Read only 

An `XRFrame` object providing the needed information about the event frame during which the event occurred. This frame may have been rendered in the past rather than being a current frame. Because this is an *event* frame, not an *animation* frame, you cannot call the `XRFrame` method `getViewerPose()` on it; instead, use `getPose()`.

`inputSource` Read only 

An `XRInputSource` object indicating which input source generated the input event.

Description
-----------

### Trigger

Triggered when the user stops to press triggers or buttons, taps a touchpad, speaks a command, or performs a recognizable gesture when using a video tracking system or handheld controller with an accelerometer.

### Use cases

The `selectend` and `selectstart` events tell you when you might want to display something to the user indicating that the primary action is going on. This might be drawing a controller with the activated button in a new color, or showing the targeted object being grabbed and moved around, starting when `selectstart` arrives and stopping when `selectend` is received.

The `select` event is the event that tells your code that the user has completed the action they want to complete. This might be as simple as throwing an object or pulling the trigger of a gun in a game, or as involved as placing a dragged object in a new location.

If your primary action is a simple trigger action and you don't need to animate anything while the trigger is engaged, you can ignore the `selectstart` and `selectend` events and act on the start event.

Examples
--------

See the `selectstart` event for example code.

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # eventdef-xrsession-selectend |
| WebXR Device API # dom-xrsession-onselectend |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `select` and `selectstart`
* `beforexrselect`
XRSession: squeezeend event
===========================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The WebXR event **`squeezeend`** is sent to an `XRSession` when one of its input sources ends its primary action or when an input source that's in the process of handling an ongoing primary action is disconnected without successfully completing the action.

Primary squeeze actions include things like users pressing triggers or buttons, tapping a touchpad, speaking a command, or performing a recognizable gesture when using a video tracking system or handheld controller with an accelerometer.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("squeezeend", (event) => {});

onsqueezeend = (event) => {};
```

Event type
----------

An `XRInputSourceEvent`. Inherits from `Event`.

Event

XRInputSourceEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`frame` Read only 

An `XRFrame` object providing the needed information about the event frame during which the event occurred. This frame may have been rendered in the past rather than being a current frame. Because this is an *event* frame, not an *animation* frame, you cannot call `XRFrame.getViewerPose()` on it; instead, use `getPose()`.

`inputSource` Read only 

An `XRInputSource` object indicating which input source generated the input event.

Description
-----------

### Trigger

Triggered when users stop squeezing the controller, making a hand gesture that mimes grabbing something, or using (squeezing) a trigger.

### Use cases

The `squeezestart` event is sent indicating that the user has begun a squeeze action.

If the primary squeeze action ends successfully, the session is sent a `squeeze` event.

A `squeezeend` event is sent to indicate that the squeeze action is no longer underway. This is sent whether the squeeze action succeeded or not.

Examples
--------

See the `squeezestart` event for example code.

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # eventdef-xrsession-squeezeend |
| WebXR Device API # dom-xrsession-onsqueezeend |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRSession: inputSources property
================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The read-only **`inputSources`** property of the
 `XRSession` interface returns an `XRInputSourceArray` object
 which lists all controllers and input devices which are expressly associated with the
 XR device and are currently available. These controllers may include handheld
 controllers, XR-equipped gloves, optically tracked hands, and gaze-based input methods.
 Keyboards, gamepads, and mice are *not* considered WebXR input sources.

**Note:** Traditional gamepad controllers are supported using the Gamepad API.

Value
-----

 An `XRInputSourceArray` object listing all of the currently-connected
 input controllers which are linked specifically to the XR device currently in use. The
 returned object is **live**; as devices are connected to and removed from
 the user's system, the list's contents update to reflect the changes.

Usage notes
-----------

 You can add a handler for the `XRSession` event
 `inputsourceschange` to be advised
 when the contents of the session's connected devices list changes. You can then either
 get the value of `inputSources` to examine the list, or you can refer to a
 reference to the list that you've previously saved.

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # dom-xrsession-inputsources |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `XRInputSource`
* The `inputsourceschange` event
* Gamepad API
XRSession: inputsourceschange event
===================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`inputsourceschange`** event is sent to an `XRSession` when the set of available WebXR input devices changes.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("inputsourceschange", (event) => {});

oninputsourceschange = (event) => {};
```

Event type
----------

An `XRInputSourcesChangeEvent`. Inherits from `Event`.

Event

XRInputSourcesChangeEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`added` Read only 

An array of zero or more `XRInputSource` objects, each representing an input device which has been recently connected or enabled.

`removed` Read only 

An array of zero or more `XRInputSource` objects representing the input devices recently disconnected or disabled.

`session` Read only 

The `XRSession` to which this input source change event is being directed.

Description
-----------

### Trigger

Triggered when the set of available WebXR input devices changes.

### Use cases

You can use this event to detect newly-available devices or when devices have become unavailable.

Examples
--------

The following example shows how to set up an event handler which uses `inputsourceschange` events to detect newly-available pointing devices and to load their models in preparation for displaying them in the next animation frame.


```js
xrSession.addEventListener("inputsourceschange", onInputSourcesChange);

function onInputSourcesChange(event) {
  for (const input of event.added) {
    if (input.targetRayMode === "tracked-pointer") {
      loadControllerMesh(input);
    }
  }
}
```


You can also add a handler for `inputsourceschange` events by setting the `oninputsourceschange` event handler:


```js
xrSession.oninputsourceschange = onInputSourcesChange;
```

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # eventdef-xrsession-inputsourceschange |
| WebXR Device API # dom-xrsession-oninputsourceschange |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRSession: preferredReflectionFormat property
=============================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The *read-only* **`preferredReflectionFormat`** property of the `XRSession` interface returns this session's preferred reflection format used for lighting estimation texture data.

Value
-----

A string representing the reflection format. Possible values:

| XRReflectionFormat | WebGL Format | WebGL Internal Format | WebGPU Format | HDR |
| --- | --- | --- | --- | --- |
| "srgba8" | RGBA | SRGB8\_ALPHA8 | "rgba8unorm-srgb" |  |
| "rgba16f" | RGBA | RGBA16F | "rgba16float" | ✓ |

Examples
--------

### Requesting a light probe with the system's preferred format

You can request a light probe with `XRSession.requestLightProbe()` and specify the system's preferred format by setting the `reflectionFormat` option equal to `XRSession.preferredReflectionFormat`.


```js
const lightProbe = await xrSession.requestLightProbe({
  reflectionFormat: xrSession.preferredReflectionFormat,
});
```

Specifications
--------------

| Specification |
| --- |
| WebXR Lighting Estimation API Level 1 # dom-xrsession-preferredreflectionformat |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `XRSession.requestLightProbe()`
XRSession: end() method
=======================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`end()`** method shuts down the
 `XRSession` on which it's called, returning a promise which resolves once
 the session has fully shut down.

Syntax
------


```js
end()
```

### Parameters

None.

### Return value

 A `promise` that resolves without a value after any platform-specific steps
 related to shutting down the session have completed. You can use the promise to do
 things like update UI elements to reflect the shut down connection, trigger application
 shut down, or whatever else you might need to do.

Examples
--------

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # dom-xrsession-end |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRSession: requestHitTestSource() method
========================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`requestHitTestSource()`** method of the
 `XRSession` interface returns a `Promise` that resolves with an `XRHitTestSource` object that can be passed to `XRFrame.getHitTestResults()`.

Syntax
------


```js
requestHitTestSource(options)
```

### Parameters

`options`

An object containing configuration options, specifically:

`space`

The `XRSpace` that will be tracked by the hit test source.

`entityTypes` Optional

An `Array` specifying the types of entities to be used for hit test source creation. If no entity type is specified, the array defaults to a single element with the `plane` type. Possible types:

* `point`: Compute hit test results based on characteristic points detected.
* `plane`: Compute hit test results based on real-world planes detected.
* `mesh`: Compute hit test results based on meshes detected.

`offsetRay` Optional

The `XRRay` object that will be used to perform hit test. If no `XRRay` object has been provided, a new `XRRay` object is constructed without any parameters.


### Return value

A `Promise` that resolves with an `XRHitTestSource` object.

### Exceptions

 Rather than throwing true exceptions, `requestHitTestSource()` rejects the
 returned promise with a `DOMException`, specifically, one of the following:

`NotSupportedError` `DOMException`

Thrown if `hit-test` is not an enabled feature in `XRSystem.requestSession()`.

`InvalidStateError` `DOMException`

Thrown if the session has already ended.

`NotAllowedError` `DOMException`

Thrown if there is an unreasonable amount of requests. Some user agents might limit usage for privacy reasons.

Examples
--------

### Requesting a hit test source

To request a hit test source, start an `XRSession` with the `hit-test` session feature enabled. Next, configure the hit test source and store it for later use in the frame loop and call `XRFrame.getHitTestResults()` to obtain the result.


```js
const xrSession = navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["local", "hit-test"],
});

let hitTestSource = null;

xrSession
  .requestHitTestSource({
    space: viewerSpace, // obtained from xrSession.requestReferenceSpace("viewer");
    offsetRay: new XRRay({ y: 0.5 }),
  })
  .then((viewerHitTestSource) => {
    hitTestSource = viewerHitTestSource;
  });

// frame loop
function onXRFrame(time, xrFrame) {
  let hitTestResults = xrFrame.getHitTestResults(hitTestSource);

  // do things with the hit test results
}
```

Specifications
--------------

| Specification |
| --- |
| WebXR Hit Test Module # dom-xrsession-requesthittestsource |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `XRSession.requestHitTestSourceForTransientInput()`
XRSession: domOverlayState property
===================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The *read-only* **`domOverlayState`** property of an `immersive-ar`
`XRSession` provides information about the DOM overlay, if the feature is enabled.

Value
-----

Returns `null` if the DOM overlay feature is not supported or not enabled or an object containing information about the DOM overlay state with the following properties:

`type`

A string indicating how the DOM overlay is being displayed. Possible values:

`screen`

The overlay is drawn on the entire screen-based device (for handheld AR devices).

`head-locked`

The overlay is drawn at a head-locked UI that fills the renderable viewport and follows the user's head movement.

`floating`

The overlay appears as a rectangle floating in space that's kept in front of the user. It doesn't necessarily fill up the entire space and/or is strictly head-locked.


Examples
--------

### Checking which DOM overlay got enabled


```js
if (session.domOverlayState) {
  console.log(session.domOverlayState.type);
} else {
  console.log("DOM overlay not supported or enabled!");
}
```

Specifications
--------------

| Specification |
| --- |
| WebXR DOM Overlays Module # dom-xrsession-domoverlaystate |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `beforexrselect`
XRSession: requestLightProbe() method
=====================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`requestLightProbe()`** method of the
 `XRSession` interface returns a `Promise` that resolves with an `XRLightProbe` object that estimates lighting information at a given point in the user's environment.

Syntax
------


```js
requestLightProbe()
requestLightProbe(options)
```

### Parameters

`options` Optional

An object containing configuration options, specifically:

`reflectionFormat`

The internal reflection format indicating how the texture data is represented, either `srgba8` (default value) or `rgba16f`. See also `XRSession.preferredReflectionFormat`.


### Return value

A `Promise` that resolves with an `XRLightProbe` object.

### Exceptions

 Rather than throwing true exceptions, `requestLightProbe()` rejects the
 returned promise with a `DOMException`, specifically, one of the following:

`NotSupportedError` `DOMException`

Thrown if `lighting-estimation` is not an enabled feature in `XRSystem.requestSession()` or if the `reflectionFormat` is not `srgb8` or the `preferredReflectionFormat`.

`InvalidStateError` `DOMException`

Thrown if the session has already ended.

Examples
--------

### Requesting a light probe with the system's preferred format

The default format is `srgb8`, however, some rendering engines may use other (high dynamic range) formats. You can request the light probe with `XRSession.preferredReflectionFormat` which reports the preferred internal format.


```js
const lightProbe = await xrSession.requestLightProbe({
  reflectionFormat: xrSession.preferredReflectionFormat,
});
```

Specifications
--------------

| Specification |
| --- |
| WebXR Lighting Estimation API Level 1 # dom-xrsession-requestlightprobe |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `XRSession.preferredReflectionFormat`
XRSession: interactionMode property
===================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The `XRSession` interface's *read-only* **`interactionMode`** property
 describes the best space (according to the user agent) for the application to draw an interactive UI for the current session.

Value
-----

 A string describing the best space (according to the user agent) for the application to draw an interactive UI
 for the current session.

Possible values are:

`screen-space`

Indicates that the UI should be drawn directly to the screen without projection. This is typically the mode reported from handheld devices.

`world-space`

Indicates that the UI should be drawn in the world, some distance from the user, so that they may interact with it using controllers. This is typically the mode reported from headworn devices.

Examples
--------


```js
if (xrSession.interactionMode === "world-space") {
  // draw UI in the world
} else {
  // draw UI directly to the screen
}
```

Specifications
--------------

| Specification |
| --- |
| WebXR Augmented Reality Module - Level 1 # dom-xrsession-interactionmode |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.