Merge pull request #1093 from Manishearth/cache-session

Manishearth · web-flow · commit d01049d5ead2 · 2020-07-01T12:28:54.000-07:00
Fixup frame and viewport caching to be explicit
diff --git a/index.bs b/index.bs
@@ -612,6 +612,8 @@ enum XRVisibilityState {
 
 Each {{XRSession}} has a <dfn for="XRSession">mode</dfn>, which is one of the values of {{XRSessionMode}}.
 
+Each {{XRSession}} has an <dfn for=XRSession>animation frame</dfn>, which is an {{XRFrame}} initialized with [=XRFrame/active=] set to <code>false</code>, [=XRFrame/animationFrame=] set to <code>true</code>, and {{XRFrame/session}} set to the {{XRSession}}.
+
 <div class="algorithm" data-algorithm="initialize-session">
 
 To <dfn>initialize the session</dfn>, given |session|, |mode|, and |device|, the user agent MUST run the following steps:
@@ -699,7 +701,9 @@ When requested, the {{XRSession}} |session| MUST <dfn>apply the pending render s
   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. Let |oldLayer| be |activeState|'s {{XRRenderState/baseLayer}}.
   1. Set |activeState| to |newState|.
+  1. If |oldLayer| is not equal to |activeState|'s {{XRRenderState/baseLayer}}, or the dimensions of |oldLayer| are different from |baseLayer|, [=update the viewports=] for |session|.
   1. If |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} is less than |session|'s [=minimum inline field of view=] set |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} to |session|'s [=minimum inline field of view=].
   1. If |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} is greater than |session|'s [=maximum inline field of view=] set |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} to |session|'s [=maximum inline field of view=].
   1. If |activeState|'s {{XRRenderState/depthNear}} is less than |session|'s [=minimum near clip plane=] set |activeState|'s {{XRRenderState/depthNear}} to |session|'s [=minimum near clip plane=].
@@ -813,7 +817,9 @@ Note: The {{XRSession}}'s [=visibility state=] does not necessarily imply the vi
 
 Note: The {{XRSession}}'s [=visibility state=] does not affect or restrict mouse behavior on tethered sessions where 2D content is still visible while an [=immersive session=] is active. Content should consider using the [[!pointerlock]] API if it wishes to have stronger control over mouse behavior.
 
