spec:infra;

type:dfn; text:string

type:dfn; text:tuple

type:dfn; text:continue

spec:permissions;

type:dfn; text:powerful feature

spec:webidl;

type:dfn; text:new

type:interface; text:any

spec:dom;

type:dfn; text:ancestor

type:dfn; text:descendant

spec:webxr-ar-module-1;

type:dfn; text:first-person observer view

spec:html; type:interface; text:Navigator

spec:infra; urlPrefix: https://infra.spec.whatwg.org/

type:dfn; for:list; text:extend; url: list-extend

spec: High Resolution Time; urlPrefix: https://www.w3.org/TR/hr-time/

type: typedef; text: DOMHighResTimeStamp; url: dom-domhighrestimestamp

spec: WebGL; urlPrefix: https://www.khronos.org/registry/webgl/specs/latest/1.0/

type: interface; text: WebGLFramebuffer; url: WebGLFramebuffer

type: interface; text: WebGLRenderingContext; url: WebGLRenderingContext

type: interface; text: WebGLRenderingContextBase; url: WebGLRenderingContextBase

type: interface; text: WebGLObject; url: WebGLObject

type: typedef; text: INVALID_OPERATION; url: WebGLRenderingContextBase

type: typedef; text: INVALID_FRAMEBUFFER_OPERATION; url: WebGLRenderingContextBase

type: typedef; text: FRAMEBUFFER_UNSUPPORTED; url: WebGLRenderingContextBase

type: method; text: clear; url: 5.14.11

type: method; text: drawArrays; url: 5.14.11

type: method; text: drawElements; url: 5.14.11

type: method; text: uniformMatrix4fv; url: 5.14.10

type: method; text: framebufferTexture2D; url: 5.14.6

type: method; text: framebufferRenderbuffer; url: 5.14.6

type: method; text: getFramebufferAttachmentParameter; url: 5.14.6

type: method; text: deleteFramebuffer; url: 5.14.6

type: method; text: checkFramebufferStatus; url: 5.14.6

type: attribute; text: statusMessage; for: WebGLContextEvent; url: 5.15.1

type: dictionary; text: WebGLContextAttributes; url: #WebGLContextAttributes

type: dfn; text: Create the WebGL context; url:#2.1

type: dfn; text: default framebuffer; url:#2.2

type: dfn; text: WebGL viewport; url:#5.14.4

type: dfn; text: WebGL context lost flag; url:#webgl-context-lost-flag

type: dfn; text: handle the context loss; url:#CONTEXT_LOST

type: dfn; text: Restore the context; url: #restore-the-drawing-buffer

type: dfn; text: actual context parameters; url: #actual-context-parameters

type: dfn; text: create a drawing buffer; url: #create-a-drawing-buffer

type: dfn; text: WebGL task source; url: #5.15

type: dfn; text: canvas; for: WebGLRenderingContext; url: context-canvas

type: dfn; text: webgl context lost flag; for: WebGLRenderingContext; url: webgl-context-lost-flag

type: dfn; text: Fire a WebGL context event; url: fire-a-webgl-context-event

type: dfn; text: invalidated; for: WebGLObject; url: #webgl-object-invalidated-flag

type: typedef; text: RGBA; url: #5.14

type: typedef; text: RGB; url: #5.14

spec: WebGL 2.0; urlPrefix: https://www.khronos.org/registry/webgl/specs/latest/2.0/

type: interface; text: WebGL2RenderingContext; url: WebGL2RenderingContext

type: typedef; text: SRGB8; url: #5.14

type: typedef; text: SRGB8_ALPHA8; url: #5.14

spec: Orientation Sensor; urlPrefix: https://www.w3.org/TR/orientation-sensor/

type: interface; text: AbsoluteOrientationSensor; url: absoluteorientationsensor

type: interface; text: RelativeOrientationSensor; url: relativeorientationsensor

spec: WebIDL; urlPrefix: https://webidl.spec.whatwg.org/

type: dfn; text: invoke the Web IDL callback function; url:invoke-a-callback-function

spec:html; urlPrefix: https://html.spec.whatwg.org/multipage/

type: method; for:HTMLCanvasElement; text:getContext(contextId); url: canvas.html#dom-canvas-getcontext

type: method; for:Window; text:requestAnimationFrame(callback); url: imagebitmap-and-animations.html#dom-animationframeprovider-requestanimationframe

type: dfn; text: currently focused area; url: interaction.html#currently-focused-area-of-a-top-level-browsing-context

type: dfn; text: rendering opportunity; url: webappapis.html#rendering-opportunity

type: dfn; text: current realm; url: webappapis.html#current

type: dfn; text: same origin-domain; url: origin.html#same-origin-domain

type: dfn; text: browsing context; url: browsers.html#browsing-context

type: dfn; text: associated document; url: window-object.html#concept-document-window

type: dfn; text: origin; url: origin.html#concept-origin

type: dfn; text: secure context; url: secure-context

type: dfn; for: Document; text: visibilityState; url: interaction.html#dom-document-visibilitystate

spec: PointerEvents; urlPrefix: https://www.w3.org/TR/pointerevents/#

type: dfn; text: primary pointer; url: dfn-primary-pointer

spec: ECMAScript; urlPrefix: https://tc39.es/ecma262/#

type: method; text: IsDetachedBuffer; url: sec-isdetachedbuffer

type: dfn; text: ?; url: sec-returnifabrupt-shorthands

type: dfn; text: Realm; url: realm

type: abstract-op; text: ToString; url: sec-tostring

spec: dom; urlPrefix: https://dom.spec.whatwg.org/#

type:algorithm; text:fire an event; url: concept-event-fire

spec: html; urlPrefix: https://html.spec.whatwg.org

type: dfn; text:focus; url: dom-focus-dev

spec: requestidlecallback; urlPrefix: https://www.w3.org/TR/requestidlecallback/#

type:method; text: requestIdleCallback(); for: Window; url:the-requestidlecallback-method

.head h1:after {

content: url(images/spec-logo.png);

float: right;

}

.unstable::before {

content: "This section is not stable";

display: block;

font-weight: bold;

text-align: right;

color: red;

}

.unstable {

border: thin solid pink;

border-radius: .5em;

padding: .5em;

margin: .5em calc(-0.5em - 1px);

background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='290'><text transform='rotate(-45)' text-anchor='middle' font-family='sans-serif' font-weight='bold' font-size='70' y='210' opacity='.1'>Unstable</text></svg>");

background-repeat: repeat;

background-color: #FFF4F4;

}

.unstable h3:first-of-type {

margin-top: 0.5rem;

}

.unstable.example:not(.no-marker)::before {

content: "Example " counter(example) " (Unstable)";

float: none;

}

.non-normative::before {

content: "This section is non-normative.";

font-style: italic;

}

.tg {

border-collapse: collapse;

border-spacing: 0;

}

.tg th {

border-style: solid;

border-width: 1px;

background: var(--def-bg);

font-family: sans-serif;

font-weight: bold;

border-color: var(--def-border);

}

.tg td {

padding: 4px 5px;

background-color: var(--def-bg);

font-family: monospace;

border-style: solid;

border-width: 1px;

border-color: var(--def-border);

overflow: hidden;

word-break: normal;

}

