VRDisplay.webidl (11364B)
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 };