Change inputSources getter from method to attrib. (#624)

toji · web-flow · commit 393984aa56c7 · 2019-05-13T16:32:21.000-07:00
Changes the `getInputSources()` method on `XRSesssion` to a readonly
attribute `inputSources`. This better reflects the expected behavior
of the returned array being a live object that is updated in-place as
input sources are added and removed.

In order to facilitate that change the `XRInputSourceArray` interface was
also added, since `FrozenArray` doesn't support the live changes that are
required for this attribute.
diff --git a/index.bs b/index.bs
@@ -363,13 +363,12 @@ enum XREnvironmentBlendMode {
   // Attributes
   readonly attribute XREnvironmentBlendMode environmentBlendMode;
   [SameObject] readonly attribute XRRenderState renderState;
+  readonly attribute XRInputSourceArray inputSources;
 
   // Methods
   void updateRenderState(optional XRRenderStateInit state);
   Promise&lt;XRReferenceSpace&gt; requestReferenceSpace(XRReferenceSpaceType type);
 
-  FrozenArray&lt;XRInputSource&gt; getInputSources();
-
   long requestAnimationFrame(XRFrameRequestCallback callback);
   void cancelAnimationFrame(long handle);
 
@@ -472,13 +471,7 @@ When the <dfn method for="XRSession">requestReferenceSpace(|options|)</dfn> meth
 
 </div>
 
-<div class="algorithm" data-algorithm="get-input-sources">
-
-When the <dfn method for="XRSession">getInputSources()</dfn> method is invoked, the user agent MUST run the following steps:
-
-  1. Return the current [=list of active input sources=].
-
-</div>
+The <dfn attribute for="XRSession">inputSources</dfn> attribute returns the {{XRSession}}'s [=list of active input sources=].
 
 Each {{XRSession}} has a <dfn>environment blending mode</dfn> value, which is a enum which MUST be set to whichever of the following values best matches the behavior of imagery rendered by the session in relation to the user's surrounding environment.
 
@@ -518,7 +511,7 @@ We still need to document what happens when we <dfn lt="blur all sessions">blur
 
 We still need to document what happens when we <dfn>poll the device pose</dfn> (This is <a href="https://github.com/immersive-web/webxr/issues/480">filed</a>.)
 
-We still need to document how the<dfn>list of active input sources</dfn> is maintained. (This is <a href="https://github.com/immersive-web/webxr/issues/465">filed</a>.)
+We still need to document how the <dfn>list of active input sources</dfn> is maintained. (This is <a href="https://github.com/immersive-web/webxr/issues/465">filed</a>.)
 
 XRRenderState {#xrrenderstate-interface}
 -------------
@@ -1162,6 +1155,27 @@ The <dfn attribute for="XRInputSource">gamepad</dfn> attribute is a {{Gamepad}}
 NOTE: {{XRInputSource}}s with a <code>null</code> {{gamepad}} can still fire {{select}}, {{selectstart}}, and {{selectend}} events to report binary inputs.
 </section>
 
+<section class="unstable">
+XRInputSourceArray {#xrinputsourcearray-interface}
+------------------
+
+An {{XRInputSourceArray}} represents a [=/list=] of {{XRInputSource}}s. It is used in favor of a [=/frozen array type=] when the contents of the [=/list=] are expected to change over time, such as with the {{XRSession}} {{XRSession/inputSources}} attribute.
+
+<pre class="idl">
+[SecureContext, Exposed=Window]
+interface XRInputSourceArray {
+  iterable&lt;XRInputSource&gt;;
+  readonly attribute unsigned long length;
+  getter XRInputSource(unsigned long index);
+};
+</pre>
+
+The <dfn attribute for="XRInputSourceArray">length</dfn> attribute of {{XRInputSourceArray}} indicates how many {{XRInputSource}}s are contained within the {{XRInputSourceArray}}.
+
+The <dfn export for="XRInputSourceArray">[=/indexed property getter=]</dfn> of {{XRInputSourceArray}} retrieves the {{XRInputSource}} at the provided index.
+
+</section>
+
 <section class="unstable">
 Gamepad API Integration {#gamepad-api-integration}
 -----------------------
@@ -1170,7 +1184,7 @@ Gamepad API Integration {#gamepad-api-integration}
 
   - {{XRInputSource/gamepad}} MUST NOT be included in the array returned by {{navigator.getGamepads()}}.
   - {{XRInputSource/gamepad}}'s {{Gamepad/index}} attribute MUST be <code>0</code>.
-  - {{XRInputSource/gamepad}}'s {{Gamepad/connected}} attribute MUST be <code>true</code> until the {{XRInputSource}} is removed from the array returned by {{XRSession/getInputSources()}} or the {{XRSession}} is ended.
+  - {{XRInputSource/gamepad}}'s {{Gamepad/connected}} attribute MUST be <code>true</code> until the {{XRInputSource}} is removed from the [=list of active input sources=] or the {{XRSession}} is ended.
 
 The {{XRInputSource/gamepad}}'s {{Gamepad/id}} also enforces additional behavioral restrictions, and MUST conform to the following rules:
 
diff --git a/input-explainer.md b/input-explainer.md
@@ -31,10 +31,10 @@ In addition to a targeting ray, all input sources provide a mechanism for the us
 ## Basic usage
 
 ### Enumerating input sources
-Calling the `getInputSources()` function on an `XRSession` will return a list of all `XRInputSource`s that the user agent considers active. The properties of an `XRInputSource` object are immutable. If a device can be manipulated in such a way that these properties can change, the `XRInputSource` will be removed from the array and a new entry created.
+The `inputSources` attribute on an `XRSession` returns a list of all `XRInputSource`s that the user agent considers active. The properties of an `XRInputSource` object are immutable. If a device can be manipulated in such a way that these properties can change, the `XRInputSource` will be removed from the array and a new entry created.
 
 ```js
-let inputSources = xrSession.getInputSources();
+let inputSources = xrSession.inputSources;
 ```
 
 When input sources are added to or removed from the list of available input sources the `inputsourceschange` event must be fired on the `XRSession` object to indicate that any cached copies of the list should be refreshed. In addition, the `inputsourceschange` event will also fire once after the session creation callback completes. This event is of the type `XRInputSourceChangeEvent` and will contain three attributes: `session` is associated session being changed, `added` is the new input sources, and `removed` is the input sources that will no longer be reported.
@@ -50,7 +50,7 @@ function onSessionStarted(session) {
 
 let xrInputSources = null;
 function onInputSourcesChange(event) {
-  xrInputSources = event.session.getInputSources();
+  xrInputSources = event.session.inputSources;
 }
 ```
 
@@ -92,7 +92,7 @@ function onSessionStarted(session) {
 All three events are `XRInputSourceEvent` events. When fired the event's `inputSource` attribute will contain the `XRInputSource` that produced the event. The event's `frame` attribute will contain a valid `XRFrame` that can be used to call `getPose()` at the time the selection event occurred. Calling the frame's `getViewerPose()` method will throw an `InvalidState` error. (The viewer's pose can still be queried by passing an `XRReferenceSpace` of type `viewer` to `XRFrame.getPose()`.)
 
 ### Transient input sources
-Some input sources are only be added to the list of input sources while an action is occurring. For example, those with an `targetRayMode` of 'screen' or those with `targetRayMode` of 'gaze' which are triggered by a voice command. In these cases, `XRInputSource` is only present in the array returned by `getInputSources()` during the lifetime of the action. In this circumstance, the order of events is as follows:
+Some input sources are only be added to the list of input sources while an action is occurring. For example, those with an `targetRayMode` of 'screen' or those with `targetRayMode` of 'gaze' which are triggered by a voice command. In these cases, `XRInputSource` is only present in the `inputSources` array during the lifetime of the action. In this circumstance, the order of events is as follows:
 1. Optionally `pointerdown`
 1. `inputsourceschange` for add
 1. `selectstart`
@@ -106,7 +106,7 @@ Some input sources are only be added to the list of input sources while an actio
 Input sources that are instantaneous, without a clear start and end point such as a verbal command like "Select", will still fire all events in the sequence.
 
 ### Choosing a preferred input source
-Many platforms support multiple input sources concurrently. Examples of this are left/right handed motion controllers or hand tracking combined with a 0DOF clicker. Since `xrSession.getInputSources()` returns all connected input sources, an application may choose to take into consideration the most recently used input sources when rendering UI hints, such as a cursor, ray or highlight.
+Many platforms support multiple input sources concurrently. Examples of this are left/right handed motion controllers or hand tracking combined with a 0DOF clicker. Since `xrSession.inputSources` returns all connected input sources, an application may choose to take into consideration the most recently used input sources when rendering UI hints, such as a cursor, ray or highlight.
 
 To simplify the sample code throughout this explainer, an example is provided which shows one potential way to set a `preferredInputSource`.
 
@@ -120,7 +120,7 @@ function onSelectStart(event) {
 }
 
 function onInputSourceChanged(event) {
-  xrInputSources = event.session.getInputSources();
+  xrInputSources = event.session.inputSources;
 
   // Choose an appropriate default from available inputSources, such as 
   // prioritizing based on the value of targetRayMode: 'screen' over 
@@ -382,7 +382,7 @@ This is a partial IDL and is considered additive to the core IDL found in the ma
 //
 
 partial interface XRSession {
-  FrozenArray<XRInputSource> getInputSources();
+  readonly attribute XRInputSourceArray inputSources;
   
   attribute EventHandler onselect;
   attribute EventHandler onselectstart;
@@ -415,6 +415,13 @@ interface XRInputSource {
   readonly attribute Gamepad? gamepad;
 };
 
+[SecureContext, Exposed=Window]
+interface XRInputSourceArray {
+  iterable<XRInputSource>;
+  readonly attribute unsigned long length;
+  getter XRInputSource(unsigned long index);
+};
+
 //
 // Events
 //
