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 data-dfn-for="GamepadTouch">
      <h2>
        <dfn>GamepadTouch</dfn> Interface
      </h2>
      <p>
        This interface defines a single touch event on a gamepad device that
        supports input. The event consists of a touch id that uniquely
        identifies the touch point from the time the input medium (e.g. finger,
        stylus, etc) makes contact with the touch device, up to the time the
        input medium is no longer making contact with the touch device.
      </p>
      <pre class="idl">
        [Exposed=Window, SecureContext]
        interface GamepadTouch {
          readonly attribute unsigned long touchId;
          readonly attribute octet surfaceId;
          readonly attribute Float32Array position;
          readonly attribute Uint32Array? surfaceDimensions;
        };
      </pre>
      <dl>
        <dt>
          <dfn>touchId</dfn> attribute
        </dt>
        <dd>
          Unique id of the touch event. Range is [0, 4294967295].
          <p>The user agent is responsible for:</p>
          <ul>
            <li>Incrementing the id for each subsequent touch event based
              on information provided by the device API.</li>
            <li>Maintaining the uniqueness of the id per origin to
              prevent fingerprinting.</li>
          </ul>
          {{GamepadTouch/touchId}} SHOULD be set to a default value of 0 when a
          new {{Gamepad}} object is created.
        </dd>
        <dt>
          <dfn>surfaceId</dfn>
        </dt>
        <dd>
          Unique id of the surface that generated the touch event.
        </dd>
        <dt>
          <dfn>position</dfn>
        </dt>
        <dd>
          x, y coordinates of the touch event. Range of each coordinate is
          normalized to [-1.0, 1.0]. Along the x-axis, -1.0 references the
          leftmost coordinate and 1.0 references the rightmost coordinate.
          Along the y-axis, -1.0 references the topmost coordinate and 1.0
          references the bottommost coordinate. MUST be a two-element array.
        </dd>
        <dt>
          <dfn>surfaceDimensions</dfn>
        </dt>
        <dd>
          Width and height of the touch surface in integer units. When not
          <code>null</code>, MUST be a two-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;
          readonly attribute FrozenArray&lt;GamepadTouch&gt;? touchEvents;
        };
      </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>
        <tr>
          <td>
            <dfn data-dfn-for="Gamepad">[[\touchEvents]]</dfn>
          </td>
          <td>
            `null`
          </td>
          <td>
            List of generated touch events.
          </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>
        <dt>
          <dfn>touchEvents</dfn>
        </dt>
        <dd>
          <p>
            A list of {{GamepadTouch}} events generated from all touch surfaces. If the
            device does not support touch events, MUST be set to `null`.
          </p>
          <p>
            The {{Gamepad/touchEvents}} getter steps are:
          </p>
          <ol>
            <li>If [=this=].{{Gamepad/[[touchEvents]]}} not `null` and not
            empty, return [=this=].{{Gamepad/[[touchEvents]]}}.
            </li>
            <li>Otherwise return `null`.
            </li>
          </ol>
        </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>
        <p>
          In addtion to the steps defined in the main <a href=
          "https://w3c.github.io/gamepad/">Gamepad specification</a>. When the
          user agent modifies the list of |active touch points| for a touch
          surface by adding touch points, removing touch points, or updating
          the values of existing touch points, <dfn data-lt=
          "updating touchEvents">update touchEvents</dfn> by running the
          following steps:
        </p>
        <ol class="algorithm">
          <li>Let |surfaceId:unsigned long| be 0.
          </li>
          <li>Remove any existing events from
          {{Gamepad}}.{{Gamepad/[[touchEvents]]}}.
          </li>
          <li>Repeat the following steps for each [=touch surface=] on
          |gamepad| in [=touch surface enumeration order=]:
            <ol>
              <li>Let |surfaceDimensions| be an `null`.
              </li>
              <li>If the touch surface exposes maximum surface dimensions in
              device units:
                <ol>
                  <li>Set |touchEvent|.{{GamepadTouch/surfaceDimensions}}[0] to
                  the maximum X dimension on the [=touch surface=] in device
                  units.
                  </li>
                  <li>Set |touchEvent|.{{GamepadTouch/surfaceDimensions}}[1] to
                  the maximum Y dimension on the [=touch surface=] in device
                  units.
                  </li>
                </ol>
              </li>
              <li>Repeat the following steps for each [=active touch point=]
              reported by the |gamepad| for the current [=touch surface=].
                <ol>
                  <li>Let |nextTouchId:unsigned long| be the next available
                  touchId for the |gamepad|.
                  </li>
                  <li>Let |touchEvent:GamepadTouch| be a {{GamepadTouch}}.
                  </li>
                  <li>Set |touchEvent|.{{GamepadTouch/surfaceId}} to be
                  |surfaceId|.
                  </li>
                  <li>If the touch data is part of an existing [=active touch
                  point=] tracked by the user agent:
                    <ol>
                      <li>Set |touchEvent|.{{GamepadTouch/touchId}} to the
                      touchId of the [=active touch point=].
                      </li>
                      <li>Otherwise, set touchId to nextTouchId and increment
                      nextTouchId.
                        <p class="note" title=
                        "Touch ids are relative to the Gamepad">
                          If the Gamepad has multiple touch surfaces the touch
                          id will be unique across surfaces.
                        </p>
                      </li>
                    </ol>
                  </li>
                  <li>Let |position| be a [=new=] {{Float32Array}} with length
                  2.
                  </li>
                  <li>
                    <p>
                      |position|[0] should be set to the device X coordinate
                      relative to the device [=touch surface=] and normalized
                      to [-1.0,1.0] where -1.0 is the leftmost coordinate and
                      1.0 is the rightmost coordinate.
                    </p>
                    <p class="note" title=
                    "Possible implementation (if surfaceDimensions are available)">
                      `position[0] = (2.0 * touchData.x / surfaceDimensions[0])
                      - 1`
                    </p>
                  </li>
                  <li>
                    <p>
                      |position|[1] should be set to the device Y coordinate
                      relative to the device [=touch surface=] and normalized
                      to [-1.0,1.0] where -1.0 is the topmost coordinate and
                      1.0 is the bottommost coordinate.
                    </p>
                    <p class="note" title=
                    "Possible implementation (if surfaceDimensions are available)">
                      `position[1] = (2.0 * touchData.y / surfaceDimensions[1])
                      - 1`
                    </p>
                  </li>
                </ol>
              </li>
              <li>Set |touchEvent|.{{GamepadTouch/position}} to be
              |position:Float32Array|.
              </li>
              <li>Add |touchEvent| to {{Gamepad}}.{{Gamepad/[[touchEvents]]}}.
              </li>
            </ol>
          </li>
          <li>Increment |surfaceId|
          </li>
          <li>Increment |surfaceId|
          </li>
        </ol>
      </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>
        <p>
          In addtion to the steps defined in the main <a href=
          "https://w3c.github.io/gamepad/">Gamepad specification</a>. When
          constructing <dfn>a new `Gamepad`</dfn> representing a connected
          gamepad device perform the following steps:
        </p>
        <ol>
          <li>Let |gamepad:Gamepad| be a newly created {{Gamepad}} instance:
            <ol>
              <li>If the |gamepad| has touch surfaces, initialize |gamepad|'s
              {{Gamepad/touchEvents}} to an empty [=list=].
              </li>
              <li>Otherwise, initialize |gamepad|'s {{Gamepad/touchEvents}}
              <code>null</code>.
              </li>
            </ol>
          </li>
        </ol>
      </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>
      <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>
    </section>
    <section>
      <h3>
        Glossary
      </h3>
      <p>
        <dfn>touch surface</dfn> is a surface that can detect contact from a
        users fingers and report where on the surface the contact is made.
      </p>
      <p>
        <dfn>touch surface enumeration order</dfn> is an ordered listing of all
        the surfaces in a |gamepad|.
      </p>
      <p>
        <dfn>active touch point</dfn> is defined in the <a href=
        "https://w3c.github.io/touch-events/#dfn-active-touch-point">Touch
        Events - Level 2</a> specification.
      </p>
    </section>
  </body>
</html>