extensions.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>
      Gamepad Extensions
    </title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1"><!--
      === NOTA BENE ===
      For the three scripts below, if your spec resides on dev.w3 you can check them
      out in the same tree and use relative links so that they'll work offline,
     -->

    <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class=
    'remove'></script>
    <script class='remove'>
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "ED",

          // the specification's short name, as in http://www.w3.org/TR/short-name/
          shortName:            "gamepad-extensions",

          // if your specification has a subtitle that goes below the main
          // formal title, define it here
          // subtitle   :  "an excellent document",

          // if you wish the publication date to be other than today, set this
          //publishDate:  "2011-01-01",

          // if the specification's copyright date is a range of years, specify
          // the start date here:
          // copyrightStart: "2005"

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status

          processVersion: "2016",

          // if there a publicly available Editor's Draft, this is the link
          edDraftURI:   "https://w3c.github.io/gamepad/extensions.html",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // editors, add as many as you like
          // only "name" is required
          editors:  [
              { name: "Brandon Jones", url: "http://tojicode.com/",
                company: "Google", companyURL: "http://www.google.com/",
                w3cid: 87824 },
          ],

          otherLinks: [{
            key: 'Repository and Participation',
            data: [
                {
                    value: 'We are on GitHub.',
                    href: 'https://github.com/w3c/gamepad/'
                }, {
                    value: 'File a bug/issue.',
                    href: 'https://github.com/w3c/gamepad/issues/new?title=[Extensions]+'
                }, {
                    value: 'Commit history.',
                    href: 'https://github.com/w3c/gamepad/commits'
                }, {
                    value: 'Mailing list search.',
                    href: 'https://www.w3.org/Search/Mail/Public/search?keywords=&hdr-1-name=subject&hdr-1-query=gamepad&index-grp=Public_FULL&index-type=t&type-index=public-webapps'
                }
             ]
          }],

          // authors, add as many as you like.
          // This is optional, uncomment if you have authors as well as editors.
          // only "name" is required. Same format as editors.

          //authors:  [
          //    { name: "Your Name", url: "http://example.org/",
          //      company: "Your Company", companyURL: "http://example.com/" },
          //],

          // name of the WG
          wg:           "Web Platform Working Group",

          // URI of the public WG page
          wgURI:        "https://www.w3.org/WebPlatform/WG/",
          license:      "w3c-software-doc",

          // name (with the @w3c.org) of the public mailing to which comments are due
          wgPublicList: "public-webapps",

          // URI of the patent status for this WG, for Rec-track documents
          // !!!! IMPORTANT !!!!
          // This is important for Rec-track documents, do not copy a patent URI from a random
          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
          // Team Contact.
          wgPatentURI:  "https://www.w3.org/2004/01/pp-impl/83482/status",
          xref: ["HTML", "DOM", "PERMISSIONS-POLICY", "HR-TIME", "INFRA", "gamepad"],
      };
    </script>
    <style>
      .event {
        color: #459900;
        font-family: monospace;
      }

      pre.idl {
        white-space: pre-wrap;
      }
    </style>
  </head>
  <body>
    <section id='abstract'>
      Extensions to the base Gamepad specification to enable access to more
      advanced device capabilities.
    </section>
    <section id='sotd'>
      If you have comments for this spec, please send them to <a href=
      "mailto:public-webapps@w3.org">public-webapps@w3.org</a> with a Subject:
      prefix of <code>[gamepad]</code>. See <a href=
      "https://www.w3.org/Bugs/Public/buglist.cgi?product=WebAppsWG&amp;component=Gamepad&amp;resolution=---">
      Bugzilla</a> for this specification's open bugs.
    </section>
    <section id='introduction' class='informative'>
      <h2>
        Introduction
      </h2>
      <p>
        The Gamepad API provides a tightly scoped interface to gamepad devices
        and is focused on the most common elements of those devices, namely
        axis and button inputs. It specifically excludes support for more
        complex devices (e.g., those that do motion tracking or haptic
        feedback).
      </p>
      <p>
        However, some uses of gamepads (e.g., those paired with Virtual Reality
        headsets) rely heavily on those more advanced features. This
        supplemetary spec describes extensions to the base API to accommodate
        those use cases. If they prove to be broadly useful, the hope is that
        they will be eventually merged into the <a href="./">main spec</a>.
      </p>
    </section>
    <section id='conformance'></section>
    <section>
      <h2>
        <dfn>GamepadHand</dfn> Enum
      </h2>
      <p>
        This enum defines the set of possible hands a gamepad may be held by.
      </p>
      <pre class="idl">
        enum GamepadHand {
          "",  /* unknown, both hands, or not applicable */
          "left",
          "right"
        };
      </pre>
      <dl data-dfn-for="GamepadHand">
        <dt>
          <dfn>""</dfn> (the empty string)
        </dt>
        <dd>
          The empty string indicates the hand that is holding the gamepad is
          unknown or not applicable (e.g., if the gamepad is held with two
          hands).
        </dd>
        <dt>
          <dfn>left</dfn>
        </dt>
        <dd>
          Gamepad is held or is most likely to be held in the left hand.
        </dd>
        <dt>
          <dfn>right</dfn>
        </dt>
        <dd>
          Gamepad is held or is most likely to be held in the right hand.
        </dd>
      </dl>
    </section>
    <section>
      <h2>
        <dfn>GamepadPose</dfn> Interface
      </h2>
      <p>
        This interface defines the gamepad's position, orientation, velocity,
        and acceleration.
      </p>
      <pre class="idl">
        [Exposed=Window]
        interface GamepadPose {
          readonly attribute boolean hasOrientation;
          readonly attribute boolean hasPosition;

          readonly attribute Float32Array? position;
          readonly attribute Float32Array? linearVelocity;
          readonly attribute Float32Array? linearAcceleration;
          readonly attribute Float32Array? orientation;
          readonly attribute Float32Array? angularVelocity;
          readonly attribute Float32Array? angularAcceleration;
        };
      </pre>
      <dl data-dfn-for="GamepadPose">
        <dt>
          <dfn>hasOrientation</dfn>
        </dt>
        <dd>
          The <code>hasOrientation</code> attribute MUST return whether the
          gamepad is capable of tracking its orientation.
        </dd>
        <dt>
          <dfn>hasPosition</dfn>
        </dt>
        <dd>
          The <code>hasPosition</code> attribute MUST return whether the
          gamepad is capable of tracking its position.
        </dd>
        <dt>
          <dfn>position</dfn>
        </dt>
        <dd>
          <p>
            Position of the gamepad as a 3D vector, given in meters from an
            origin point, which is determined by the gamepad hardware and MAY
            be the position of the gamepad when first polled if no other
            reference point is available. The coordinate system uses these axis
            definitions, assuming the user is holding the gamepad in the
            forward orientation:
          </p>
          <ul>
            <li>Positive X is to the user's right.
            </li>
            <li>Positive Y is up.
            </li>
            <li>Positive Z is behind the user.
            </li>
          </ul>
          <p>
            MUST be <code>null</code> if the gamepad is incapable of providing
            positional data. When not <code>null</code>, MUST be a
            three-element array.
          </p>
        </dd>
        <dt>
          <dfn>linearVelocity</dfn>
        </dt>
        <dd>
          Linear velocity of the gamepad in meters per second. MUST be
          <code>null</code> if the sensor is incapable of providing linear
          velocity. When not <code>null</code>, MUST be a three-element array.
        </dd>
        <dt>
          <dfn>linearAcceleration</dfn>
        </dt>
        <dd>
          Linear acceleration of the gamepad in meters per second. MUST be
          <code>null</code> if the sensor is incapable of providing linear
          acceleration. When not <code>null</code>, MUST be a three-element
          array.
        </dd>
        <dt>
          <dfn>orientation</dfn>
        </dt>
        <dd>
          Orientation of the gamepad as a quaternion. An orientation of
          <code>[0, 0, 0, 1]</code> is considered to be <code>forward</code>.
          The forward direction MUST be determined by the gamepad hardware. The
          forward direction MAY be the orientation of the hardware when it was
          first polled if no other reference orientation is available. If the
          sensor is incapable of providing orientation data, the orientation
          MUST be <code>null</code>. When not <code>null</code>, the
          <code>orientation</code> MUST be a four-element array.
        </dd>
        <dt>
          <dfn>angularVelocity</dfn>
        </dt>
        <dd>
          Angular velocity of the gamepad in meters per second. MUST be
          <code>null</code> if the sensor is incapable of providing angular
          velocity. When not <code>null</code>, the
          <code>angularVelocity</code> MUST be a three-element array.
        </dd>
        <dt>
          <dfn>angularAcceleration</dfn>
        </dt>
        <dd>
          Angular acceleration of the gamepad in meters per second. MUST be
          <code>null</code> if the sensor is incapable of providing angular
          acceleration. When not <code>null</code>,
          <code>angularAcceleration</code> MUST be a three-element array.
        </dd>
      </dl>
    </section>
    <section>
      <h2>
        Partial <dfn>Gamepad</dfn> Interface
      </h2>
      <p>
        This partial interface supplements the Gamepad interface described in
        the main <a href="https://w3c.github.io/gamepad/">Gamepad spec</a>.
      </p>
      <pre class="idl">
        partial interface Gamepad {
          readonly attribute GamepadHand hand;
          readonly attribute FrozenArray&lt;GamepadHapticActuator&gt; hapticActuators;
          readonly attribute GamepadPose? pose;
        };
      </pre>
      <p>
        Instances of {{Gamepad}} are created with the internal slots described
        in the following table:
      </p>
      <table class="simple">
        <tr>
          <th>
            Internal slot
          </th>
          <th>
            Initial value
          </th>
          <th>
            Description (non-normative)
          </th>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\hand]]</dfn>
          </td>
          <td>
            `undefined`
          </td>
          <td>
            Indicates the hand the controller is held in.
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\hapticActuators]]</dfn>
          </td>
          <td>
            `undefined`
          </td>
          <td>
            List of all the haptic actuators in the gamepad.
          </td>
        </tr>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\pose]]</dfn>
          </td>
          <td>
            `null`
          </td>
          <td>
            The current pose of the gamepad.
          </td>
        </tr>
      </table>
      <dl data-dfn-for="Gamepad">
        <dt>
          <dfn>hand</dfn>
        </dt>
        <dd>
          An enumeration, {{GamepadHand}}, that indicates which hand the
          controller is being held in or is most likely to be held in.
        </dd>
        <dt>
          <dfn>hapticActuators</dfn>
        </dt>
        <dd>
          A list of all the {{GamepadHapticActuator}}s in the gamepad. The same
          object MUST be returned until the user agent needs to return
          different values (or values in a different order).
        </dd>
        <dt>
          <dfn>pose</dfn>
        </dt>
        <dd>
          The current {{GamepadPose}} of the gamepad, if supported by the
          hardware. Includes position, orientation, velocity, and acceleration.
          If the hardware cannot supply any pose values, MUST be set to `null`.
        </dd>
      </dl>
      <section>
        <h3>
          Receiving inputs
        </h3>
        <p>
          This section supplements the <a href=
          "https://w3c.github.io/gamepad/#receiving-inputs">Receiving
          inputs</a> section of the main <a href=
          "https://w3c.github.io/gamepad/">Gamepad specification</a>.
        </p>
      </section>
      <section>
        <h3>
          Constructing a `Gamepad`
        </h3>
        <p>
          This section supplements the <a href=
          "https://w3c.github.io/gamepad/#constructing-a-gamepad">Constructing
          a `Gamepad`</a> section of the main <a href=
          "https://w3c.github.io/gamepad/">Gamepad specification</a>.
        </p>
      </section>
    </section>
    <section>
      <h2>
        Partial <dfn>GamepadHapticActuator</dfn> Interface
      </h2>
      <p>
        This partial interface supplements the {{GamepadHapticActuator}}
        interface described in the main <a href=
        "https://w3c.github.io/gamepad/">Gamepad spec</a>.
      </p>
      <pre class="idl">
        [Exposed=Window]
        partial interface GamepadHapticActuator {
          Promise&lt;boolean&gt; pulse(double value, double duration);
        };
      </pre>
      <dl>
        <dt>
          <dfn>pulse()</dfn> method
        </dt>
        <dd>
          <p>
            {{GamepadHapticActuator/pulse()}} applies a |value:double| to the
            actuator for <var>duration</var> milliseconds. The <var>value</var>
            passed to <code>pulse()</code> is clamped to limits defined by the
            actuator type. The returned Promise will resolve <code>true</code>
            once the pulse has completed.
          </p>
          <p>
            Repeated calls to <code>pulse()</code> override the previous
            values.
          </p>
        </dd>
      </dl>
    </section>
  </body>
</html>