diff options
Diffstat (limited to 'dom/webidl/VRDisplay.webidl')
| -rw-r--r-- | dom/webidl/VRDisplay.webidl | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/dom/webidl/VRDisplay.webidl b/dom/webidl/VRDisplay.webidl new file mode 100644 index 0000000000..d1ce4b949e --- /dev/null +++ b/dom/webidl/VRDisplay.webidl @@ -0,0 +1,325 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * The origin of this IDL file is + * https://immersive-web.github.io/webvr/spec/1.1/ + */ + +enum VREye { + "left", + "right" +}; + +[Pref="dom.vr.enabled", + HeaderFile="mozilla/dom/VRDisplay.h", + SecureContext, + Exposed=Window] +interface VRFieldOfView { + readonly attribute double upDegrees; + readonly attribute double rightDegrees; + readonly attribute double downDegrees; + readonly attribute double leftDegrees; +}; + +typedef (HTMLCanvasElement or OffscreenCanvas) VRSource; + +dictionary VRLayer { + /** + * XXX - When WebVR in WebWorkers is implemented, HTMLCanvasElement below + * should be replaced with VRSource. + */ + HTMLCanvasElement? source = null; + + /** + * The left and right viewports contain 4 values defining the viewport + * rectangles within the canvas to present to the eye in UV space. + * [0] left offset of the viewport (0.0 - 1.0) + * [1] top offset of the viewport (0.0 - 1.0) + * [2] width of the viewport (0.0 - 1.0) + * [3] height of the viewport (0.0 - 1.0) + * + * When no values are passed, they will be processed as though the left + * and right sides of the viewport were passed: + * + * leftBounds: [0.0, 0.0, 0.5, 1.0] + * rightBounds: [0.5, 0.0, 0.5, 1.0] + */ + sequence<float> leftBounds = []; + sequence<float> rightBounds = []; +}; + +/** + * Values describing the capabilities of a VRDisplay. + * These are expected to be static per-device/per-user. + */ +[Pref="dom.vr.enabled", + HeaderFile="mozilla/dom/VRDisplay.h", + SecureContext, + Exposed=Window] +interface VRDisplayCapabilities { + /** + * hasPosition is true if the VRDisplay is capable of tracking its position. + */ + readonly attribute boolean hasPosition; + + /** + * hasOrientation is true if the VRDisplay is capable of tracking its orientation. + */ + readonly attribute boolean hasOrientation; + + /** + * Whether the VRDisplay is separate from the device’s + * primary display. If presenting VR content will obscure + * other content on the device, this should be false. When + * false, the application should not attempt to mirror VR content + * or update non-VR UI because that content will not be visible. + */ + readonly attribute boolean hasExternalDisplay; + + /** + * Whether the VRDisplay is capable of presenting content to an HMD or similar device. + * Can be used to indicate “magic window” devices that are capable of 6DoF tracking but for + * which requestPresent is not meaningful. If false then calls to requestPresent should + * always fail, and getEyeParameters should return null. + */ + readonly attribute boolean canPresent; + + /** + * Indicates the maximum length of the array that requestPresent() will accept. MUST be 1 if + canPresent is true, 0 otherwise. + */ + readonly attribute unsigned long maxLayers; +}; + +/** + * Values describing the the stage / play area for devices + * that support room-scale experiences. + */ +[Pref="dom.vr.enabled", + HeaderFile="mozilla/dom/VRDisplay.h", + SecureContext, + Exposed=Window] +interface VRStageParameters { + /** + * A 16-element array containing the components of a column-major 4x4 + * affine transform matrix. This matrix transforms the sitting-space position + * returned by get{Immediate}Pose() to a standing-space position. + */ + [Throws] readonly attribute Float32Array sittingToStandingTransform; + + /** + * Dimensions of the play-area bounds. The bounds are defined + * as an axis-aligned rectangle on the floor. + * The center of the rectangle is at (0,0,0) in standing-space + * coordinates. + * These bounds are defined for safety purposes. + * Content should not require the user to move beyond these + * bounds; however, it is possible for the user to ignore + * the bounds resulting in position values outside of + * this rectangle. + */ + readonly attribute float sizeX; + readonly attribute float sizeZ; +}; + +[Pref="dom.vr.enabled", + HeaderFile="mozilla/dom/VRDisplay.h", + SecureContext, + Exposed=Window] +interface VRPose +{ + /** + * position, linearVelocity, and linearAcceleration are 3-component vectors. + * position is relative to a sitting space. Transforming this point with + * VRStageParameters.sittingToStandingTransform converts this to standing space. + */ + [Constant, Throws] readonly attribute Float32Array? position; + [Constant, Throws] readonly attribute Float32Array? linearVelocity; + [Constant, Throws] readonly attribute Float32Array? linearAcceleration; + + /* orientation is a 4-entry array representing the components of a quaternion. */ + [Constant, Throws] readonly attribute Float32Array? orientation; + /* angularVelocity and angularAcceleration are the components of 3-dimensional vectors. */ + [Constant, Throws] readonly attribute Float32Array? angularVelocity; + [Constant, Throws] readonly attribute Float32Array? angularAcceleration; +}; + +[Pref="dom.vr.enabled", + HeaderFile="mozilla/dom/VRDisplay.h", + SecureContext, + Exposed=Window] +interface VRFrameData { + constructor(); + + readonly attribute DOMHighResTimeStamp timestamp; + + [Throws, Pure] readonly attribute Float32Array leftProjectionMatrix; + [Throws, Pure] readonly attribute Float32Array leftViewMatrix; + + [Throws, Pure] readonly attribute Float32Array rightProjectionMatrix; + [Throws, Pure] readonly attribute Float32Array rightViewMatrix; + + [Pure] readonly attribute VRPose pose; +}; + +[Pref="dom.vr.enabled", + HeaderFile="mozilla/dom/VRDisplay.h", + SecureContext, + Exposed=Window] +interface VREyeParameters { + /** + * offset is a 3-component vector representing an offset to + * translate the eye. This value may vary from frame + * to frame if the user adjusts their headset ipd. + */ + [Constant, Throws] readonly attribute Float32Array offset; + + /* These values may vary as the user adjusts their headset ipd. */ + [Constant] readonly attribute VRFieldOfView fieldOfView; + + /** + * renderWidth and renderHeight specify the recommended render target + * size of each eye viewport, in pixels. If multiple eyes are rendered + * in a single render target, then the render target should be made large + * enough to fit both viewports. + */ + [Constant] readonly attribute unsigned long renderWidth; + [Constant] readonly attribute unsigned long renderHeight; +}; + +[Pref="dom.vr.enabled", + HeaderFile="mozilla/dom/VRDisplay.h", + SecureContext, + Exposed=Window] +interface VRDisplay : EventTarget { + /** + * presentingGroups is a bitmask indicating which VR session groups + * have an active VR presentation. + */ + [ChromeOnly] readonly attribute unsigned long presentingGroups; + /** + * Setting groupMask causes submitted frames by VR sessions that + * aren't included in the bitmasked groups to be ignored. + * Non-chrome content is not aware of the value of groupMask. + * VRDisplay.RequestAnimationFrame will still fire for VR sessions + * that are hidden by groupMask, enabling their performance to be + * measured by chrome UI that is presented in other groups. + * This is expected to be used in cases where chrome UI is presenting + * information during link traversal or presenting options when content + * performance is too low for comfort. + * The VR refresh / VSync cycle is driven by the visible content + * and the non-visible content may have a throttled refresh rate. + */ + [ChromeOnly] attribute unsigned long groupMask; + + readonly attribute boolean isConnected; + readonly attribute boolean isPresenting; + + /** + * Dictionary of capabilities describing the VRDisplay. + */ + [Constant] readonly attribute VRDisplayCapabilities capabilities; + + /** + * If this VRDisplay supports room-scale experiences, the optional + * stage attribute contains details on the room-scale parameters. + */ + readonly attribute VRStageParameters? stageParameters; + + /* Return the current VREyeParameters for the given eye. */ + VREyeParameters getEyeParameters(VREye whichEye); + + /** + * An identifier for this distinct VRDisplay. Used as an + * association point in the Gamepad API. + */ + [Constant] readonly attribute unsigned long displayId; + + /** + * A display name, a user-readable name identifying it. + */ + [Constant] readonly attribute DOMString displayName; + + /** + * Populates the passed VRFrameData with the information required to render + * the current frame. + */ + boolean getFrameData(VRFrameData frameData); + + /** + * Return a VRPose containing the future predicted pose of the VRDisplay + * when the current frame will be presented. Subsequent calls to getPose() + * MUST return a VRPose with the same values until the next call to + * submitFrame(). + * + * The VRPose will contain the position, orientation, velocity, + * and acceleration of each of these properties. + */ + [NewObject] VRPose getPose(); + + /** + * Reset the pose for this display, treating its current position and + * orientation as the "origin/zero" values. VRPose.position, + * VRPose.orientation, and VRStageParameters.sittingToStandingTransform may be + * updated when calling resetPose(). This should be called in only + * sitting-space experiences. + */ + undefined resetPose(); + + /** + * z-depth defining the near plane of the eye view frustum + * enables mapping of values in the render target depth + * attachment to scene coordinates. Initially set to 0.01. + */ + attribute double depthNear; + + /** + * z-depth defining the far plane of the eye view frustum + * enables mapping of values in the render target depth + * attachment to scene coordinates. Initially set to 10000.0. + */ + attribute double depthFar; + + /** + * The callback passed to `requestAnimationFrame` will be called + * any time a new frame should be rendered. When the VRDisplay is + * presenting the callback will be called at the native refresh + * rate of the HMD. When not presenting this function acts + * identically to how window.requestAnimationFrame acts. Content should + * make no assumptions of frame rate or vsync behavior as the HMD runs + * asynchronously from other displays and at differing refresh rates. + */ + [Throws] long requestAnimationFrame(FrameRequestCallback callback); + + /** + * Passing the value returned by `requestAnimationFrame` to + * `cancelAnimationFrame` will unregister the callback. + */ + [Throws] undefined cancelAnimationFrame(long handle); + + /** + * Begin presenting to the VRDisplay. Must be called in response to a user gesture. + * Repeat calls while already presenting will update the VRLayers being displayed. + */ + [NewObject, NeedsCallerType] Promise<undefined> requestPresent(sequence<VRLayer> layers); + + /** + * Stops presenting to the VRDisplay. + */ + [NewObject] Promise<undefined> exitPresent(); + + /** + * Get the layers currently being presented. + */ + sequence<VRLayer> getLayers(); + + /** + * The VRLayer provided to the VRDisplay will be captured and presented + * in the HMD. Calling this function has the same effect on the source + * canvas as any other operation that uses its source image, and canvases + * created without preserveDrawingBuffer set to true will be cleared. + */ + undefined submitFrame(); +}; |