-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 [=XRSession/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=].
+Each {{XRSession}} has a <dfn for="XRSession">viewer reference space</dfn>, which is an {{XRReferenceSpace}} of type {{XRReferenceSpaceType/"viewer"}} with an [=identity transform=] [=XRSpace/origin offset=].
+
+Each {{XRSession}} has a <dfn for="XRSession">list of views</dfn>, which is a [=/list=] of [=view=]s corresponding to the views provided by the [=XRSession/XR device=]. If the {{XRSession}}'s {{XRSession/renderState}}'s [=XRRenderState/composition 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.
 
@@ -940,20 +946,15 @@ NOTE: The <a href="https://immersive-web.github.io/layers">WebXR layers module</
 When an {{XRSession}} |session| receives updated [=viewer=] state for timestamp |frameTime| from the [=XRSession/XR device=], it runs an <dfn>XR animation frame</dfn>, which MUST run the following steps regardless of if the [=list of animation frame callbacks=] is empty or not:
 
   1. Let |now| be the [=current high resolution time=].
-  1. Initialize |frame| as follows:
-    <dl class="switch">
-      <dt>If |session| has previously run an [=XR animation frame=], the user agent MUST:</dt>
-      <dd>Let |frame| be the same {{XRFrame}} object created by the earlier [=XR animation frame=]</dd>
-      <dt>Otherwise:</dt>
-      <dd>Let |frame| be a [=new=] {{XRFrame}} with [=XRFrame/time=] |frameTime| and {{XRFrame/session}} |session| in the [=relevant realm=] of |session|.</dd>
-    </dl>
+  1. Let |frame| be |session|'s [=XRSession/animation frame=].
+  1. Set |frame|'s [=XRFrame/time=] to |frameTime|.
   1. If |session|'s [=pending render state=] is not <code>null</code>, [=apply the pending render state=].
+  1. If the [=XRSession/list of views=] has changed since the last [=XR animation frame=], [=update the viewports=].
   1. If [=check the layers state=] with |session|'s {{XRSession/renderState}} is <code>false</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. Set  |session|'s [=list of currently running animation frame callbacks=] to be |session|'s [=list of animation frame callbacks=].
   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. [=XRFrame/Apply frame updates=] for |frame|.
   1. For each |entry| in |session|'s [=list of currently running animation frame callbacks=], in order:
     1. If the |entry|'s [=cancelled=] boolean is <code>true</code>, continue to the next entry.
@@ -1057,11 +1058,12 @@ When this method is invoked, the user agent MUST run the following steps:
   1. [=Populate the pose=] of |session|'s [=XRSession/viewer reference space=] in |referenceSpace| at the time represented by |frame| into |pose|, with <code>force emulation</code> set to <code>true</code>.
   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. For each [=view=] |view| in the [=XRSession/list of views=] on {{XRFrame/session}}, perform the following steps:
       1. Let |xrview| be a new {{XRView}} object in the [=relevant realm=] of |session|.
       1. Initialize |xrview|'s [=XRView/underlying view=] to |view|.
       1. Initialize |xrview|'s {{XRView/eye}} to |view|'s [=view/eye=].
-      1. Initialize |xrview|'s [=XRView/frame=] to |frame|.
+      1. Initialize |xrview|'s [=XRView/frame time=] to |frame|'s [=XRFrame/time=].
+      1. Initialize |xrview|'s [=XRView/session=] to |session|.
       1. Let |offset| be an [=new=] {{XRRigidTransform}} object equal to the [=view offset=] of |view| in the [=relevant realm=] of |session|.
       1. Set |xrview|'s {{XRView/transform}} property to the result of [=multiply transforms|multiplying=] the {{XRViewerPose}}'s {{XRPose/transform}} by the |offset| transform in the relevant realm of |session|
       1. [=list/Append=] |xrview| to |xrviews|
@@ -1337,7 +1339,9 @@ The <dfn attribute for="XRView">projectionMatrix</dfn> attribute is the [=view/p
 
 The <dfn attribute for="XRView">transform</dfn> attribute is the {{XRRigidTransform}} of the viewpoint. It represents the position and orientation of the viewpoint in the {{XRReferenceSpace}} provided in {{XRFrame/getViewerPose()}}.
 
-Each {{XRView}} has an associated <dfn for="XRView">frame</dfn> which is the {{XRFrame}} that produced it.
+Each {{XRView}} has an associated <dfn for="XRView">session</dfn> which is the {{XRSession}} that produced it.
+
+Each {{XRView}} has an associated <dfn for="XRView">frame time</dfn> which is the [=XRFrame/time=] of the {{XRFrame}} that produced it.
 
 Each {{XRView}} has an associated <dfn for="XRView">underlying view</dfn> which is the underlying [=view=] that it represents.
 
@@ -1357,6 +1361,23 @@ To <dfn for="XRView">obtain the projection matrix</dfn> for a given {{XRView}} |
 
 </div>
 
+<div class=algorithm data-algorithm="update-the-viewports">
+
+When the [=XRSession/list of views=] changes, one can <dfn>update the viewports</dfn> for an {{XRSession}} |session| by performing the following steps:
+
+  1. Let |layer| be the {{XRSession/renderState}}'s {{XRRenderState/baseLayer}}.
+  1. If |layer| is <code>null</code> abort these steps.
+  1. Set |layer|'s [=list of viewport objects=] to the empty [=/list=].
+  1. For each [=view=] |view| in [=XRSession/list of views=]:
+    1. Let |glViewport| be the [=WebGL viewport=] from the [=list of viewports=] associated with |view|.
+    1. Let |viewport| be a [=new=] {{XRViewport}} in the [=relevant realm=] of |session|.
+    1. Initialize |viewport|'s {{XRViewport/x}} to |glViewport|'s <code>x</code> component.
+    1. Initialize |viewport|'s {{XRViewport/y}} to |glViewport|'s <code>y</code> component.
+    1. Initialize |viewport|'s {{XRViewport/width}} to |glViewport|'s <code>width</code>.
+    1. Initialize |viewport|'s {{XRViewport/height}} to |glViewport|'s <code>height</code>.
+    1. [=list/Append=] |viewport| to |layer|'s [=list of viewport objects=].
+
+</div>
 
 Primary and Secondary Views {#primary-and-secondary-views}
 ----------
@@ -1953,29 +1974,22 @@ Depth values stored in the buffer are expected to be between <code>0.0</code> an
 
 Note: Making the scene's depth buffer available to the compositor allows some platforms to provide quality and comfort improvements such as improved reprojection.
 
-Each {{XRWebGLLayer}} MUST have a <dfn>list of viewports</dfn> which is a [=/list=] containing one [=WebGL viewport=] for each {{XRView}} the {{XRSession}} currently exposes. The viewports MUST have a {{XRViewport/width}} and {{XRViewport/height}} greater than <code>0</code> and MUST describe a rectangle that does not exceed the bounds of the [=target framebuffer=]. The viewports MUST NOT be overlapping. If [=XRWebGLLayer/composition disabled=] is <code>true</code>, the [=list of viewports=] MUST contain a single [=WebGL viewport=] that covers the [=XRWebGLLayer/context=]'s entire default framebuffer.
+Each {{XRWebGLLayer}} MUST have a <dfn>list of viewports</dfn> which is a [=/list=] containing one [=WebGL viewport=] for each [=view=] the {{XRSession}} may expose, including [=secondary views=] that are not currently active but may become active for the current session. The viewports MUST have a {{XRViewport/width}} and {{XRViewport/height}} greater than <code>0</code> and MUST describe a rectangle that does not exceed the bounds of the [=target framebuffer=]. The viewports MUST NOT be overlapping. If [=XRWebGLLayer/composition disabled=] is <code>true</code>, the [=list of viewports=] MUST contain a single [=WebGL viewport=] that covers the [=XRWebGLLayer/context=]'s entire default framebuffer.
+
+Each {{XRWebGLLayer}} MUST have a <dfn>list of viewport objects</dfn> which is a [=/list=] containing one {{XRViewport}} for each [=view=] the {{XRSession}} currently exposes.
 
 {{getViewport()}} queries the {{XRViewport}} the given {{XRView}} should use when rendering to the layer.
 
 <div class="algorithm" data-algorithm="get-viewport">
 
 The <dfn method for="XRWebGLLayer">getViewport(|view|)</dfn> method, when invoked on an {{XRWebGLLayer}} |layer|, MUST run the following steps:
 
-  1. Let |frame| be |view|'s [=XRView/frame=].
-  1. If |frame|'s {{XRFrame/session}} is not equal to |layer|'s [=XRWebGLLayer/session=], throw an {{InvalidStateError}} and abort these steps.
+  1. Let |session| be |view|'s [=XRView/session=].
+  1. Let |frame| be |session|'s [=XRSession/animation frame=].
+  1. If |session| is not equal to |layer|'s [=XRWebGLLayer/session=], throw an {{InvalidStateError}} and abort these steps.
   1. If |frame|'s [=XRFrame/active=] boolean is <code>false</code>, throw an {{InvalidStateError}} and abort these steps.
-  1. Let |glViewport| be the [=WebGL viewport=] from the [=list of viewports=] associated with |view|.
-  1. Initialize |viewport| as follows:
-    <dl class="switch">
-      <dt>If a |view| with the same underlying [=view=] has been passed to a getViewport() call previously, and |glViewport| has not changed since then, the user agent MUST:</dt>
-      <dd>Let |viewport| be the same {{XRViewport}} object returned by the earlier call to {{XRWebGLLayer/getViewport()}}</dd>
-      <dt>Otherwise:</dt>
-      <dd>Let |viewport| be a [=new=] {{XRViewport}} in the [=relevant realm=] of |layer|'s [=XRWebGLLayer/session=].</dd>
-    </dl>
-  1. Initialize |viewport|'s {{XRViewport/x}} to |glViewport|'s <code>x</code> component.
-  1. Initialize |viewport|'s {{XRViewport/y}} to |glViewport|'s <code>y</code> component.
-  1. Initialize |viewport|'s {{XRViewport/width}} to |glViewport|'s <code>width</code>.
-  1. Initialize |viewport|'s {{XRViewport/height}} to |glViewport|'s <code>height</code>.
+  1. If |view|'s [=XRView/frame time=] is not equal to |frame|'s [=XRFrame/time=], throw an {{InvalidStateError}} and abort these steps.
+  1. Let |viewport| be the {{XRViewport}} from the [=list of viewport objects=] associated with |view|.
   1. Return |viewport|.
 
 </div>
