Add inlineVerticalFieldOfView to XRRenderState (#519)

toji · web-flow · commit 595aa0e81743 · 2019-04-16T11:32:54.000-07:00
Defined the behavior of the `inlineVerticalFieldOfView` render state attribute in the explainer and spec. Only applies to inline sessions (Hence the name) and throws errors if you attempt to set it against an immersive session.
diff --git a/explainer.md b/explainer.md
@@ -555,6 +555,26 @@ function drawScene() {
 }
 ```
 
+### Changing the Field of View for inline sessions
+
+Whenever possible the matrices given by `XRView`'s `projectionMatrix` attribute should make use of physical properties, such as the headset optics or camera lens, to determine the field of view to use. Most inline content, however, won't have any physically based values from which to infer a field of view. In order to provide a unified render pipeline for inline content an arbitrary field of view must be selected.
+
+By default a vertical field of view of 0.5 radians (90 degrees) is used for inline sessions. The horizontal field of view can be computed from the vertical field of view based on the width/height ratio of the `outputContext`'s canvas.
+
+If a different default field of view is desired, it can be specified by passing a new `inlineVerticalFieldOfView` value, in radians, to the `updateRenderState` method:
+
+```js
+// This changes the default vertical field of view for an inline session to
+// 0.4 radians (72 degrees).
+xrSession.updateRenderState({
+  inlineVerticalFieldOfView: 0.4 * Math.PI,
+});
+```
+
+The UA is allowed to clamp the value, and if a physically-based field of view is available it must always be used in favor of the default value.
+
+Attempting to set a `inlineVerticalFieldOfView` value on an immersive session will cause `updateRenderState()` to throw an `InvalidStateError`. `XRRenderState.inlineVerticalFieldOfView` must return `null` on immersive sessions.
+
 ## Appendix A: I don’t understand why this is a new API. Why can’t we use…
 
 ### `DeviceOrientation` Events
@@ -646,13 +666,15 @@ enum XREnvironmentBlendMode {
 dictionary XRRenderStateInit {
   double depthNear;
   double depthFar;
+  double inlineVerticalFieldOfView;
   XRLayer? baseLayer;
   XRPresentationContext? outputContext
 };
 
 [SecureContext, Exposed=Window] interface XRRenderState {
   readonly attribute double depthNear;
   readonly attribute double depthFar;
+  readonly attribute double? inlineVerticalFieldOfView;
   readonly attribute XRLayer? baseLayer;
   readonly attribute XRPresentationContext? outputContext;
 };
diff --git a/index.bs b/index.bs
@@ -411,13 +411,16 @@ Each {{XRSession}} has an <dfn>active render state</dfn> which is a new {{XRRend
 
 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">
 
 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. Append |newState| to |session|'s [=list of pending render states=].
 
 </div>
@@ -433,8 +436,11 @@ When requested, the {{XRSession}} MUST <dfn>apply pending render states</dfn> by
   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/inlineVerticalFieldOfView}} is set, set |activeState|'s {{XRRenderState/inlineVerticalFieldOfView}} to |newState|'s {{XRRenderStateInit/inlineVerticalFieldOfView}}.
     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|.
+  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=].
 
 </div>
 
@@ -543,25 +549,29 @@ There are multiple values that developers can configure which affect how the ses
 dictionary XRRenderStateInit {
   double depthNear;
   double depthFar;
+  double inlineVerticalFieldOfView;
   XRLayer? baseLayer;
   XRPresentationContext? outputContext;
 };
 
 [SecureContext, Exposed=Window] interface XRRenderState {
   readonly attribute double depthNear;
   readonly attribute double depthFar;
+  readonly attribute double? inlineVerticalFieldOfView;
   readonly attribute XRLayer? baseLayer;
   readonly attribute XRPresentationContext? outputContext;
 };
 </pre>
 
 <div class="algorithm" data-algorithm="initialize-renderstate">
 
-When an {{XRRenderState}} object is created, the user agent MUST <dfn>initialize the render state</dfn> by running the following steps:
+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. If |session| is an [=immersive session=], initialize |state|'s {{XRRenderState/inlineVerticalFieldOfView}} to <code>null</code>.
+  1. Else initialize |state|'s {{XRRenderState/inlineVerticalFieldOfView}} to <code>PI * 0.5</code>.
   1. Initialize |state|'s {{XRRenderState/baseLayer}} to <code>null</code>.
   1. Initialize |state|'s {{XRRenderState/outputContext}} to <code>null</code>.
 
@@ -571,6 +581,8 @@ The <dfn attribute for="XRRenderState">depthNear</dfn> attribute defines the dis
 
 {{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/outputContext}}'s {{XRPresentationContext/canvas}}. This value MUST be <code>null</code> for [=immersive sessions=].
+
 Animation Frames {#animation-frames}
 ----------------
 
