Mirrors/overte-thingvellir
3
0
Fork 0
mirror of https://thingvellir.net/git/overte synced 2025-03-27 23:52:03 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add HMD JSDoc

Browse source
This commit is contained in:
David Rowe 2018-03-28 12:25:12 +13:00
parent 11f5e7812b
commit f27e8868eb
3 changed files with 278 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

257
interface/src/scripting/HMDScriptingInterface.h
View file

@ -24,6 +24,36 @@ class QScriptEngine;
#include <QReadWriteLock>
/**jsdoc
* The HMD API provides access to the HMD used in VR display mode.
*
* @namespace HMD
* @property {Vec3} position - The position of the HMD if currently in VR display mode, otherwise
* {@link Vec3(0)|Vec3.ZERO}. <em>Read-only.</em>
* @property {Quat} orientation - The orientation of the HMD if currently in VR display mode, otherwise
* {@link Quat(0)|Quat.IDENTITY}.<em>Read-only.</em>
* @property {boolean} active - <code>true</code> if the display mode is HMD, otherwise <code>false</code>. <em>Read-only.</em>
* @property {boolean} mounted - <code>true</code> if currently in VR display mode and the HMD is being worn, otherwise
* <code>false</code>. <em>Read-only.</em>
*
* @property {number} playerHeight - The real-world height of the user. <em>Read-only.</em> <em>Currently always returns a
* value of <code>1.755</code>.</em>
* @property {number} eyeHeight - The real-world height of the user's eyes. <em>Read-only.</em> <em>Currently always returns a
* value of <code>1.655</code>.</em>
* @property {number} ipd - The inter-pupillary distance (distance between eyes) of the user, used for rendering. Defaults to
* the human average of <code>0.064</code> unless set by the HMD. <em>Read-only.</em>
* @property {number} ipdScale=1.0 - A scale factor applied to the <code>ipd</code> property value.
*
* @property {boolean} showTablet - <code>true</code> if the tablet is being displayed, <code>false</code> otherwise.
* <em>Read-only.</em>
* @property {boolean} tabletContextualMode - <code>true</code> if the tablet has been opened in contextual mode, otherwise
* <code>false</code>. In contextual mode, the tablet has been opened at a specific world position and orientation rather
* than at a position and orientation relative to the user. <em>Read-only.</em>
* @property {Uuid} tabletID - The UUID of the tablet body model overlay.
* @property {Uuid} tabletScreenID - The UUID of the tablet's screen overlay.
* @property {Uuid} homeButtonID - The UUID of the tablet's "home" button overlay.
* @property {Uuid} homeButtonHighlightID - The UUID of the tablet's "home" button highlight overlay.
*/
class HMDScriptingInterface : public AbstractHMDScriptingInterface, public Dependency {
Q_OBJECT
Q_PROPERTY(glm::vec3 position READ getPosition)
@ -37,26 +67,200 @@ class HMDScriptingInterface : public AbstractHMDScriptingInterface, public Depen
Q_PROPERTY(QUuid tabletScreenID READ getCurrentTabletScreenID WRITE setCurrentTabletScreenID)
public:
/**jsdoc
* Calculate the intersection of a ray with the HUD overlay.
* @function HMD.calculateRayUICollisionPoint
* @param {Vec3} position - The origin of the ray.
* @param {Vec3} direction - The direction of the ray.
* @returns {Vec3} The point of intersection with the HUD overlay if it intersects, otherwise {@link Vec3(0)|Vec3.ZERO}.
*/
Q_INVOKABLE glm::vec3 calculateRayUICollisionPoint(const glm::vec3& position, const glm::vec3& direction) const;
/**jsdoc
* Get the 2D HUD overlay coordinates of a 3D point on the HUD overlay.
* 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay.
* @function HMD.overlayFromWorldPoint
* @param {Vec3} position - The point on the HUD overlay in world coordinates.
* @returns {Vec2} The point on the HUD overlay in HUD coordinates.
* @example <caption>Draw a square on the HUD overlay in the direction you're looking.</caption>
* var hudIntersection = HMD.calculateRayUICollisionPoint(MyAvatar.getHeadPosition(),
* Quat.getForward(MyAvatar.headOrientation));
* var hudPoint = HMD.overlayFromWorldPoint(hudIntersection);
*
* var DIMENSIONS = { x: 50, y: 50 };
* var square = Overlays.addOverlay("rectangle", {
* x: hudPoint.x - DIMENSIONS.x / 2,
* y: hudPoint.y - DIMENSIONS.y / 2,
* width: DIMENSIONS.x,
* height: DIMENSIONS.y,
* color: { red: 255, green: 0, blue: 0 }
* });
*
* Script.scriptEnding.connect(function () {
* Overlays.deleteOverlay(square);
* });
*/
Q_INVOKABLE glm::vec2 overlayFromWorldPoint(const glm::vec3& position) const;
/**jsdoc
* Get the 3D world coordinates of a 2D point on the HUD overlay.
* 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay.
* @function HMD.worldPointFromOverlay
* @param {Vec2} coordinates - The point on the HUD overlay in HUD coordinates.
* @returns {Vec3} The point on the HUD overlay in world coordinates.
*/
Q_INVOKABLE glm::vec3 worldPointFromOverlay(const glm::vec2& overlay) const;
/**jsdoc
* Get the 2D point on the HUD overlay represented by given spherical coordinates.
* 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay.
* Spherical coordinates are polar coordinates in radians with <code>{ x: 0, y: 0 }</code> being the center of the HUD
* overlay.
* @function HMD.sphericalToOverlay
* @param {Vec2} sphericalPos - The point on the HUD overlay in spherical coordinates.
* @returns {Vec2} The point on the HUD overlay in HUD coordinates.
*/
Q_INVOKABLE glm::vec2 sphericalToOverlay(const glm::vec2 & sphericalPos) const;
/**jsdoc
* Get the spherical coordinates of a 2D point on the HUD overlay.
* 2D HUD overlay coordinates are pixels with the origin at the top left of the overlay.
* Spherical coordinates are polar coordinates in radians with <code>{ x: 0, y: 0 }</code> being the center of the HUD
* overlay.
* @function HMD.overlayToSpherical
* @param {Vec2} overlayPos - The point on the HUD overlay in HUD coordinates.
* @returns {Vec2} The point on the HUD overlay in spherical coordinates.
*/
Q_INVOKABLE glm::vec2 overlayToSpherical(const glm::vec2 & overlayPos) const;
/**jsdoc
* Recenter the HMD HUD to the current HMD position and orientation.
* @function HMD.centerUI
*/
Q_INVOKABLE void centerUI();
/**jsdoc
* Get the name of the HMD audio input device.
* @function HMD.preferredAudioInput
* @returns {string} The name of the HMD audio input device if in HMD mode, otherwise an empty string.
*/
Q_INVOKABLE QString preferredAudioInput() const;
/**jsdoc
* Get the name of the HMD audio output device.
* @function HMD.preferredAudioOutput
* @returns {string} The name of the HMD audio output device if in HMD mode, otherwise an empty string.
*/
Q_INVOKABLE QString preferredAudioOutput() const;
/**jsdoc
* Check whether there is an HMD available.
* @function HMD.isHMDAvailable
* @param {string} [name=""] - The name of the HMD to check for, e.g., <code>"Oculus Rift"</code>. The name is the same as
* may be displayed in Interface's "Display" menu. If no name is specified then any HMD matches.
* @returns {boolean} <code>true</code> if an HMD of the specified <code>name</code> is available, otherwise
* <code>false</code>.
* @example <caption>Report on HMD availability.</caption>
* print("Is any HMD available: " + HMD.isHMDAvailable());
* print("Is an Oculus Rift HMD available: " + HMD.isHMDAvailable("Oculus Rift"));
* print("Is a Vive HMD available: " + HMD.isHMDAvailable("OpenVR (Vive)"));
*/
Q_INVOKABLE bool isHMDAvailable(const QString& name = "");
/**jsdoc
* Check whether there is an HMD head controller available.
* @function HMD.isHeadControllerAvailable
* @param {string} [name=""] - The name of the HMD head controller to check for, e.g., <code>"Oculus"</code>. If no name is
* specified then any HMD head controller matches.
* @returns {boolean} <code>true</code> if an HMD head controller of the specified <code>name</code> is available,
* otherwise <code>false</code>.
* @example <caption>Report HMD head controller availability.</caption>
* print("Is any HMD head controller available: " + HMD.isHeadControllerAvailable());
* print("Is an Oculus head controller available: " + HMD.isHeadControllerAvailable("Oculus"));
* print("Is a Vive head controller available: " + HMD.isHeadControllerAvailable("OpenVR"));
*/
Q_INVOKABLE bool isHeadControllerAvailable(const QString& name = "");
/**jsdoc
* Check whether there are HMD hand controllers available.
* @function HMD.isHandControllerAvailable
* @param {string} [name=""] - The name of the HMD hand controller to check for, e.g., <code>"Oculus"</code>. If no name is
* specified then any HMD hand controller matches.
* @returns {boolean} <code>true</code> if an HMD hand controller of the specified <code>name</code> is available,
* otherwise <code>false</code>.
* @example <caption>Report HMD hand controller availability.</caption>
* print("Are any HMD hand controllers available: " + HMD.isHandControllerAvailable());
* print("Are Oculus hand controllers available: " + HMD.isHandControllerAvailable("Oculus"));
* print("Are Vive hand controllers available: " + HMD.isHandControllerAvailable("OpenVR"));
*/
Q_INVOKABLE bool isHandControllerAvailable(const QString& name = "");
/**jsdoc
* Check whether there are specific HMD controllers available.
* @function HMD.isSubdeviceContainingNameAvailable
* @param {string} - The name of the HMD controller to check for, e.g., <code>"OculusTouch"</code>.
* @returns {boolean} <code>true</code> if an HMD controller with a name containing the specified <code>name</code> is
* available, otherwise <code>false</code>.
* @example <caption>Report if particular Oculus controllers are available.</caption>
* print("Is an Oculus Touch controller available: " + HMD.isSubdeviceContainingNameAvailable("Touch"));
* print("Is an Oculus Remote controller available: " + HMD.isSubdeviceContainingNameAvailable("Remote"));
*/
Q_INVOKABLE bool isSubdeviceContainingNameAvailable(const QString& name);
/**jsdoc
* Signal that models of the HMD hand controllers being used should be displayed. The models are displayed at their actual,
* real-world locations.
* @function HMD.requestShowHandControllers
* @example <caption>Show your hand controllers for 10 seconds.</caption>
* HMD.requestShowHandControllers();
* Script.setTimeout(function () {
* HMD.requestHideHandControllers();
* }, 10000);
*/
Q_INVOKABLE void requestShowHandControllers();
/**jsdoc
* Signal that it is no longer necessary to display models of the HMD hand controllers being used. If no other scripts
* want the models displayed then they are no longer displayed.
* @function HMD.requestHideHandControllers
*/
Q_INVOKABLE void requestHideHandControllers();
/**jsdoc
* Check whether any script wants models of the HMD hand controllers displayed. Requests are made and canceled using
* {@link HMD.requestShowHandControllers|requestShowHandControllers} and
* {@link HMD.requestHideHandControllers|requestHideHandControllers}.
* @function HMD.shouldShowHandControllers
* @returns {boolean} <code>true</code> if any script is requesting that HMD hand controller models be displayed.
*/
Q_INVOKABLE bool shouldShowHandControllers() const;
/**jsdoc
* Causes the borders and decorations in HUD windows to be enlarged when the laser intersects them in HMD mode. By default,
* borders and decorations are not enlarged.
* @function HMD.activateHMDHandMouse
*/
Q_INVOKABLE void activateHMDHandMouse();
/**jsdoc
* Causes the border and decorations in HUD windows to no longer be enlarged when the laser intersects them in HMD mode. By
* default, borders and decorations are not enlarged.
* @function HMD.deactivateHMDHandMouse
*/
Q_INVOKABLE void deactivateHMDHandMouse();
/**jsdoc
* Suppress the activation of the HMD-provided keyboard, if any. Successful calls should be balanced with a call to
* {@link HMD.unspressKeyboard|unspressKeyboard} within a reasonable amount of time.
* @function HMD.suppressKeyboard
* @returns {boolean} <code>true</code> if the current HMD provides a keyboard and it was successfully suppressed (e.g., it
* isn't being displayed), otherwise <code>false</code>.
*/
/// Suppress the activation of any on-screen keyboard so that a script operation will
/// not be interrupted by a keyboard popup
/// Returns false if there is already an active keyboard displayed.
@ -65,21 +269,68 @@ public:
/// call to unsuppressKeyboard() within a reasonable amount of time
Q_INVOKABLE bool suppressKeyboard();
/**jsdoc
* Unsuppress the activation of the HMD-provided keyboard, if any.
* @function HMD.unsuppressKeyboard
*/
/// Enable the keyboard following a suppressKeyboard call
Q_INVOKABLE void unsuppressKeyboard();
/**jsdoc
* Check whether the HMD-provided keyboard, if any, is visible.
* @function HMD.isKeyboardVisible
* @returns {boolean} <code>true</code> if the current HMD provides a keyboard and it is visible, otherwise
* <code>false</code>.
*/
/// Query the display plugin to determine the current VR keyboard visibility
Q_INVOKABLE bool isKeyboardVisible();
// rotate the overlay UI sphere so that it is centered about the the current HMD position and orientation
Q_INVOKABLE void centerUI();
/**jsdoc
* Closes the tablet if it is open.
* @function HMD.closeTablet
*/
Q_INVOKABLE void closeTablet();
/**jsdoc
* Opens the tablet if the tablet is used in the current display mode and it isn't already showing, and sets the tablet to
* contextual mode if requested. In contextual mode, the page displayed on the tablet is wholly controlled by script (i.e.,
* the user cannot navigate to another).
* @function HMD.openTablet
* @param {boolean} [contextualMode=false] - If <code>true</code> then the tablet is opened at a specific position and
* orientation already set by the script, otherwise it opens at a position and orientation relative to the user. For
* contextual mode, set the world or local position and orientation of the <code>HMD.tabletID</code> overlay.
*/
Q_INVOKABLE void openTablet(bool contextualMode = false);
signals:
/**jsdoc
* Triggered when a request to show or hide models of the HMD hand controllers is made using
* {@link HMD.requestShowHandControllers|requestShowHandControllers} or
* {@link HMD.requestHideHandControllers|requestHideHandControllers}.
* @function HMD.shouldShowHandControllersChanged
* @returns {Signal}
* @example <caption>Report when showing of hand controllers changes.</caption>
* function onShouldShowHandControllersChanged() {
* print("Should show hand controllers: " + HMD.shouldShowHandControllers());
* }
* HMD.shouldShowHandControllersChanged.connect(onShouldShowHandControllersChanged);
*
* HMD.requestShowHandControllers();
* Script.setTimeout(function () {
* HMD.requestHideHandControllers();
* }, 10000);
*/
bool shouldShowHandControllersChanged();
/**jsdoc
* Triggered when the <code>HMD.mounted</code> property value changes.
* @function HMD.mountedChanged
* @returns {Signal}
* @example <caption>Report when there's a change in the HMD being worn.</caption>
* HMD.mountedChanged.connect(function () {
* print("Mounted changed. HMD is mounted: " + HMD.mounted);
* });
*/
void mountedChanged();
public:

21
libraries/display-plugins/src/display-plugins/AbstractHMDScriptingInterface.h
View file

@ -12,6 +12,7 @@
#include <GLMHelpers.h>
// These properties have JSDoc documentation in HMDScriptingInterface.h.
class AbstractHMDScriptingInterface : public QObject {
Q_OBJECT
Q_PROPERTY(bool active READ isHMDMode)
@ -30,7 +31,27 @@ public:
bool isHMDMode() const;
signals:
/**jsdoc
* Triggered when the <code>HMD.ipdScale</code> property value changes.
* @function HMD.IPDScaleChanged
* @returns {Signal}
*/
void IPDScaleChanged();
/**jsdoc
* Triggered when Interface's display mode changes and when the user puts on or takes off their HMD.
* @function HMD.displayModeChanged
* @param {boolean} isHMDMode - <code>true</code> if the display mode is HMD, otherwise <code>false</code>. This is the
* same value as provided by <code>HMD.active</code>.
* @returns {Signal}
* @example <caption>Report when the display mode changes.</caption>
* HMD.displayModeChanged.connect(function (isHMDMode) {
* print("Display mode changed");
* print("isHMD = " + isHMD);
* print("HMD.active = " + HMD.active);
* print("HMD.mounted = " + HMD.mounted);
* });
*/
void displayModeChanged(bool isHMDMode);
private:

5
tools/jsdoc/plugins/hifi.js
View file

@ -24,11 +24,12 @@ exports.handlers = {
'../../libraries/animation/src',
'../../libraries/avatars/src',
'../../libraries/controllers/src/controllers/',
'../../libraries/graphics-scripting/src/graphics-scripting/',
'../../libraries/display-plugins/src/display-plugins/',
'../../libraries/entities/src',
'../../libraries/graphics-scripting/src/graphics-scripting/',
'../../libraries/model-networking/src/model-networking/',
'../../libraries/octree/src',
'../../libraries/networking/src',
'../../libraries/octree/src',
'../../libraries/physics/src',
'../../libraries/pointers/src',
'../../libraries/script-engine/src',