dom/webidl/VRDisplay.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is
   7  * https://immersive-web.github.io/webvr/spec/1.1/
   8  */
   9
  10 enum VREye {
  11   "left",
  12   "right"
  13 };
  14
  15 [Pref="dom.vr.enabled",
  16  HeaderFile="mozilla/dom/VRDisplay.h",
  17  SecureContext,
  18  Exposed=Window]
  19 interface VRFieldOfView {
  20   readonly attribute double upDegrees;
  21   readonly attribute double rightDegrees;
  22   readonly attribute double downDegrees;
  23   readonly attribute double leftDegrees;
  24 };
  25
  26 typedef (HTMLCanvasElement or OffscreenCanvas) VRSource;
  27
  28 dictionary VRLayer {
  29   /**
  30    * XXX - When WebVR in WebWorkers is implemented, HTMLCanvasElement below
  31    *       should be replaced with VRSource.
  32    */
  33   HTMLCanvasElement? source = null;
  34
  35   /**
  36    * The left and right viewports contain 4 values defining the viewport
  37    * rectangles within the canvas to present to the eye in UV space.
  38    * [0] left offset of the viewport (0.0 - 1.0)
  39    * [1] top offset of the viewport (0.0 - 1.0)
  40    * [2] width of the viewport (0.0 - 1.0)
  41    * [3] height of the viewport (0.0 - 1.0)
  42    *
  43    * When no values are passed, they will be processed as though the left
  44    * and right sides of the viewport were passed:
  45    *
  46    * leftBounds: [0.0, 0.0, 0.5, 1.0]
  47    * rightBounds: [0.5, 0.0, 0.5, 1.0]
  48    */
  49   sequence<float> leftBounds = [];
  50   sequence<float> rightBounds = [];
  51 };
  52
  53 /**
  54  * Values describing the capabilities of a VRDisplay.
  55  * These are expected to be static per-device/per-user.
  56  */
  57 [Pref="dom.vr.enabled",
  58  HeaderFile="mozilla/dom/VRDisplay.h",
  59  SecureContext,
  60  Exposed=Window]
  61 interface VRDisplayCapabilities {
  62   /**
  63    * hasPosition is true if the VRDisplay is capable of tracking its position.
  64    */
  65   readonly attribute boolean hasPosition;
  66
  67   /**
  68    * hasOrientation is true if the VRDisplay is capable of tracking its orientation.
  69    */
  70   readonly attribute boolean hasOrientation;
  71
  72   /**
  73    * Whether the VRDisplay is separate from the device’s
  74    * primary display. If presenting VR content will obscure
  75    * other content on the device, this should be false. When
  76    * false, the application should not attempt to mirror VR content
  77    * or update non-VR UI because that content will not be visible.
  78    */
  79   readonly attribute boolean hasExternalDisplay;
  80
  81   /**
  82    * Whether the VRDisplay is capable of presenting content to an HMD or similar device.
  83    * Can be used to indicate “magic window” devices that are capable of 6DoF tracking but for
  84    * which requestPresent is not meaningful. If false then calls to requestPresent should
  85    * always fail, and getEyeParameters should return null.
  86    */
  87   readonly attribute boolean canPresent;
  88
  89   /**
  90    * Indicates the maximum length of the array that requestPresent() will accept. MUST be 1 if
  91      canPresent is true, 0 otherwise.
  92    */
  93   readonly attribute unsigned long maxLayers;
  94 };
  95
  96 /**
  97  * Values describing the the stage / play area for devices
  98  * that support room-scale experiences.
  99  */
 100 [Pref="dom.vr.enabled",
 101  HeaderFile="mozilla/dom/VRDisplay.h",
 102  SecureContext,
 103  Exposed=Window]
 104 interface VRStageParameters {
 105   /**
 106    * A 16-element array containing the components of a column-major 4x4
 107    * affine transform matrix. This matrix transforms the sitting-space position
 108    * returned by get{Immediate}Pose() to a standing-space position.
 109    */
 110   [Throws] readonly attribute Float32Array sittingToStandingTransform;
 111
 112   /**
 113    * Dimensions of the play-area bounds. The bounds are defined
 114    * as an axis-aligned rectangle on the floor.
 115    * The center of the rectangle is at (0,0,0) in standing-space
 116    * coordinates.
 117    * These bounds are defined for safety purposes.
 118    * Content should not require the user to move beyond these
 119    * bounds; however, it is possible for the user to ignore
 120    * the bounds resulting in position values outside of
 121    * this rectangle.
 122    */
 123   readonly attribute float sizeX;
 124   readonly attribute float sizeZ;
 125 };
 126
 127 [Pref="dom.vr.enabled",
 128  HeaderFile="mozilla/dom/VRDisplay.h",
 129  SecureContext,
 130  Exposed=Window]
 131 interface VRPose
 132 {
 133   /**
 134    * position, linearVelocity, and linearAcceleration are 3-component vectors.
 135    * position is relative to a sitting space. Transforming this point with
 136    * VRStageParameters.sittingToStandingTransform converts this to standing space.
 137    */
 138   [Constant, Throws] readonly attribute Float32Array? position;
 139   [Constant, Throws] readonly attribute Float32Array? linearVelocity;
 140   [Constant, Throws] readonly attribute Float32Array? linearAcceleration;
 141
 142   /* orientation is a 4-entry array representing the components of a quaternion. */
 143   [Constant, Throws] readonly attribute Float32Array? orientation;
 144   /* angularVelocity and angularAcceleration are the components of 3-dimensional vectors. */
 145   [Constant, Throws] readonly attribute Float32Array? angularVelocity;
 146   [Constant, Throws] readonly attribute Float32Array? angularAcceleration;
 147 };
 148
 149 [Pref="dom.vr.enabled",
 150  HeaderFile="mozilla/dom/VRDisplay.h",
 151  SecureContext,
 152  Exposed=Window]
 153 interface VRFrameData {
 154   constructor();
 155
 156   readonly attribute DOMHighResTimeStamp timestamp;
 157
 158   [Throws, Pure] readonly attribute Float32Array leftProjectionMatrix;
 159   [Throws, Pure] readonly attribute Float32Array leftViewMatrix;
 160
 161   [Throws, Pure] readonly attribute Float32Array rightProjectionMatrix;
 162   [Throws, Pure] readonly attribute Float32Array rightViewMatrix;
 163
 164   [Pure] readonly attribute VRPose pose;
 165 };
 166
 167 [Pref="dom.vr.enabled",
 168  HeaderFile="mozilla/dom/VRDisplay.h",
 169  SecureContext,
 170  Exposed=Window]
 171 interface VREyeParameters {
 172   /**
 173    * offset is a 3-component vector representing an offset to
 174    * translate the eye. This value may vary from frame
 175    * to frame if the user adjusts their headset ipd.
 176    */
 177   [Constant, Throws] readonly attribute Float32Array offset;
 178
 179   /* These values may vary as the user adjusts their headset ipd. */
 180   [Constant] readonly attribute VRFieldOfView fieldOfView;
 181
 182   /**
 183    * renderWidth and renderHeight specify the recommended render target
 184    * size of each eye viewport, in pixels. If multiple eyes are rendered
 185    * in a single render target, then the render target should be made large
 186    * enough to fit both viewports.
 187    */
 188   [Constant] readonly attribute unsigned long renderWidth;
 189   [Constant] readonly attribute unsigned long renderHeight;
 190 };
 191
 192 [Pref="dom.vr.enabled",
 193  HeaderFile="mozilla/dom/VRDisplay.h",
 194  SecureContext,
 195  Exposed=Window]
 196 interface VRDisplay : EventTarget {
 197   /**
 198    * presentingGroups is a bitmask indicating which VR session groups
 199    * have an active VR presentation.
 200    */
 201   [ChromeOnly] readonly attribute unsigned long presentingGroups;
 202   /**
 203    * Setting groupMask causes submitted frames by VR sessions that
 204    * aren't included in the bitmasked groups to be ignored.
 205    * Non-chrome content is not aware of the value of groupMask.
 206    * VRDisplay.RequestAnimationFrame will still fire for VR sessions
 207    * that are hidden by groupMask, enabling their performance to be
 208    * measured by chrome UI that is presented in other groups.
 209    * This is expected to be used in cases where chrome UI is presenting
 210    * information during link traversal or presenting options when content
 211    * performance is too low for comfort.
 212    * The VR refresh / VSync cycle is driven by the visible content
 213    * and the non-visible content may have a throttled refresh rate.
 214    */
 215   [ChromeOnly] attribute unsigned long groupMask;
 216
 217   readonly attribute boolean isConnected;
 218   readonly attribute boolean isPresenting;
 219
 220   /**
 221    * Dictionary of capabilities describing the VRDisplay.
 222    */
 223   [Constant] readonly attribute VRDisplayCapabilities capabilities;
 224
 225   /**
 226    * If this VRDisplay supports room-scale experiences, the optional
 227    * stage attribute contains details on the room-scale parameters.
 228    */
 229   readonly attribute VRStageParameters? stageParameters;
 230
 231   /* Return the current VREyeParameters for the given eye. */
 232   VREyeParameters getEyeParameters(VREye whichEye);
 233
 234   /**
 235    * An identifier for this distinct VRDisplay. Used as an
 236    * association point in the Gamepad API.
 237    */
 238   [Constant] readonly attribute unsigned long displayId;
 239
 240   /**
 241    * A display name, a user-readable name identifying it.
 242    */
 243   [Constant] readonly attribute DOMString displayName;
 244
 245   /**
 246    * Populates the passed VRFrameData with the information required to render
 247    * the current frame.
 248    */
 249   boolean getFrameData(VRFrameData frameData);
 250
 251   /**
 252    * Return a VRPose containing the future predicted pose of the VRDisplay
 253    * when the current frame will be presented. Subsequent calls to getPose()
 254    * MUST return a VRPose with the same values until the next call to
 255    * submitFrame().
 256    *
 257    * The VRPose will contain the position, orientation, velocity,
 258    * and acceleration of each of these properties.
 259    */
 260   [NewObject] VRPose getPose();
 261
 262   /**
 263    * Reset the pose for this display, treating its current position and
 264    * orientation as the "origin/zero" values. VRPose.position,
 265    * VRPose.orientation, and VRStageParameters.sittingToStandingTransform may be
 266    * updated when calling resetPose(). This should be called in only
 267    * sitting-space experiences.
 268    */
 269   undefined resetPose();
 270
 271   /**
 272    * z-depth defining the near plane of the eye view frustum
 273    * enables mapping of values in the render target depth
 274    * attachment to scene coordinates. Initially set to 0.01.
 275    */
 276   attribute double depthNear;
 277
 278   /**
 279    * z-depth defining the far plane of the eye view frustum
 280    * enables mapping of values in the render target depth
 281    * attachment to scene coordinates. Initially set to 10000.0.
 282    */
 283   attribute double depthFar;
 284
 285   /**
 286    * The callback passed to `requestAnimationFrame` will be called
 287    * any time a new frame should be rendered. When the VRDisplay is
 288    * presenting the callback will be called at the native refresh
 289    * rate of the HMD. When not presenting this function acts
 290    * identically to how window.requestAnimationFrame acts. Content should
 291    * make no assumptions of frame rate or vsync behavior as the HMD runs
 292    * asynchronously from other displays and at differing refresh rates.
 293    */
 294   [Throws] long requestAnimationFrame(FrameRequestCallback callback);
 295
 296   /**
 297    * Passing the value returned by `requestAnimationFrame` to
 298    * `cancelAnimationFrame` will unregister the callback.
 299    */
 300   [Throws] undefined cancelAnimationFrame(long handle);
 301
 302   /**
 303    * Begin presenting to the VRDisplay. Must be called in response to a user gesture.
 304    * Repeat calls while already presenting will update the VRLayers being displayed.
 305    */
 306   [NewObject, NeedsCallerType] Promise<undefined> requestPresent(sequence<VRLayer> layers);
 307
 308   /**
 309    * Stops presenting to the VRDisplay.
 310    */
 311   [NewObject] Promise<undefined> exitPresent();
 312
 313   /**
 314    * Get the layers currently being presented.
 315    */
 316   sequence<VRLayer> getLayers();
 317
 318   /**
 319    * The VRLayer provided to the VRDisplay will be captured and presented
 320    * in the HMD. Calling this function has the same effect on the source
 321    * canvas as any other operation that uses its source image, and canvases
 322    * created without preserveDrawingBuffer set to true will be cleared.
 323    */
 324   undefined submitFrame();
 325 };