spec:infra;

type:dfn; text:string

urlPrefix: https://www.w3.org/TR/hr-time/

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

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: typedef; text: INVALID_OPERATION; url: WebGLRenderingContextBase

type: typedef; text: INVALID_FRAMEBUFFER_OPERATION; url: WebGLRenderingContextBase

type: typedef; text: FRAMEBUFFER_UNSUPPORTED; url: WebGLRenderingContextBase

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: getRenderbufferParameter; url: 5.14.7

type: method; text: checkFramebufferStatus; url: 5.14.6

type: dictionary; text: WebGLContextAttributes; url: WebGLContextAttributes

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

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

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

type: interface; text: WebGL2RenderingContext; url: WebGL2RenderingContext

urlPrefix: https://w3c.github.io/orientation-sensor/; spec: ORIENTATION-SENSOR

type: interface; text: AbsoluteOrientationSensor

type: interface; text: RelativeOrientationSensor

spec: WebIDL; urlPrefix: https://www.w3.org/TR/WebIDL-1/#

type: dfn

text: invoke the Web IDL callback function; url:es-invoking-callback-functions

.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;

}

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 formfactors.

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 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 for 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 it's position.

Application flow {#applicationflow}

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

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

* Query {{XR/supportsSessionMode()|navigator.xr.supportsSessionMode()}} 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 user to [=triggered by user activation|trigger a user activation event=] indicating they want to begin viewing XR content.

* Request an {{XRSession}} within the user activation event with {{XR/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 [=/XR device=] in response.

* Continue running the [[#frame|frame loop]] until the UA [=end the session|ends the session=] 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 imagery to the user. 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=] "<code>inline</code>" and all the other enumeration values of {{XRSessionMode}} that the [=/XR device=] supports.

Initialization {#initialization}

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

navigator.xr {#navigator-xr-attribute}

----

partial interface Navigator {

[SecureContext, SameObject] readonly attribute XR xr;

};

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

XR {#xr-interface}

----

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

// Methods

Promise&lt;void&gt; supportsSessionMode(XRSessionMode mode);

Promise&lt;XRSession&gt; requestSession(optional XRSessionCreationOptions parameters);

// Events

attribute EventHandler ondevicechange;

};

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

An {{XR}} 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.

An {{XR}} object has a <dfn>list of XR devices</dfn> (a [=/list=] of [=/XR device=]), which MUST be initially an empty [=/list=].

An {{XR}} object has an <dfn for=XR>XR device</dfn> (null or [=/XR device=]) which is initially null and represents the active [=/XR device=] from the [=list of XR devices=].

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

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

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

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

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

1. If there are any active {{XRSession}}s and the [=list of XR devices=] [=list/contains=] |oldDevice|, set the [=XR/XR device=] to |oldDevice|.

1. Else, set the [=XR/XR device=] to a device of the user agent's choosing.

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

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

1. Set the [=XR compatible=] boolean of all {{WebGLRenderingContextBase}} instances to `false`.

1. [=Queue a task=] that fires a simple event named {{devicechange!!event}} on the [=context object=].

NOTE: The user agent is allowed to use any criteria it wishes to [=select an XR device=] when the [=list of 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 <dfn>ensures an XR device is selected</dfn> by running the following steps:

1. If the [=context object=]'s [=XR/XR device=] is not null, abort these steps.

1. [=Enumerate XR devices=].

1. [=Select an XR device=].

The <dfn attribute for="XR">ondevicechange</dfn> attribute is an [=Event handler IDL attribute=] for the {{devicechange}} event type.

When the <dfn method for="XR">supportsSessionMode(|mode|)</dfn> method is invoked, it MUST return [=a new Promise=] |promise| and run the following steps [=in parallel=]:

1. [=ensures an XR device is selected|Ensure an XR device is selected=].

1. If the [=XR/XR device=] is null, [=reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}} and abort these steps.

1. If the [=XR/XR device=]'s [=list of supported modes=] does not [=list/contain=] |mode|, [=reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}} and abort these steps.

1. Else [=/resolve=] |promise|.

Calling {{XR/supportsSessionMode()}} MUST NOT trigger device-selection UI as this would cause many sites to display XR-specific dialogs early in the document lifecycle without user activation.

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

navigator.xr.supportsSessionMode('immersive-vr').then(() => {

// 'immersive-vr' sessions are supported.

// Page should advertise support to the user.

}

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

When the <dfn method for="XR">requestSession(|options|)</dfn> method is invoked, the user agent MUST return [=a new Promise=] |promise| and run the following steps [=in parallel=]:

1. Let |mode| be the {{XRSessionCreationOptions/mode}} attribute of the |options| argument.

1. Let |immersive| be a boolean set to <code>true</code> if |mode| is {{immersive-vr}} or {{immersive-ar}} and <code>false</code> otherwise.

1. If |immersive| is <code>true</code>:

1. If [=pending immersive session=] is <code>true</code> or [=active immersive session=] is not <code>null</code>, [=reject=] |promise| with an {{InvalidStateError}} and abort these steps.

1. Else set [=pending immersive session=] to be <code>true</code>.

1. [=ensures an XR device is selected|Ensure an XR device is selected=].

1. If the [=XR/XR device=] is null, [=reject=] |promise| with null.

1. Else if the [=XR/XR device=]'s [=list of supported modes=] does not [=list/contain=] |mode|, [=reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}}.

1. Else If |immersive| is <code>true</code> and the algorithm is not [=triggered by user activation=], [=reject=] |promise| with a {{SecurityError}} and abort these steps.

1. If |promise| was [=rejected=] and |immersive| is <code>true</code>, set [=pending immersive session=] to be <code>false</code>.

1. If |promise| was [=rejected=], abort these steps.

1. Let |session| be a new {{XRSession}}.

1. [=Initialize the session=] |session| with the [=session description=] given by |options|.

1. If |immersive| is <code>true</code> set the [=active immersive session=] to |session| and set [=pending immersive session=] to <code>false</code>.

1. Else append |session| to the [=list of inline sessions=].

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

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

let xrSession;

navigator.xr.requestSession({ mode: "immersive-vr" }).then((session) => {

xrSession = session;

});

Session {#session}

=======

XRSession {#xrsession-interface}

---------

Any interaction with XR hardware is done via an {{XRSession}} object, which can only be retrieved by calling {{requestSession()}} on the {{XR}} object. Once a session has been successfully acquired it can be used to [=poll the device 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 XREnvironmentBlendMode {

"opaque",

"additive",

"alpha-blend",

};

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

// Attributes

readonly attribute XRSessionMode mode;

readonly attribute XREnvironmentBlendMode environmentBlendMode;

readonly attribute XRRenderState renderState;

readonly attribute XRSpace viewerSpace;

// Methods

void updateRenderState(optional XRRenderStateInit state);

Promise&lt;XRReferenceSpace&gt; requestReferenceSpace(XRReferenceSpaceOptions options);

FrozenArray&lt;XRInputSource&gt; getInputSources();

long requestAnimationFrame(XRFrameRequestCallback callback);

void cancelAnimationFrame(long handle);

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

// Events

attribute EventHandler onblur;

attribute EventHandler onfocus;

attribute EventHandler onend;

attribute EventHandler onselect;

attribute EventHandler oninputsourceschange;

attribute EventHandler onselectstart;

attribute EventHandler onselectend;

};

When an {{XRSession}} is created, the user agent MUST <dfn>initialize the session</dfn> by running the following steps:

1. Let |session| be the newly created {{XRSession}} object.

1. Let |options| be the {{XRSessionCreationOptions}} passed to {{requestSession()}}.

1. Initialize |session|'s {{XRSession/mode}} to |options| {{XRSessionCreationOptions/mode}} value.

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.

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 [=/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 <code>false</code>, that indicates if it has been shut down.

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

1. Let |session| be the target {{XRSession}} object.

1. Set |session|'s [=ended=] value to <code>true</code>.

1. If the [=active immersive session=] is equal to |session|, set the [=active immersive session=] to <code>null</code>.

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

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.

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=].

1. [=Shut down the session|Shut down=] the target {{XRSession}} object.

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}}, a <dfn>list of pending render states</dfn>, which is initially empty.

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

When the <dfn method for="XRSession">updateRenderState(|newState|)</dfn> method is invoked, the user agent MUST run the following steps:

1. Let |session| be the target {{XRSession}}.

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

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

1. Append |newState| to |session|'s [=list of pending render states=].

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

1. Let |session| be the target {{XRSession}}.

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

1. Let |pendingStates| be |session|'s [=list of pending render states=].

1. Set |session|'s [=list of pending render states=] to the empty list.

1. For each |newState| in |pendingStates|:

1. If |newState|'s {{XRRenderStateInit/depthNear}} value is set, set |activeState|'s {{XRRenderState/depthNear}} to |newState|'s {{XRRenderStateInit/depthNear}}.

1. If |newState|'s {{XRRenderStateInit/depthFar}} value is set, set |activeState|'s {{XRRenderState/depthFar}} to |newState|'s {{XRRenderStateInit/depthFar}}.

1. If |newState|'s {{XRRenderStateInit/baseLayer}} is set, set |activeState|'s {{XRRenderState/baseLayer}} to |newState|'s {{XRRenderStateInit/baseLayer}}.

1. If |newState|'s {{XRRenderStateInit/outputContext}} is set, set |activeState|'s {{XRRenderState/outputContext}} to |newState|'s {{XRRenderStateInit/outputContext}} and [=update the XRPresentationContext session=] to |session|.

When the <dfn method for="XRSession">requestReferenceSpace(|options|)</dfn> method is invoked, the user agent MUST return [=a new Promise=] |promise| and run the following steps [=in parallel=]:

1. [=Create a reference space=], |referenceSpace|, as described by |options|.

1. If |referenceSpace| is <code>null</code>, [=reject=] |promise| with a {{NotSupportedError}} and abort these steps.

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

When the <dfn method for="XRSession">getInputSources()</dfn> method is invoked, the user agent MUST run the following steps:

1. Return the current [=list of active input sources=].

Each {{XRSession}} has a <dfn>environment blending mode</dfn> value, which is a enum which MUST be set to whichever of the following values best matches the behavior of imagery rendered by the session in relation to the user's surrounding environment.

- A blend mode of <dfn enum-value for="XREnvironmentBlendMode">opaque</dfn> indicates that the user's surrounding environment is not visible at all. Alpha values in the {{XRRenderState/baseLayer}} will be ignored, with the compositor treating all alpha values as 1.0.

- A blend mode of <dfn enum-value for="XREnvironmentBlendMode">additive</dfn> indicates that the user's surrounding environment is visible and the {{XRRenderState/baseLayer}} will be shown additively against it. Alpha values in the {{XRRenderState/baseLayer}} will be ignored, with the compositor treating all alpha values as 1.0. When this blend mode is in use black pixels will appear fully transparent, and there is no way to make a pixel appear fully opaque.

- A blend mode of <dfn enum-value for="XREnvironmentBlendMode">alpha-blend</dfn> indicates that the user's surrounding environment is visible and the {{XRRenderState/baseLayer}} will be blended with it according to the alpha values of each pixel. Pixels with an alpha value of 1.0 will be fully opaque and pixels with an alpha value of 0.0 will be fully transparent.

The <dfn attribute for="XRSession">environmentBlendMode</dfn> attribute returns the {{XRSession}}'s [=environment blending mode=]

NOTE: Most Virtual Reality devices exhibit {{XREnvironmentBlendMode/opaque}} blending behavior. Augmented Reality devices that use transparent optical elements frequently exhibit {{XREnvironmentBlendMode/additive}} blending behavior, and Augmented Reality devices that use passthrough cameras frequently exhibit {{XREnvironmentBlendMode/alpha-blend}} blending behavior.

The <dfn attribute for="XRSession">viewerSpace</dfn> attribute is an {{XRSpace}} which tracks the pose of the [=viewer=].

NOTE: For any given {{XRFrame}} calling {{XRFrame/getPose()}} with the {{XRSession/viewerSpace}} and any {{XRReferenceSpace}} will return the same pose (without the {{views}} array) as calling {{XRFrame/getViewerPose()}} with the same {{XRReferenceSpace}}.

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

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

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 {{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.

We still need to document what happens when we <dfn>end the session</dfn>. (This is <a href="https://github.com/immersive-web/webxr/issues/467">filed</a>.)

We still need to document what happens when we <dfn lt="blur all sessions">blur all sessions</dfn>. (This is <a href="https://github.com/immersive-web/webxr/issues/468">filed</a>.)

We still need to document what happens when we <dfn>poll the device pose</dfn> (This is <a href="https://github.com/immersive-web/webxr/issues/480">filed</a>.)

We still need to document how the<dfn>list of active input sources</dfn> is maintained. (This is <a href="https://github.com/immersive-web/webxr/issues/465">filed</a>.)

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 MAY be displayed in mono or stereo and MAY allow for [=viewer=] tracking. User agents MUST allow {{inline}} sessions to be created for any [=/XR device=].

- 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 [=/XR device=] display and that content <b>is not</b> intended to be integrated with the user's environment. The {{environmentBlendMode}} for {{immersive-vr}} sessions is expected to be {{opaque}} when possible, but MAY be {{additive}} if the hardware requires it.

- A session mode of <dfn enum-value for="XRSessionMode">immersive-ar</dfn> indicates that the session's output will be given [=exclusive access=] to the [=/XR device=] display and that content <b>is</b> intended to be integrated with the user's environment. The {{environmentBlendMode}} MUST NOT be {{opaque}} for {{immersive-ar}} sessions.

An <dfn>immersive session</dfn> refers to either an {{immersive-vr}} or an {{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 [=/XR device=], meaning that while the [=immersive session=] is not [=blurred=] the HTML document is not shown on the [=/XR device=]'s display, nor is content from other applications shown on the [=/XR device=]'s display.

NOTE: Examples of ways [=exclusive access=] may be presented include stereo content displayed on a virtual reality or augmented reality headset, or augmented reality content displayed fullscreen on a mobile device.

XRSessionCreationOptions {#xrsessioncreationoptions-interface}

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

The {{XRSessionCreationOptions}} dictionary provides a <dfn>session description</dfn>, indicating the desired properties of a session to be returned from {{requestSession()}}.

dictionary XRSessionCreationOptions {

XRSessionMode mode = "inline";

};

XRRenderState {#xrrenderstate-interface}

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

There are multiple values that developers can configure which affect how the session's output is composited. These values are tracked by an {{XRRenderState}} object.

dictionary XRRenderStateInit {

double depthNear;

double depthFar;

XRLayer? baseLayer;

XRPresentationContext? outputContext;

};

[SecureContext, Exposed=Window] interface XRRenderState {

readonly attribute double depthNear;

readonly attribute double depthFar;

readonly attribute XRLayer? baseLayer;

readonly attribute XRPresentationContext? outputContext;

};

When an {{XRRenderState}} object is created, the user agent MUST <dfn>initialize the render state</dfn> by running the following steps:

1. Let |state| be the newly created {{XRRenderState}} object.

1. Initialize |state|'s {{XRRenderState/depthNear}} to <code>0.1</code>.

1. Initialize |state|'s {{XRRenderState/depthFar}} to <code>1000.0</code>.

1. Initialize |state|'s {{XRRenderState/baseLayer}} to <code>null</code>.

1. Initialize |state|'s {{XRRenderState/outputContext}} to <code>null</code>.

The <dfn attribute for="XRRenderState">depthNear</dfn> attribute defines the distance, in meters, of the near clip plane from the viewer. The <dfn attribute for="XRRenderState">depthFar</dfn> attribute defines the distance, in meters, of the far clip plane from the viewer.

{{XRRenderState/depthNear}} and {{XRRenderState/depthFar}} is used in the computation of the {{XRView/projectionMatrix}} of {{XRView}}s and determines how the values of an {{XRWebGLLayer}} depth buffer are interpreted. {{XRRenderState/depthNear}} MAY be greater than {{XRRenderState/depthFar}}.

Animation Frames {#animation-frames}

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

The primary way an {{XRSession}} provides information about the tracking state of the [=/XR device=] is via callbacks scheduled by calling {{requestAnimationFrame()}} on the {{XRSession}} instance.

callback XRFrameRequestCallback = void (DOMHighResTimeStamp time, XRFrame frame);

Each {{XRFrameRequestCallback}} object has a <dfn for="XRFrameRequestCallback">cancelled</dfn> boolean initially set to <code>false</code>.

Each {{XRSession}} has a <dfn>list of animation frame callbacks</dfn>, which is initially empty, and an <dfn>animation frame callback identifier</dfn>, which is a number initially be zero.

When the <dfn method for="XRSession">requestAnimationFrame(|callback|)</dfn> method is invoked, the user agent MUST run the following steps:

1. Let |session| be the target {{XRSession}} object.

1. Increment |session|'s [=animation frame callback identifier=] by one.

1. Append |callback| to |session|'s [=list of animation frame callbacks=], associated with |session|'s [=animation frame callback identifier=]’s current value.

1. Return |session|'s [=animation frame callback identifier=]’s current value.

When the <dfn method for="XRSession">cancelAnimationFrame(|handle|)</dfn> method is invoked, the user agent MUST run the following steps:

1. Let |session| be the target {{XRSession}} object.

1. Find the entry in |session|'s [=list of animation frame callbacks=] that is associated with the value |handle|.

1. If there is such an entry, set it's [=cancelled=] boolean to <code>true</code> and remove it from |session|'s [=list of animation frame callbacks=].

When an {{XRSession}} |session| receives updated [=viewer=] state from the [=/XR device=], it runs an <dfn>XR animation frame</dfn> with a timestamp |now| and an {{XRFrame}} |frame|, which MUST run the following steps regardless of if the [=list of animation frame callbacks=] is empty or not:

1. If |session|'s [=list of pending render states=] is not empty, [=apply pending render states=].

1. If |session|'s {{XRSession/renderState}}'s {{XRRenderState/baseLayer}} is <code>null</code>, abort these steps.

1. If |session|'s {{XRSession/mode}} is {{XRSessionMode/inline}} and |session|'s {{XRSession/renderState}}'s {{XRRenderState/outputContext}} is <code>null</code>, abort these steps.

1. Let |callbacks| be a list of the entries in |session|'s [=list of animation frame callback=], in the order in which they were added to the list.

1. Set |session|'s [=list of animation frame callbacks=] to the empty list.

1. Set |frame|'s [=active=] boolean to <code>true</code>.

1. Set |frame|'s [=animationFrame=] boolean to <code>true</code>.

1. For each entry in |callbacks|, in order:

1. If the entry's [=cancelled=] boolean is <code>true</code>, continue to the next entry.

1. [=Invoke the Web IDL callback function=], passing |now| and |frame| as the arguments

1. If an exception is thrown, [=report the exception=].

1. Set |frame|'s [=active=] boolean to <code>false</code>.

The XR Compositor {#compositor}

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

The user agent MUST maintain an <dfn>XR Compositor</dfn> which handles presentation to the [=/XR device=] and frame timing. The compositor MUST use an independent rendering context whose state is isolated from that of any WebGL contexts used as {{XRWebGLLayer}} sources to prevent the page from corrupting the compositor state or reading back content from other pages. the compositor MUST also run in separate thread or processes to decouple performance of the page from the ability to present new imagery to the user at the appropriate framerate.

The [=XR Compositor=] has a list of layer images, which is initially empty.

<!--There are no direct interfaces to the compositor, but applications may submit bitmaps to be composited via the layer system and observe the frame timing via calls to {{XRSession/requestAnimationFrame()}}. The compositor consists of two different loops, assumed to be running in separate threads or processes. The <dfn>Frame Loop</dfn>, which drives the page script, and the <dfn>Render Loop</dfn>, which continuously presents imagery provided by the Frame Loop to the XR device. The render loop maintains its own copy of the session's layer list. Communication between the two loops is synchronized with a lock that limits access to the render loop's layer list.

Both loops are started when a session is successfully created. The compositor's render loop goes through the following steps:

1. The layer lock is acquired.

1. The render loop's layer list images are composited and presented to the device.

1. The layer lock is released.

1. Notify the frame loop that a frame has been completed.

1. return to step 1.

The render loop MUST throttle its throughput to the refresh rate of the XR device. The exact point in the loop that is most effective to block at may differ between platforms, so no perscription is made for when that should happen.

Upon session creation, the following steps are taken to start the frame loop:

1. A new promise is created and set as the session's current frame promise. The current frame promise is returned any time XRCanvasLayer/commit() is called.

1. The {{sessionchange}} event is fired.

1. The promise returned from {{requestSession()}} is resolved.

Then, the frame loop performs the following steps while the session is active:

1. The render loop's layer lock is acquired.

1. Any dirty layers in the session's layer list are copied to the render loop's layer list.

1. The render loop's layer lock is released.

1. Wait for the render loop to signal that a frame has been completed.

1. The session's current frame promise is set as the the previous frame promise.

1. A new promise is created and set as the session's current frame promise.

1. The previous frame promise is resolved.

1. Once the promise has been resolved, return to step 1.-->

Frame Loop {#frame}

==========

XRFrame {#xrframe-interface}

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

An {{XRFrame}} represents a snapshot of the state of all of the tracked objects for an {{XRSession}}. Applications can acquire an {{XRFrame}} by calling {{XRSession/requestAnimationFrame()}} on an {{XRSession}} with an {{XRFrameRequestCallback}}. When the callback is called it will be passed an {{XRFrame}}. Events which need to communicate tracking state, such as the {{select}} event, will also provide a {{XRFrame}}.

[SecureContext, Exposed=Window] interface XRFrame {

readonly attribute XRSession session;

XRViewerPose? getViewerPose(XRReferenceSpace referenceSpace);

XRPose? getPose(XRSpace space, XRSpace relativeTo);

};

Each {{XRFrame}} has a <dfn for="XRFrame">active</dfn> boolean which is initially set to <code>false</code>, and an <dfn for="XRFrame">animationFrame</dfn> boolean which is initially set to <code>false</code>.

The <dfn attribute for="XRFrame">session</dfn> attribute returns the {{XRSession}} that produced the {{XRFrame}}.

When the <dfn method for="XRFrame">getViewerPose(|referenceSpace|)</dfn> method is invoked, the user agent MUST run the following steps:

1. If the {{XRFrame}}'s [=active=] boolean is <code>false</code>, throw an {{InvalidStateError}} and abort these steps.

1. If the {{XRFrame}}'s [=animationFrame=] boolean is <code>false</code>, throw an {{InvalidStateError}} and abort these steps.

1. Let |session| be the {{XRFrame}}'s {{XRFrame/session}} object.

1. If |referenceSpace|'s [=XRSpace/session=] does not equal |session|, throw an {{InvalidStateError}} and abort these steps.

1. If the [=viewer=]'s pose cannot be determined relative to |referenceSpace|, return <code>null</code>

1. Return a new {{XRViewerPose}} describing the [=viewer=]'s pose relative to the origin of |referenceSpace| at the timestamp of the {{XRFrame}}.

When the <dfn method for="XRFrame">getPose(|space|, |relativeTo|)</dfn> method is invoked, the user agent MUST run the following steps:

1. If the {{XRFrame}}'s [=active=] boolean is <code>false</code>, throw a {{InvalidStateError}} and abort these steps.

1. Let |session| be the {{XRFrame}}'s {{XRFrame/session}} object.

1. If |space|'s [=XRSpace/session=] does not equal |session|, throw an {{InvalidStateError}} and abort these steps.

1. If |relativeTo|'s [=XRSpace/session=] does not equal |session|, throw an {{InvalidStateError}} and abort these steps.

1. If |space|'s pose cannot be determined relative to |relativeTo|, return <code>null</code>

1. Return a new {{XRPose}} describing |space|'s pose relative to the origin of |relativeTo|.

Spaces {#spaces}

======

XRSpace {#xrspace-interface}

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

An {{XRSpace}} describes an entity that is tracked by the [=/XR device=]'s tracking systems. {{XRSpace}}s MAY NOT have a fixed spatial relationship to one another or to any given {{XRReferenceSpace}}. The transform between two {{XRSpace}} can be evaluated by calling an {{XRFrame}}'s {{XRFrame/getPose()}} method. The interface is intentionally opaque.

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

};

Each {{XRSpace}} has a <dfn for="XRSpace">session</dfn> which is set to the {{XRSession}} that created the {{XRSpace}.

An {{XRReferenceSpace}} describes an {{XRSpace}} that is generally expected to remain static for the duration of the {{XRSession}}, with the most common exception being mid-session reconfiguration by the user. Every {{XRReferenceSpace}} describes a coordinate system where the Y axis MUST be aligned with gravity, with <code>+Y</code> being "Up". <code>-Z</code> is considered "Forward", and <code>+X</code> is considered "Right".

The base {{XRReferenceSpace}} represents a reference space without any tracking behavior.

enum XRReferenceSpaceType {

"identity",

"stationary",

"bounded",

"unbounded"

};

enum XRStationaryReferenceSpaceSubtype {

"eye-level",

"floor-level",

"position-disabled"

};

dictionary XRReferenceSpaceOptions {

required XRReferenceSpaceType type;

XRStationaryReferenceSpaceSubtype subtype;

};

[SecureContext, Exposed=Window] interface XRReferenceSpace : XRSpace {

attribute XRRigidTransform originOffset;

attribute EventHandler onreset;

};

An {{XRReferenceSpace}} is obtained by calling {{XRSession/requestReferenceSpace()}}, which creates an instance of an interface extending {{XRReferenceSpace}}, determined by the {{XRReferenceSpaceOptions/type}} value of the {{XRReferenceSpaceOptions}} dictionary passed into the call:

- Passing a {{XRReferenceSpaceOptions/type}} of <dfn enum-value for="XRReferenceSpaceType">identity</dfn> creates an {{XRReferenceSpace}} instance.

- Passing a {{XRReferenceSpaceOptions/type}} of <dfn enum-value for="XRReferenceSpaceType">stationary</dfn> creates an {{XRStationaryReferenceSpace}} instance.

- Passing a {{XRReferenceSpaceOptions/type}} of <dfn enum-value for="XRReferenceSpaceType">bounded</dfn> creates an {{XRBoundedReferenceSpace}} instance if supported by the [=/XR device=] and the {{XRSession}}.

- Passing a {{XRReferenceSpaceOptions/type}} of <dfn enum-value for="XRReferenceSpaceType">unbounded</dfn> creates an {{XRUnboundedReferenceSpace}} instance if supported by the [=/XR device=] and the {{XRSession}}.

If a {{XRReferenceSpaceOptions/type}} of {{XRReferenceSpaceType/stationary}} is specified a {{XRReferenceSpaceOptions/subtype}} must also be given:

- Passing a {{XRReferenceSpaceOptions/subtype}} of <dfn enum-value for="XRStationaryReferenceSpaceSubtype">eye-level</dfn> creates an {{XRStationaryReferenceSpace}} with it's origin near the user's head at the time of creation. The exact position and orientation will be initialized based on the conventions of the underlying platform.

- Passing a {{XRReferenceSpaceOptions/subtype}} of <dfn enum-value for="XRStationaryReferenceSpaceSubtype">floor-level</dfn> creates an {{XRStationaryReferenceSpace}} with it's origin positioned at the floor in a safe position for the user to stand. The `y` axis equals `0` at floor level, with the `x` and `z` position and orientation initialized based on the conventions of the underlying platform. If the floor level isn't known it will be estimated.

- Passing a {{XRReferenceSpaceOptions/subtype}} of <dfn enum-value for="XRStationaryReferenceSpaceSubtype">position-disabled</dfn> creates an {{XRStationaryReferenceSpace}} where orientation is tracked but the [=viewer=]s position is always reported as being at the origin.

Note: The {{position-disabled}} subtype is primarily intended for use with pre-rendered media such as panoramic photos or videos. It should not be used for most other media types due to user discomfort associated with the lack of a neck model or full positional tracking.

Devices that support {{XRReferenceSpaceType/stationary}} reference spaces MUST support all {{XRStationaryReferenceSpaceSubtype}}s.

The <dfn attribute for="XRReferenceSpace">originOffset</dfn> attribute is a {{XRRigidTransform}} that describes an additional translation and rotation to be applied to any poses queried using the {{XRReferenceSpace}}. It is initially set to an [=identity transform=]. Changes to the {{originOffset}} take effect immediately, and subsequent poses queried with the {{XRReferenceSpace}} will take into account the new transform.

Note: Changing the {{originOffset}} between pose queries in a single [=XR animation frame=] is not advised, since it will cause inconsistencies in the tracking data and rendered output.

The <dfn attribute for="XRReferenceSpace">onreset</dfn> attribute is an [=Event handler IDL attribute=] for the {{reset}} event type.

When an {{XRReferenceSpace}} is requested, the user agent MUST <dfn>create a reference space</dfn> by running the following steps:

1. Let |session| be the {{XRSession}} object that requested creation of a reference space.

1. Initialize [=XRSpace/session=] to be |session|.

1. Let |options| be the {{XRReferenceSpaceOptions}} passed to {{requestReferenceSpace()}}.

1. Let |type| be set to |options| {{XRReferenceSpaceOptions/type}}.

1. Let |referenceSpace| be set to <code>null</code>.

1. If |type| is {{identity}} let |referenceSpace| be a new {{XRReferenceSpace}}.

1. If |type| is {{stationary}} and |options| does not have a {{XRReferenceSpaceOptions/subtype}} field, throw {{TypeError}}.

1. Else if |type| is {{bounded}} or {{unbounded}} and |options| has a {{XRReferenceSpaceOptions/subtype}} field, throw a {{TypeError}}.

1. If |type| is {{stationary}}, let |referenceSpace| be a new {{XRStationaryReferenceSpace}} with a {{XRStationaryReferenceSpace/subtype}} of |options| {{XRReferenceSpaceOptions/subtype}}.

1. Else if |type| is {{bounded}}, let |referenceSpace| be a new {{XRBoundedReferenceSpace}}.

1. Else if |type| is {{unbounded}}, let |referenceSpace| be a new {{XRUnboundedReferenceSpace}}.

1. Return |referenceSpace|.

XRStationaryReferenceSpace {#xrstationaryreferencespace-interface}

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

An {{XRStationaryReferenceSpace}} represents a tracking space that the user is not expected to move around within. Tracking in a {{stationary}} reference space is optimized for the assumption that the user will not move much beyond their starting point, if at all. For devices with [=6DoF=] tracking, {{stationary}} reference spaces should emphasize keeping the origin stable relative to the user's environment.

interface XRStationaryReferenceSpace : XRReferenceSpace {

readonly attribute XRStationaryReferenceSpaceSubtype subtype;

};

The {{XRStationaryReferenceSpace}}'s <dfn attribute for="XRStationaryReferenceSpace">subtype</dfn> attribute is the {{XRStationaryReferenceSpaceSubtype}} that the {{XRStationaryReferenceSpace}} was created with.

XRBoundedReferenceSpace {#xrboundedreferencespace-interface}

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

An {{XRBoundedReferenceSpace}} represents a floor-relative tracking space where the user is expected to move within a pre-established boundary. Tracking in an {{bounded}} reference space is optimized for keeping the reference space origin and bounds geometry stable relative to the user's environment.

interface XRBoundedReferenceSpace : XRReferenceSpace {

readonly attribute FrozenArray&lt;DOMPointReadOnly&gt; boundsGeometry;

};

The origin of a {{XRBoundedReferenceSpace}} MUST be positioned at the floor, such that the `y` axis equals `0` at floor level. The `x` and `z` position and orientation are initialized based on the conventions of the underlying platform, typically expected to be near the center of the room facing in a logical forward direction.

Note: Other XR platforms sometimes refer to the type of tracking offered by a {{bounded}} reference space as "room scale" tracking. An {{XRBoundedReferenceSpace}} is not intended to describe multi-room spaces, areas with uneven floor levels, or very large open areas. Content that needs to handle those scenarios should use an {{XRUnboundedReferenceSpace}}.

The <dfn attribute for="XRBoundedReferenceSpace">boundsGeometry</dfn> attribute describes the border around the {{XRBoundedReferenceSpace}}, which the user can expect to safely move within.

The polygonal boundary is given as an array of {{DOMPointReadOnly}}s, which represents a loop of points at the edges of the safe space. The points describe offsets from the {{XRReferenceSpace}} origin in meters. Points MUST be given in a clockwise order as viewed from above, looking towards the negative end of the Y axis. The {{DOMPointReadOnly/y}} value of each point MUST be <code>0</code> and the {{DOMPointReadOnly/w}} value of each point MUST be <code>1</code>. The bounds can be considered to originate at the floor and extend infinitely high. The shape it describes MAY be convex or concave.

Note: Content should not require the user to move beyond the {{boundsGeometry}}. It is possible for the user to move beyond the bounds if their physical surroundings allow for it, resulting in position values outside of the polygon they describe. This is not an error condition and should be handled gracefully by page content.

Note: Content generally should not provide a visualization of the {{boundsGeometry}}, as it's the user agent's responsibility to ensure that safety critical information is provided to the user.

XRUnboundedReferenceSpace {#xrunboundedreferencespace-interface}

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

An {{XRUnboundedReferenceSpace}} represents a tracking space where the user is expected to move freely around their environment, potentially even long distances from their starting point. Tracking in an {{unbounded}} reference space is optimized for stability around the user's current position, and as such the tracking origin may drift over time.

[SecureContext, Exposed=Window]

interface XRUnboundedReferenceSpace : XRReferenceSpace {

};

Views {#views}

=====

XRView {#xrview-interface}

------

An {{XRView}} describes a single <dfn>view</dfn> into an XR scene. Each [=view=] corresponds to a display or portion of a display used by an XR device to present imagery to the user. They are used to retrieve all the information necessary to render content that is well aligned to the [=view=]'s physical output properties, including the field of view, eye offset, and other optical properties. [=Views=] may cover overlapping regions of the user's vision. No guarantee is made about the number of [=views=] any XR device uses or their order, nor is the number of [=views=] required to be constant for the duration of an {{XRSession}}.

NOTE: Many HMDs will request that content render two [=views=], one for the left eye and one for the right, while most magic window devices will only request one [=view=], but applications should never assume a specific view configuration. For example: A magic window device may request two views if it is capable of stereo output, but may revert to requesting a single view for performance reasons if the stereo output mode is turned off. Similarly, HMDs may request more than two views to facilitate a wide field of view or displays of different pixel density.

enum XREye {

"left",

"right"

};

[SecureContext, Exposed=Window] interface XRView {

readonly attribute XREye eye;

readonly attribute Float32Array projectionMatrix;

readonly attribute XRRigidTransform transform;

};

The <dfn attribute for="XRView">eye</dfn> attribute describes which eye this view is expected to be shown to. This attribute's primary purpose is to ensure that pre-rendered stereo content can present the correct portion of the content to the correct eye. If the view does not have an intrinsically associated eye (the display is monoscopic, for example) this attribute MUST be set to {{XREye/"left"}}.

The <dfn attribute for="XRView">projectionMatrix</dfn> attribute provides a [=matrix=] describing the projection to be used when rendering the [=view=]. It is <b>strongly recommended</b> that applications use this matrix without modification. Failure to use the provided projection matrices when rendering may cause the presented frame to be distorted or badly aligned, resulting in varying degrees of user discomfort.

The <dfn attribute for="XRView">transform</dfn> attribute is the {{XRRigidTransform}} of the viewpoint.

NOTE: The {{XRView/transform}} can be used to position camera objects in many rendering libraries. If a more traditional view matrix is needed by the application one can be retrieved by calling `view.transform.inverse().matrix`.

XRViewport {#xrviewport-interface}

------

An {{XRViewport}} object describes a viewport, or rectangular region, of a graphics surface.

[SecureContext, Exposed=Window] interface XRViewport {

readonly attribute long x;

readonly attribute long y;

readonly attribute long width;

readonly attribute long height;

};

The <dfn attribute for="XRViewport">x</dfn> and <dfn attribute for="XRViewport">y</dfn> attributes define an offset from the surface origin and the <dfn attribute for="XRViewport">width</dfn> and <dfn attribute for="XRViewport">height</dfn> attributes define the rectangular dimensions of the viewport.

The exact interpretation of the viewport values depends on the conventions of the graphics API the viewport is associated with:

- When used with a {{XRWebGLLayer}} the {{XRViewport/x}} and {{XRViewport/y}} attributes specify the lower left corner of the viewport rectangle, in pixels, with the viewport rectangle extending {{XRViewport/width}} pixels to the right of {{XRViewport/x}} and {{XRViewport/height}} pixels above {{XRViewport/y}}. The values can be passed to the [=WebGL viewport=] function directly.

The following code loops through all of the {{XRView}}s of an {{XRViewerPose}}, queries an {{XRViewport}} from an {{XRWebGLLayer}} for each, and uses them to set the appropriate [=WebGL viewport=]s for rendering.

xrSession.requestAnimationFrame((time, xrFrame) => {

let viewer = xrFrame.getViewerPose(xrReferenceSpace);

gl.bindFramebuffer(xrWebGLLayer.framebuffer);

for (xrView of viewer.views) {

let xrViewport = xrWebGLLayer.getViewport(xrView);

gl.viewport(xrViewport.x, xrViewport.y, xrViewport.width, xrViewport.height);

// WebGL draw calls will now be rendered into the appropriate viewport.

}

});

Geometric Primitives {#geometricprimitives}

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

Matrices {#matrices}

--------

WebXR provides various transforms in the form of <dfn lt="matrix">matrices</dfn>. WebXR matrices are always 4x4 and given as 16 element {{Float32Array}}s in column major order. They may be passed directly to WebGL's {{uniformMatrix4fv}} function, used to create an equivalent {{DOMMatrix}}, or used with a variety of third party math libraries.

Translations specified by WebXR matrices are always given in meters.

Normalization {#normalization}

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

There are several algorithms which call for a vector or quaternion to be normalized, which means to scale the components to have a collective magnitude of <code>1.0</code>.

To <dfn>normalize</dfn> a list of components the UA MUST perform the following steps:

1. Let |length| be the square root of the sum of the squares of each component.

1. If |length| is <code>0</code>, throw an {{InvalidStateError}} and abort these steps.

1. Divide each component by |length| and set the component.

XRRigidTransform {#xrrigidtransform-interface}

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

An {{XRRigidTransform}} is a transform described by a {{XRRigidTransform/position}} and {{XRRigidTransform/orientation}}. When interpreting an {{XRRigidTransform}} the {{XRRigidTransform/orientation}} is always applied prior to the {{XRRigidTransform/position}}.

[SecureContext, Exposed=Window,

Constructor(optional DOMPointInit position, optional DOMPointInit orientation)]

interface XRRigidTransform {

readonly attribute DOMPointReadOnly position;

readonly attribute DOMPointReadOnly orientation;

readonly attribute Float32Array matrix;

XRRigidTransform inverse();

};

The <dfn constructor for="XRRigidTransform">XRRigidTransform(|position|, |orientation|)</dfn> constructor MUST perform the following steps when invoked:

1. Let |transform| be a new {{XRRigidTransform}}.

1. If |position| is not a {{DOMPointInit}} initialize |transform|'s {{XRRigidTransform/position}} to <code>{ x: 0.0, y: 0.0, z: 0.0, w: 1.0 }</code>.

1. If |position|'s {{DOMPointReadOnly/w}} value is not 1.0, throw a {{TypeError}}.

1. Else initialize |transform|'s {{XRRigidTransform/position}}’s {{DOMPointReadOnly/x}} value to |position|'s x dictionary member, {{DOMPointReadOnly/y}} value to |position|'s y dictionary member, {{DOMPointReadOnly/z}} value to |position|'s z dictionary member and {{DOMPointReadOnly/w}} to <code>1.0</code>.

1. If |orientation| is not a {{DOMPointInit}} initialize |transform|'s {{XRRigidTransform/orientation}} to <code>{ x: 0.0, y: 0.0, z: 0.0, w: 1.0 }</code>.

1. Else initialize |transform|'s {{XRRigidTransform/orientation}}’s {{DOMPointReadOnly/x}} value to |orientation|'s x dictionary member, {{DOMPointReadOnly/y}} value to |orientation|'s y dictionary member, {{DOMPointReadOnly/z}} value to |orientation|'s z dictionary member and {{DOMPointReadOnly/w}} value to |orientation|'s w dictionary member.

1. [=Normalize=] {{DOMPointReadOnly/x}}, {{DOMPointReadOnly/y}}, {{DOMPointReadOnly/z}}, and {{DOMPointReadOnly/w}} components of |transform|'s {{XRRigidTransform/orientation}}.

1. Return |transform|.

The <dfn attribute for="XRRigidTransform">position</dfn> attribute is a 3-dimensional point, given in meters, describing the translation component of the transform. The {{XRRigidTransform/position}}'s {{DOMPointReadOnly/w}} attribute MUST be <code>1.0</code>.

The <dfn attribute for="XRRigidTransform">orientation</dfn> attribute is a quaternion describing the rotational component of the transform. The {{XRRigidTransform/orientation}} MUST be normalized to have a length of <code>1.0</code>.

The <dfn attribute for="XRRigidTransform">matrix</dfn> attribute returns the transform described by the {{XRRigidTransform/position}} and {{XRRigidTransform/orientation}} attributes as a [=matrix=].

An {{XRRigidTransform}} with a {{XRRigidTransform/position}} of <code>{ x: 0, y: 0, z: 0 w: 1 }</code> and an {{XRRigidTransform/orientation}} of <code>{ x: 0, y: 0, z: 0, w: 1 }</code> is known as an <dfn>identity transform</dfn>.

The {{XRRigidTransform/inverse()}} method returns a {{XRRigidTransform}} which, if applied to an object that had previously been transformed by the original {{XRRigidTransform}}, would undo the transform and return the object to it's initial pose.

XRRay {#xrray-interface}

-----

An {{XRRay}} is a geometric ray described by a {{XRRay/origin}} point and {{XRRay/direction}} vector.

[SecureContext, Exposed=Window,

Constructor(optional DOMPointInit origin, optional DOMPointInit direction),

Constructor(XRRigidTransform transform)]

interface XRRay {

readonly attribute DOMPointReadOnly origin;

readonly attribute DOMPointReadOnly direction;

readonly attribute Float32Array matrix;

};

The <dfn constructor for="XRRay">XRRay(|origin|, |direction|)</dfn> constructor MUST perform the following steps when invoked:

1. Let |ray| be a new {{XRRay}}.

1. If |origin| is not a {{DOMPointInit}} initialize |ray|'s {{XRRay/origin}} to <code>{ x: 0.0, y: 0.0, z: 0.0, w: 1.0 }</code>.

1. Else initialize |ray|'s {{XRRay/origin}}’s {{DOMPointReadOnly/x}} value to |origin|'s x dictionary member, {{DOMPointReadOnly/y}} value to |origin|'s y dictionary member, {{DOMPointReadOnly/z}} value to |origin|'s z dictionary member and {{DOMPointReadOnly/w}} to <code>1.0</code>.

1. If |direction| is not a {{DOMPointInit}} initialize |ray|'s {{XRRay/direction}} to <code>{ x: 0.0, y: 0.0, z: -1.0, w: 0.0 }</code>.

1. Else initialize |ray|'s {{XRRay/direction}}’s {{DOMPointReadOnly/x}} value to |direction|'s x dictionary member, {{DOMPointReadOnly/y}} value to |direction|'s y dictionary member, {{DOMPointReadOnly/z}} value to |direction|'s z dictionary member and {{DOMPointReadOnly/w}} value to to <code>0.0</code>.

1. [=Normalize=] the {{DOMPointReadOnly/x}}, {{DOMPointReadOnly/y}}, and {{DOMPointReadOnly/z}} components of |ray|'s {{XRRay/direction}}.

1. Return |ray|.

The <dfn constructor for="XRRay">XRRay(|transform|)</dfn> constructor MUST perform the following steps when invoked:

1. Let |ray| be a new {{XRRay}}.

1. Initialize |ray|'s {{XRRay/origin}} to <code>{ x: 0.0, y: 0.0, z: 0.0, w: 1.0 }</code>.

1. Initialize |ray|'s {{XRRay/direction}} to <code>{ x: 0.0, y: 0.0, z: -1.0, w: 0.0 }</code>.

1. Multiply |ray|'s {{XRRay/origin}} by the |transform|'s {{XRRigidTransform/matrix}} and set |ray| to the result.

1. Multiply |ray|'s {{XRRay/direction}} by the |transform|'s {{XRRigidTransform/matrix}} and set |ray| to the result.