Introduction {#intro}

============

Hardware that enables Virtual Reality (VR) and Augmented Reality (AR) applications are now broadly available to consumers, offering an immersive computing platform with both new opportunities and challenges. The ability to interact directly with immersive hardware is critical to ensuring that the web is well equipped to operate as a first-class citizen in this environment.

Immersive computing introduces strict requirements for high-precision, low-latency communication in order to deliver an acceptable experience. It also brings unique [[#security|security]] concerns for a platform like the web. The WebXR Device API provides the interfaces necessary to enable developers to build compelling, comfortable, and safe immersive applications on the web across a wide variety of hardware form factors.

Other web interfaces, such as the {{RelativeOrientationSensor}} and {{AbsoluteOrientationSensor}}, can be repurposed to surface input from some devices to polyfill the WebXR Device API in limited situations. These interfaces cannot support multiple features of high-end immersive experiences, however, such as [=6DoF=] tracking, presentation to headset peripherals, or tracked input devices.

Terminology {#terminology}

-----------

This document uses the acronym <b>XR</b> throughout to refer to the spectrum of hardware, applications, and techniques used for Virtual Reality, Augmented Reality, and other related technologies. Examples include, but are not limited to:

* Head-mounted displays, whether they are opaque, transparent, or utilize video passthrough

* Mobile devices with positional tracking

* Fixed displays with head tracking capabilities

The important commonality between them being that they offer some degree of spatial tracking with which to simulate a view of virtual content.

Terms like "XR device", "XR application", etc. are generally understood to apply to any of the above. Portions of this document that only apply to a subset of these devices will indicate so as appropriate.

The terms [=3DoF=] and [=6DoF=] are used throughout this document to describe the tracking capabilities of [=/XR devices=].

- A <dfn>3DoF</dfn> device, short for "Three Degrees of Freedom", is one that can only track rotational movement. This is common in devices which rely exclusively on accelerometer and gyroscope readings to provide tracking. [=3DoF=] devices do not respond to translational movements from the user, though they may employ algorithms to estimate translational changes based on modeling of the neck or arms.

- A <dfn>6DoF</dfn> device, short for "Six Degrees of Freedom", is one that can track both rotation and translation, enabling precise 1:1 tracking in space. This typically requires some level of understanding of the user's environment. That environmental understanding may be achieved via inside-out tracking, where sensors on the tracked device itself (such as cameras or depth sensors) are used to determine the device's position, or outside-in tracking, where external devices placed in the user's environment (like a camera or light emitting device) provides a stable point of reference against which the [=/XR device=] can determine its position.

Application flow {#applicationflow}

----------------

Most applications using the WebXR Device API will follow a similar usage pattern:

* Query {{XRSystem/isSessionSupported()|navigator.xr.isSessionSupported()}} to determine if the desired type of XR content is supported by the hardware and UA.

* If so, advertise the XR content to the user.

* Wait for the window to have [=transient activation=]. This is most commonly indicated by the user clicking a button on the page indicating they want to begin viewing XR content.

* Request an {{XRSession}} within the user activation event with {{XRSystem/requestSession()|navigator.xr.requestSession()}}.

* If the {{XRSession}} request succeeds, use it to run a [[#frame|frame loop]] to respond to XR input and produce images to display on the [=XRSession/XR device=] in response.

* Continue running the [[#frame|frame loop]] until the [=shut down the session|session is shut down=] by the UA or the user indicates they want to exit the XR content.

Model {#model}

=====

XR device {#xr-device-concept}

---------

An <dfn for="">XR device</dfn> is a physical unit of hardware that can present immersive content to the user. Content is considered to be "immersive" if it produces visual, audio, haptic, or other sensory output that simulates or augments various aspects of the user's environment. Most frequently this involves tracking the user's motion in space and producing outputs that are synchronized to the user's movement. On desktop clients, this is usually a headset peripheral. On mobile clients, it may represent the mobile device itself in conjunction with a viewer harness. It may also represent devices without stereo-presentation capabilities but with more advanced tracking.

An [=/XR device=] has a <dfn>list of supported modes</dfn> (a [=/list=] of [=/strings=]) that [=list/contains=] the enumeration values of {{XRSessionMode}} that the [=/XR device=] supports.

Each [=/XR device=] has a <dfn for="XR device">set of granted features</dfn> for each {{XRSessionMode}} in its [=list of supported modes=], which is a [=/set=] of [=feature descriptors=] which MUST be initially an empty [=/set=].

The user agent has a <dfn for="">list of immersive XR devices</dfn> (a [=/list=] of [=/XR device=]), which MUST be initially an empty [=/list=].

The user agent has an <dfn for="">immersive XR device</dfn> (`null` or [=/XR device=]) which is initially `null` and represents the active [=/XR device=] from the [=list of immersive XR devices=]. This object MAY live on a separate thread and be updated asynchronously.

The user agent MUST have a <dfn for="">default inline XR device</dfn>, which is an [=/XR device=] that MUST [=list/contains|contain=] {{XRSessionMode/"inline"}} in its [=list of supported modes=]. The [=/default inline XR device=] MUST NOT report any pose information, and MUST NOT report [=XR input source=]s or events other than those created by pointer events.

Note: The [=/default inline XR device=] exists purely as a convenience for developers, allowing them to use the same rendering and input logic for both inline and immersive content. The [=/default inline XR device=] does not expose any information not already available to the developer through other mechanisms on the page (such as pointer events for input), it only surfaces those values in an XR-centric format.

The user agent MUST have a <dfn for="">inline XR device</dfn>, which is an [=/XR device=] that MUST [=list/contains|contain=] {{XRSessionMode/"inline"}} in its [=list of supported modes=]. The [=/inline XR device=] MAY be the [=immersive XR device=] if the tracking it provides makes sense to expose to inline content or the [=/default inline XR device=] otherwise.

Note: On phones, the [=/inline XR device=] may report pose information derived from the phone's internal sensors, such as the gyroscope and accelerometer. On desktops and laptops without similar sensors, the [=/inline XR device=] will not be able to report a pose, and as such should fall back to the [=/default inline XR device=]. In case the user agent is already running on an [=/XR device=], the [=/inline XR device=] will be the same device, and may support multiple [=view|views=]. User consent must be given before any tracking or input features beyond what the [=/default inline XR device=] exposes are provided.

The current values of [=list of immersive XR devices=], [=/inline XR device=], and [=immersive XR device=] MAY live on a separate thread and be updated asynchronously. These objects SHOULD NOT be directly accessed in steps that are not running [=in parallel=].

Initialization {#initialization}

==============

navigator.xr {#navigator-xr-attribute}

------------

partial interface Navigator {

[SecureContext, SameObject] readonly attribute XRSystem xr;

};

The <dfn attribute for="Navigator">xr</dfn> attribute's getter MUST return the {{XRSystem}} object that is associated with it.

XRSystem {#xrsystem-interface}

----

[SecureContext, Exposed=Window] interface XRSystem : EventTarget {

// Methods

Promise&lt;boolean&gt; isSessionSupported(XRSessionMode mode);

[NewObject] Promise&lt;XRSession&gt; requestSession(XRSessionMode mode, optional XRSessionInit options = {});

// Events

attribute EventHandler ondevicechange;

};

The user agent MUST create an {{XRSystem}} object when a {{Navigator}} object is created and associate it with that object.

An {{XRSystem}} object is the entry point to the API, used to query for XR features available to the user agent and initiate communication with XR hardware via the creation of {{XRSession}}s.

The user agent MUST be able to <dfn>enumerate immersive XR devices</dfn> attached to the system, at which time each available device is placed in the [=list of immersive XR devices=]. Subsequent algorithms requesting enumeration MUST reuse the cached [=list of immersive XR devices=]. Enumerating the devices [=should not initialize device tracking=]. After the first enumeration the user agent MUST begin monitoring device connection and disconnection, adding connected devices to the [=list of immersive XR devices=] and removing disconnected devices.

Each time the [=list of immersive XR devices=] changes the user agent should <dfn>select an immersive XR device</dfn> by running the following steps:

1. Let |oldDevice| be the [=immersive XR device=].

1. If the [=list of immersive XR devices=] is an empty [=/list=], set the [=immersive XR device=] to `null`.

1. If the [=list of immersive XR devices=]'s [=list/size=] is one, set the [=immersive XR device=] to the [=list of immersive XR devices=][0].

1. Set the [=immersive XR device=] as follows:

<dl class="switch">

: If there are any active {{XRSession}}s and the [=list of immersive XR devices=] [=list/contains=] |oldDevice|:

:: Set the [=immersive XR device=] to |oldDevice|.

: Otherwise:

:: Set the [=immersive XR device=] to a device of the user agent's choosing.

</dl>

1. The user agent MAY update the [=/inline XR device=] to the [=immersive XR device=] if appropriate, or the [=/default inline XR device=] otherwise.

1. If this is the first time devices have been enumerated or |oldDevice| equals the [=immersive XR device=], abort these steps.

1. [=Shut down the session|Shut down=] any active {{XRSession}}s.

1. [=Queue a task=] to set the [=XR compatible=] boolean of all {{WebGLRenderingContextBase}} instances to `false`.

1. [=Queue a task=] to [=fire an event=] named <a for="XRSystem" data-link-type="event">devicechange</a> on the [=relevant Global object=]'s {{Window/navigator}}'s {{Navigator/xr}}.

1. [=Queue a task=] to fire appropriate `change` events on any {{XRPermissionStatus}} objects who are affected by the change in the [=immersive XR device=] or [=/inline XR device=].

Note: These steps should always be run [=in parallel=].

Note: The user agent is allowed to use any criteria it wishes to [=select an immersive XR device=] when the [=list of immersive XR devices=] contains multiple devices. For example, the user agent may always select the first item in the list, or provide settings UI that allows users to manage device priority. Ideally the algorithm used to select the default device is stable and will result in the same device being selected across multiple browsing sessions.

The user agent can <dfn>ensure an immersive XR device is selected</dfn> by running the following steps:

1. If [=immersive XR device=] is not `null`, return [=immersive XR device=] and abort these steps.

1. [=Enumerate immersive XR devices=].

1. [=Select an immersive XR device=].

1. Return the [=immersive XR device=].

Note: These steps should always be run [=in parallel=].

The <dfn attribute for="XRSystem">ondevicechange</dfn> attribute is an [=Event handler IDL attribute=] for the <a for="XRSystem" data-link-type="event">devicechange</a> event type.

The <dfn method for="XRSystem">isSessionSupported(|mode|)</dfn> method queries if a given |mode| may be supported by the user agent and device capabilities.

When this method is invoked, it MUST run the following steps:

1. Let |promise| be [=a new Promise=] in the [=relevant realm=] of this {{XRSystem}}.

1. If |mode| is {{XRSessionMode/"inline"}}, [=/resolve=] |promise| with `true` and return it.

1. If the requesting document's [=origin=] is not allowed to use the "xr-spatial-tracking" [[#permissions-policy|permissions policy]], [=reject=] |promise| with a "{{SecurityError}}" {{DOMException}} and return it.

1. Check whether the session |mode| is supported as follows:

<dl class="switch">

: If the user agent and system are known to [=never support=] |mode| sessions

:: [=/Resolve=] |promise| with `false`.

: If the user agent and system are known to [=usually support=] |mode| sessions

:: |promise| MAY be [=/resolved=] with `true` provided that all instances of this user agent [=indistinguishable by user agent string=] produce the same result here.

: Otherwise

:: Run the following steps [=in parallel=]:

1. Let |device| be the result of [=ensure an immersive XR device is selected|ensuring an immersive XR device is selected=].

1. If |device| is null, [=/resolve=] |promise| with `false` and abort these steps.

1. If |device|'s [=list of supported modes=] does not [=list/contain=] |mode|, [=queue a task=] to [=/resolve=] |promise| with `false` and abort these steps.

1. [=request permission to use=] the [=powerful feature=] <a permission>"xr-session-supported"</a> with {{XRSessionSupportedPermissionDescriptor}} with {{XRSessionSupportedPermissionDescriptor/mode}} equal to |mode|. If it returns {{PermissionState/"denied"}} [=queue a task=] to [=/resolve=] |promise| with `false` and abort these steps. <span class=note>See [[#issessionsupported-fingerprinting|Fingerprinting considerations]] for more information.

1. [=queue a task=] to [=/resolve=] |promise| with `true`.

</dl>

1. Return |promise|.

Note: The purpose of {{XRSystem/isSessionSupported()}} is not to report with perfect accuracy the user agent's ability to create an {{XRSession}}, but to inform the page whether or not advertising the ability to create sessions of the given mode is advised. A certain level of false-positives are expected, even when user agent checks for the presence of the necessary hardware/software prior to resolving the method. (For example, even if the appropriate hardware is present it may have given exclusive access to another application at the time a session is requested.)

It is expected that most pages with XR content will call {{XRSystem/isSessionSupported()}} early in the document lifecycle. As such, calling {{XRSystem/isSessionSupported()}} SHOULD avoid displaying any modal or otherwise intrusive UI. Calling {{XRSystem/isSessionSupported()}} MUST NOT trigger device-selection UI, MUST NOT interfere with any running XR applications on the system, and MUST NOT cause XR-related applications to launch such as system trays or storefronts.

The following code checks to see if {{immersive-vr}} sessions are supported.

const supported = await navigator.xr.isSessionSupported('immersive-vr');

if (supported) {

// 'immersive-vr' sessions may be supported.

// Page should advertise support to the user.

} else {

// 'immersive-vr' sessions are not supported.

}

The {{XRSystem}} object has a <dfn>pending immersive session</dfn> boolean, which MUST be initially `false`, an <dfn>active immersive session</dfn>, which MUST be initially `null`, and a <dfn>list of inline sessions</dfn>, which MUST be initially empty.

The <dfn method for="XRSystem">requestSession(|mode|, |options|)</dfn> method attempts to initialize an {{XRSession}} for the given |mode| if possible, entering immersive mode if necessary.

When this method is invoked, the user agent MUST run the following steps:

1. Let |promise| be [=a new Promise=] in the [=relevant realm=] of this {{XRSystem}}.

1. Let |immersive| be `true` if |mode| is an [=immersive session=] mode, and `false` otherwise.

1. Let |global object| be the [=relevant Global object=] for the {{XRSystem}} on which this method was invoked.

1. Check whether the session request is allowed as follows:

<dl class="switch">

: If |immersive| is `true`:

::

1. Check if an [=immersive session request is allowed=] for the |global object|, and if not [=reject=] |promise| with a "{{SecurityError}}" {{DOMException}} and return |promise|.

1. If [=pending immersive session=] is `true` or [=active immersive session=] is not `null`, [=reject=] |promise| with an "{{InvalidStateError}}" {{DOMException}} and return |promise|.

1. Set [=pending immersive session=] to `true`.

: Otherwise:

:: Check if an [=inline session request is allowed=] for the |global object|, and if not [=reject=] |promise| with a "{{SecurityError}}" {{DOMException}} and return |promise|.

</dl>

1. Run the following steps [=in parallel=]:

1. Let |requiredFeatures| be |options|' {{XRSessionInit/requiredFeatures}}.

1. Let |optionalFeatures| be |options|' {{XRSessionInit/optionalFeatures}}.

1. Set |device| to the result of [=obtain the current device|obtaining the current device=] for |mode|, |requiredFeatures|, and |optionalFeatures|.

1. [=Queue a task=] to perform the following steps:

1. If |device| is `null` or |device|'s [=list of supported modes=] does not [=list/contain=] |mode|, run the following steps:

1. [=Reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}}.

1. If |immersive| is `true`, set [=pending immersive session=] to `false`.

1. Abort these steps.

1. Let |descriptor| be an {{XRPermissionDescriptor}} initialized with |mode|, |requiredFeatures|, and |optionalFeatures|

1. Let |status| be an {{XRPermissionStatus}}, initially `null`

1. [=Request the xr permission=] with |descriptor| and |status|.

1. If |status|' {{PermissionStatus/state}} is {{PermissionState/"denied"}} run the following steps:

1. [=Reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}}.

1. If |immersive| is `true`, set [=pending immersive session=] to `false`.

1. Abort these steps.

1. Let |granted| be a [=/set=] obtained from |status|' {{XRPermissionStatus/granted}}.

1. Let |session| be a [=new=] {{XRSession}} object in the [=relevant realm=] of this {{XRSystem}}.

1. [=Initialize the session=] with |session|, |mode|, |granted|, and |device|.

1. Potentially set the [=active immersive session=] as follows:

<dl class="switch">

: If |immersive| is `true`:

:: Set the [=active immersive session=] to |session|, and set [=pending immersive session=] to `false`.

: Otherwise:

:: Append |session| to the [=list of inline sessions=].

</dl>

1. [=/Resolve=] |promise| with |session|.

1. [=Queue a task=] to perform the following steps:

<div class=note>Note: These steps ensure that initial {{inputsourceschange!!event}} events occur after the initial session is resolved.</div>

1. Set |session|'s [=XRSession/promise resolved=] flag to `true`.

1. Let |sources| be any existing input sources attached to |session|.

1. If |sources| is non-empty, perform the following steps:

1. Set |session|'s [=list of active XR input sources=] to |sources|.

1. Fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/added}} set to |sources|.

1. Return |promise|.

To <dfn>obtain the current device</dfn> for an {{XRSessionMode}} |mode|, |requiredFeatures|, and |optionalFeatures| the user agent MUST run the following steps:

1. Choose |device| as follows:

<dl class="switch">

: If |mode| is an [=immersive session=] mode:

:: Set |device| to the result of [=ensure an immersive XR device is selected|ensuring an immersive XR device is selected=].

: Else if |requiredFeatures| or |optionalFeatures| are not empty:

:: Set |device| to the [=/inline XR device=].

: Otherwise:

:: Set |device| to the [=/default inline XR device=].

</dl>

1. Return |device|.

Note: These steps should always be run [=in parallel=].

The following code attempts to retrieve an {{immersive-vr}} {{XRSession}}.

const xrSession = await navigator.xr.requestSession("immersive-vr");

XRSessionMode {#xrsessionmode-enum}

-------------

The {{XRSessionMode}} enum defines the modes that an {{XRSession}} can operate in.

enum XRSessionMode {

"inline",

"immersive-vr",

"immersive-ar"

};

- A session mode of <dfn enum-value for="XRSessionMode">inline</dfn> indicates that the session's output will be shown as an element in the HTML document. {{inline}} session content MUST be displayed in mono (i.e., with a single [=view=]). It MAY allow for [=viewer=] tracking. User agents MUST allow {{inline}} sessions to be created.

- A session mode of <dfn enum-value for="XRSessionMode">immersive-vr</dfn> indicates that the session's output will be given [=exclusive access=] to the [=immersive XR device=] display and that content <b>is not</b> intended to be integrated with the user's environment.

- The behavior of the <dfn enum-value for="XRSessionMode">immersive-ar</dfn> session mode is defined in the <a href="https://www.w3.org/TR/webxr-ar-module-1/">WebXR AR Module</a> and MUST NOT be added to the [=immersive XR device=]'s [=list of supported modes=] unless the UA implements that module.

In this document, the term <dfn>inline session</dfn> is synonymous with an {{inline}} session and the term <dfn>immersive session</dfn> refers to either an {{immersive-vr}} or {{immersive-ar}} session.

[=Immersive sessions=] MUST provide some level of [=viewer=] tracking, and content MUST be shown at the proper scale relative to the user and/or the surrounding environment. Additionally, [=Immersive sessions=] MUST be given <dfn>exclusive access</dfn> to the [=immersive XR device=], meaning that while the [=immersive session=] is {{XRVisibilityState/"visible"}} the HTML document is not shown on the [=immersive XR device=]'s display, nor does content from any other source have exclusive access. [=Exclusive access=] does not prevent the user agent from overlaying its own UI, however this UI SHOULD be minimal.

Note: UA may choose to overlay content for accessibility or safety such as guardian boundaries, obstructions or the user's hands when there are no alternative input sources.

Note: Future specifications or modules may expand the definition of [=immersive session=] to include additional session modes.

Note: Examples of ways [=exclusive access=] may be presented include stereo content displayed on a virtual reality headset.

Note: As an example of overlaid UI, the user agent or operating system in an [=immersive session=] may show notifications over the rendered content.

Note: While the HTML document is not shown on the [=immersive XR device=]'s display during an [=immersive session=], it may still be shown on a separate display, e.g. when the user is entering the [=immersive session=] from a 2d browser on their computer tethered to their [=immersive XR device=].

Feature Dependencies {#feature-dependencies}

--------------------

Some features of an {{XRSession}} may not be universally available for a number of reasons, among which is the fact not all XR devices can support the full set of features. Another consideration is that some features expose [=sensitive information=] which may require a clear signal of [=user intent=] before functioning.

Since it is a poor user experience to initialize the underlying XR platform and create an {{XRSession}} only to immediately notify the user that the applications cannot function correctly, developers can indicate <dfn>required features</dfn> by passing an {{XRSessionInit}} dictionary to {{XRSystem/requestSession()}}. This will block the creation of the {{XRSession}} if any of the [=required features=] are unavailable due to device limitations or in the absence of a clear signal of [=user intent=] to expose [=sensitive information=] related to the feature.

Additionally, developers are encouraged to design experiences which progressively enhance their functionality when run on more capable devices. <dfn>Optional features</dfn> which the experience does not require but will take advantage of when available must also be indicated in an {{XRSessionInit}} dictionary to ensure that [=user intent=] can be determined before enabling the feature if necessary.

dictionary XRSessionInit {

sequence&lt;DOMString&gt; requiredFeatures;

sequence&lt;DOMString&gt; optionalFeatures;

};

The <dfn dict-member for="XRSessionInit">requiredFeatures</dfn> array contains any [=Required features=] for the experience. If any value in the list is not a recognized [=feature descriptor=] the {{XRSession}} will not be created. If any feature listed in the {{XRSessionInit/requiredFeatures}} array is not supported by the [=XRSession/XR device=] or, if necessary, has not received a clear signal of [=user intent=] the {{XRSession}} will not be created.

The <dfn dict-member for="XRSessionInit">optionalFeatures</dfn> array contains any [=Optional features=] for the experience. If any value in the list is not a recognized [=feature descriptor=] it will be ignored. Features listed in the {{XRSessionInit/optionalFeatures}} array will be enabled if supported by the [=XRSession/XR device=] and, if necessary, given a clear signal of [=user intent=], but will not block creation of the {{XRSession}} if absent.

Values given in the feature lists are considered a valid <dfn>feature descriptor</dfn> if the value is one of the following:

- The string representation of any {{XRReferenceSpaceType}} enum value

Future iterations of this specification and additional modules may expand the list of accepted [=feature descriptors=].

Note: If a feature needs additional initialization, {{XRSessionInit}} should be extended with a new field for that feature.

Depending on the {{XRSessionMode}} requested, certain [=feature descriptors=] are added to the {{XRSessionInit/requiredFeatures}} or {{XRSessionInit/optionalFeatures}} lists by default. The following table describes the <dfn>default features</dfn> associated with each session type and feature list:

<thead>

<tr>

<th>Feature</th>

<th>Sessions</th>

<th>List</th>

</tr>

</thead>

<tbody>

<tr>

<td>{{XRReferenceSpaceType/"viewer"}}</td>

<td>[=Inline sessions=] and [=immersive sessions=]</td>

<td>{{XRSessionInit/requiredFeatures}}</td>

</tr>

<tr>

<td>{{XRReferenceSpaceType/"local"}}</td>

<td>[=Immersive sessions=]</td>

<td>{{XRSessionInit/requiredFeatures}}</td>

</tr>

</tbody>

The combined list of [=feature descriptors=] given by the {{XRSessionInit/requiredFeatures}} and {{XRSessionInit/optionalFeatures}} are collectively considered the <dfn>requested features</dfn> for an {{XRSession}}.

Some [=feature descriptors=], when present in the [=requested features=] list, are subject to [[#permissions-policy|permissions policy]] and/or requirements that [=user intent=] to use the feature is well understood, via either [=explicit consent=] or [=implicit consent=]. The following table describes the <dfn>feature requirements</dfn> that must be satisfied prior to being enabled:

<thead>

<tr>

<th>Feature</th>

<th>[=Permissions Policy=] Required</th>

<th>Consent Required</th>

</tr>

</thead>

<tbody>

<tr>

<td>{{XRReferenceSpaceType/"local"}}</td>

<td>"xr-spatial-tracking"</td>

<td>[=Inline sessions=] require consent</td>

</tr>

<tr>

<td>{{XRReferenceSpaceType/"local-floor"}}</td>

<td>"xr-spatial-tracking"</td>

<td>Always requires consent</td>

</tr>

<tr>

<td>{{XRReferenceSpaceType/"bounded-floor"}}</td>

<td>"xr-spatial-tracking"</td>

<td>Always requires consent</td>

</tr>

<tr>

<td>{{XRReferenceSpaceType/"unbounded"}}</td>

<td>"xr-spatial-tracking"</td>

<td>Always requires consent</td>

</tr>

</tbody>

Note: {{XRReferenceSpaceType/"local"}} is always included in the [=requested features=] of [=immersive sessions=] as a [=default feature=], and as such [=immersive sessions=] always need to obtain [=explicit consent=] or [=implicit consent=].

[=Requested features=] can only be enabled for a session if the [=XRSession/XR device=] is <dfn>capable of supporting</dfn> the feature, which means that the feature is known to be supported by the [=XRSession/XR device=] in some configurations, even if the current configuration has not yet been verified as supporting the feature. The user agent MAY apply more rigorous constraints if desired in order to yield a more consistent user experience.

Note: For example, several VR devices support either configuring a safe boundary for the user to move around within or skipping boundary configuration and operating in a mode where the user is expected to stand in place. Such a device can be considered to be [=capable of supporting=] {{"bounded-floor"}} {{XRReferenceSpace}}s even if they are currently not configured with safety boundaries, because it's expected that the user could configure the device appropriately if the experience required it. This is to allow user agents to avoid fully initializing the [=XRSession/XR device=] or waiting for the user's environment to be recognized prior to [=resolve the requested features|resolving the requested features=] if desired. If, however, the user agent knows the boundary state at the time the session is requested without additional initialization it may choose to reject the {{"bounded-floor"}} feature if the safety boundary is not already configured.

Session {#session}

=======

XRSession {#xrsession-interface}

---------

Any interaction with XR hardware is done via an {{XRSession}} object, which can only be retrieved by calling {{XRSystem/requestSession()}} on the {{XRSystem}} object. Once a session has been successfully acquired, it can be used to {{XRFrame/getViewerPose()|poll the viewer pose}}, query information about the user's environment, and present imagery to the user.

The user agent, when possible, <dfn>SHOULD NOT initialize device tracking</dfn> or rendering capabilities until an {{XRSession}} has been acquired. This is to prevent unwanted side effects of engaging the XR systems when they're not actively being used, such as increased battery usage or related utility applications from appearing when first navigating to a page that only wants to test for the presence of XR hardware in order to advertise XR features. Not all XR platforms offer ways to detect the hardware's presence without initializing tracking, however, so this is only a strong recommendation.

enum XRVisibilityState {

"visible",

"visible-blurred",

"hidden",

};

[SecureContext, Exposed=Window] interface XRSession : EventTarget {

// Attributes

readonly attribute XRVisibilityState visibilityState;

readonly attribute float? frameRate;

readonly attribute Float32Array? supportedFrameRates;

[SameObject] readonly attribute XRRenderState renderState;

[SameObject] readonly attribute XRInputSourceArray inputSources;

[SameObject] readonly attribute XRInputSourceArray trackedSources;

readonly attribute FrozenArray&lt;DOMString&gt; enabledFeatures;

readonly attribute boolean isSystemKeyboardSupported;

// Methods

undefined updateRenderState(optional XRRenderStateInit state = {});

Promise&lt;undefined&gt; updateTargetFrameRate(float rate);

[NewObject] Promise&lt;XRReferenceSpace&gt; requestReferenceSpace(XRReferenceSpaceType type);

unsigned long requestAnimationFrame(XRFrameRequestCallback callback);

undefined cancelAnimationFrame(unsigned long handle);

Promise&lt;undefined&gt; end();

// Events

attribute EventHandler onend;

attribute EventHandler oninputsourceschange;

attribute EventHandler onselect;

attribute EventHandler onselectstart;

attribute EventHandler onselectend;

attribute EventHandler onsqueeze;

attribute EventHandler onsqueezestart;

attribute EventHandler onsqueezeend;

attribute EventHandler onvisibilitychange;

attribute EventHandler onframeratechange;

};

Each {{XRSession}} has a <dfn for="XRSession">mode</dfn>, which is one of the values of {{XRSessionMode}}.

Each {{XRSession}} has an <dfn for=XRSession>animation frame</dfn>, which is an {{XRFrame}} initialized with [=XRFrame/active=] set to `false`, [=XRFrame/animationFrame=] set to `true`, and {{XRFrame/session}} set to the {{XRSession}}.

Each {{XRSession}} has a <dfn for=XRSession>set of granted features</dfn>, which is a [=/set=] of {{DOMString}}s corresponding to the [=feature descriptors=] that have been granted to the {{XRSession}}.

The <dfn attribute for="XRSession">enabledFeatures</dfn> attribute returns the features in the [=XRSession/set of granted features=] as a new array of {{DOMString}}s.

The <dfn attribute for="XRSession">isSystemKeyboardSupported</dfn> attribute indicates that the {{XRSystem}} has the ability to display the system keyboard while the {{XRSession}} is active. If {{XRSession/isSystemKeyboardSupported}} is <code>true</code>, Web APIs that would trigger the overlay keyboard (such as [=focus=]) will show the system keyboard. The {{XRSession}} MUST set the [=visibility state=] of the {{XRSession}} to {{XRVisibilityState/"visible-blurred"}} while the keyboard is shown.

To <dfn>initialize the session</dfn>, given |session|, |mode|, |granted|, and |device|, the user agent MUST run the following steps:

1. Set |session|'s [=XRSession/mode=] to |mode|.

1. Set |session|'s [=XRSession/XR device=] to |device|.

1. Set |session|'s [=XRSession/set of granted features=] to |granted|.

1. [=Initialize the render state=].

1. If no other features of the user agent have done so already, perform the necessary platform-specific steps to initialize the device's tracking and rendering capabilities, including showing any necessary instructions to the user.

Note: Some devices require additional user instructions for activation. For example, going into immersive mode on a phone-based headset device requires inserting the phone into the headset, and doing so on a desktop browser connected to an external headset requires wearing the headset. It is the responsibility of the user agent &mdash; not the author &mdash; to ensure any such instructions are shown.

A number of different circumstances may <dfn>shut down the session</dfn>, which is permanent and irreversible. Once a session has been shut down the only way to access the [=XRSession/XR device=]'s tracking or rendering capabilities again is to request a new session. Each {{XRSession}} has an <dfn>ended</dfn> boolean, initially set to `false`, that indicates if it has been shut down.

When an {{XRSession}} |session| is shut down the following steps are run:

1. Set |session|'s [=ended=] value to `true`.

1. If the [=active immersive session=] is equal to |session|, set the [=active immersive session=] to `null`.

1. Remove |session| from the [=list of inline sessions=].

1. [=Reject=] any outstanding promises returned by |session| with an {{InvalidStateError}}, except for any promises returned by {{XRSession/end()}}.

1. If no other features of the user agent are actively using them, perform the necessary platform-specific steps to shut down the device's tracking and rendering capabilities. This MUST include:

- Releasing [=exclusive access=] to the [=XRSession/XR device=] if |session| is an [=immersive session=].

- Deallocating any graphics resources acquired by |session| for presentation to the [=XRSession/XR device=].

- Putting the [=XRSession/XR device=] in a state such that a different source may be able to initiate a session with the same device if |session| is an [=immersive session=].

1. [=Queue a task=] that fires an {{XRSessionEvent}} named {{end!!event}} on |session|.

The <dfn method for="XRSession">end()</dfn> method provides a way to manually shut down a session. When invoked, it MUST run the following steps:

1. Let |promise| be [=a new Promise=] in the [=relevant realm=] of this {{XRSession}}.

1. If the [=ended=] value of [=this=] is `true`, [=reject=] |promise| with a "{{InvalidStateError}}" {{DOMException}} and return |promise|.

1. [=Shut down the session|Shut down=] [=this=].

1. [=Queue a task=] to perform the following steps:

1. Wait until any platform-specific steps related to shutting down the session have completed.

1. [=/Resolve=] |promise|.

1. Return |promise|.

Each {{XRSession}} has an <dfn>active render state</dfn> which is a new {{XRRenderState}}, and a <dfn>pending render state</dfn>, which is an {{XRRenderState}} which is initially `null`.

The <dfn attribute for="XRSession">renderState</dfn> attribute returns the {{XRSession}}'s [=active render state=].

Each {{XRSession}} has a <dfn>minimum inline field of view</dfn> and a <dfn>maximum inline field of view</dfn>, defined in radians. The values MUST be determined by the user agent and MUST fall in the range of `0` to `PI`.

Each {{XRSession}} has a <dfn>minimum near clip plane</dfn> and a <dfn>maximum far clip plane</dfn>, defined in meters. The values MUST be determined by the user agent and MUST be non-negative. The [=minimum near clip plane=] SHOULD be less than `0.1`. The [=maximum far clip plane=] SHOULD be greater than `1000.0` (and MAY be infinite).

When the user agent will <dfn>update the pending layers state</dfn> with {{XRSession}} <var ignore>session</var> and {{XRRenderStateInit}} |newState|, it must run the following steps:

1. If |newState|'s {{XRRenderStateInit/layers}}'s value is not `null`, throw a {{NotSupportedError}}.

NOTE: The <a href="https://www.w3.org/TR/webxrlayers-1/">WebXR layers module</a> will introduce new semantics for this algorithm.

When the user agent wants to <dfn>apply the nominal frame rate</dfn> |rate| on an {{XRSession}} |session|, it MUST run the following steps:

1. If |rate| is the same as |session|'s [=XRSession/internal nominal framerate=], abort these steps.

1. If |session|’s [=ended=] value is `true`, abort these steps.

1. Set |session|'s [=XRSession/internal nominal framerate=] to |rate|.

1. Fire an {{XRSessionEvent}} event named {{frameratechange!!event}} on |session|.

The <dfn method for="XRSession">updateTargetFrameRate(|rate|)</dfn> method passes the [=target frame rate=] |rate| to the {{XRSession}}.

When this method is invoked, the user agent MUST run the following steps:

1. Let |session| be [=this=].

1. Let |promise| be [=a new Promise=] in the [=relevant realm=] of |session|.

1. If the |session| has no [=XRSession/internal nominal framerate=], [=reject=] |promise| with an "{{InvalidStateError}}" {{DOMException}} and return |promise|.

1. If |session|'s [=ended=] value is `true`, [=reject=] |promise| with an "{{InvalidStateError}}" {{DOMException}} and return |promise|.

1. If |rate| is not in {{XRSession/supportedFrameRates}}, [=reject=] |promise| with an "{{TypeError}}" {{DOMException}} and return |promise|.

1. Set |session|'s [=XRSession/internal target framerate=] to |rate|.

1. [=Queue a task=] to perform the following steps:

1. The [=XR Compositor=] MAY use |rate| to calculate a new [=display frame rate=] and/or [=nominal frame rate=].

1. Let |newrate| be the new [=nominal frame rate=].

1. [=Queue a task=] to perform the following steps:

1. Await until the {{XRSystem}}'s actions to update the [=nominal frame rate=] to |newrate| have taken effect.

1. [=Apply the nominal frame rate=] with |newrate| and |session|.

1. [=/Resolve=] |promise|.

1. Return |promise|.

If the [=XR Compositor=] changes the [=nominal frame rate=] for any reason (for example during a {{XRVisibilityState/"visible-blurred"}} event), it SHOULD use the [=XRSession/internal target framerate=] once the event that caused the frame rate change has ended.

The <dfn method for="XRSession">updateRenderState(|newState|)</dfn> method queues an update to the [=active render state=] to be applied on the next frame. Unset fields of the {{XRRenderStateInit}} |newState| passed to this method will not be changed.

When this method is invoked, the user agent MUST run the following steps:

1. Let |session| be [=this=].

1. If |session|'s [=ended=] value is `true`, throw an {{InvalidStateError}} and abort these steps.

1. If |newState|'s {{XRRenderStateInit/baseLayer}} was created with an {{XRSession}} other than |session|, throw an {{InvalidStateError}} and abort these steps.

1. If |newState|'s {{XRRenderStateInit/inlineVerticalFieldOfView}} is set and |session| is an [=immersive session=], throw an {{InvalidStateError}} and abort these steps.

1. If none of |newState|'s {{XRRenderStateInit/depthNear}}, {{XRRenderStateInit/depthFar}}, {{XRRenderStateInit/inlineVerticalFieldOfView}}, {{XRRenderStateInit/baseLayer}}, {{XRRenderStateInit/layers}} are set, abort these steps.

1. Run [=update the pending layers state=] with |session| and |newState|.

1. Let |activeState| be |session|'s [=active render state=].

1. If |session|'s [=pending render state=] is `null`, set it to a copy of |activeState|.

1. If |newState|'s {{XRRenderStateInit/depthNear}} value is set, set |session|'s [=pending render state=]'s {{XRRenderState/depthNear}} to |newState|'s {{XRRenderStateInit/depthNear}}.

1. If |newState|'s {{XRRenderStateInit/depthFar}} value is set, set |session|'s [=pending render state=]'s {{XRRenderState/depthFar}} to |newState|'s {{XRRenderStateInit/depthFar}}.

1. If |newState|'s {{XRRenderStateInit/inlineVerticalFieldOfView}} is set, set |session|'s [=pending render state=]'s {{XRRenderState/inlineVerticalFieldOfView}} to |newState|'s {{XRRenderStateInit/inlineVerticalFieldOfView}}.

1. If |newState|'s {{XRRenderStateInit/baseLayer}} is set, set |session|'s [=pending render state=]'s {{XRRenderState/baseLayer}} to |newState|'s {{XRRenderStateInit/baseLayer}}.

When requested, the {{XRSession}} |session| MUST <dfn>apply the pending render state</dfn> by running the following steps:

1. Let |activeState| be |session|'s [=active render state=].

1. Let |newState| be |session|'s [=pending render state=].

1. Set |session|'s [=pending render state=] to `null`.

1. Let |oldBaseLayer| be |activeState|'s {{XRRenderState/baseLayer}}.

1. Let |oldLayers| be |activeState|'s {{XRRenderState/layers}}.

1. [=Queue a task=] to perform the following steps:

1. Set |activeState| to |newState|.

1. If |oldBaseLayer| is not equal to |activeState|'s {{XRRenderState/baseLayer}}, |oldLayers| is not equal to |activeState|'s {{XRRenderState/layers}}, or the dimensions of any of the layers have changed, [=update the viewports=] for |session|.

1. If |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} is less than |session|'s [=minimum inline field of view=] set |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} to |session|'s [=minimum inline field of view=].

1. If |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} is greater than |session|'s [=maximum inline field of view=] set |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} to |session|'s [=maximum inline field of view=].

1. If |activeState|'s {{XRRenderState/depthNear}} is less than |session|'s [=minimum near clip plane=] set |activeState|'s {{XRRenderState/depthNear}} to |session|'s [=minimum near clip plane=].

1. If |activeState|'s {{XRRenderState/depthFar}} is greater than |session|'s [=maximum far clip plane=] set |activeState|'s {{XRRenderState/depthFar}} to |session|'s [=maximum far clip plane=].

1. Let |baseLayer| be |activeState|'s {{XRRenderState/baseLayer}}.

1. Set |activeState|'s [=XRRenderState/composition enabled=] and [=XRRenderState/output canvas=] as follows:

<dl class="switch">

: If |session|'s [=XRSession/mode=] is {{XRSessionMode/"inline"}} and |baseLayer| is an instance of an {{XRWebGLLayer}} with [=XRWebGLLayer/composition enabled=] set to `false`:

:: Set |activeState|'s [=XRRenderState/composition enabled=] boolean to `false`.

:: Set |activeState|'s [=XRRenderState/output canvas=] to |baseLayer|'s [=XRWebGLLayer/context=]'s {{WebGLRenderingContext|canvas}}.

: Otherwise:

:: Set |activeState|'s [=XRRenderState/composition enabled=] boolean to `true`.

:: Set |activeState|'s [=XRRenderState/output canvas=] to `null`.

</dl>

The <dfn method for="XRSession">requestReferenceSpace(|type|)</dfn> method constructs a new {{XRReferenceSpace}} of a given |type|, if possible.

When this method is invoked, the user agent MUST run the following steps:

1. Let |promise| be [=a new Promise=] in the [=relevant realm=] of this {{XRSession}}.

1. Run the following steps [=in parallel=]:

1. If the result of running [=reference space is supported=] for |type| and |session| is `false`, [=queue a task=] to [=reject=] |promise| with a {{NotSupportedError}} and abort these steps.

1. Set up any platform resources required to track reference spaces of type |type|.

<div class=note>User agents need not wait for tracking to be established for such reference spaces to resolve {{XRSession/requestReferenceSpace()}}. It is okay for {{XRFrame/getViewerPose()}} to return `null` when the session is initially attempting to establish tracking, and content can use this time to show a splash screen or something else. Note that if |type| is {{XRReferenceSpaceType/"bounded-floor"}}, and the bounds have not yet been established, user agents MAY set the bounds to a small initial area and use a {{reset}} event when bounds are established.</div>

1. [=Queue a task=] to run the following steps:

1. [=Create a reference space=], |referenceSpace|, with |type| and |session|.

1. [=/Resolve=] |promise| with |referenceSpace|.

1. Return |promise|.

Each {{XRSession}} has a <dfn>list of active XR input sources</dfn> (a [=/list=] of {{XRInputSource}}) and a <dfn>list of active XR tracked sources</dfn> (a [=/list=] of {{XRInputSource}}) which MUST both be initially an empty [=/list=].

Each {{XRSession}} has an <dfn for="XRSession">XR device</dfn>, which is an [=/XR device=] set at initialization.

The <dfn attribute for="XRSession">inputSources</dfn> attribute returns the {{XRSession}}'s [=list of active XR input sources=].

The <dfn attribute for="XRSession">trackedSources</dfn> attribute returns the {{XRSession}}'s [=list of active XR tracked sources=].

The user agent MUST monitor any [=XR input source=]s associated with the [=XRSession/XR device=], including detecting when [=XR input source=]s are added, removed, or changed.

Each {{XRSession}} has a <dfn for=XRSession>promise resolved</dfn> flag, initially `false`.

NOTE: The purpose of this flag is to ensure that the [=XRSession/add input source=], [=XRSession/remove input source=], and [=XRSession/change input source=] algorithms do not run until the user code actually has had a chance to attach event listeners. Implementations may not need this flag if they simply choose to start listening for input source changes after the session resolves.

When <dfn for="XRSession" lt="add input source">new [=XR input source=]s become available</dfn> for {{XRSession}} |session|, the user agent MUST run the following steps:

1. If |session|'s [=XRSession/promise resolved=] flag is not set, abort these steps.

1. Let |added primary sources| be a new [=/list=].

1. Let |added tracked sources| be a new [=/list=].

1. For each new [=XR input source=]:

1. Let |inputSource| be a [=new=] {{XRInputSource}} in the [=relevant realm=] of this {{XRSession}}, then perform the following step:

<dl class="switch">

: If |inputSource| is a [=primary input source=]:

::

Add |inputSource| to |added primary sources|.

: Otherwise:

::

Add |inputSource| to |added tracked sources|.

</dl>

1. [=Queue a task=] to perform the following steps:

1. [=list/Extend=] |session|'s [=list of active XR input sources=] with |added primary sources|.

1. If |added primary sources| is not empty, fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/added}} set to |added primary sources|.

1. [=list/Extend=] |session|'s [=list of active XR tracked sources=] with |added tracked sources|.

1. If |added tracked sources| is not empty, fire an {{XRInputSourcesChangeEvent}} named {{trackedsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/added}} set to |added tracked sources|.

When any previously added <dfn for="XRSession" lt="remove input source">[=XR input source=]s are no longer available</dfn> for {{XRSession}} |session|, the user agent MUST run the following steps:

1. If |session|'s [=XRSession/promise resolved=] flag is not set, abort these steps.

1. Let |removed primary sources| be a new [=/list=].

1. Let |removed tracked sources| be a new [=/list=].

1. For each [=XR input source=] that is no longer available:

1. Let |inputSource| be the {{XRInputSource}} in |session|'s [=list of active XR input sources=] associated with the [=XR input source=], then perform the following step:

<dl class="switch">

: If |inputSource| is a [=primary input source=]:

::

Add |inputSource| to |removed primary sources|.

: Otherwise:

::

Add |inputSource| to |removed tracked sources|.

</dl>

1. [=Queue a task=] to perform the following steps:

1. [=list/Remove=] each {{XRInputSource}} in |removed primary sources| from |session|'s [=list of active XR input sources=].

1. If |removed primary sources| is not empty, fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/removed}} set to |removed primary sources|.

1. [=list/Remove=] each {{XRInputSource}} in |removed tracked sources| from |session|'s [=list of active XR tracked sources=].

1. If |removed tracked sources| is not empty, fire an {{XRInputSourcesChangeEvent}} named {{trackedsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/removed}} set to |removed tracked sources|.

Note: The user agent MAY fire this event when an input source temporarily loses both position and orientation tracking. It is recommended that this only be done for physical handheld controller input sources. It is not recommended that this event be fired when this happens for tracked hand input sources, because this will happen often, nor is it recommended when this happens for tracker object input sources, since this makes it harder for the application to maintain a notion of identity.

When the <dfn for="XRSession" export lt="change input source">{{XRInputSource/handedness}}, {{XRInputSource/targetRayMode}}, {{XRInputSource/profiles}}, presence of a {{XRInputSource/gripSpace}} or the status as a [=primary input source=] or [=tracked input source=] for any [=XR input source=]s change</dfn> for {{XRSession}} |session|, the user agent MUST run the following steps:

1. If |session|'s [=XRSession/promise resolved=] flag is not set, abort these steps.

1. Let |added primary sources| be a new [=/list=].

1. Let |removed primary sources| be a new [=/list=].

1. Let |added tracked sources| be a new [=/list=].

1. Let |removed tracked sources| be a new [=/list=].

1. For each changed [=XR input source=]:

1. Let |oldInputSource| be the {{XRInputSource}} in |session|'s [=list of active XR input sources=] previously associated with the [=XR input source=], then perform the following step:

<dl class="switch">

: If |oldInputSource| is a [=primary input source=] or its state changed from a [=primary input source=] to [=tracked input source=] a:

::

Add |oldInputSource| to |removed primary sources|.

: Otherwise:

::

Add |oldInputSource| to |removed tracked sources|.

</dl>

1. Let |newInputSource| be a [=new=] {{XRInputSource}} in the [=relevant realm=] of |session|, then perform the following step:

<dl class="switch">

: If |newInputSource| is a [=primary input source=] or its state changed from a [=tracked input source=] to [=primary input source=] :

::

Add |newInputSource| to |added primary sources|.

: Otherwise:

::

Add |newInputSource| to |added tracked sources|.

</dl>

1. [=Queue a task=] to perform the following steps:

1. [=list/Remove=] each {{XRInputSource}} in |removed primary sources| from |session|'s [=list of active XR input sources=].

1. [=list/Extend=] |session|'s [=list of active XR input sources=] with |added primary sources|.

1. If |added primary sources| or |removed primary sources| are not empty, fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with{{XRInputSourcesChangeEvent/added}} set to |added primary sources| and {{XRInputSourcesChangeEvent/removed}} set to |removed primary sources|.

1. [=list/Remove=] each {{XRInputSource}} in |removed tracked sources| from |session|'s [=list of active XR tracked sources=].

1. [=list/Extend=] |session|'s [=list of active XR input sources=] with |added tracked sources|.

1. If |added tracked sources| or |removed tracked sources| are not empty, fire an {{XRInputSourcesChangeEvent}} named {{trackedsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/added}} set to |added tracked sources| and {{XRInputSourcesChangeEvent/removed}} set to |removed tracked sources|.

Each {{XRSession}} has a <dfn for="XRSession">visibility state</dfn> value, which is an enum. For [=inline sessions=] the [=XRSession/visibility state=] MUST mirror the {{Document}}'s [=Document/visibilityState=]. For [=immersive sessions=] the [=XRSession/visibility state=] MUST be set to whichever of the following values best matches the state of session.

- A state of <dfn enum-value for="XRVisibilityState">visible</dfn> indicates that imagery rendered by the {{XRSession}} can be seen by the user and {{XRSession/requestAnimationFrame()}} callbacks are processed at the [=XRSession/XR device=]'s native refresh rate. Input is processed by the {{XRSession}} normally.

- A state of <dfn enum-value for="XRVisibilityState">visible-blurred</dfn> indicates that imagery rendered by the {{XRSession}} may be seen by the user, but is not the primary focus. {{XRSession/requestAnimationFrame()}} callbacks MAY be [=throttling|throttled=]. Input is not processed by the {{XRSession}}.

- A state of <dfn enum-value for="XRVisibilityState">hidden</dfn> indicates that imagery rendered by the {{XRSession}} cannot be seen by the user. {{XRSession/requestAnimationFrame()}} callbacks will not be processed until the [=visibility state=] changes. Input is not processed by the {{XRSession}}.

The <dfn attribute for="XRSession">visibilityState</dfn> attribute returns the {{XRSession}}'s [=visibility state=]. The <dfn attribute for="XRSession">onvisibilitychange</dfn> attribute is an [=Event handler IDL attribute=] for the {{visibilitychange}} event type.

The [=visibility state=] MAY be changed by the user agent at any time other than during the processing of an [=XR animation frame=], and the user agent SHOULD monitor the XR platform when possible to observe when session visibility has been affected external to the user agent and update the [=visibility state=] accordingly.

Note: The {{XRSession}}'s [=visibility state=] does not necessarily imply the visibility of the HTML document. Depending on the system configuration the page may continue to be visible while an [=immersive session=] is active. (For example, a headset connected to a PC may continue to display the page on the monitor while the headset is viewing content from an [=immersive session=].) Developers should continue to rely on the [Page Visibility](https://html.spec.whatwg.org/multipage/interaction.html#page-visibility) to determine page visibility.

Note: The {{XRSession}}'s [=visibility state=] does not affect or restrict mouse behavior on tethered sessions where 2D content is still visible while an [=immersive session=] is active. Content should consider using the [[!pointerlock]] API if it wishes to have stronger control over mouse behavior.

In an {{XRSystem}}, there are several definitions which can describe a frame rate:

- The <dfn>nominal frame rate</dfn>: the rate at which the {{XRSystem}} is asking the experience to render frames to maintain nominal performance. Experiences that miss frames may not end up actually getting calls to {{requestAnimationFrame()}} this many times per second, but that is what the {{XRSystem}} is aiming to achieve.

- The <dfn>effective frame rate</dfn>: a performance measurement of how many calls to {{requestAnimationFrame()}} the experience is actually managing to process each second. This will fluctuate based on the experience hitting or missing the {{XRSystem}}'s frame timing.

- The <dfn>target frame rate</dfn>: the experience's hint to the {{XRSystem}} on what [=nominal frame rate=] it prefers to target.

- The <dfn>display frame rate</dfn>: the actual rate at which frames are drawn to the physical display, which MAY be derived from the experience's [=nominal frame rate=]. This is a hardware implementation detail that is not exposed to the experience.

Each {{XRSession}} MAY have an <dfn for="XRSession">internal target frameRate</dfn> which is the [=target frame rate=].

Each {{XRSession}} MAY have an <dfn for="XRSession">internal nominal frameRate</dfn> which is the [=nominal frame rate=]. If the [=effective frame rate=] is lower than the [=nominal frame rate=], the [=XR Compositor=] MAY use reprojection or other techniques to improve the experience. It is optional and MUST NOT be present for {{XRSessionMode/inline}} sessions.

The <dfn attribute for="XRSession">frameRate</dfn> attribute reflects the [=XRSession/internal nominal framerate=]. If the {{XRSession}} has no [=XRSession/internal nominal framerate=], return `null`.

The <dfn attribute for="XRSession">onframeratechange</dfn> attribute is an [=Event handler IDL attribute=] for the {{frameratechange}} event type. If {{XRSession}}'s [=nominal frame rate=] is changed for any reason, it MUST [=apply the nominal frame rate=] with the new nominal frame rate and the {{XRSession}}.

The <dfn attribute for="XRSession">supportedFrameRates</dfn> attribute returns a list of supported [=target frame rate=] values. This attribute is optional and MUST NOT be present for {{XRSessionMode/inline}} sessions or for an {{XRSystem}} that doesn't let the author control the frame rate. If the {{XRSession}} supports the {{XRSession/supportedFrameRates}} attribute, it also MUST support {{XRSession/frameRate}}.

Each {{XRSession}} has a <dfn for="XRSession">viewer reference space</dfn>, which is an {{XRReferenceSpace}} of type {{XRReferenceSpaceType/"viewer"}} with an [=identity transform=] [=XRSpace/origin offset=].

Each {{XRSession}} has a <dfn for="XRSession">list of views</dfn>, which is a [=/list=] of [=view=]s corresponding to the views provided by the [=XRSession/XR device=]. If the {{XRSession}}'s {{XRSession/renderState}}'s [=XRRenderState/composition enabled=] boolean is set to `false` the [=list of views=] MUST contain a single [=view=]. The [=XRSession/list of views=] is immutable during the {{XRSession}} and MUST contain any [=views=] that may be surfaced during the session, including [=secondary views=] that may not initially be [=view/active=].

The <dfn attribute for="XRSession">onend</dfn> attribute is an [=Event handler IDL attribute=] for the {{end}} event type.

The <dfn attribute for="XRSession">oninputsourceschange</dfn> attribute is an [=Event handler IDL attribute=] for the {{inputsourceschange}} event type.

The <dfn attribute for="XRSession">onselectstart</dfn> attribute is an [=Event handler IDL attribute=] for the {{XRSession/selectstart}} event type.

The <dfn attribute for="XRSession">onselectend</dfn> attribute is an [=Event handler IDL attribute=] for the {{selectend}} event type.

The <dfn attribute for="XRSession">onselect</dfn> attribute is an [=Event handler IDL attribute=] for the {{XRSession/select}} event type.

The <dfn attribute for="XRSession">onsqueezestart</dfn> attribute is an [=Event handler IDL attribute=] for the {{squeezestart}} event type.

The <dfn attribute for="XRSession">onsqueezeend</dfn> attribute is an [=Event handler IDL attribute=] for the {{squeezeend}} event type.

The <dfn attribute for="XRSession">onsqueeze</dfn> attribute is an [=Event handler IDL attribute=] for the {{XRSession/squeeze}} event type.

XRRenderState {#xrrenderstate-interface}

-------------

An {{XRRenderState}} represents a set of configurable values which affect how an {{XRSession}}'s output is composited. The [=active render state=] for a given {{XRSession}} can only change between frame boundaries, and updates can be queued up via {{XRSession/updateRenderState()}}.

dictionary XRRenderStateInit {

double depthNear;

double depthFar;

double inlineVerticalFieldOfView;