index.html 34.1 KB

Raw Blame History Permalink

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">

<html lang=en>
 <head>
  <title>DeviceOrientation Event Specification</title>
  <meta content="text/html;charset=utf-8" http-equiv=Content-Type>

  <style type="text/css">
   dt, dfn { font-weight: bold; font-style: normal; }
   img.extra { float: right; }
   body ins, body del { display: block; }
   body * ins, body * del { display: inline; }
   pre, code { color: black; background: transparent; font-size: inherit; font-family: monospace; }
   pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
   pre em { font-weight: bolder; font-style: normal; }
   pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
   pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em; }
   table { border-collapse: collapse; border-style: hidden hidden none hidden; }
   table thead { border-bottom: solid; }
   table tbody th:first-child { border-left: solid; }
   table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
   ul.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
   ul.toc li ul { margin-bottom: 0.75em; }
   ul.toc li ul li ul { margin-bottom: 0.25em; }
   var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
   @media screen { code { color: rgb(255, 69, 0); background: transparent; } }
   code :link, code :visited { color: inherit; background: transparent; }
   .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 1em; padding-left: 1em; }
   .issue, .big-issue { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
   .issue > :first-child, .big-issue > :first-child { margin-top: 0; }
   p .big-issue { line-height: 3em; }
   .note { color: green; background: transparent; }
   .note { font-family: sans-serif; }
   p.note:before { content: 'Note: '; }
   .warning { color: red; background: transparent; }
   .warning:before { font-style: normal; }
   p.warning:before { content: '\26A0 Warning! '; }
   .note, .warning { font-weight: bolder; font-style: italic; padding: 0.5em 2em; }
   .copyright { margin: 0.25em 0; }
   img { max-width: 100%; }
   h4 + .element { margin-top: -2.5em; padding-top: 2em; }
   h4 + p + .element { margin-top: -5em; padding-top: 4em; }
   .element { background: #EEEEFF; color: black; margin: 0 0 1em -1em; padding: 0 1em 0.25em 0.75em; border-left: solid #9999FF 0.25em; }
   table.matrix, table.matrix td { border: none; text-align: right; }
   table.matrix { margin-left: 2em; }
   ol#rotations li div { display: inline-block; width: 350px; margin-right: 20px; font-size: small; }
   ol#rotations li div img { width: 350px; }
   object.equation {display: block; height: 140px; width: 100%; margin: 20px 20px -60px; }
  </style>
  <link href="http://www.w3.org/StyleSheets/TR/W3C-WD.css" rel=stylesheet type="text/css">
 </head>

 <body>
  <div class=head> <!--begin-logo-->
   <p><a href="http://www.w3.org/"><img alt="W3C" height="48"
    src="http://www.w3.org/Icons/w3c_home" width=72></a> <!--end-logo-->

   <h1 id="title_heading">DeviceOrientation Event Specification</h1>

   <h2 class="no-num no-toc" id="draft_date">W3C Working Draft 1 December 2011</h2>

   <dl>
	<dt>This Version:</dt>
      <dd><a href="http://www.w3.org/TR/2011/WD-orientation-event-20111201/">http://www.w3.org/TR/2011/WD-orientation-event-20111201/</a></dd>

    <dt>Latest Published Version:</dt>

    <dd><a
     href="http://www.w3.org/TR/orientation-event/">http://www.w3.org/TR/orientation-event/</a></dd>

    <dt>Previous version:</dt>
    <dd><a
     href="http://www.w3.org/TR/2011/WD-orientation-event-20110628/">http://www.w3.org/TR/2011/WD-orientation-event-20110628/</a></dd>
    <dt>Latest Editor's Draft:

    <dd><a
     href="http://dev.w3.org/geo/api/spec-source-orientation.html">http://dev.w3.org/geo/api/spec-source-orientation.html</a></dd>


    <dt>Editors:</dt>

    <dd>Steve Block, Google, Inc</dd>
    <dd>Andrei Popescu, Google, Inc</dd>
   </dl>

   <p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> &copy; 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>&reg;</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p>

   <hr>
  </div>

  <h2 class="no-num no-toc" id="abstract">Abstract</h2>

  <p>This specification defines several new DOM events that provide
  information about the physical orientation and motion of a hosting device.</p>

  <h2 class="no-num no-toc" id="status">Status of This Document</h2>
  <!-- intro boilerplate (required) -->
<p><em>This section describes the status of this document at the time
of its publication. Other documents may supersede this document. A
list of current W3C publications and the latest revision of this
technical report can be found in
the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
http://www.w3.org/TR/.</em></p>

  <!-- where to send feedback (required) -->

  <p>This document was published by the <a
  href="http://www.w3.org/2008/geolocation/">Geolocation Working Group</a> as a Last Call Working Draft.
When providing feedback, please first refer to the <a href="http://dev.w3.org/geo/api/spec-source-orientation.html">Editor's Draft</a> and confirm that the issue has not been addressed already. If the issue has not been addressed, please send it to the <a
  href="mailto:public-geolocation@w3.org">public-geolocation@w3.org</a> (<a
  href="mailto:public-geolocation-request@w3.org?subject=subscribe">subscribe</a>,
  <a
  href="http://lists.w3.org/Archives/Public/public-geolocation/">archives</a>) mailing list.  The Last Call period ends 15 January 2012.  For a list of changes, please see the <a href="orientation-fpwd-lc-diff.html">changes since the First Public Working Draft</a> diff document.</p>
  <p>All feedback is welcome.</p>
  <!-- stability (required) -->

<p>Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced
or obsoleted by other documents at any time. It is inappropriate to
cite this document as other than work in progress.</p>

  <!-- required patent boilerplate -->

  <p> This document was produced by a group operating under the <a
   href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
   2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42891/status" rel="disclosure">public list of any patent disclosures</a>
   made in connection with the deliverables of the group; that page also
   includes instructions for disclosing a patent. An individual who has
   actual knowledge of a patent which the individual believes contains <a
   href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
   Claim(s)</a> must disclose the information in accordance with <a
   href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
   6 of the W3C Patent Policy</a>.

  <h2 class="no-num no-toc" id="contents">Table of Contents</h2>
  <!--begin-toc-->
  <ul class=toc>
    <li><a href="#conformance-requirements"><span class=secno>1 </span>Conformance requirements</a>
    <li><a href="#introduction"><span class=secno>2 </span>Introduction</a>
    <li><a href="#scope"><span class=secno>3 </span>Scope</a>
    <li><a href="#description"><span class=secno>4 </span>Description</a>
    <ul class=toc>
      <li><a href="#deviceorientation"><span class=secno>4.1 </span>deviceorientation Event</a>
      <li><a href="#compassneedscalibration"><span class=secno>4.2 </span>compassneedscalibration Event</a>
      <li><a href="#devicemotion"><span class=secno>4.3 </span>devicemotion Event</a>
    </ul>
    <li><a href="#use-cases-and-requirements"><span class=secno>5 </span>Use-Cases and Requirements</a>
    <ul class=toc>
      <li><a href="#use-cases"><span class=secno>5.1 </span>Use-Cases</a>
      <li><a href="#requirements"><span class=secno>5.2 </span>Requirements</a>
    </ul>
    <li><a href="#worked-example"><span class=secno>6 </span>Worked Example</a>
    <li><a href="#acknowledgments">Acknowledgments</a>
    <li><a href="#references">References</a>
  </ul>
  <!--end-toc-->

  <h2 id="conformance-requirements"><span class=secno>1 </span>Conformance requirements</h2>

  <p>All diagrams, examples, and notes in this specification are
   non-normative, as are all sections explicitly marked non-normative.
   Everything else in this specification is normative.

  <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
  NOT",-->
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the
   normative parts of this document are to be interpreted as described in
   RFC2119. For readability, these words do not appear in all uppercase
   letters in this specification. <a href="#ref-rfc2119">[RFC2119]</a></p>
  <!-- XXX but they should be
  marked up -->

  <p>Requirements phrased in the imperative as part of algorithms (such as
   "strip any leading space characters" or "return false and abort these
   steps") are to be interpreted with the meaning of the key word ("must",
   "should", "may", etc) used in introducing the algorithm.

  <p>Conformance requirements phrased as algorithms or specific steps may be
   implemented in any manner, so long as the end result is equivalent. (In
   particular, the algorithms defined in this specification are intended to
   be easy to follow, and not intended to be performant.)

  <p id="hardwareLimitations">User agents may impose implementation-specific
   limits on otherwise unconstrained inputs, e.g. to prevent denial of
   service attacks, to guard against running out of memory, or to work around
   platform-specific limitations.

  <p>Implementations that use ECMAScript to implement the APIs defined in
   this specification must implement them in a manner consistent with the
   ECMAScript Bindings defined in the Web IDL specification, as this
   specification uses that specification's terminology. <a
   href="#ref-webidl">[WEBIDL]</a>

  <p>The events introduced by this specification implement the Event interface
  defined in the DOM Level 2 Events Specification,
  <a href="#ref-domevents">[DOMEVENTS]</a>.
  Implementations must therefore support this specification.

  <h2 id="introduction"><span class=secno>2 </span>Introduction</h2>

  <p><em>This section is non-normative.</em>

  <p>This specification provides several 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.

  <p>The first DOM event provided by the specification,
  <code>deviceorientation</code>, supplies the physical orientation of the
  device, expressed as a series of rotations from a local coordinate frame.

  <p>The second DOM event provided by this specification,
  <code>devicemotion</code>, 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.

  <p>Finally, the specification provides a <code>compassneedscalibration</code>
  DOM event, which is used to inform Web sites that a compass being used to
  provide data for one of the above events is in need of calibration.

  <p>The following code extracts illustrate basic use of the events.

  <div class=example>
    <p>Registering to receive
    <a href="#deviceorientation"><code>deviceorientation</code></a>
    events:</p>
    <pre>
      window.addEventListener("deviceorientation", function(event) {
          // process event.alpha, event.beta and event.gamma
      }, true);
    </pre>
  </div>

  <div class=example>
    <p>A device lying flat on a horizontal surface with the top of the
    screen pointing West has the following orientation:</p>
    <pre>
      {alpha: 90,
       beta: 0,
       gamma: 0};
    </pre>
    <p> To get the compass heading, one would simply
    subtract <code>alpha</code> from 360 degrees. As the device is
    turned on the horizontal surface, the compass heading is (360
    - <code>alpha</code>).</p>
  </div>

  <div class=example>
    <p>A user is holding the device in their hand, with the screen in
    a vertical plane and the top of the screen pointing upwards. The
    value of <code>beta</code> is 90, irrespective of
    what <code>alpha</code> and <code>gamma</code> are.</p>
  </div>

  <div class=example>
    <p>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:</p>
    <pre>
      {alpha: 270 - alpha,
       beta: 0,
       gamma: 90};
    </pre>
  </div>

  <div class=example>
    <p>Showing custom UI to instruct the user to calibrate the compass:</p>
    <pre>
      window.addEventListener("compassneedscalibration", function(event) {
          alert('Your compass needs calibrating! Wave your device in a figure-eight motion');
          event.preventDefault();
      }, true);
    </pre>
  </div>

  <div class=example>
    <p>Registering to receive
    <a href="#devicemotion"><code>devicemotion</code></a> events:</p>
    <pre>
      window.addEventListener("devicemotion", function(event) {
          // Process event.acceleration, event.accelerationIncludingGravity,
          // event.rotationRate and event.interval
      }, true);
    </pre>
  </div>

  <div class=example>
    <p>A device lying flat on a horizontal surface with the screen upmost has
    an <code>acceleration</code> of zero and the following value for
    <code>accelerationIncludingGravity</code>:</p>
    <pre>
      {x: 0,
       y: 0,
       z: 9.81};
    </pre>
  </div>

  <div class=example>
    <p>A device in free-fall, with the screen horizontal and upmost, has an
    <code>accelerationIncludingGravity</code> of zero and the following value
    for <code>acceleration</code>:</p>
    <pre>
      {x: 0,
       y: 0,
       z: -9.81};
    </pre>
  </div>

  <div class=example>
    <p>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 <code>acceleration</code>
    and <code>accelerationIncludingGravity</code>. The device also records a
    negative value for <code>rotationRate.gamma</code>:</p>
    <pre>
      {acceleration: {x: v^2/r, y: 0, z: 0},
       accelerationIncludingGravity: {x: v^2/r, y: 0, z: 9.81},
       rotationRate: {alpha: 0, beta: 0, gamma: -v/r*180/pi} };
    </pre>
  </div>

  <h2 id="scope"><span class=secno>3 </span>Scope</h2>

  <p><em>This section is non-normative.</em>

  <p>This specification is limited to providing DOM events for retrieving
  information describing the physical orientation and motion of the hosting
  device. The intended purpose of this API is to enable simple use cases such
  as those in <a href="#use-cases">Section 5.1</a>.

  The scope of this specification does not include providing utilities to
  manipulate this data, such as transformation libraries. Nor does it include
  providing access to low sensor data, or direct control of these sensors.

  <h2 id="description"><span class=secno>4 </span>Description</h2>

  <h3 id="deviceorientation"><span class=secno>4.1 </span>deviceorientation Event</h3>

  <p>User agents implementing this specification must provide a new DOM event,
  named <code>deviceorientation</code>. The corresponding event must be of
  type <code>DeviceOrientationEvent</code> and must fire on the
  <code>window</code> object. Registration for, and firing of the
  <code>deviceorientation</code> event must follow the usual behavior of DOM
  Level 2 Events, <a href="#ref-domevents">[DOMEVENTS]</a>.

  <p>User agents must also provide an event handler IDL attribute
  <a href="#ref-html5">[HTML5]</a> named <code>ondeviceorientation</code> on the
  <code>window</code> object. The type of this event handler must be
  <code>DeviceOrientationEvent</code>.

  <pre class=idl>
    interface <dfn id="deviceorientation_event">DeviceOrientationEvent</dfn> : Event {
    readonly attribute double? alpha;
    readonly attribute double? beta;
    readonly attribute double? gamma;
    readonly attribute boolean absolute;
    void initDeviceOrientationEvent(in DOMString type,
                                    in boolean bubbles,
                                    in boolean cancelable,
                                    in double? alpha,
                                    in double? beta,
                                    in double? gamma,
                                    in boolean absolute);
    }
  </pre>

  <p>The event should fire whenever a significant change in orientation occurs.
  The definition of a significant change in this context is left to the
  implementation. In addition, when a new listener registers for the event,
  implementations should fire the event as soon as sufficiently fresh data is
  available.</p>

  <p>The <code>alpha</code>, <code>beta</code> and <code>gamma</code> properties
  of the event must specify the orientation of the device in terms of the
  transformation from a coordinate frame fixed on the Earth to a
  coordinate frame fixed in the device. The coordinate frames must be oriented
  as described below.</p>

  <p>The Earth coordinate frame is a 'East, North, Up' frame at the user's
  location. It has the following 3 axes, where the ground plane is tangent to
  the spheriod of the World Geodetic System 1984
  <a href="#ref-wgs84">[WGS84]</a>, at the user's location.

  <ul>
    <li>East (X) is in the ground plane, perpendicular to the North axis and positive towards the East.</li>
    <li>North (Y) is in the ground plane and positive towards True North (towards the North Pole).</li>
    <li>Up (Z) is perpendicular to the ground plane and positive upwards.</li>
  </ul>

  <p>For a mobile device such as a phone or tablet, the device coordinate frame
  is defined relative to the screen in its standard orientation, typically
  portrait. This means that slide-out elements such as keyboards are not
  deployed, and swiveling elements such as displays are folded to their default
  position. If the
  orientation of the screen changes when the device is rotated or a slide-out
  keyboard is deployed, this does not affect the orientation of the coordinate
  frame relative to the device. Users wishing to detect these changes in screen
  orientation may be able to do so with the existing
  <code>orientationchange</code> event.
  For a laptop computer, the device coordinate frame is defined relative to the
  integrated keyboard.

  <ul>
    <li>x is in the plane of the screen or keyboard and is positive towards the right hand side of the screen or keyboard.</li>
    <li>y is in the plane of the screen or keyboard and is positive towards the top of the screen or keyboard.</li>
    <li>z is perpendicular to the screen or keyboard, positive out of the screen or keyboard.</li>
  </ul>

  <p>The transformation from the Earth coordinate frame to the device coordinate
  frame must use the following system of rotations.

  <p>Rotations must use the right-hand convention, such that positive rotation
  around an axis is clockwise when viewed along the positive direction of the
  axis. Starting with the two frames aligned, the rotations are applied in the
  following order:</p>

  <ol id="rotations">
    <li>
      <p>Rotate the device frame around its z axis by <code>alpha</code> degrees, with <code>alpha</code> in [0, 360).</p>
      <div>
        <img src="start.png" alt="start orientation">
        <div>Device in the initial position, with Earth (XYZ) and body (xyz) frames aligned.</div>
      </div>
      <div>
        <img src="c-rotation.png" alt="rotation about z axis">
        <div>Device rotated through angle alpha about z axis, with previous locations of x and y axes shown as x<sub>0</sub> and y<sub>0</sub>.</div>
      </div>
    </li>
    <li>
      <p>Rotate the device frame around its x axis by <code>beta</code> degrees, with <code>beta</code> in [-180, 180).</p>
      <div>
        <img src="a-rotation.png" alt="rotation about x axis">
        <div>Device rotated through angle beta about new x axis, with previous locations of y and z axes shown as y<sub>0</sub> and z<sub>0</sub>.</div>
      </div>
    </li>
    <li>
      <p>Rotate the device frame around its y axis by <code>gamma</code> degrees, with <code>gamma</code> in [-90, 90).</p>
      <div>
        <img src="b-rotation.png" alt="rotation about y axis">
        <div>Device rotated through angle gamma about new y axis, with previous locations of x and z axes shown as x<sub>0</sub> and z<sub>0</sub>.</div>
      </div>
    </li>
  </ol>

  <p>Thus the angles <code>alpha</code>, <code>beta</code> and
  <code>gamma</code> form a set of intrinsic Tait-Bryan angles of type Z-X'-Y''.
  <a href="#ref-eulerangles">[EULERANGLES]</a>
  Note that this choice of angles follows mathematical convention, but means
  that <code>alpha</code> is in the opposite sense to a compass heading. It also
  means that the angles do not match the roll-pitch-yaw convention used in
  vehicle dynamics.</p>

  <p> Implementations that are unable to provide absolute values for the three
  angles may instead provide values relative to some arbitrary orientation, as
  this may still be of utility. In this case, the <code>absolute</code> property
  must be set to <code>false</code>. Otherwise, the <code>absolute</code>
  property must be set to <code>true</code>.</p>

  <p> Implementations that are unable to provide all three angles must
  set the values of the unknown angles to null. If any angles are provided, the
  <code>absolute</code> property must be set appropriately. If an implementation
  can never provide orientation information, the event should be fired
  with all properties set to null.</p>

  <h3 id="compassneedscalibration"><span class=secno>4.2 </span>compassneedscalibration Event</h3>

  <p>User agents implementing this specification must provide a new DOM event,
  named <code>compassneedscalibration</code> that uses the <code>Event</code>
  interface defined in the DOM Level 2 Events specification
  <a href="#ref-domevents">[DOMEVENTS]</a>. This event must fire on the
  <code>window</code> object. Registration for, and firing of the
  <code>compassneedscalibration</code> event must follow the usual behavior of
  DOM Level 2 Events <a href="#ref-domevents">[DOMEVENTS]</a>.

  <p>User agents must also provide an event handler IDL attribute
  <a href="#ref-html5">[HTML5]</a> named <code>oncompassneedscalibration</code>
  on the <code>window</code> object. The type of this event handler must be
  <code>Event</code>.

  <p>This event must be fired when the user agent determines that a compass used
  to obtain orientation data is in need of calibration. Furthermore, user agents
  should only fire the event if calibrating the compass will increase the
  accuracy of the data provided by the
  <code><a href="#deviceorientation">deviceorientation</a></code> event.

  <p>The default action of this event should be for the user agent to present the
  user with details of how to calibrate the compass. The event must be
  cancelable, so that web sites can provide their own alternative calibration
  UI.

  <h3 id="devicemotion"><span class=secno>4.3 </span>devicemotion Event</h3>

  <p>User agents implementing this specification must provide a new DOM event,
  named <code>devicemotion</code>. The corresponding event must be of type
  <code>DeviceMotionEvent</code> and must fire on the <code>window</code>
  object.
  Registration for, and firing of the <code>devicemotion</code>
  event must follow the usual behavior of DOM Level 2 Events,
  <a href="#ref-domevents">[DOMEVENTS]</a>.

  <p>User agents must also provide an event handler IDL attribute
  <a href="#ref-html5">[HTML5]</a> named <code>ondevicemotion</code>
  on the <code>window</code> object. The type of this event handler must be
  <code>DeviceMotionEvent</code>.

  <pre class=idl>
    [Callback, NoInterfaceObject]
    interface <dfn id="device_acceleration">DeviceAcceleration</dfn> {
    readonly attribute double? x;
    readonly attribute double? y;
    readonly attribute double? z;
    }

    [Callback, NoInterfaceObject]
    interface <dfn id="device_rotation_rate">DeviceRotationRate</dfn> {
    readonly attribute double? alpha;
    readonly attribute double? beta;
    readonly attribute double? gamma;
    }

    interface <dfn id="devicemotion_event">DeviceMotionEvent</dfn> : Event {
    readonly attribute DeviceAcceleration? acceleration;
    readonly attribute DeviceAcceleration? accelerationIncludingGravity;
    readonly attribute DeviceRotationRate? rotationRate;
    readonly attribute double? interval;
    void initAccelerometerEvent(in DOMString type,
                                in boolean bubbles,
                                in boolean cancelable,
                                in DeviceAcceleration? acceleration,
                                in DeviceAcceleration? accelerationIncludingGravity,
                                in DeviceRotationRate? rotationRate,
                                in double? interval);
    }
  </pre>

  <p>The <code>acceleration</code> property must provide the acceleration of the
  hosting device relative to the Earth frame, expressed in the body frame, as
  defined in <a href="#deviceorientation">section 4.1</a>. The acceleration must
  be expressed in m/s^2.

  <p>Implementations that are unable to provide acceleration data without the
  effect of gravity (due, for example, to the lack of a gyroscope) may instead
  supply the acceleration including the effect of gravity. This is less useful
  in many applications but is provided as a means of providing best-effort
  support. In this case, the <code>accelerationIncludingGravity</code> property
  must provide the acceleration of the hosting device, plus an acceleration
  equal and opposite to the acceleration due to gravity. Again, the acceleration
  must be given in the body frame defined in
  <a href="#deviceorientation">section 4.1</a> and must be expressed in m/s^2.

  <p>The <code>rotationRate</code> property must provide the rate of rotation of
  the hosting device in space. It must be expressed as the rate of change of
  the angles of the defined in <a href="#deviceorientation">section 4.1</a> and
  must be expressed in deg/s.

  <p>The <code>interval</code> property must provide the interval at which
  data is obtained from the underlying hardware and must be expressed in
  milliseconds. It must be a constant, to simplify filtering of the data by the
  Web application.

  <p>Implementations that are unable to provide all properties must
  set the values of the unknown properties to null. If an implementation
  can never provide motion information, the event should be fired
  with all properties set to null.

  <h2 id="use-cases-and-requirements"><span class=secno>5 </span>Use-Cases and Requirements</h2>

  <h3 id="use-cases"><span class=secno>5.1 </span>Use-Cases</h3>

  <h4 id="controlling-a-game"><span class=secno>5.1.1 </span>Controlling a game</h4>
  <p>A gaming Web application monitors the device's orientation and interprets
  tilting in a certain direction as a means to control an on-screen sprite.

  <h4 id="gesture-recognition"><span class=secno>5.1.2 </span>Gesture recognition</h4>
  <p>A Web application monitors the device's acceleration and applies signal
  processing in order to recognize certain specific gestures. For example, using
  a shaking gesture to clear a web form.

  <h4 id="mapping"><span class=secno>5.1.3 </span>Mapping</h4>
  <p>A mapping Web application uses the device's orientation to correctly align
  the map with reality.

  <h3 id="requirements"><span class=secno>5.2 </span>Requirements</h3>

  <h4 id="requirement-orientation"><span class=secno>5.2.1 </span>The specification must provide data that describes the physical orientation in space of the device.</h4>
  <h4 id="requirement-motion"><span class=secno>5.2.2 </span>The specification must provide data that describes the motion in space of the device.</h4>
  <h4 id="requirement-changes"><span class=secno>5.2.3 </span>The specification must allow Web applications to register for changes in the device's orientation.</h4>
  <h4 id="requirement-agnostic"><span class=secno>5.2.4 </span>The specification must be agnostic to the underlying sources of orientation and motion data.</h4>
  <h4 id="requirement-use-dom"><span class=secno>5.2.5 </span>The specification must use the existing DOM event framework.</h4>

  <h2 id="worked-example">Worked Example</h2>

  <p><em>This section is non-normative.</em>

  <p>The following worked example is intended as an aid to users of the
  DeviceOrientation event.

  <p><a href="#introduction">Section 2</a> provided an example of using the
  DeviceOrientation event to obtain a compass heading when the device is held
  with the screen horizontal. This example shows how to determine the compass
  heading that the user is 'facing' when holding the device with the screen
  approximately vertical in front of them. An application of this is an
  augmented-reality system.

  <p>More precisely, we wish to determine the compass heading of the horizontal
  component of a vector which is orthogonal to the device's screen and pointing
  out of the back of the screen.

  <p>If r represents this vector in the rotated device body frame xyz, then r
  is as follows.

  <object class="equation" data="equation1.xhtml" type="application/mathml+xml">
    <p><img src="equation1.gif">
  </object>

  <p>The transformation of r due to the rotation about the z axis can be
  represented by the following rotation matrix.

  <object class="equation" data="equation2.xhtml" type="application/mathml+xml">
    <img src="equation2.gif">
  </object>

  <p>The transformation of r due to the rotation about the x axis can be
  represented by the following rotation matrix.

  <object class="equation" data="equation3.xhtml" type="application/mathml+xml">
    <img src="equation3.gif">
  </object>

  <p>The transformation of r due to the rotation about the y axis can be
  represented by the following rotation matrix.

  <object class="equation" data="equation4.xhtml" type="application/mathml+xml">
    <img src="equation4.gif">
  </object>

  <p>If R resresents the vector r in the earth frame XYZ, then since the inital
  body frame is aligned with the earth, R is as follows.

  <object class="equation" data="equation5a.xhtml" type="application/mathml+xml">
    <img src="equation5a.gif">
  </object>
  <object class="equation" data="equation5b.xhtml" type="application/mathml+xml">
    <img src="equation5b.gif">
  </object>
  <object class="equation" data="equation5c.xhtml" type="application/mathml+xml">
    <img src="equation5c.gif">
  </object>
  <object class="equation" data="equation5d.xhtml" type="application/mathml+xml">
    <img src="equation5d.gif">
  </object>
  <object class="equation" data="equation5e.xhtml" type="application/mathml+xml">
    <img src="equation5e.gif">
  </object>

  <p>The compass heading &theta; is given by

  <object class="equation" data="equation6.xhtml" type="application/mathml+xml">
    <img src="equation6.gif">
  </object>

  <p>provided that &beta; and &gamma; are not both zero.

  <p>As a consistency check, if we set &gamma; = 0, then

  <object class="equation" data="equation7.xhtml" type="application/mathml+xml">
    <img src="equation7.gif">
  </object>

  <p>as expected.

  <p>Alternatively, if we set &beta; = 90, then

  <object class="equation" data="equation8a.xhtml" type="application/mathml+xml">
    <img src="equation8a.gif">
  </object>
  <object class="equation" data="equation8b.xhtml" type="application/mathml+xml">
    <img src="equation8b.gif">
  </object>

  <p>as expected.

  <h2 class=no-num id="acknowledgments">Acknowledgments</h2>

  <p>Lars Erik Bolstad, Dean Jackson, Claes Nilsson, George Percivall, Doug Turner, Matt Womer

  <h2 class=no-num id="references">References</h2>

  <dl>
   <dt><a id="ref-domevents">[DOMEVENTS]</a></dt>
   <dd><cite><a href="http://www.w3.org/TR/DOM-Level-2-Events/">DOM Level 2 Events</a></cite>, See http://www.w3.org/TR/DOM-Level-2-Events/</dd>
   <dt><a id="ref-eulerangles">[EULERANGLES]</a></dt>
   <dd><em>(Non-normative)</em> <cite><a href="http://en.wikipedia.org/wiki/Euler_angles">Euler Angles</a></cite>, See http://en.wikipedia.org/wiki/Euler_angles</dd>
   <dt><a id="ref-html5">[HTML5]</a></dt>
   <dd><cite><a href="http://dev.w3.org/html5/spec/Overview.html">HTML5</a></cite>, See http://dev.w3.org/html5/spec/Overview.html</dd>
   <dt><a id=ref-rfc2119>[RFC2119]</a></dt>
   <dd><cite><a href="http://www.ietf.org/rfc/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a></cite>, Scott Bradner.  Internet Engineering Task Force, March 1997. See http://www.ietf.org/rfc/rfc2119.txt</dd>
   <dt><a id=ref-webidl>[WEBIDL]</a></dt>
   <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, Cameron McCormack, Editor. World Wide Web Consortium, 19 December 2008. See http://dev.w3.org/2006/webapi/WebIDL</dd>
   <dt><a id="ref-wgs84">[WGS84]</a></dt>
   <dd><cite><a href="http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf">National Imagery and Mapping Agency Technical Report 8350.2, Third Edition</a></cite>. National Imagery and Mapping Agency, 3 January 2000. See http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf</dd>
  </dl>
 </body>
</html>