forked from immersive-web/webxr
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.bs
2026 lines (1465 loc) · 133 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class="metadata">
Shortname: webxr
Title: WebXR Device API
Group: immersivewebwg
Status: ED
TR: https://www.w3.org/TR/webxr/
ED: https://immersive-web.github.io/webxr/
Previous Version: https://www.w3.org/TR/2019/WD-webxr-20190521/
Repository: immersive-web/webxr
Level: 1
Mailing List Archives: https://lists.w3.org/Archives/Public/public-immersive-web/
!Participate: <a href="https://github.com/immersive-web/webxr/issues/new">File an issue</a> (<a href="https://github.com/immersive-web/webxr/issues">open issues</a>)
!Participate: <a href="https://lists.w3.org/Archives/Public/public-immersive-web/">Mailing list archive</a>
!Participate: <a href="irc://irc.w3.org:6665/">W3C's #immersive-web IRC</a>
Editor: Brandon Jones 87824, Google http://google.com/, [email protected]
Editor: Nell Waliczek 93109, Amazon [Microsoft until 2018] https://amazon.com/, [email protected]
Abstract: This specification describes support for accessing virtual reality (VR) and augmented reality (AR) devices, including sensors and head-mounted displays, on the Web.
Ignored Vars: layer
Warning: custom
Custom Warning Title: Unstable API
Custom Warning Text:
<b>Parts of the API represented in this document are incomplete and may change at any time.</b>
<p>For additional context on the use of this API please reference the <a href="https://github.com/immersive-web/webxr/blob/master/explainer.md">WebXR Device API Explainer</a>.</p>
</pre>
<pre class="link-defaults">
spec:infra;
type:dfn; text:string
</pre>
<pre class="anchors">
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
type: dfn; text: actual context parameters; url: #actual-context-parameters
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
spec: Gamepad; urlPrefix: https://w3c.github.io/gamepad/#
type: interface; text: Gamepad; url: dom-gamepad
type: interface; text: GamepadButton; url: dom-gamepadbutton
type: enum; text: GamepadMappingType; url: dom-gamepadmappingtype
type: method; text: navigator.getGamepads(); url: dom-navigator-getgamepads
type: attribute; text: id; for: Gamepad; url: dom-gamepad-id
type: attribute; text: index; for: Gamepad; url: dom-gamepad-index
type: attribute; text: mapping; for: Gamepad; url: dom-gamepad-mapping
type: attribute; text: connected; for: Gamepad; url: dom-gamepad-connected
type: attribute; text: buttons; for: Gamepad; url: dom-gamepad-buttons
type: attribute; text: axes; for: Gamepad; url: dom-gamepad-axes
type: attribute; text: touched; for: GamepadButton; url: dom-gamepadbutton-touched
type: attribute; text: pressed; for: GamepadButton; url: dom-gamepadbutton-pressed
type: attribute; text: value; for: GamepadButton; url: dom-gamepadbutton-value
spec:html; type:method; for:HTMLCanvasElement; text:getContext(contextId); url: https://html.spec.whatwg.org/multipage/canvas.html#dom-canvas-getcontext
spec: ECMAScript; urlPrefix: https://tc39.github.io/ecma262/#
type: method; text: IsDetachedBuffer; url: sec-isdetachedbuffer
spec: dom; urlPrefix: https://dom.spec.whatwg.org/#
type:algorithm; text:fire an event; url: concept-event-fire
</pre>
<link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
<link rel="icon" type="image/png" sizes="96x96" href="favicon-96x96.png">
<style>
.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: #90b8de;
color: #fff;
font-family: sans-serif;
font-weight: bold;
border-color: grey;
}
.tg td {
padding: 4px 5px;
background-color: rgb(221, 238, 255);
font-family: monospace;
border-style: solid;
border-width: 1px;
border-color: grey;
overflow: hidden;
word-break: normal;
}
</style>
Introduction {#intro}
=============
<section class="non-normative">
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.
</section>
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}
----------------
<section class="non-normative">
Most applications using the WebXR Device API will follow a similar usage pattern:
* Query {{XR/supportsSession()|navigator.xr.supportsSession()}} 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 [=shut down the session|session is shut down=] by the UA or the user indicates they want to exit the XR content.
</section>
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}
----
<pre class="idl">
partial interface Navigator {
[SecureContext, SameObject] readonly attribute XR xr;
};
</pre>
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}
----
<pre class="idl">
[SecureContext, Exposed=Window] interface XR : EventTarget {
// Methods
Promise<void> supportsSession(XRSessionMode mode);
Promise<XRSession> requestSession(XRSessionMode mode);
// Events
attribute EventHandler ondevicechange;
};
</pre>
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 MUST reuse the cached [=list of 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 XR devices=] and removing disconnected devices.
<div class="algorithm" data-algorithm="xr-device-selection">
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. Set the [=XR/XR device=] based on the following:
<dl class="switch">
<dt> If there are any active {{XRSession}}s and the [=list of XR devices=] [=list/contains=] |oldDevice|
<dd> Set the [=XR/XR device=] to |oldDevice|
<dt> Otherwise
<dd> Set the [=XR/XR device=] to a device of the user agent's choosing
</dl>
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=] to [=fire an event=] named {{devicechange!!event}} on the [=context object=].
</div>
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.
<div class="algorithm" data-algorithm="ensure-device-selected">
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=].
</div>
The <dfn attribute for="XR">ondevicechange</dfn> attribute is an [=Event handler IDL attribute=] for the {{devicechange}} event type.
<div class="algorithm" data-algorithm="supports-session">
When the <dfn method for="XR">supportsSession(|mode|)</dfn> method is invoked, it MUST run the following steps:
1. Let |promise| be [=a new Promise=]
1. 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. [=/Resolve=] |promise|.
1. Return |promise|.
</div>
Calling {{XR/supportsSession()}} 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. Additionally, calling {{XR/supportsSession()}} 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.
<div class="example">
The following code checks to see if {{immersive-vr}} sessions are supported.
<pre highlight="js">
navigator.xr.supportsSession('immersive-vr').then(() => {
// 'immersive-vr' sessions are supported.
// Page should advertise support to the user.
}
</pre>
</div>
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.
<div class="algorithm" data-algorithm="request-session">
When the <dfn method for="XR">requestSession(|mode|)</dfn> method is invoked, the user agent MUST run the following steps:
1. Let |promise| be [=a new Promise=].
1. Let |immersive| be <code>true</code> if |mode| is {{XRSessionMode/"immersive-vr"}} or {{XRSessionMode/"immersive-ar"}}, and <code>false</code> otherwise.
1. If |immersive| is <code>true</code>:
1. If the algorithm is not [=triggered by user activation=], [=reject=] |promise| with a "{{SecurityError}}" {{DOMException}} and return |promise|.
1. If [=pending immersive session=] is <code>true</code> or [=active immersive session=] is not <code>null</code>, [=reject=] |promise| with an "{{InvalidStateError}}" {{DOMException}} and return |promise|.
1. Set [=pending immersive session=] to <code>true</code>.
1. Run the following steps [=in parallel=]:
1. [=ensures an XR device is selected|Ensure an XR device is selected=].
1. [=Queue a task=] to perform the following steps:
1. If the [=XR/XR device=] is <code>null</code> or [=XR/XR 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 <code>true</code>, set [=pending immersive session=] to <code>false</code>.
1. Abort these steps.
1. Let |session| be a new {{XRSession}} object.
1. [=Initialize the session=] with |session| and |mode|.
1. Potentially set the [=active immersive session=] based on the following:
<dl class="switch">
<dt> If |immersive| is <code>true</code>
<dd> Set the [=active immersive session=] to |session|, and set [=pending immersive session=] to <code>false</code>.
<dt> Otherwise
<dd> Append |session| to the [=list of inline sessions=].
</dl>
1. [=/Resolve=] |promise| with |session|.
1. Return |promise|.
</div>
<div class="example">
The following code attempts to retrieve an {{immersive-vr}} {{XRSession}}.
<pre highlight="js">
let xrSession;
navigator.xr.requestSession("immersive-vr").then((session) => {
xrSession = session;
});
</pre>
</div>
XRSessionMode {#xrsessionmode-enum}
-------------------------
The {{XRSessionMode}} enum defines the modes that an {{XRSession}} can operate in.
<pre class="idl">
enum XRSessionMode {
"inline",
"immersive-vr",
"immersive-ar"
};
</pre>
- 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.
- <section class="unstable">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.</section>
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 {{XRVisibilityState/visible}} the HTML document is not shown on the [=/XR device=]'s display, nor does content from any other source have exclusive access. [=Exclusive access=] does not prevent the browser or user agent from overlaying its own UI, however this UI SHOULD be minimal.
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.
NOTE: As an example of overlaid UI, the user-agent or operating system in an [=immersive session=] may show notifications over the rendered content. Similarly, in {{immersive-ar}} mode the user-agent or operating system may overlay mandatory "home" and navigational buttons over the user's wrist.
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 {{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.
<pre class="idl">
enum XREnvironmentBlendMode {
"opaque",
"additive",
"alpha-blend",
};
enum XRVisibilityState {
"visible",
"visible-blurred",
"hidden",
};
[SecureContext, Exposed=Window] interface XRSession : EventTarget {
// Attributes
readonly attribute XREnvironmentBlendMode environmentBlendMode;
readonly attribute XRVisibilityState visibilityState;
[SameObject] readonly attribute XRRenderState renderState;
[SameObject] readonly attribute XRInputSourceArray inputSources;
// Methods
void updateRenderState(optional XRRenderStateInit state);
Promise<XRReferenceSpace> requestReferenceSpace(XRReferenceSpaceType type);
long requestAnimationFrame(XRFrameRequestCallback callback);
void cancelAnimationFrame(long handle);
Promise<void> end();
// Events
attribute EventHandler onend;
attribute EventHandler onselect;
attribute EventHandler oninputsourceschange;
attribute EventHandler onselectstart;
attribute EventHandler onselectend;
attribute EventHandler onvisibilitychange;
};
</pre>
Each {{XRSession}} has a <dfn for="XRSession">mode</dfn>, which is one of the values of {{XRSessionMode}}.
<div class="algorithm" data-algorithm="initialize-session">
To <dfn>initialize the session</dfn>, given |session| and |mode|, the user agent MUST run the following steps:
1. Set |session|'s [=XRSession/mode=] to |mode|.
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.
</div>
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.
<div class="algorithm" data-algorithm="shut-down-session">
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. [=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 [=/XR device=].
- Deallocating any graphics resources acquired by |session| for presentation to the [=/XR device=].
- Putting the [=/XR device=] in a state such that a different source may be able to initiate a session with the same device.
1. [=Queue a task=] that fires an {{XRSessionEvent}} named {{end!!event}} on |session|.
</div>
<div class="algorithm" data-algorithm="end-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=].
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|.
</div>
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 <code>null</code>.
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 <code>0</code> to <code>PI</code>.
<div class="algorithm" data-algorithm="update-render-state">
The {{XRSession/updateRenderState()}} method queues an update to the [=active render state=] to be applied on the next frame. Unset fields of the {{XRRenderStateInit}} passed to this method will not be changed.
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. If |newState|'s {{XRRenderStateInit/inlineVerticalFieldOfView}} is set and |session| is an [=immersive session=], throw an {{InvalidStateError}} and abort these steps.
1. Let |activeState| be |session|'s [=active render state=].
1. If |session|'s [=pending render state=] is <code>null</code>, 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}}.
</div>
<div class="algorithm" data-algorithm="apply-pending-render-state">
When requested, the {{XRSession}} MUST <dfn>apply the pending render state</dfn> by running the following steps:
1. Let |session| be the target {{XRSession}}.
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 <code>null</code>.
1. Set |activeState| to |newState|.
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. Let |baseLayer| be |activeState|'s {{XRRenderState/baseLayer}}.
1. Set |activeState|'s [=XRRenderState/composition disabled=] and [=XRRenderState/output canvas=] based on the following:
<dl class="switch">
<dt> If |session|'s [=XRSession/mode=] is {{XRSessionMode/inline}} and |baseLayer| is an instance of an {{XRWebGLLayer}} with [=XRWebGLLayer/composition disabled=] set to <code>true</code>
<dd> Set |activeState|'s [=XRRenderState/composition disabled=] boolean to <code>true</code>.
<dd> Set |activeState|'s [=XRRenderState/output canvas=] to |baseLayer|'s [=XRWebGLLayer/context=]'s {{WebGLRenderingContext|canvas}}.
<dt> Otherwise
<dd> Set |activeState|'s [=XRRenderState/composition disabled=] boolean to <code>false</code>.
<dd> Set |activeState|'s [=XRRenderState/output canvas=] to <code>null</code>.
</dl>
</div>
<div class="algorithm" data-algorithm="request-reference-space">
When the <dfn method for="XRSession">requestReferenceSpace(|type|)</dfn> method is invoked, the user agent MUST run the following steps:
1. Let |promise| be [=a new Promise=].
1. Run the following steps [=in parallel=]:
1. [=Create a reference space=], |referenceSpace|, with the {{XRReferenceSpaceType}} |type|.
1. If |referenceSpace| is <code>null</code>, [=reject=] |promise| with a {{NotSupportedError}} and abort these steps.
1. [=/Resolve=] |promise| with |referenceSpace|.
1. Return |promise|.
</div>
Each {{XRSession}} has a <dfn>list of active XR input sources</dfn> (a [=/list=] of {{XRInputSource}}) which MUST be initially an empty [=/list=].
The <dfn attribute for="XRSession">inputSources</dfn> attribute returns the {{XRSession}}'s [=list of active XR input sources=].
The user agent MUST monitor any [=XR input source=]s associated with the [=/XR Device=], including detecting when [=XR input source=]s are added, removed, or changed.
<div class="algorithm" data-algorithm="on-input-source-added">
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. Let |added| be a new [=/list=].
1. For each new [=XR input source=]:
1. Let |inputSource| be a new {{XRInputSource}}.
1. Add |inputSource| to |added|.
1. [=Queue a task=] to perform the following steps:
1. [=list/Extend=] |session|'s [=list of active XR input sources=] with |added|.
1. Fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/added}} set to |added|.
</div>
<div class="algorithm" data-algorithm="on-input-source-removed">
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. Let |removed| 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=].
1. Add |inputSource| to |removed|.
1. [=Queue a task=] to perform the following steps:
1. [=list/Remove=] each {{XRInputSource}} in |removed| from |session|'s [=list of active XR input sources=].
1. Fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/removed}} set to |removed|.
</div>
<div class="algorithm" data-algorithm="on-input-source-change">
When the {{XRInputSource/handedness}}, {{XRInputSource/targetRayMode}}, or presence of a {{XRInputSource/gripSpace}} or {{XRInputSource/gamepad}} for any [=XR input source=]s change for {{XRSession}} |session|, the user agent MUST run the following steps:
1. Let |added| be a new [=/list=].
1. Let |removed| 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=].
1. Let |newInputSource| be a new {{XRInputSource}}.
1. Add |oldInputSource| to |removed|.
1. Add |newInputSource| to |added|.
1. [=Queue a task=] to perform the following steps:
1. [=list/Remove=] each {{XRInputSource}} in |removed| from |session|'s [=list of active XR input sources=].
1. [=list/Extend=] |session|'s [=list of active XR input sources=] with |added|.
1. Fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with{{XRInputSourcesChangeEvent/added}} set to |added| and {{XRInputSourcesChangeEvent/removed}} set to |removed|.
</div>
Each {{XRSession}} has a <dfn for="XRSession">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.
Each {{XRSession}} has a <dfn for="XRSession">visibility state</dfn> value, which is a enum which 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 [=/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 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 API](https://w3c.github.io/page-visibility/) to determine page visibility.
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=]. The [=XRSession/viewer reference space=] has a <dfn for="XRSession/viewer reference space">list of views</dfn>, which is a [=/list=] of [=view=]s corresponding to the views provided by the [=/XR device=]. If the {{XRSession}}'s {{XRSession/renderState}}'s [=XRRenderState/composition disabled=] boolean is set to <code>true</code> the [=list of views=] MUST contain a single [=view=].
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.
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()}}.
<pre class="idl">
dictionary XRRenderStateInit {
double depthNear;
double depthFar;
double inlineVerticalFieldOfView;
XRWebGLLayer? baseLayer;
};
[SecureContext, Exposed=Window] interface XRRenderState {
readonly attribute double depthNear;
readonly attribute double depthFar;
readonly attribute double? inlineVerticalFieldOfView;
readonly attribute XRWebGLLayer? baseLayer;
};
</pre>
Each {{XRRenderState}} has a <dfn for="XRRenderState">output canvas</dfn>, which is an {{HTMLCanvasElement}} initially set to <code>null</code>. The [=XRRenderState/output canvas=] is the DOM element that will display any content rendered for an {{XRSessionMode/inline}} {{XRSession}}.
Each {{XRRenderState}} also has <dfn for="XRRenderState">composition disabled</dfn> boolean, which is initially <code>false</code>. The {{XRRenderState}} is considered to be have [=XRRenderState/composition disabled=] if rendering commands performed for an {{XRSessionMode/inline}} {{XRSession}} are executed in such a way that they are directly displayed into [=XRRenderState/output canvas=], rather than first being processed by the [=XR Compositor=].
Note: At this point the {{XRRenderState}} will only have an [=XRRenderState/output canvas=] if it has [=XRRenderState/composition disabled=], but future versions of the specification are likely to introduce methods for setting [=XRRenderState/output canvas=]' that support more advanced uses like mirroring and layer compositing that will require composition.
<div class="algorithm" data-algorithm="initialize-renderstate">
When an {{XRRenderState}} object is created for an {{XRSession}} |session|, 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/inlineVerticalFieldOfView}} based on the following:
<dl class="switch">
<dt> If |session| is an [=immersive session=]
<dd> Initialize |state|'s {{XRRenderState/inlineVerticalFieldOfView}} to <code>null</code>.
<dt> Else
<dd> Initialize |state|'s {{XRRenderState/inlineVerticalFieldOfView}} to <code>PI * 0.5</code>.
</dl>
1. Initialize |state|'s {{XRRenderState/baseLayer}} to <code>null</code>.
</div>
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}}.
The <dfn attribute for="XRRenderState">inlineVerticalFieldOfView</dfn> attribute defines the default vertical field of view in radians used when computing projection matrices for {{XRSessionMode/inline}} {{XRSession}}s. The projection matrix calculation also takes into account the aspect ratio of the [=XRRenderState/output canvas=]. This value MUST be <code>null</code> for [=immersive sessions=].
<section class="unstable">
The <dfn attribute for="XRRenderState">baseLayer</dfn> attribute defines an {{XRWebGLLayer}} which the [=XR compositor=] will obtain images from.
</section>
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.
<pre class="idl">
callback XRFrameRequestCallback = void (DOMHighResTimeStamp time, XRFrame frame);
</pre>
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.
<div class="algorithm" data-algorithm="request-animation-frame">
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.
</div>
<div class="algorithm" data-algorithm="cancel-animation-frame">
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=].
</div>
<div class="algorithm" data-algorithm="run-animation-frames">
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 [=pending render state=] is not <code>null</code>, [=apply the pending render state=].
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/output canvas=] 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>.
</div>
<section class="unstable">
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.-->
</section>
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}}.
<pre class="idl">
[SecureContext, Exposed=Window] interface XRFrame {
[SameObject] readonly attribute XRSession session;
XRViewerPose? getViewerPose(XRReferenceSpace referenceSpace);
XRPose? getPose(XRSpace space, XRSpace baseSpace);
};
</pre>
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}}.
<div class="algorithm" data-algorithm="get-viewer-pose">
When the <dfn method for="XRFrame">getViewerPose(|referenceSpace|)</dfn> method is invoked, the user agent MUST run the following steps:
1. Let |frame| be the target {{XRFrame}}
1. Let |session| be |frame|'s {{XRFrame/session}} object.
1. If |frame|'s [=animationFrame=] boolean is <code>false</code>, throw an {{InvalidStateError}} and abort these steps.
1. Let |pose| be a new {{XRViewerPose}} object.
1. [=Populate the pose=] of |session|'s [=XRSession/viewer reference space=] in |referenceSpace| at the time represented by |frame| into |pose|.
1. If |pose| is <code>null</code> return <code>null</code>.
1. Let |xrviews| be an empty [=/list=].
1. For each [=view=] |view| in the [=XRSession/viewer reference space/list of views=] on the[=XRSession/viewer reference space=] of {{XRFrame/session}}, perform the following steps:
1. Let |xrview| be a new {{XRView}} object.
1. Initialize |xrview|'s {{XRView/eye}} to |view|'s [=view/eye=]
1. Initialize |xrview|'s {{XRView/projectionMatrix}} to |view|'s [=view/projection matrix=]
1. Let |offset| be an {{XRRigidTransform}} equal to the [=view offset=] of |view|
1. Set |xrview|'s {{XRView/transform}} property to the result of [=multiply transforms|multiplying=] the {{XRViewerPose}}'s {{XRPose/transform}} by the |offset| transform
1. [=list/Append=] |xrview| to |xrviews|
1. Set |pose|'s {{XRViewerPose/views}} to |xrviews|
1. Return |pose|.
</div>
<div class="algorithm" data-algorithm="get-pose">
When the <dfn method for="XRFrame">getPose(|space|, |baseSpace|)</dfn> method is invoked, the user agent MUST run the following steps:
1. Let |frame| be the target {{XRFrame}}
1. Let |pose| be a new {{XRPose}} object.
1. [=Populate the pose=] of |space| in |baseSpace| at the time represented by |frame| into |pose|.
1. Return |pose|.
</div>
Spaces {#spaces}
======
A core feature of the WebXR Device API is the ability to provide spatial tracking. Spaces are the interface that enable applications to reason about how tracked entities are spatially related to the user's physical environment and each other.
XRSpace {#xrspace-interface}
------------------
An {{XRSpace}} represents a virtual coordinate system with an origin that corresponds to a physical location. Spatial data that is requested from the API or given to the API is always expressed in relation to a specific {{XRSpace}} at the time of a specific {{XRFrame}}. Numeric values such as pose positions are coordinates in that space relative to its origin. The interface is intentionally opaque.
<pre class="idl">
[SecureContext, Exposed=Window] interface XRSpace : EventTarget {
};
</pre>
Each {{XRSpace}} has a <dfn for="XRSpace">session</dfn> which is set to the {{XRSession}} that created the {{XRSpace}}.
Each {{XRSpace}} has a <dfn for="XRSpace">native origin</dfn> that is tracked by the [=/XR device=]'s underlying tracking system, and an <dfn for="XRSpace">effective origin</dfn>, which is the basis of the {{XRSpace}}'s <dfn for="XRSpace">coordinate system</dfn>. The transform from the effective space to the [=native origin=]'s space is defined by an <dfn for="XRSpace">origin offset</dfn>, which is an {{XRRigidTransform}} initially set to an [=identity transform=].
The [=effective origin=] of an {{XRSpace}} can only be observed in the coordinate system of another {{XRSpace}} as an {{XRPose}}, returned by an {{XRFrame}}'s {{XRFrame/getPose()}} method. The spatial relationship between {{XRSpace}}s MAY change between {{XRFrame}}s.
<div class="algorithm" data-algorithm="populate-the-pose">
To <dfn>populate the pose</dfn> of a {{XRSpace}} |space| in an {{XRSpace}} |baseSpace| at the time represented by a {{XRFrame}} |frame| into an {{XRPose}} |pose|, the user agent MUST run the following steps:
1. 1. If |frame|'s [=active=] boolean is <code>false</code>, throw an {{InvalidStateError}} and abort these steps.
1. Let |session| be |frame|'s {{XRFrame/session}} object.
1. If |space|'s [=XRSpace/session=] does not equal |session|, throw an {{InvalidStateError}} and abort these steps.
1. If |baseSpace|'s [=XRSpace/session=] does not equal |session|, throw an {{InvalidStateError}} and abort these steps.
1. If |baseSpace|'s pose cannot be determined relative to |space| at the time represented by |frame|, set |pose| to <code>null</code>.
1. Let |transform| be |pose|'s {{XRPose/transform}}.
1. Set |transform|'s {{XRRigidTransform/position}} to the location of |space|'s [=effective origin=] in |baseSpace|'s [=coordinate system=].
1. Set |transform|'s {{XRRigidTransform/orientation}} to the orientation of |space|'s [=effective origin=] in |baseSpace|'s [=coordinate system=].
</div>
XRReferenceSpace {#xrreferencespace-interface}
------------------
An {{XRReferenceSpace}} is one of several common {{XRSpace}}s that applications can use to establish a spatial relationship with the user's physical environment.
{{XRReferenceSpace}}s are generally expected to remain static for the duration of the {{XRSession}}, with the most common exception being mid-session reconfiguration by the user. The [=native origin=] for every {{XRReferenceSpace}} describes a coordinate system where <code>+X</code> is considered "Right", <code>+Y</code> is considered "Up", and <code>-Z</code> is considered "Forward".
<pre class="idl">
enum XRReferenceSpaceType {
"viewer",
"local",
"local-floor",
"bounded-floor",
"unbounded"
};
[SecureContext, Exposed=Window]
interface XRReferenceSpace : XRSpace {
XRReferenceSpace getOffsetReferenceSpace(XRRigidTransform originOffset);
attribute EventHandler onreset;
};
</pre>
Each {{XRReferenceSpace}} has a <dfn for="XRReferenceSpace">type</dfn>, which is an {{XRReferenceSpaceType}}.
An {{XRReferenceSpace}} is most frequently obtained by calling {{XRSession/requestReferenceSpace()}}, which creates an instance of an {{XRReferenceSpace}} or an interface extending it, determined by the {{XRReferenceSpaceType}} enum value passed into the call. The type indicates the tracking behavior that the reference space will exhibit:
- Passing a type of <dfn enum-value for="XRReferenceSpaceType">viewer</dfn> creates an {{XRReferenceSpace}} instance. It represents a tracking space with a [=native origin=] which tracks the position and orientation of the [=viewer=]. Every {{XRSession}} MUST support {{XRReferenceSpaceType/viewer}} {{XRReferenceSpace}}s.
- Passing a type of <dfn enum-value for="XRReferenceSpaceType">local</dfn> creates an {{XRReferenceSpace}} instance. It represents a tracking space with a [=native 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. When using this reference space the user is not expected to move beyond their initial position much, if at all, and tracking is optimized for that purpose. For devices with [=6DoF=] tracking, {{local}} reference spaces should emphasize keeping the origin stable relative to the user's environment.
- Passing a type of <dfn enum-value for="XRReferenceSpaceType">local-floor</dfn> creates an {{XRReferenceSpace}} instance. It represents a tracking space with a [=native origin=] 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 MUST be estimated. When using this reference space the user is not expected to move beyond their initial position much, if at all, and tracking is optimized for that purpose. For devices with [=6DoF=] tracking, {{local-floor}} reference spaces should emphasize keeping the origin stable relative to the user's environment.
- Passing a type of <dfn enum-value for="XRReferenceSpaceType">bounded-floor</dfn> creates an {{XRBoundedReferenceSpace}} instance if supported by the [=/XR device=] and the {{XRSession}}. It represents a tracking space with it's [=native origin=] at the floor, where the user is expected to move within a pre-established boundary, given as the {{boundsGeometry}}. Tracking in a {{bounded-floor}} reference space is optimized for keeping the [=native origin=] and {{boundsGeometry}} stable relative to the user's environment.
- Passing a type of <dfn enum-value for="XRReferenceSpaceType">unbounded</dfn> creates an {{XRReferenceSpace}} instance if supported by the [=/XR device=] and the {{XRSession}}. It 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 [=native origin=] may drift over time.
Devices that support {{XRReferenceSpaceType/local}} reference spaces MUST support {{XRReferenceSpaceType/local-floor}} reference spaces, through emulation if necessary, and vice versa.
The <dfn attribute for="XRReferenceSpace">onreset</dfn> attribute is an [=Event handler IDL attribute=] for the {{reset}} event type.
<div class="algorithm" data-algorithm="create-reference-space">
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. Let |type| be set to the {{XRReferenceSpaceType}} passed to {{requestReferenceSpace()}}.
1. If the [=reference space is supported=] for |type| and |session|, run the following steps:
1. Initialize |referenceSpace| based on the following:
<dl class="switch">
<dt> If |type| is {{bounded-floor}}
<dd> Let |referenceSpace| be a new {{XRBoundedReferenceSpace}}.
<dt> Otherwise
<dd> Let |referenceSpace| be a new {{XRReferenceSpace}}.
</dl>
1. Initialize |referenceSpace|'s [=XRReferenceSpace/type=] to |type|.
1. Initialize |referenceSpace|'s [=XRSpace/session=] to |session|.
1. Return |referenceSpace|
1. Return <code>null</code>.
</div>
<div class="algorithm" data-algorithm="reference-space-supported">
To check if a <dfn>reference space is supported</dfn> for a given reference space type |type| and {{XRSession}} |session|, run the following steps:
1. If |type| is {{inline}}, return <code>true</code>.
1. If |type| is {{local}} or {{local-floor}}, and |session| is an [=immersive session=], return <code>true</code>.
1. If |type| is {{local}} or {{local-floor}}, and the [=/XR device=] supports reporting orientation data, return <code>true</code>.
1. If |type| is {{bounded-floor}} and |session| is an [=immersive session=], return if [=bounded reference spaces are supported=] by the [=/XR device=].
1. If |type| is {{unbounded}}, |session| is an [=immersive session=], and the [=/XR device=] supports stable tracking near the user over an unlimited distance, return <code>true</code>.
1. Return <code>false</code>.
</div>
<div class="algorithm" data-algorithm="get-offset-space">
The <dfn method for="XRReferenceSpace">getOffsetReferenceSpace(|originOffset|)</dfn> method MUST perform the following steps when invoked:
1. Let |base| be the {{XRReferenceSpace}} the method was called on.
1. Initialize |offsetSpace| based on the following:
<dl class="switch">
<dt> If |base| is an instance of {{XRBoundedReferenceSpace}}
<dd> Let |offsetSpace| be a new {{XRBoundedReferenceSpace}} and set |offsetSpace|'s {{boundsGeometry}} to |base|'s {{boundsGeometry}}, with each point multiplied by the {{XRRigidTransform/inverse}} of |originOffset|.
<dt> Else
<dd> Let |offsetSpace| be a new {{XRReferenceSpace}}.
</dl>
1. Set |offsetSpace|'s [=native origin=] to |base|'s [=native origin=].
1. Set |offsetSpace|'s [=origin offset=] to the result of [=multiply transforms|multiplying=] |base|'s [=origin offset=] by |originOffset|.
1. Return |offsetSpace|.
</div>
Note: It's expected that some applications will use {{getOffsetReferenceSpace()}} to implement scene navigation controls based on mouse, keyboard, touch, or gamepad input. This will result in {{getOffsetReferenceSpace()}} being called frequently, at least once per-frame during periods of active input. As a result UAs are strongly encouraged to make the creation of new {{XRReferenceSpace}}s with {{getOffsetReferenceSpace()}} a lightweight operation.
XRBoundedReferenceSpace {#xrboundedreferencespace-interface}
----------------------------
{{XRBoundedReferenceSpace}} extends {{XRReferenceSpace}} to include {{boundsGeometry}}, indicating the pre-confingured boundaries of the users space.
<pre class="idl">
[SecureContext, Exposed=Window]
interface XRBoundedReferenceSpace : XRReferenceSpace {
readonly attribute FrozenArray<DOMPointReadOnly> boundsGeometry;
};
</pre>
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-floor}} 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 {{unbounded}} reference space.
Each {{XRBoundedReferenceSpace}} has a <dfn for="XRBoundedReferenceSpace">native bounds geometry</dfn> describing 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 [=XRSpace/native 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.
The <dfn attribute for="XRBoundedReferenceSpace">boundsGeometry</dfn> attribute is an array of {{DOMPointReadOnly}}s such that each entry is equal to the entry in the {{XRBoundedReferenceSpace}}'s [=XRBoundedReferenceSpace/native bounds geometry=] premultiplied by the {{XRRigidTransform/inverse}} of the [=XRSpace/origin offset=]. In other words, it provides the same border in {{XRBoundedReferenceSpace}} coordinates relative to the [=XRSpace/effective origin=].
<div class="algorithm" data-algorithm="bounded-space-supported">
To check if <dfn>bounded reference spaces are supported</dfn> run the following steps:
1. If the [=/XR device=] cannot report boundaries, return false.
1. If the [=/XR device=] cannot identify the height of the user's physical floor, return false.
1. Return true.
</div>
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.
Views {#views}
=====
XRView {#xrview-interface}
------
An {{XRView}} describes a single <dfn>view</dfn> into an XR scene for a given frame.
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}}.
A [=view=] has an associated internal <dfn>view offset</dfn>, which is an {{XRRigidTransform}} describing the position and orientation of the [=view=] in the [=XRSession/viewer reference space=]'s [=coordinate system=].
A [=view=] has an associated <dfn for="view">projection matrix</dfn> which is a [=matrix=] describing the projection to be used when rendering the [=view=], provided by the underlying XR device. The [=view/projection matrix=] MAY include transformations such as shearing that prevent the projection from being accurately described by a simple frustum.
A [=view=] has an associated <dfn for="view">eye</dfn> which is an {{XREye}} describing which eye this view is expected to be shown to. If the view does not have an intrinsically associated eye (the display is monoscopic, for example) this value MUST be set to {{XREye/"none"}}.