Skip to content

Commit

Permalink
Merge branch 'main' into remove_conformance
Browse files Browse the repository at this point in the history
  • Loading branch information
@marcoscaceres
marcoscaceres authored May 3, 2024
2 parents c480969 + 876932f commit 36ee177
Showing 1 changed file with 35 additions and 23 deletions.
58 changes: 35 additions & 23 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ Implementation Report: https://wpt.fyi/results/orientation-event
Issue Tracking: DeviceOrientation Event Specification Issues Repository https://github.com/w3c/deviceorientation/issues
Status Text: <p>This specification was initially published as a <a href="https://www.w3.org/TR/2016/CR-orientation-event-20160818/">Candidate Recommendation</a> in August 2016 and was <a href="https://www.w3.org/TR/2017/NOTE-orientation-event-20170530/">retired</a> in 2017 due to the Geolocation Working Group closure. In 2019 Devices and Sensors Working Group adopted this specification and during 2019-2024 made substantial interoperability, test automation, privacy and editorial improvements as outlined in the <a href="#changes">Changes</a> section. These changes aligned the specification with widely available implementations. In 2024 this specification became a joint deliverable between the Devices and Sensors Working Group and WebApps Working Group.</p>
Markup Shorthands: css no
Markup Shorthands: markdown yes
text macro: JOINT yes
text macro: JOINTWEBAPPS yes
</pre>
Expand All @@ -41,24 +42,29 @@ Introduction {#introduction}

This specification provides two new DOM events for obtaining information about the physical orientation and movement of the hosting device. The information provided by the events is not raw sensor data, but rather high-level data which is agnostic to the underlying source of information. Common sources of information include gyroscopes, compasses and accelerometers.

The first DOM event provided by the specification, {{deviceorientation}}, supplies the physical orientation of the device, expressed as a series of rotations from a local coordinate frame.
The {{deviceorientation}} event represents the physical orientation of the device, expressed as a series of rotations from a local coordinate frame.

The second DOM event provided by this specification, {{devicemotion}}, supplies the acceleration of the device, expressed in Cartesian coordinates in a coordinate frame defined in the device. It also supplies the rotation rate of the device about a local coordinate frame. Where practically possible, the event should provide the acceleration of the device's center of mass.
The {{devicemotion}} event represents the acceleration of the device, expressed in Cartesian coordinates in a coordinate frame defined in the device. It also supplies the rotation rate of the device about a local coordinate frame. Where practically possible, the event should provide the acceleration of the device's center of mass.

The following code extracts illustrate basic use of the events.

<div class="example">
Registering to receive {{deviceorientation}} events:
<pre class="lang-js">
window.addEventListener("deviceorientation", function(event) {
// process event.alpha, event.beta and event.gamma
}, true);
<pre class="highlight lang-javascript">
window.addEventListener("deviceorientation", event => {
// process event.alpha, event.beta and event.gamma
});

// Alternatively...
window.ondeviceorientation = event => {
// process event.alpha, event.beta and event.gamma
};
</pre>
</div>

<div class="example">
A device lying flat on a horizontal surface with the top of the screen pointing West has the following orientation:
<pre class="lang-js">
<pre class="highlight lang-javascript">
{
alpha: 90,
beta: 0,
Expand All @@ -74,7 +80,7 @@ A user is holding the device in their hand, with the screen in a vertical plane

<div class="example">
A user facing a compass heading of alpha degrees is holding the device in their hand, with the screen in a vertical plane and the top of the screen pointing to their right. The orientation of the device is:
<pre class="lang-js">
<pre class="highlight lang-javascript">
{
alpha: 270 - alpha,
beta: 0,
Expand All @@ -85,17 +91,23 @@ A user facing a compass heading of alpha degrees is holding the device in their

<div class="example">
Registering to receive {{devicemotion}} events:
<pre class="lang-js">
window.addEventListener("devicemotion", function(event) {
// Process event.acceleration, event.accelerationIncludingGravity,
// event.rotationRate and event.interval
}, true);
<pre class="highlight lang-javascript">
window.addEventListener("devicemotion", (event) => {
// Process event.acceleration, event.accelerationIncludingGravity,
// event.rotationRate and event.interval
});

// Alternatively...
window.ondevicemotion = (event) => {
// Process event.acceleration, event.accelerationIncludingGravity,
// event.rotationRate and event.interval
};
</pre>
</div>

<div class="example">
A device lying flat on a horizontal surface with the screen upmost has an {{DeviceMotionEvent/acceleration}} of zero and the following value for {{DeviceMotionEvent/accelerationIncludingGravity}}:
<pre class="lang-js">
<pre class="highlight lang-javascript">
{
x: 0,
y: 0,
Expand All @@ -106,7 +118,7 @@ A device lying flat on a horizontal surface with the screen upmost has an {{Devi

<div class="example">
A device in free-fall, with the screen horizontal and upmost, has an {{DeviceMotionEvent/accelerationIncludingGravity}} of zero and the following value for acceleration:
<pre class="lang-js">
<pre class="highlight lang-javascript">
{
x: 0,
y: 0,
Expand All @@ -117,7 +129,7 @@ A device in free-fall, with the screen horizontal and upmost, has an {{DeviceMot

<div class="example">
A device is mounted in a vehicle, with the screen in a vertical plane, the top uppermost and facing the rear of the vehicle. The vehicle is travelling at speed v around a right-hand bend of radius r. The device records a positive x component for both {{DeviceMotionEvent/acceleration}} and {{DeviceMotionEvent/accelerationIncludingGravity}}. The device also records a negative value for {{DeviceMotionEvent/rotationRate!!attribute}}.{{DeviceMotionEventRotationRate/gamma}}:
<pre class="lang-js">
<pre class="highlight lang-javascript">
{
acceleration: {x: v^2/r, y: 0, z: 0},
accelerationIncludingGravity: {x: v^2/r, y: 9.8, z: 0},
Expand Down Expand Up @@ -217,9 +229,9 @@ This integration is [=at risk=] due to a lack of test coverage in Web Platform T

This specification defines the following <a>policy-controlled features</a>:

- "<code><dfn export data-lt="accelerometer-feature">accelerometer</dfn></code>", whose <a>default allowlist</a> is "<code>self</code>".
- "<code><dfn export data-lt="gyroscope-feature">gyroscope</dfn></code>", whose <a>default allowlist</a> is "<code>self</code>".
- "<code><dfn export data-lt="magnetometer-feature">magnetometer</dfn></code>", whose <a>default allowlist</a> is "<code>self</code>".
- "<code><dfn export data-lt="accelerometer-feature">accelerometer</dfn></code>", whose <a>default allowlist</a> is [=default allowlist/'self'=].
- "<code><dfn export data-lt="gyroscope-feature">gyroscope</dfn></code>", whose <a>default allowlist</a> is [=default allowlist/'self'=].
- "<code><dfn export data-lt="magnetometer-feature">magnetometer</dfn></code>", whose <a>default allowlist</a> is [=default allowlist/'self'=].

<div class="note">
<span class="marker">Note:</span> Usage of the <a>policy-controlled features</a> above by this specification is as follows:
Expand Down Expand Up @@ -255,7 +267,7 @@ This specification defines the following <a>default powerful features</a>:
Task Source {#taks-source}
===========

The <a>task source</a> for the <a>tasks</a> mentioned in this specification is the <dfn>device motion and orientation task source</dfn>.
The [=task source=] for the [=tasks=] mentioned in this specification is the <dfn>device motion and orientation task source</dfn>.

API {#api}
==========================
Expand Down Expand Up @@ -848,7 +860,7 @@ provided that &beta; and &gamma; are not both zero.

The compass heading calculation above can be represented in JavaScript as follows to return the correct compass heading when the provided parameters are defined, not null and represent {{DeviceOrientationEvent/absolute}} values.

<pre class="lang-js">
<pre class="highlight lang-javascript">
var degtorad = Math.PI / 180; // Degree-to-Radian conversion

function compassHeading( alpha, beta, gamma ) {
Expand Down Expand Up @@ -919,7 +931,7 @@ If R represents the rotation matrix of the device in the earth frame XYZ, then s

<div class="example">
The above combined rotation matrix can be represented in JavaScript as follows provided passed parameters are defined, not null and represent {{DeviceOrientationEvent/absolute}} values.
<pre class="lang-js">
<pre class="highlight lang-javascript">
var degtorad = Math.PI / 180; // Degree-to-Radian conversion

function getRotationMatrix( alpha, beta, gamma ) {
Expand Down Expand Up @@ -971,7 +983,7 @@ If q represents the unit quaternion of the device in the earth frame XYZ, then s

<div class="example">
The above quaternion can be represented in JavaScript as follows provided the passed parameters are defined, are {{DeviceOrientationEvent/absolute}} values and those parameters are not null.
<pre class="lang-js">
<pre class="highlight lang-javascript">
var degtorad = Math.PI / 180; // Degree-to-Radian conversion

function getQuaternion( alpha, beta, gamma ) {
Expand Down

0 comments on commit 36ee177

Please sign in to comment.