You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
automation: Adapt to Generic Sensor changes to stash provided readings
Just like with w3c/sensors#487, the idea is to make it possible for
users to write, for example
```js
await test_driver.create_virtual_sensor(...);
await test_driver.update_virtual_sensor(...);
window.addEventListener('deviceorientation', ...);
```
and receive the readings above even if the connection to the virtual sensor
was made only after the addEventListener() call. Previously, users would
need to carefully order the calls to addEventListener(),
update_virtual_sensor() and possibly even need to add a dummy event listener
first to get everything to work correctly.
Unfortunately, just as with w3c/sensors#487 this requires quite a few
changes, even more so in this specification, which is quite vague when it
comes to connecting to sensors and the lifetimes of such connections.
Some of that behavior is now specified for the virtual sensors case, so that
each Document has a `[[virtualSensorMapping]]` that maps virtual sensor
types to "orientation event platform sensor-likes", a concept borrowed from
Generic Sensor's automation section.
Similarly to that section, the idea is that:
- Whenever the user agent needs to connect to the underlying hardware
because addEventListener() was called, it first attempts to find a virtual
sensor, get/create an orientation event platform sensor-like, adds it to
`[[virtualSensorMapping]]` and to the virtual sensor's connected platform
sensors set and retrieves any existing readings from the virtual sensor.
- When a Document is being unloaded, all platform sensor-likes in
`[[virtualSensorMapping]]` are removed from their virtual sensors'
connected platform sensors set.
- Similarly, when a virtual sensor is removed, any platform sensor-likes in
its connected platform set have their associated "device sensor" set to
null.
In the rest of the spec, we switch from attempting to derive a virtual
sensor from the top-level traversable directly to trying to find a suitable
platform sensor-like entry in `[[virtualSensorMapping]]` and checking its
associated virtual sensor when one is set.
Related to: w3c/sensors#478.
@@ -334,12 +340,14 @@ The <dfn method for="DeviceOrientationEvent">requestPermission(<var>absolute</va
334
340
To <dfn>fire an orientation event</dfn> given a <var>event name</var> (a string), <var>window</var> (a {{Window}}) and <var>absolute</var> (a boolean):
335
341
336
342
1. Let <var>orientation</var> be null.
337
-
1. Let <var>topLevelTraversable</var> be <var>window</var>'s <a for=Window>navigable</a>'s <a for=navigable>top-level traversable</a>.
338
343
1. Let <var>virtualSensorType</var> be "<code><a data-lt="relative-orientation virtual sensor type">relative-orientation</a></code>" if <var>absolute</var> is false, and "<code><a data-lt="absolute-orientation virtual sensor type">absolute-orientation</a></code>" otherwise.
339
-
1. If <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a><a for=map>contains</a><var>virtualSensorType</var>:
340
-
1. Let <var>virtualSensor</var> be <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a>[<var>virtualSensorType</var>].
341
-
1. If <var>virtualSensor</var>'s <a>can provide readings flag</a> is true:
342
-
1. Set <var>orientation</var> to the latest readings provided to <var>virtualSensor</var> with the "<code>alpha</code>", "<code>beta</code>", and "<code>gamma</code>" keys.
344
+
1. Let <var>document</var> be <var>window</var>'s <a>associated document</a>.
345
+
1. If <var>document</var>'s {{Document/[[virtualSensorMapping]]}}<a for=map>contains</a><var>virtualSensorType</var>:
346
+
1. Let <var>virtualSensor</var> be <var>document</var>'s {{Document/[[virtualSensorMapping]]}}[<var>virtualSensorType</var>]'s [=orientation event platform sensor-like/device sensor=].
347
+
1. If <var>virtualSensor</var> is not null:
348
+
1. Set <var>orientation</var> to <var>virtualSensor</var>'s <a for="virtual sensor">latest saved reading</a>.
349
+
350
+
Note: <var>orientation</var> will remain null otherwise.
343
351
1. Otherwise:
344
352
1. If <var>absolute</var> is false:
345
353
1. Set <var>orientation</var> to the device's <a>relative orientation</a> in the tridimensional plane.
@@ -560,11 +568,11 @@ At an <a>implementation-defined</a> interval <var>interval</var>, the user agent
560
568
1. If <var>document</var>'s <a>visibility state</a> is not "<code>visible</code>", return.
1. If <var>document</var> is not <a>allowed to use</a> the <a>policy-controlled feature</a> named <var>policy</var>, return.
563
-
1. Let <var>topLevelTraversable</var> be <var>window</var>'s <a for=Window>navigable</a>'s <a for=navigable>top-level traversable</a>.
571
+
1. Let <var>virtualSensorMapping</var> be <var>document</var>'s {{Document/[[virtualSensorMapping]]}}.
564
572
1. Let <var>platformLinearAcceleration</var> be null.
565
-
1. If <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a><a for=map>contains</a> "<code>linear-acceleration</code>":
566
-
1. Let <var>virtualSensor</var> be <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a>["<code>linear-acceleration</code>"].
567
-
1. If <var>virtualSensor</var>'s <a>can provide readings flag</a>is true, then set <var>platformLinearAcceleration</var> to the latest readings provided to <var>virtualSensor</var>.
573
+
1. If <var>virtualSensorMapping</var><a for=map>contains</a> "<code>linear-acceleration</code>":
574
+
1. Let <var>virtualSensor</var> be <var>virtualSensorMapping</var>["<code>linear-acceleration</code>"]'s [=orientation event platform sensor-like/device sensor=].
575
+
1. If <var>virtualSensor</var>is not null, then set <var>platformLinearAcceleration</var> to <var>virtualSensor</var>'s <a for="virtual sensor">latest saved reading</a>.
568
576
1. Otherwise, if the implementation is able to provide <a>linear acceleration</a>:
569
577
1. Set <var>platformLinearAcceleration</var> to the device's <a>linear acceleration</a> along the X, Y and Z axes.
570
578
1. Let <var>acceleration</var> be null.
@@ -577,9 +585,9 @@ At an <a>implementation-defined</a> interval <var>interval</var>, the user agent
577
585
1. Set <var>acceleration</var>'s <a for="DeviceMotionEventAcceleration">z axis acceleration</a> to <var>platformLinearAcceleration</var>'s value along the Z axis, or null if it cannot be provided.
578
586
1. If <var>acceleration</var>'s <a for="DeviceMotionEventAcceleration">z axis acceleration</a> is not null, limit its precision to no more than 0.1 m/s<sup>2</sup>.
579
587
1. Let <var>platformAccelerationIncludingGravity</var> be null.
580
-
1. If <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a><a for=map>contains</a> "<code>accelerometer</code>":
581
-
1. Let <var>virtualSensor</var> be <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a>["<code>accelerometer</code>"].
582
-
1. If <var>virtualSensor</var>'s <a>can provide readings flag</a>is true, then set <var>platformAccelerationIncludingGravity</var> to the latest readings provided to <var>virtualSensor</var>.
588
+
1. If <var>virtualSensorMapping</var><a for=map>contains</a> "<code>accelerometer</code>":
589
+
1. Let <var>virtualSensor</var> be <var>virtualSensorMapping</var>["<code>accelerometer</code>"]'s [=orientation event platform sensor-like/device sensor=].
590
+
1. If <var>virtualSensor</var>is not null, then set <var>platformAccelerationIncludingGravity</var> to <var>virtualSensor</var>'s <a for="virtual sensor">latest saved reading</a>.
583
591
1. Otherwise, if the implementation is able to provide <a>acceleration with gravity</a>:
584
592
1. Set <var>platformAccelerationIncludingGravity</var> to the device's <a>linear acceleration</a> along the X, Y and Z axes.
585
593
1. Let <var>accelerationIncludingGravity</var> be null.
@@ -592,9 +600,9 @@ At an <a>implementation-defined</a> interval <var>interval</var>, the user agent
592
600
1. Set <var>accelerationIncludingGravity</var>'s <a for="DeviceMotionEventAcceleration">z axis acceleration</a> to <var>platformAccelerationIncludingGravity</var>'s value along the Z axis, or null if it cannot be provided.
593
601
1. If <var>accelerationIncludingGravity</var>'s <a for="DeviceMotionEventAcceleration">z axis acceleration</a> is not null, limit its precision to no more than 0.1 m/s<sup>2</sup>.
594
602
1. Let <var>platformRotationRate</var> be null.
595
-
1. If <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a><a for=map>contains</a> "<code>gyroscope</code>":
596
-
1. Let <var>virtualSensor</var> be <var>topLevelTraversable</var>'s <a>virtual sensor mapping</a>["<code>gyroscope</code>"].
597
-
1. If <var>virtualSensor</var>'s <a>can provide readings flag</a>is true, then set <var>platformRotationRate</var> to the latest readings provided to <var>virtualSensor</var>.
603
+
1. If <var>virtualSensorMapping</var><a for=map>contains</a> "<code>gyroscope</code>":
604
+
1. Let <var>virtualSensor</var> be <var>virtualSensorMapping</var>["<code>gyroscope</code>"]'s [=orientation event platform sensor-like/device sensor=].
605
+
1. If <var>virtualSensor</var>'s is not null, then set <var>platformRotationRate</var> to <var>virtualSensor</var>'s <a for="virtual sensor">latest saved reading</a>.
598
606
1. Otherwise, if the implementation is able to provide <a>rotation rate</a>:
599
607
1. Set <var>platformRotationRate</var> to the device's <a>rotation rate</a> about the X, Y and Z axes.
600
608
1. Let <var>rotationRate</var> be null.
@@ -681,6 +689,72 @@ To address this challenge, this document builds upon the [[WEBDRIVER2]] <a>exten
681
689
682
690
This specification only requires implementations to support the [[GENERIC-SENSOR#automation]] section of the [[GENERIC-SENSOR]] specification, not its interfaces and events.
Several aspects of the manner in which the user agent interacts with the underlying hardware or operating system are [=implementation-defined=]. For instance, the [[#model]] and [[#api]] sections do not mandate:
696
+
- That readings must be retrieved in a specific way.
697
+
- When or how the user agent connects to one or more providers of readings.
698
+
- Which types or data structures need to be used to store readings.
699
+
- Whether readings obtained from the platform or operating system are shared across [=documents=].
700
+
701
+
For automation support to work, specifically in the context of integrating with [[GENERIC-SENSOR#automation]], some of this behavior needs to be specified in more detail.
702
+
703
+
The {{Document}} interface must have a <dfn attribute for="Document">\[[virtualSensorMapping]]</dfn> internal slot, a [=map=] of [=virtual sensor types=] to [=orientation event platform sensor-likes=]. A <dfn>orientation event platform sensor-like</dfn> is a [=platform sensor-like=][=struct=] with the following items:
704
+
705
+
- A <dfn for="orientation event platform sensor-like">sampling frequency</dfn> (a number). It represents either the frequency with which the user agent either polls the underlying hardware for readings, or the frequency at which the underlying hardware should notify the user agent of new readings.
706
+
- A <dfn for="orientation event platform sensor-like">device sensor</dfn> (a [=virtual sensor=] or null).
To <dfn>connect to a virtual sensor</dfn> given |window| (a {{Window}}), |virtualSensorType| (a string), and |samplingFrequency| (a number) perform the following steps. They return a boolean.
718
+
719
+
1. Let |topLevelTraversable| be |window|'s [=Window/navigable=]'s [=navigable/top-level traversable=].
720
+
1. If |topLevelTraversable|'s [=virtual sensor mapping=] does not [=map/contain=] |virtualSensorType|, return false.
721
+
1. Let |virtualSensor| be |topLevelTraversable|'s [=virtual sensor mapping=][|virtualSensorType|].
722
+
1. Let |platformSensorLike| be null.
723
+
1. If |window|'s [=associated Document=]'s {{Document/[[virtualSensorMapping]]}}[=map/contains=] |virtualSensorType|:
724
+
1. Set |platformSensorLike| to |window|'s [=associated Document=]'s {{Document/[[virtualSensorMapping]]}}[|virtualSensorType|].
725
+
1. Otherwise:
726
+
1. Set |platformSensorLike| to a new [=orientation event platform sensor-like=] whose [=orientation event platform sensor-like/device sensor=] is null.
727
+
1. Set |window|'s [=associated Document=]'s {{Document/[[virtualSensorMapping]]}}[|virtualSensorType|] to |platformSensorLike|.
728
+
1. If |samplingFrequency| is less than |virtualSensor|'s [=virtual sensor/minimum sampling frequency=] or greater than |virtualSensor|'s
Note: |platformSensorLike|'s [=orientation event platform sensor-like/device sensor=] will remain null.
732
+
733
+
1. Set |platformSensorLike|'s [=orientation event platform sensor-like/sampling frequency=] to |samplingFrequency|.
734
+
1. If |virtualSensor|'s [=virtual sensor/can provide readings flag=] is false, return true.
735
+
736
+
Note: |platformSensorLike|'s [=orientation event platform sensor-like/device sensor=] will remain null.
737
+
1. If |platformSensorLike|'s [=orientation event platform sensor-like/device sensor=] is null:
738
+
1. Set |platformSensorLike|'s [=orientation event platform sensor-like/device sensor=] to |virtualSensor|.
739
+
1. [=set/Append=] |platformSensorLike| to |virtualSensor|'s [=virtual sensor/connected platform sensors=].
740
+
1. [=In parallel=]:
741
+
1. If |virtualSensor|'s [=virtual sensor/latest saved readings=] is not null:
742
+
1. In an [=implementation-defined=] way, make |virtualSensor|'s [=virtual sensor/latest saved readings=] available to |platformSensorLike|.
743
+
1. Return true.
744
+
745
+
</div>
746
+
747
+
<div algorithm>
748
+
To <dfn>disconnect from a virtual sensor</dfn> given |window| (a {{Window}}) and |virtualSensorType| (a string), perform the following steps. They return a boolean.
749
+
750
+
1. If |window|'s [=associated Document=]'s {{Document/[[virtualSensorMapping]]}} does not [=map/contain=] |virtualSensorType|, return false.
751
+
1. Let |platformSensorLike| be |window|'s [=associated Document=]'s {{Document/[[virtualSensorMapping]]}}[|virtualSensorType|].
752
+
1. If |platformSensorLike|'s [=orientation event platform sensor-like/device sensor=] is null, return true.
@@ -690,6 +764,25 @@ Orientation data retrieved from the platform by the user agent comes from accele
690
764
691
765
Therefore, instead of requiring implementations (and automation users) to provide orientation readings via lower-level virtual sensors which use different units of measurement, this specification defines extra <a>virtual sensor types</a> for relative and orientation data in the format used by this specification.
When an [=event listener=] whose <a for="event listener" spec=dom>type</a> is {{Window/deviceorientation}} or {{Window/deviceorientationabsolute}} is added to a {{Window}} |window|, the process for attempting to connect to the underlying hardware must be as follows:
769
+
770
+
1. Let |virtualSensorType| be "[=relative-orientation virtual sensor type|relative-orientation=]" if the user agent is attempting to connect to hardware that provides [=relative orientation=] data, and "[=absolute-orientation virtual sensor type|absolute-orientation=]" otherwise.
771
+
1. Let |interval| be [=implementation-defined=] interval in seconds at which implementations either poll for new readings or request new readings to be delivered.
772
+
1. If [=connect to a virtual sensor=] with |window|, |virtualSensorType|, and (1 / |interval|) returns false, abort these steps and continue with the regular [=implementation-defined=] steps to connect to real hardware.
773
+
1. [=In parallel=]:
774
+
1. In an [=implementation-defined=] way, start the process that the user agent uses to determine whether a [=significant change in orientation=] has occurred.
When an [=event listener=] whose <a for="event listener" spec=dom>type</a> is {{Window/deviceorientation}} or {{Window/deviceorientationabsolute}} is removed from a {{Window}} |window| and the user agent determines it should stop retrieving readings from the underlying hardware:
780
+
781
+
1. Let |virtualSensorType| be "[=relative-orientation virtual sensor type|relative-orientation=]" if the user agent is attempting to disconnect from hardware that provides [=relative orientation=] data, and "[=absolute-orientation virtual sensor type|absolute-orientation=]" otherwise.
782
+
1. If [=disconnect from a virtual sensor=] with |window| and |virtualSensorType| returns false, abort these steps and continue with the regular [=implementation-defined=] steps to disconnect to real hardware.
783
+
784
+
</div>
785
+
693
786
### Parse orientation reading data algorithm ### {#parse-orientation-data-reading-algorithm}
694
787
695
788
<div algorithm>
@@ -739,6 +832,29 @@ The motion data retrieved from the platform by the user agent comes from acceler
739
832
740
833
Accelerometer virtual sensors are used to provide <a>acceleration with gravity</a> data to the platform. Linear Acceleration virtual sensors are used to provide <a>linear acceleration</a> data to the platform. Gyroscope virtual sensors are used to provide <a>rotation rate</a> data to the platform.
When an [=event listener=] whose <a for="event listener" spec=dom>type</a> is {{Window/devicemotion}} is added to a {{Window}} |window|, the process for attempting to connect to the underlying hardware must be as follows:
837
+
838
+
1. Let |virtualSensorType| be null.
839
+
1. If the user agent needs to connect to hardware that provides [=acceleration with gravity=] data, set |virtualSensorType| to "[=accelerometer virtual sensor type|accelerometer=]".
840
+
1. Otherwise, if the user agent needs to connect to hardware that provides [=linear acceleration=] data, set |virtualSensorType| to "[=linear-acceleration virtual sensor type|linear-acceleration=]".
841
+
1. Otherwise, if the user agent needs to connect to hardware that provides [=rotation rate=] data, set |virtualSensorType| to "[=gyroscope virtual sensor type|gyroscope=]".
842
+
1. Let |interval| be [=implementation-defined=] interval in seconds at which implementations either poll for new readings or request new readings to be delivered.
843
+
1. If [=connect to a virtual sensor=] with |window|, |virtualSensorType|, and (1 / |interval|) returns false, abort these steps and continue with the regular [=implementation-defined=] steps to connect to real hardware.
When an [=event listener=] whose <a for="event listener" spec=dom>type</a> is {{Window/devicemotion}} is removed from a {{Window}} |window| and the user agent determines it should stop retrieving readings from the underlying hardware:
849
+
850
+
1. Let |virtualSensorType| be null.
851
+
1. If the user agent needs to disconnect from hardware that provides [=acceleration with gravity=] data, set |virtualSensorType| to "[=accelerometer virtual sensor type|accelerometer=]".
852
+
1. Otherwise, if the user agent needs to disconnect from hardware that provides [=linear acceleration=] data, set |virtualSensorType| to "[=linear-acceleration virtual sensor type|linear-acceleration=]".
853
+
1. Otherwise, if the user agent needs to disconnect from hardware that provides [=rotation rate=] data, set |virtualSensorType| to "[=gyroscope virtual sensor type|gyroscope=]".
854
+
1. If [=disconnect from a virtual sensor=] with |window| and |virtualSensorType| returns false, abort these steps and continue with the regular [=implementation-defined=] steps to disconnect to real hardware.
855
+
856
+
</div>
857
+
742
858
### The "accelerometer" virtual sensor type ### {#accelerometer-virtual-sensors}
743
859
744
860
The <a>per-type virtual sensor metadata</a><a>map</a> must have the following <a for=map>entry</a>:
0 commit comments