From 0b7cddb886ffd24f7e150b9150fe7a582626be77 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 8 Mar 2019 13:49:10 +1300 Subject: [PATCH] Fill in and tidy MyAvatar JSDoc --- interface/src/avatar/MyAvatar.cpp | 14 + interface/src/avatar/MyAvatar.h | 533 +++++++++++++----- .../src/avatars-renderer/Avatar.h | 93 ++- libraries/shared/src/RegisteredMetaTypes.cpp | 9 +- 4 files changed, 483 insertions(+), 166 deletions(-) diff --git a/interface/src/avatar/MyAvatar.cpp b/interface/src/avatar/MyAvatar.cpp index 30e8733a42..f62896772d 100755 --- a/interface/src/avatar/MyAvatar.cpp +++ b/interface/src/avatar/MyAvatar.cpp @@ -3531,6 +3531,12 @@ void MyAvatar::clearScaleRestriction() { _haveReceivedHeightLimitsFromDomain = false; } +/**jsdoc + * A teleport target. + * @typedef {object} MyAvatar.GoToProperties + * @property {Vec3} position - The new position for the avatar, in world coordinates. + * @property {Quat} [orientation] - The new orientation for the avatar. + */ void MyAvatar::goToLocation(const QVariant& propertiesVar) { qCDebug(interfaceapp, "MyAvatar QML goToLocation"); auto properties = propertiesVar.toMap(); @@ -3887,6 +3893,14 @@ void MyAvatar::setCollisionWithOtherAvatarsFlags() { _characterController.setPendingFlagsUpdateCollisionMask(); } +/**jsdoc + * A collision capsule is a cylinder with hemispherical ends. It is used, in particular, to approximate the extents of an + * avatar. + * @typedef {object} MyAvatar.CollisionCapsule + * @property {Vec3} start - The bottom end of the cylinder, excluding the bottom hemisphere. + * @property {Vec3} end - The top end of the cylinder, excluding the top hemisphere. + * @property {number} radius - The radius of the cylinder and the hemispheres. + */ void MyAvatar::updateCollisionCapsuleCache() { glm::vec3 start, end; float radius; diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index a0f1531e64..f05bdd5184 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -155,33 +155,45 @@ class MyAvatar : public Avatar { * @property {boolean} hasProceduralEyeFaceMovement=true - If true then procedural eye movement is turned on. * @property {boolean} hasAudioEnabledFaceMovement=true - If true then voice audio will move the mouth * blendshapes while MyAvatar.hasScriptedBlendshapes is enabled. - * @property {number} rotationRecenterFilterLength - * @property {number} rotationThreshold - * @property {boolean} enableStepResetRotation - * @property {boolean} enableDrawAverageFacing + * @property {number} rotationRecenterFilterLength - Configures how quickly the avatar root rotates to recenter its facing + * direction to match that of the user's torso based on head and hands orientation. A smaller value makes the + * recentering happen more quickly. The minimum value is 0.01. + * @property {number} rotationThreshold - The angle in radians that the user's torso facing direction (based on head and + * hands orientation) can differ from that of the avatar before the avatar's root is rotated to match the user's torso. + * @property {boolean} enableStepResetRotation - If true then after the user's avatar takes a step, the + * avatar's root immediately rotates to recenter its facing direction to match that of the user's torso based on head + * and hands orientation. + * @property {boolean} enableDrawAverageFacing - If true, debug graphics are drawn that show the average + * facing direction of the user's torso (based on head and hands orientation). This can be useful if you want to try + * out different filter lengths and thresholds. * * @property {Vec3} leftHandPosition - The position of the left hand in avatar coordinates if it's being positioned by * controllers, otherwise {@link Vec3(0)|Vec3.ZERO}. Read-only. * @property {Vec3} rightHandPosition - The position of the right hand in avatar coordinates if it's being positioned by * controllers, otherwise {@link Vec3(0)|Vec3.ZERO}. Read-only. - * @property {Vec3} leftHandTipPosition - The position 30cm offset from the left hand in avatar coordinates if it's being - * positioned by controllers, otherwise {@link Vec3(0)|Vec3.ZERO}. Read-only. - * @property {Vec3} rightHandTipPosition - The position 30cm offset from the right hand in avatar coordinates if it's being - * positioned by controllers, otherwise {@link Vec3(0)|Vec3.ZERO}. Read-only. + * @property {Vec3} leftHandTipPosition - The position 0.3m in front of the left hand's position, in the direction along the + * palm, in avatar coordinates. If the hand isn't being positioned by a controller, the value is + * {@link Vec3(0)|Vec3.ZERO}. Read-only. + * @property {Vec3} rightHandTipPosition - The position 0.3m in front of the right hand's position, in the direction along + * the palm, in avatar coordinates. If the hand isn't being positioned by a controller, the value is + * {@link Vec3(0)|Vec3.ZERO}. Read-only. * - * @property {Pose} leftHandPose - The pose of the left hand as determined by the hand controllers. Read-only. - * @property {Pose} rightHandPose - The pose right hand position as determined by the hand controllers. Read-only. - * @property {Pose} leftHandTipPose - The pose of the left hand as determined by the hand controllers, with the position - * by 30cm. Read-only. - * @property {Pose} rightHandTipPose - The pose of the right hand as determined by the hand controllers, with the position - * by 30cm. Read-only. + * @property {Pose} leftHandPose - The pose of the left hand as determined by the hand controllers, relative to the avatar. + * Read-only. + * @property {Pose} rightHandPose - The pose right hand position as determined by the hand controllers, relative to the + * avatar. Read-only. + * @property {Pose} leftHandTipPose - The pose of the left hand as determined by the hand controllers, relative to the + * avatar, with the position adjusted to be 0.3m along the direction of the palm. Read-only. + * @property {Pose} rightHandTipPose - The pose of the right hand as determined by the hand controllers, relative to the + * avatar, with the position adjusted by 0.3m along the direction of the palm. Read-only. * - * @property {number} energy - * @property {boolean} isAway + * @property {number} energy - Deprecated: This property will be removed from the API. + * @property {boolean} isAway - true if your avatar is away (i.e., inactive), false if it is + * active. * - * @property {boolean} centerOfGravityModelEnabled=true - If true then the avatar hips are placed according to the center of - * gravity model that balance the center of gravity over the base of support of the feet. Setting the value false - * will result in the default behaviour where the hips are placed under the head. + * @property {boolean} centerOfGravityModelEnabled=true - If true then the avatar hips are placed according to + * the center of gravity model that balances the center of gravity over the base of support of the feet. Setting the + * value false results in the default behavior where the hips are positioned under the head. * @property {boolean} hmdLeanRecenterEnabled=true - If true then the avatar is re-centered to be under the * head's position. In room-scale VR, this behavior is what causes your avatar to follow your HMD as you walk around * the room. Setting the value false is useful if you want to pin the avatar to a fixed position. @@ -198,8 +210,8 @@ class MyAvatar : public Avatar { * boundaries while teleporting.
* Note: Setting the value has no effect unless Interface is restarted. * - * @property {number} yawSpeed=75 - * @property {number} pitchSpeed=50 + * @property {number} yawSpeed=75 - The mouse X sensitivity value in Settings > General. Read-only. + * @property {number} pitchSpeed=50 - The mouse Y sensitivity value in Settings > General. Read-only. * * @property {boolean} hmdRollControlEnabled=true - If true, the roll angle of your HMD turns your avatar * while flying. @@ -215,13 +227,20 @@ class MyAvatar : public Avatar { * where MyAvatar.sessionUUID is not available (e.g., if not connected to a domain). Note: Likely to be deprecated. * Read-only. * - * @property {number} walkSpeed - * @property {number} walkBackwardSpeed - * @property {number} sprintSpeed - * @property {number} isInSittingState - * @property {MyAvatar.SitStandModelType} userRecenterModel - * @property {boolean} isSitStandStateLocked - * @property {boolean} allowTeleporting + * @property {number} walkSpeed - Adjusts the walk speed of your avatar. + * @property {number} walkBackwardSpeed - Adjusts the walk backward speed of your avatar. + * @property {number} sprintSpeed - Adjusts the sprint speed of your avatar. + * @property {MyAvatar.SitStandModelType} userRecenterModel - Controls avatar leaning and recentering behavior. + * @property {number} isInSittingState - true if your avatar is sitting (avatar leaning is disabled, + * recenntering is enabled), false if it is standing (avatar leaning is enabled, and avatar recenters if it + * leans too far). If userRecenterModel == 2 (i.e., auto) the property value automatically updates as the + * user sits or stands, unless isSitStandStateLocked == true. Setting the property value overrides the + * current siting / standing state, which is updated when the user next sits or stands unless + * isSitStandStateLocked == true. + * @property {boolean} isSitStandStateLocked - true locks the avatar sitting / standing state, i.e., disables + * automatically changing it based on the user sitting or standing. + * @property {boolean} allowTeleporting - true if teleporting is enabled in the Interface settings, + * false if it isn't. Read-only. * * @borrows Avatar.getDomainMinScale as getDomainMinScale * @borrows Avatar.getDomainMaxScale as getDomainMaxScale @@ -353,6 +372,40 @@ class MyAvatar : public Avatar { using TimePoint = Clock::time_point; public: + + /**jsdoc + *

Logical keys that drive your avatar and camera.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0TRANSLATE_XMove the user's avatar in the direction of its x-axis, if the + * camera isn't in independent or mirror modes.
1TRANSLATE_YMove the user's avatar in the direction of its y-axis, if the + * camera isn't in independent or mirror modes.
2TRANSLATE_ZMove the user's avatar in the direction of its z-axis, if the + * camera isn't in independent or mirror modes
3YAWRotate the user's avatar about its y-axis at a rate proportional to the + * control value, if the camera isn't in independent or mirror modes.
4STEP_TRANSLATE_XNo action.
5STEP_TRANSLATE_YNo action.
6STEP_TRANSLATE_ZNo action.
7STEP_YAWRotate the user's avatar about its y-axis in a step increment, if + * the camera isn't in independent or mirror modes.
8PITCHRotate the user's avatar head and attached camera about its negative + * x-axis (i.e., positive values pitch down) at a rate proportional to the control value, if the camera isn't in HMD, + * independent, or mirror modes.
9ZOOMZooms the camera in or out.
10DELTA_YAWRotate the user's avatar about its y-axis by an amount proportional + * to the control value, if the camera isn't in independent or mirror modes.
11DELTA_PITCHRotate the user's avatar head and attached camera about its + * negative x-axis (i.e., positive values pitch down) by an amount proportional to the control value, if the camera + * isn't in HMD, independent, or mirror modes.
+ * @typedef {number} MyAvatar.DriveKeys + */ enum DriveKeys { TRANSLATE_X = 0, TRANSLATE_Y, @@ -371,6 +424,25 @@ public: Q_ENUM(DriveKeys) /**jsdoc + *

Specifies different avatar leaning and recentering behaviors.

+ * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0ForceSitAssumes the user is seated in the real world. Disables avatar + * leaning regardless of what the avatar is doing in the virtual world (i.e., avatar always recenters).
1ForceStandAssumes the user is standing in the real world. Enables avatar + * leaning regardless of what the avatar is doing in the virtual world (i.e. avatar leans, then if leans too far it + * recenters).
2AutoInterface detects when the user is standing or seated in the real world. + * Avatar leaning is disabled when the user is sitting (i.e., avatar always recenters), and avatar leaning is enabled + * when the user is standing (i.e., avatar leans, then if leans too far it recenters).
3DisableHMDLeanBoth avatar leaning and recentering are disabled regardless of + * what the user is doing in the real world and no matter what their avatar is doing in the virtual world. Enables + * the avatar to sit on the floor when the user sits on the floor.
Note: Experimental.
* @typedef {number} MyAvatar.SitStandModelType */ enum SitStandModelType { @@ -399,6 +471,7 @@ public: void setCollisionWithOtherAvatarsFlags() override; /**jsdoc + * Resets the sensor positioning of your HMD (if used) and recenters your avatar body and head. * @function MyAvatar.resetSensorsAndBody */ Q_INVOKABLE void resetSensorsAndBody(); @@ -427,14 +500,16 @@ public: const glm::quat& getHMDSensorOrientation() const { return _hmdSensorOrientation; } /**jsdoc + * Gets the avatar orientation. Suitable for use in QML. * @function MyAvatar.setOrientationVar - * @param {object} newOrientationVar + * @param {object} newOrientationVar - The avatar orientation. */ Q_INVOKABLE void setOrientationVar(const QVariant& newOrientationVar); /**jsdoc + * Gets the avatar orientation. Suitable for use in QML. * @function MyAvatar.getOrientationVar - * @returns {object} + * @returns {object} The avatar orientation. */ Q_INVOKABLE QVariant getOrientationVar() const; @@ -598,74 +673,124 @@ public: // a handler must not remove properties from animStateDictionaryIn, nor change property values that it does not intend to change. // It is not specified in what order multiple handlers are called. /**jsdoc + * Adds an animation state handler function that is invoked just before each animation graph update. More than one + * animation state handler function may be added by calling addAnimationStateHandler multiple times. It is not + * specified in what order multiple handlers are called. + *

The animation state handler function is called with an {@link MyAvatar.AnimStateDictionary|AnimStateDictionary} + * "animStateDictionaryIn" parameter and is expected to return an + * {@link MyAvatar.AnimStateDictionary|AnimStateDictionary} "animStateDictionaryOut" object. The + * animStateDictionaryOut object can be the same object as animStateDictionaryIn, or it can be a + * different object. The animStateDictionaryIn may be shared among multiple handlers and thus may contain + * additional properties specified when adding the different handlers.

+ *

A handler may change a value from animStateDictionaryIn or add different values in the + * animStateDictionaryOut returned. Any property values set in animStateDictionaryOut will + * override those of the internal animation machinery.|null} propertiesList - The list of {@link MyAvatar.AnimStateDictionary|AnimStateDictionary} + * properties that should be included the in parameter that the handler function is called with. If null + * then all properties are included in the call parameter. + * @returns {number} The ID of the animation state handler function if successfully added, undefined if not + * successfully added. + * @example Log all the animation state dictionary parameters for a short while. + * function animStateHandler(dictionary) { + * print("Anim state dictionary: " + JSON.stringify(dictionary)); + * } + * + * var handler = MyAvatar.addAnimationStateHandler(animStateHandler, null); + * + * Script.setTimeout(function () { + * MyAvatar.removeAnimationStateHandler(handler); + * }, 100); */ Q_INVOKABLE QScriptValue addAnimationStateHandler(QScriptValue handler, QScriptValue propertiesList) { return _skeletonModel->getRig().addAnimationStateHandler(handler, propertiesList); } /**jsdoc + * Removes an animation state handler function. * @function MyAvatar.removeAnimationStateHandler - * @param {number} handler + * @param {number} handler - The ID of the animation state handler function to remove. */ // Removes a handler previously added by addAnimationStateHandler. Q_INVOKABLE void removeAnimationStateHandler(QScriptValue handler) { _skeletonModel->getRig().removeAnimationStateHandler(handler); } /**jsdoc + * Gets whether or not you do snap turns in HMD mode. * @function MyAvatar.getSnapTurn - * @returns {boolean} + * @returns {boolean} true if you do snap turns in HMD mode; false if you do smooth turns in HMD + * mode. */ Q_INVOKABLE bool getSnapTurn() const { return _useSnapTurn; } /**jsdoc + * Sets whether your should do snap turns or smooth turns in HMD mode. * @function MyAvatar.setSnapTurn - * @param {boolean} on + * @param {boolean} on - true to do snap turns in HMD mode; false to do smooth turns in HMD mode. */ Q_INVOKABLE void setSnapTurn(bool on) { _useSnapTurn = on; } /**jsdoc + * Sets the avatar's dominant hand. * @function MyAvatar.setDominantHand - * @param {string} hand + * @param {string} hand - The dominant hand: "left" for the left hand or "right" for the right + * hand. Any other value has no effect. */ Q_INVOKABLE void setDominantHand(const QString& hand); /**jsdoc + * Gets the avatar's dominant hand. * @function MyAvatar.getDominantHand - * @returns {string} + * @returns {string} "left" for the left hand, "right" for the right hand. */ Q_INVOKABLE QString getDominantHand() const; /**jsdoc * @function MyAvatar.setHmdAvatarAlignmentType - * @param {string} hand + * @param {string} type - "head" to align your head and your avatar's head, "eyes" to align your + * eyes and your avatar's eyes. + * */ - Q_INVOKABLE void setHmdAvatarAlignmentType(const QString& hand); + Q_INVOKABLE void setHmdAvatarAlignmentType(const QString& type); /**jsdoc + * Gets the HMD alignment for your avatar. * @function MyAvatar.getHmdAvatarAlignmentType - * @returns {string} + * @returns {string} "head" if aligning your head and your avatar's head, "eyes" if aligning your + * eyes and your avatar's eyes. */ Q_INVOKABLE QString getHmdAvatarAlignmentType() const; /**jsdoc + * Sets whether the avatar hips are balanced over the feet or positioned under the head. * @function MyAvatar.setCenterOfGravityModelEnabled - * @param {boolean} enabled + * @param {boolean} enabled - true to balance the hips over the feet, false to position the hips + * under the head. */ Q_INVOKABLE void setCenterOfGravityModelEnabled(bool value) { _centerOfGravityModelEnabled = value; } /**jsdoc + * Gets whether the avatar hips are being balanced over the feet or placed under the head. * @function MyAvatar.getCenterOfGravityModelEnabled - * @returns {boolean} + * @returns {boolean} true if the hips are being balanced over the feet, false if the hips are + * being positioned under the head. */ Q_INVOKABLE bool getCenterOfGravityModelEnabled() const { return _centerOfGravityModelEnabled; } + /**jsdoc + * Sets whether or not the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering + * causes your avatar to follow your HMD as you walk around the room. Disabling recentering is useful if you want to pin + * the avatar to a fixed position. * @function MyAvatar.setHMDLeanRecenterEnabled - * @param {boolean} enabled + * @param {boolean} enabled - true to recenter the avatar under the head as it moves, false to + * disable recentering. */ Q_INVOKABLE void setHMDLeanRecenterEnabled(bool value) { _hmdLeanRecenterEnabled = value; } /**jsdoc + * Gets whether or not the avatar's position updates to recenter the avatar under the head. In room-scale VR, recentering + * causes your avatar to follow your HMD as you walk around the room. * @function MyAvatar.getHMDLeanRecenterEnabled - * @returns {boolean} + * @returns {boolean} true if recentering is enabled, false if not. */ Q_INVOKABLE bool getHMDLeanRecenterEnabled() const { return _hmdLeanRecenterEnabled; } @@ -739,30 +864,42 @@ public: float getDriveKey(DriveKeys key) const; /**jsdoc + * Gets the value of a drive key, regardless of whether or not it is disabled. * @function MyAvatar.getRawDriveKey - * @param {DriveKeys} key - * @returns {number} + * @param {MyAvatar.DriveKeys} key - The drive key. + * @returns {number} The value of the drive key. */ Q_INVOKABLE float getRawDriveKey(DriveKeys key) const; void relayDriveKeysToCharacterController(); /**jsdoc + * Disables the action associated with a drive key. * @function MyAvatar.disableDriveKey - * @param {DriveKeys} key + * @param {MyAvatar.DriveKeys} key - The drive key to disable. + * @example Disable rotating your avatar using the keyboard for a couple of seconds. + * var YAW = 3; + * print("Disable"); + * MyAvatar.disableDriveKey(YAW); + * Script.setTimeout(function () { + * print("Enable"); + * MyAvatar.enableDriveKey(YAW); + * }, 5000); */ Q_INVOKABLE void disableDriveKey(DriveKeys key); /**jsdoc + * Enables the acction associated with a drive key. * @function MyAvatar.enableDriveKey - * @param {DriveKeys} key + * @param {MyAvatar.DriveKeys} key - The drive key to enable. */ Q_INVOKABLE void enableDriveKey(DriveKeys key); /**jsdoc + * Checks whether or not a drive key is disabled. * @function MyAvatar.isDriveKeyDisabled - * @param {DriveKeys} key - * @returns {boolean} + * @param {DriveKeys} key - The drive key to check. + * @returns {boolean} true if the drive key is disabled, false if it isn't. */ Q_INVOKABLE bool isDriveKeyDisabled(DriveKeys key) const; @@ -809,26 +946,32 @@ public: Q_INVOKABLE glm::vec3 getHeadPosition() const { return getHead()->getPosition(); } /**jsdoc + * Gets the yaw of the avatar's head relative to its body. * @function MyAvatar.getHeadFinalYaw - * @returns {number} + * @returns {number} The yaw of the avatar's head, in degrees. */ Q_INVOKABLE float getHeadFinalYaw() const { return getHead()->getFinalYaw(); } /**jsdoc + * Gets the roll of the avatar's head relative to its body. * @function MyAvatar.getHeadFinalRoll - * @returns {number} + * @returns {number} The roll of the avatar's head, in degrees. */ Q_INVOKABLE float getHeadFinalRoll() const { return getHead()->getFinalRoll(); } /**jsdoc + * Gets the pitch of the avatar's head relative to its body. * @function MyAvatar.getHeadFinalPitch - * @returns {number} + * @returns {number} The pitch of the avatar's head, in degrees. */ Q_INVOKABLE float getHeadFinalPitch() const { return getHead()->getFinalPitch(); } /**jsdoc + * If a face tracker is connected and being used, gets the estimated pitch of the user's head scaled such that the avatar + * looks at the edge of the view frustum when the user looks at the edge of their screen. * @function MyAvatar.getHeadDeltaPitch - * @returns {number} + * @returns {number} The pitch that the avatar's head should be if a face tracker is connected and being used, otherwise + * 0, in degrees. */ Q_INVOKABLE float getHeadDeltaPitch() const { return getHead()->getDeltaPitch(); } @@ -845,21 +988,27 @@ public: /**jsdoc * Gets the position of the avatar your avatar is currently looking at. * @function MyAvatar.getTargetAvatarPosition - * @returns {Vec3} The position of the avatar your avatar is currently looking at. + * @returns {Vec3} The position of the avatar beeing looked at. * @example Report the position of the avatar you're currently looking at. * print(JSON.stringify(MyAvatar.getTargetAvatarPosition())); */ + // FIXME: If not looking at an avatar, the most recently looked-at position is returned. This should be fixed to return + // undefined or {NaN, NaN, NaN} or similar. Q_INVOKABLE glm::vec3 getTargetAvatarPosition() const { return _targetAvatarPosition; } /**jsdoc + * Gets information on the avatar your avatar is currently looking at. * @function MyAvatar.getTargetAvatar - * @returns {AvatarData} + * @returns {AvatarData} Information on the avatar being looked at. */ + // FIXME: The return type doesn't have a conversion to a script value so the function always returns undefined in + // JavaScript. Note: When fixed, JSDoc is needed for the return type. Q_INVOKABLE ScriptAvatarData* getTargetAvatar() const; /**jsdoc - * Gets the position of the avatar's left hand as positioned by a hand controller (e.g., Oculus Touch or Vive).
+ * Gets the position of the avatar's left hand, relative to the avatar, as positioned by a hand controller (e.g., Oculus + * Touch or Vive). *

Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints * for hand animation.)

* @function MyAvatar.getLeftHandPosition @@ -871,7 +1020,8 @@ public: Q_INVOKABLE glm::vec3 getLeftHandPosition() const; /**jsdoc - * Gets the position of the avatar's right hand as positioned by a hand controller (e.g., Oculus Touch or Vive).
+ * Gets the position of the avatar's right hand, relative to the avatar, as positioned by a hand controller (e.g., Oculus + * Touch or Vive). *

Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints * for hand animation.)

* @function MyAvatar.getRightHandPosition @@ -883,26 +1033,32 @@ public: Q_INVOKABLE glm::vec3 getRightHandPosition() const; /**jsdoc + * Gets the position 0.3m in front of the left hand's position in the direction along the palm, in avatar coordinates, as + * positioned by a hand controller. * @function MyAvatar.getLeftHandTipPosition - * @returns {Vec3} + * @returns {Vec3} The position 0.3m in front of the left hand's position in the direction along the palm, in avatar + * coordinates. If the hand isn't being positioned by a controller, {@link Vec3(0)|Vec3.ZERO} is returned. */ Q_INVOKABLE glm::vec3 getLeftHandTipPosition() const; /**jsdoc + * Gets the position 0.3m in front of the right hand's position in the direction along the palm, in avatar coordinates, as + * positioned by a hand controller. * @function MyAvatar.getRightHandTipPosition - * @returns {Vec3} + * @returns {Vec3} The position 0.3m in front of the right hand's position in the direction along the palm, in avatar + * coordinates. If the hand isn't being positioned by a controller, {@link Vec3(0)|Vec3.ZERO} is returned. */ Q_INVOKABLE glm::vec3 getRightHandTipPosition() const; /**jsdoc * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a - * hand controller (e.g., Oculus Touch or Vive).
+ * hand controller (e.g., Oculus Touch or Vive). *

Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints * for hand animation.) If you are using the Leap Motion, the return value's valid property will be * false and any pose values returned will not be meaningful.

* @function MyAvatar.getLeftHandPose - * @returns {Pose} + * @returns {Pose} The pose of the avatar's left hand, relative to the avatar, as positioned by a hand controller. * @example Report the pose of your avatar's left hand. * print(JSON.stringify(MyAvatar.getLeftHandPose())); */ @@ -910,26 +1066,38 @@ public: /**jsdoc * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a - * hand controller (e.g., Oculus Touch or Vive).
+ * hand controller (e.g., Oculus Touch or Vive). *

Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints * for hand animation.) If you are using the Leap Motion, the return value's valid property will be * false and any pose values returned will not be meaningful.

* @function MyAvatar.getRightHandPose - * @returns {Pose} + * @returns {Pose} The pose of the avatar's right hand, relative to the avatar, as positioned by a hand controller. * @example Report the pose of your avatar's right hand. * print(JSON.stringify(MyAvatar.getRightHandPose())); */ Q_INVOKABLE controller::Pose getRightHandPose() const; /**jsdoc + * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand, relative to the avatar, as + * positioned by a hand controller (e.g., Oculus Touch or Vive), and translated 0.3m along the palm. + *

Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints + * for hand animation.) If you are using the Leap Motion, the return value's valid property will be + * false and any pose values returned will not be meaningful.

* @function MyAvatar.getLeftHandTipPose - * @returns {Pose} + * @returns {Pose} The pose of the avatar's left hand, relative to the avatar, as positioned by a hand controller, and + * translated 0.3m along the palm. */ Q_INVOKABLE controller::Pose getLeftHandTipPose() const; /**jsdoc + * Gets the pose (position, rotation, velocity, and angular velocity) of the avatar's right hand, relative to the avatar, as + * positioned by a hand controller (e.g., Oculus Touch or Vive), and translated 0.3m along the palm. + *

Note: The Leap Motion isn't part of the hand controller input system. (Instead, it manipulates the avatar's joints + * for hand animation.) If you are using the Leap Motion, the return value's valid property will be + * false and any pose values returned will not be meaningful.

* @function MyAvatar.getRightHandTipPose - * @returns {Pose} + * @returns {Pose} The pose of the avatar's right hand, relative to the avatar, as positioned by a hand controller, and + * translated 0.3m along the palm. */ Q_INVOKABLE controller::Pose getRightHandTipPose() const; @@ -952,33 +1120,39 @@ public: virtual void clearJointsData() override; /**jsdoc + * Sets and locks a joint's position and orientation. + *

Note: Only works on the hips joint.

* @function MyAvatar.pinJoint - * @param {number} index - * @param {Vec3} position - * @param {Quat} orientation - * @returns {boolean} + * @param {number} index - The index of the joint. + * @param {Vec3} position - The position of the joint in world coordinates. + * @param {Quat} orientation - The orientation of the joint in world coordinates. + * @returns {boolean} true if the joint was pinned, false if it wasn't. */ Q_INVOKABLE bool pinJoint(int index, const glm::vec3& position, const glm::quat& orientation); bool isJointPinned(int index); /**jsdoc + * Clears a lock on a joint's position and orientation, as set by {@link MyAvatar.pinJoint|pinJoint}. + *

Note: Only works on the hips joint.

* @function MyAvatar.clearPinOnJoint - * @param {number} index - * @returns {boolean} + * @param {number} index - The index of the joint. + * @returns {boolean} true if the joint was unpinned, false if it wasn't. */ Q_INVOKABLE bool clearPinOnJoint(int index); /**jsdoc + * Gets the maximum error distance from the most recent inverse kinematics (IK) solution. * @function MyAvatar.getIKErrorOnLastSolve - * @returns {number} + * @returns {number} The maximum IK error distance. */ Q_INVOKABLE float getIKErrorOnLastSolve() const; /**jsdoc + * Changes the user's avatar and associated descriptive name. * @function MyAvatar.useFullAvatarURL - * @param {string} fullAvatarURL - * @param {string} [modelName=""] + * @param {string} fullAvatarURL - The URL of the avatar's .fst file. + * @param {string} [modelName=""] - Descriptive name of the avatar. */ Q_INVOKABLE void useFullAvatarURL(const QUrl& fullAvatarURL, const QString& modelName = QString()); @@ -1065,7 +1239,7 @@ public: /**jsdoc * Gets the list of avatar entities and their properties. * @function MyAvatar.getAvatarEntitiesVariant - * @returns {MyAvatar.AvatarEntityData[]} + * @returns {MyAvatar.AvatarEntityData[]} The list of avatar entities and their properties. */ Q_INVOKABLE QVariantList getAvatarEntitiesVariant(); @@ -1141,60 +1315,76 @@ public: */ Q_INVOKABLE bool getFlyingHMDPref(); - /**jsdoc + * Gets the target scale of the avatar. The target scale is the desired scale of the avatar without any restrictions on + * permissible scale values imposed by the domain. * @function MyAvatar.getAvatarScale - * @returns {number} + * @returns {number} The target scale for the avatar, range 0.005 – 1000.0. */ Q_INVOKABLE float getAvatarScale(); /**jsdoc + * Sets the target scale of the avatar. The target scale is the desired scale of the avatar without any restrictions on + * permissible scale values imposed by the domain. * @function MyAvatar.setAvatarScale - * @param {number} scale + * @param {number} scale - The target scale for the avatar, range 0.005 – 1000.0. */ Q_INVOKABLE void setAvatarScale(float scale); - /**jsdoc + * Sets whether or not the avatar should collide with entities. + *

Note: A false value won't disable collisions if the avatar is in a zone that disallows + * collisionless avatars, however the false value will be set so that collisions are disabled as soon as the + * avatar moves to a position where collisionless avatars are allowed. * @function MyAvatar.setCollisionsEnabled - * @param {boolean} enabled + * @param {boolean} enabled - true to enable the avatar to collide with entities, false to + * disable. */ Q_INVOKABLE void setCollisionsEnabled(bool enabled); /**jsdoc + * Gets whether or not the avatar will currently collide with entities. + *

Note: The avatar will always collide with entities if in a zone that disallows collisionless avatars. * @function MyAvatar.getCollisionsEnabled - * @returns {boolean} + * @returns {boolean} true if the avatar will currently collide with entities, false if it won't. */ Q_INVOKABLE bool getCollisionsEnabled(); /**jsdoc + * Sets whether or not the avatar should collide with other avatars. * @function MyAvatar.setOtherAvatarsCollisionsEnabled - * @param {boolean} enabled + * @param {boolean} enabled - true to enable the avatar to collide with other avatars, false + * to disable. */ Q_INVOKABLE void setOtherAvatarsCollisionsEnabled(bool enabled); /**jsdoc + * Gets whether or not the avatar will collide with other avatars. * @function MyAvatar.getOtherAvatarsCollisionsEnabled - * @returns {boolean} + * @returns {boolean} true if the avatar will collide with other avatars, false if it won't. */ Q_INVOKABLE bool getOtherAvatarsCollisionsEnabled(); /**jsdoc + * Gets the avatar's collision capsule: a cylinder with hemispherical ends that approximates the extents or the avatar. + *

Warning: The values returned are in world coordinates but aren't necessarily up to date with the + * avatar's current position.

* @function MyAvatar.getCollisionCapsule - * @returns {object} + * @returns {MyAvatar.CollisionCapsule} The avatar's collision capsule. */ Q_INVOKABLE QVariantMap getCollisionCapsule() const; /**jsdoc * @function MyAvatar.setCharacterControllerEnabled - * @param {boolean} enabled + * @param {boolean} enabled - true to enable the avatar to collide with entities, false to + * disable. * @deprecated Use {@link MyAvatar.setCollisionsEnabled} instead. */ Q_INVOKABLE void setCharacterControllerEnabled(bool enabled); // deprecated /**jsdoc * @function MyAvatar.getCharacterControllerEnabled - * @returns {boolean} + * @returns {boolean} true if the avatar will currently collide with entities, false if it won't. * @deprecated Use {@link MyAvatar.getCollisionsEnabled} instead. */ Q_INVOKABLE bool getCharacterControllerEnabled(); // deprecated @@ -1248,16 +1438,22 @@ public: glm::mat4 deriveBodyUsingCgModel(); /**jsdoc + * Tests whether a vector is pointing in the general direction of the avatar's "up" direction (i.e., dot product of vectors + * is > 0). * @function MyAvatar.isUp - * @param {Vec3} direction - * @returns {boolean} + * @param {Vec3} direction - The vector to test. + * @returns {boolean} true if the direction vector is pointing generally in the direction of the avatar's "up" + * direction. */ Q_INVOKABLE bool isUp(const glm::vec3& direction) { return glm::dot(direction, _worldUpDirection) > 0.0f; }; // true iff direction points up wrt avatar's definition of up. /**jsdoc + * Tests whether a vector is pointing in the general direction of the avatar's "down" direction (i.e., dot product of + * vectors is < 0). * @function MyAvatar.isDown - * @param {Vec3} direction - * @returns {boolean} + * @param {Vec3} direction - The vector to test. + * @returns {boolean} true if the direction vector is pointing generally in the direction of the avatar's + * "down" direction. */ Q_INVOKABLE bool isDown(const glm::vec3& direction) { return glm::dot(direction, _worldUpDirection) < 0.0f; }; @@ -1326,14 +1522,14 @@ public: * Gets the avatar entities as binary data. * @function MyAvatar.getAvatarEntityData * @override - * @returns {AvatarEntityMap} + * @returns {AvatarEntityMap} The avatar entities as binary data. */ AvatarEntityMap getAvatarEntityData() const override; /**jsdoc * Sets the avatar entities from binary data. * @function MyAvatar.setAvatarEntityData - * @param {AvatarEntityMap} avatarEntityData + * @param {AvatarEntityMap} avatarEntityData - The avatar entities as binary data. */ void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; @@ -1345,8 +1541,7 @@ public: void avatarEntityDataToJson(QJsonObject& root) const override; /**jsdoc - * @function MyAvatar.sendAvatarDataPacket - * @param {boolean} sendAll + * @comment Uses the base class's JSDoc. */ int sendAvatarDataPacket(bool sendAll = false) override; @@ -1386,18 +1581,22 @@ public slots: /**jsdoc * @function MyAvatar.animGraphLoaded + * @deprecated This function is deprecated and will be removed. */ void animGraphLoaded(); /**jsdoc + * Sets the amount of gravity applied to the avatar in the y-axis direction. (Negative values are downward.) * @function MyAvatar.setGravity - * @param {number} gravity + * @param {number} gravity - The amount of gravity to be applied to the avatar, in m/s2. */ void setGravity(float gravity); /**jsdoc + * Sets the amount of gravity applied to the avatar in the y-axis direction. (Negative values are downward.) The default + * value is -5 m/s2. * @function MyAvatar.getGravity - * @returns {number} + * @returns {number} The amount of gravity currently applied to the avatar, in m/s2. */ float getGravity(); @@ -1428,125 +1627,149 @@ public slots: bool hasOrientation = false, const glm::quat& newOrientation = glm::quat(), bool shouldFaceLocation = false, bool withSafeLanding = true); /**jsdoc + * Moves the avatar to a new position and (optional) orientation in the domain. * @function MyAvatar.goToLocation - * @param {object} properties + * @param {MyAvatar.GoToProperties} target - The goto target. */ void goToLocation(const QVariant& properties); /**jsdoc + * Moves the avatar to a new position and then enables collisions. * @function MyAvatar.goToLocationAndEnableCollisions - * @param {Vec3} position + * @param {Vec3} position - The new position for the avatar, in world coordinates. */ void goToLocationAndEnableCollisions(const glm::vec3& newPosition); /**jsdoc * @function MyAvatar.safeLanding - * @param {Vec3} position - * @returns {boolean} + * @param {Vec3} position -The new position for the avatar, in world coordinates. + * @returns {boolean} true if the avatar was moved, false if it wasn't. + * @deprecated This function is deprecated and will be removed. */ bool safeLanding(const glm::vec3& position); /**jsdoc * @function MyAvatar.restrictScaleFromDomainSettings - * @param {object} domainSettingsObject + * @param {object} domainSettings - Domain settings. + * @deprecated This function is deprecated and will be removed. */ void restrictScaleFromDomainSettings(const QJsonObject& domainSettingsObject); /**jsdoc * @function MyAvatar.clearScaleRestriction + * @deprecated This function is deprecated and will be removed from the API. */ void clearScaleRestriction(); /**jsdoc + * Adds a thrust to your avatar's current thrust, to be applied for a short while. * @function MyAvatar.addThrust - * @param {Vec3} thrust + * @param {Vec3} thrust - The thrust direction and magnitude. + * @deprecated Use {@link MyAvatar|MyAvatar.motorVelocity} and related properties instead. */ // Set/Get update the thrust that will move the avatar around void addThrust(glm::vec3 newThrust) { _thrust += newThrust; }; /**jsdoc + * Gets the thrust currently being applied to your avatar. * @function MyAvatar.getThrust - * @returns {vec3} + * @returns {Vec3} The thrust currently being applied to your avatar. + * @deprecated Use {@link MyAvatar|MyAvatar.motorVelocity} and related properties instead. */ glm::vec3 getThrust() { return _thrust; }; /**jsdoc + * Sets the thrust to be applied to your avatar for a short while. * @function MyAvatar.setThrust - * @param {Vec3} thrust + * @param {Vec3} thrust - The thrust direction and magnitude. + * @deprecated Use {@link MyAvatar|MyAvatar.motorVelocity} and related properties instead. */ void setThrust(glm::vec3 newThrust) { _thrust = newThrust; } /**jsdoc + * Updates avatar motion behavior from the Developer > Avatar > Enable Default Motor Control and Enable Scripted + * Motor Control menu items. * @function MyAvatar.updateMotionBehaviorFromMenu */ Q_INVOKABLE void updateMotionBehaviorFromMenu(); /**jsdoc * @function MyAvatar.setToggleHips - * @param {boolean} enabled + * @param {boolean} enabled - Enabled. + * @deprecated This function is deprecated and will be removed. */ void setToggleHips(bool followHead); /**jsdoc + * Displays base of support of feet debug graphics. * @function MyAvatar.setEnableDebugDrawBaseOfSupport - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawBaseOfSupport(bool isEnabled); /**jsdoc + * Displays default pose debug graphics. * @function MyAvatar.setEnableDebugDrawDefaultPose - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawDefaultPose(bool isEnabled); /**jsdoc + * Displays animation debug graphics. * @function MyAvatar.setEnableDebugDrawAnimPose - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawAnimPose(bool isEnabled); /**jsdoc + * Displays position debug graphics. * @function MyAvatar.setEnableDebugDrawPosition - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawPosition(bool isEnabled); /**jsdoc + * Displays controller hand target debug graphics. * @function MyAvatar.setEnableDebugDrawHandControllers - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawHandControllers(bool isEnabled); /**jsdoc + * Displays sensor-to-world matrix debug graphics. * @function MyAvatar.setEnableDebugDrawSensorToWorldMatrix - * @param {boolean} enabled + * @param {boolean} enable - true to show the debug graphics, false to hide. */ void setEnableDebugDrawSensorToWorldMatrix(bool isEnabled); /**jsdoc + * Displays inverse kinematics targets debug graphics. * @function MyAvatar.setEnableDebugDrawIKTargets - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawIKTargets(bool isEnabled); /**jsdoc + * Displays inverse kinematics constraints debug graphics. * @function MyAvatar.setEnableDebugDrawIKConstraints - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawIKConstraints(bool isEnabled); /**jsdoc + * Displays inverse kinematics chains debug graphics. * @function MyAvatar.setEnableDebugDrawIKChains - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawIKChains(bool isEnabled); /**jsdoc + * Displays detailed collision debug graphics. * @function MyAvatar.setEnableDebugDrawDetailedCollision - * @param {boolean} enabled + * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawDetailedCollision(bool isEnabled); @@ -1570,13 +1793,15 @@ public slots: /**jsdoc * @function MyAvatar.sanitizeAvatarEntityProperties + * @param {EntityItemProperties} properties - Properties. + * @deprecated This function is deprecated and will be removed. */ void sanitizeAvatarEntityProperties(EntityItemProperties& properties) const; /**jsdoc - * Sets whether or not your avatar mesh is visible. + * Sets whether or not your avatar mesh is visible to you. * @function MyAvatar.setEnableMeshVisible - * @param {boolean} visible - true to set your avatar mesh visible; false to set it invisible. + * @param {boolean} enabled - true to show your avatar mesh, false to hide. * @example Make your avatar invisible for 10s. * MyAvatar.setEnableMeshVisible(false); * Script.setTimeout(function () { @@ -1586,57 +1811,76 @@ public slots: virtual void setEnableMeshVisible(bool isEnabled) override; /**jsdoc + * Sets whether or not inverse kinematics (IK) for your avatar. * @function MyAvatar.setEnableInverseKinematics - * @param {boolean} enabled + * @param {boolean} enabled - true to enable IK, false to disable. */ void setEnableInverseKinematics(bool isEnabled); /**jsdoc + * Gets the URL of the override animation graph. + *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for + * information on animation graphs.

* @function MyAvatar.getAnimGraphOverrideUrl - * @returns {string} + * @returns {string} The URL of the override animation graph. "" if there is no override animation graph. */ QUrl getAnimGraphOverrideUrl() const; // thread-safe /**jsdoc + * Sets the animation graph to use in preference to the default animation graph. + *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for + * information on animation graphs.

* @function MyAvatar.setAnimGraphOverrideUrl - * @param {string} url + * @param {string} url - The URL of the animation graph to use. Set to "" to clear an override. */ void setAnimGraphOverrideUrl(QUrl value); // thread-safe /**jsdoc + * Gets the URL of animation graph that's currently being used for avatar animations. + *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for + * information on animation graphs.

* @function MyAvatar.getAnimGraphUrl - * @returns {string} + * @returns {string} The URL of the current animation graph. */ QUrl getAnimGraphUrl() const; // thread-safe /**jsdoc + * Sets the current animation graph to use for avatar animations and makes it the default. + *

See {@link https://docs.highfidelity.com/create/avatars/custom-animations.html|Custom Avatar Animations} for + * information on animation graphs.

* @function MyAvatar.setAnimGraphUrl - * @param {string} url + * @param {string} url - The URL of the animation graph to use. */ void setAnimGraphUrl(const QUrl& url); // thread-safe /**jsdoc + * Gets your listening position for spatialized audio. The position depends on the value of the + * {@link Myavatar|audioListenerMode} property. * @function MyAvatar.getPositionForAudio - * @returns {Vec3} + * @returns {Vec3} Your listening position. */ glm::vec3 getPositionForAudio(); /**jsdoc + * Gets the orientation of your listening position for spatialized audio. The orientation depends on the value of the + * {@link Myavatar|audioListenerMode} property. * @function MyAvatar.getOrientationForAudio - * @returns {Quat} + * @returns {Quat} The orientation of your listening position. */ glm::quat getOrientationForAudio(); /**jsdoc * @function MyAvatar.setModelScale - * @param {number} scale + * @param {number} scale - The scale. + * @deprecated This function is deprecated and will be removed. */ virtual void setModelScale(float scale) override; signals: /**jsdoc + * Triggered when the {@link MyAvatar|audioListenerMode} property value changes. * @function MyAvatar.audioListenerModeChanged * @returns {Signal} */ @@ -1645,12 +1889,14 @@ signals: /**jsdoc * @function MyAvatar.transformChanged * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ void transformChanged(); /**jsdoc + * Triggered when the {@link MyAvatar|collisionSoundURL} property value changes. * @function MyAvatar.newCollisionSoundURL - * @param {string} url + * @param {string} url - The URL of the new collision sound. * @returns {Signal} */ void newCollisionSoundURL(const QUrl& url); @@ -1658,7 +1904,7 @@ signals: /**jsdoc * Triggered when the avatar collides with an entity. * @function MyAvatar.collisionWithEntity - * @param {Collision} collision + * @param {Collision} collision - Details of the collision. * @returns {Signal} * @example Report each time your avatar collides with an entity. * MyAvatar.collisionWithEntity.connect(function (collision) { @@ -1686,21 +1932,23 @@ signals: void otherAvatarsCollisionsEnabledChanged(bool enabled); /**jsdoc - * Triggered when the avatar's animation changes. + * Triggered when the avatar's animation graph URL changes. * @function MyAvatar.animGraphUrlChanged - * @param {url} url - The URL of the new animation. + * @param {string} url - The URL of the new animation graph. * @returns {Signal} */ void animGraphUrlChanged(const QUrl& url); /**jsdoc * @function MyAvatar.energyChanged - * @param {number} energy + * @param {number} energy - Avatar energy. * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ void energyChanged(float newEnergy); /**jsdoc + * Triggered when the avatar has been moved to a new position by one of the MyAvatar "goTo" functions. * @function MyAvatar.positionGoneTo * @returns {Signal} */ @@ -1708,57 +1956,78 @@ signals: void positionGoneTo(); /**jsdoc + * Triggered when the avatar's model finishes loading. * @function MyAvatar.onLoadComplete * @returns {Signal} */ void onLoadComplete(); /**jsdoc + * Triggered when your avatar changes from being active to being away. * @function MyAvatar.wentAway * @returns {Signal} + * @example Report when your avatar goes away. + * MyAvatar.wentAway.connect(function () { + * print("My avatar went away"); + * }); + * // In desktop mode, pres the Esc key to go away. */ void wentAway(); /**jsdoc + * Triggered when your avatar changes from being away to being active. * @function MyAvatar.wentActive * @returns {Signal} */ void wentActive(); /**jsdoc + * Triggered when the avatar's model (i.e., {@link MyAvatar|skeletonModelURL} property value) is changed. + *

Synonym of {@link MyAvatar.skeletonModelURLChanged|skeletonModelURLChanged}.

* @function MyAvatar.skeletonChanged * @returns {Signal} */ void skeletonChanged(); /**jsdoc + * Triggered when the avatar's dominant hand changes. * @function MyAvatar.dominantHandChanged - * @param {string} hand + * @param {string} hand - The dominant hand: "left" for the left hand, "right" for the right hand. * @returns {Signal} */ void dominantHandChanged(const QString& hand); /**jsdoc + * Triggered when the HMD alignment for your avatar changes. * @function MyAvatar.hmdAvatarAlignmentTypeChanged - * @param {string} type + * @param {string} type - "head" if aligning your head and your avatar's head, "eyes" if aligning + * your eyes and your avatar's eyes. * @returns {Signal} */ void hmdAvatarAlignmentTypeChanged(const QString& type); /**jsdoc + * Triggered when the avatar's sensorToWorldScale property value changes. * @function MyAvatar.sensorToWorldScaleChanged - * @param {number} scale + * @param {number} scale - The scale that transforms dimensions in the user's real world to the avatar's size in the virtual + * world. * @returns {Signal} */ void sensorToWorldScaleChanged(float sensorToWorldScale); /**jsdoc + * Triggered when the a model is attached to or detached from one of the avatar's joints using one of + * {@link MyAvatar.attach|attach}, {@link MyAvatar.detachOne|detachOne}, {@link MyAvatar.detachAll|detachAll}, or + * {@link MyAvatar.setAttachmentData|setAttachmentData}. * @function MyAvatar.attachmentsChanged * @returns {Signal} + * @deprecated Use avatar entities instead. */ void attachmentsChanged(); /**jsdoc + * Triggered when the avatar's size changes. This can be due to the user changing the size of their avatar or the domain + * limiting the size of their avatar. * @function MyAvatar.scaleChanged * @returns {Signal} */ diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 11940ad76a..aedfcedf89 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -201,16 +201,24 @@ public: virtual QStringList getJointNames() const override; /**jsdoc + * Gets the default rotation of a joint (in the current avatar) relative to its parent. + *

For information on the joint hierarchy used, see + * Avatar Standards.

* @function MyAvatar.getDefaultJointRotation - * @param {number} index - * @returns {Quat} + * @param {number} index - The joint index. + * @returns {Quat} The default rotation of the joint if the joint index is valid, otherwise {@link Quat(0)|Quat.IDENTITY}. */ Q_INVOKABLE virtual glm::quat getDefaultJointRotation(int index) const; /**jsdoc + * Gets the default translation of a joint (in the current avatar) relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

For information on the joint hierarchy used, see + * Avatar Standards.

* @function MyAvatar.getDefaultJointTranslation - * @param {number} index - * @returns {Vec3} + * @param {number} index - The joint index. + * @returns {Vec3} The default translation of the joint (in model coordinates) if the joint index is valid, otherwise + * {@link Vec3(0)|Vec3.ZERO}. */ Q_INVOKABLE virtual glm::vec3 getDefaultJointTranslation(int index) const; @@ -261,50 +269,62 @@ public: // world-space to avatar-space rigconversion functions /**jsdoc + * Transforms a position in world coordinates to a position in a joint's coordinates, or avatar coordinates if no joint is + * specified. * @function MyAvatar.worldToJointPoint - * @param {Vec3} position - * @param {number} [jointIndex=-1] - * @returns {Vec3} + * @param {Vec3} position - The position in world coordinates. + * @param {number} [jointIndex=-1] - The index of the joint. + * @returns {Vec3} The position in the joint's coordinate system, or avatar coordinate system if no joint is specified. */ Q_INVOKABLE glm::vec3 worldToJointPoint(const glm::vec3& position, const int jointIndex = -1) const; /**jsdoc + * Transforms a direction in world coordinates to a direction in a joint's coordinates, or avatar coordinates if no joint + * is specified. * @function MyAvatar.worldToJointDirection - * @param {Vec3} direction - * @param {number} [jointIndex=-1] - * @returns {Vec3} + * @param {Vec3} direction - The direction in world coordinates. + * @param {number} [jointIndex=-1] - The index of the joint. + * @returns {Vec3} The direction in the joint's coordinate system, or avatar coordinate system if no joint is specified. */ Q_INVOKABLE glm::vec3 worldToJointDirection(const glm::vec3& direction, const int jointIndex = -1) const; /**jsdoc + * Transforms a rotation in world coordinates to a rotation in a joint's coordinates, or avatar coordinates if no joint is + * specified. * @function MyAvatar.worldToJointRotation - * @param {Quat} rotation - * @param {number} [jointIndex=-1] - * @returns {Quat} + * @param {Quat} rotation - The rotation in world coordinates. + * @param {number} [jointIndex=-1] - The index of the joint. + * @returns {Quat} The rotation in the joint's coordinate system, or avatar coordinate system if no joint is specified. */ Q_INVOKABLE glm::quat worldToJointRotation(const glm::quat& rotation, const int jointIndex = -1) const; /**jsdoc + * Transforms a position in a joint's coordinates, or avatar coordinates if no joint is specified, to a position in world + * coordinates. * @function MyAvatar.jointToWorldPoint - * @param {vec3} position - * @param {number} [jointIndex=-1] - * @returns {Vec3} + * @param {Vec3} position - The position in joint coordinates, or avatar coordinates if no joint is specified. + * @param {number} [jointIndex=-1] - The index of the joint. + * @returns {Vec3} The position in world coordinates. */ Q_INVOKABLE glm::vec3 jointToWorldPoint(const glm::vec3& position, const int jointIndex = -1) const; /**jsdoc + * Transforms a direction in a joint's coordinates, or avatar coordinates if no joint is specified, to a direction in world + * coordinates. * @function MyAvatar.jointToWorldDirection - * @param {Vec3} direction - * @param {number} [jointIndex=-1] - * @returns {Vec3} + * @param {Vec3} direction - The direction in joint coordinates, or avatar coordinates if no joint is specified. + * @param {number} [jointIndex=-1] - The index of the joint. + * @returns {Vec3} The direction in world coordinates. */ Q_INVOKABLE glm::vec3 jointToWorldDirection(const glm::vec3& direction, const int jointIndex = -1) const; /**jsdoc + * Transforms a rotation in a joint's coordinates, or avatar coordinates if no joint is specified, to a rotation in world + * coordinates. * @function MyAvatar.jointToWorldRotation - * @param {Quat} rotation - * @param {number} [jointIndex=-1] - * @returns {Quat} + * @param {Quat} rotation - The rotation in joint coordinates, or avatar coordinates if no joint is specified. + * @param {number} [jointIndex=-1] - The index of the joint. + * @returns {Quat} The rotation in world coordinates. */ Q_INVOKABLE glm::quat jointToWorldRotation(const glm::quat& rotation, const int jointIndex = -1) const; @@ -375,8 +395,9 @@ public: Q_INVOKABLE glm::vec3 getNeckPosition() const; /**jsdoc + * Gets the current acceleration of the avatar. * @function MyAvatar.getAcceleration - * @returns {Vec3} + * @returns {Vec3} The current acceleration of the avatar. */ Q_INVOKABLE glm::vec3 getAcceleration() const { return _acceleration; } @@ -410,29 +431,37 @@ public: void setOrientationViaScript(const glm::quat& orientation) override; /**jsdoc + * Gets the ID of the entity of avatar that the avatar is parented to. * @function MyAvatar.getParentID - * @returns {Uuid} + * @returns {Uuid} The ID of the entity or avatar that the avatar is parented to. {@link Uuid|Uuid.NULL} if not parented. */ // This calls through to the SpatiallyNestable versions, but is here to expose these to JavaScript. Q_INVOKABLE virtual const QUuid getParentID() const override { return SpatiallyNestable::getParentID(); } /**jsdoc + * Sets the ID of the entity of avatar that the avatar is parented to. * @function MyAvatar.setParentID - * @param {Uuid} parentID + * @param {Uuid} parentID - The ID of the entity or avatar that the avatar should be parented to. Set to + * {@link Uuid|Uuid.NULL} to unparent. */ // This calls through to the SpatiallyNestable versions, but is here to expose these to JavaScript. Q_INVOKABLE virtual void setParentID(const QUuid& parentID) override; /**jsdoc + * Gets the joint of the entity or avatar that the avatar is parented to. * @function MyAvatar.getParentJointIndex - * @returns {number} + * @returns {number} The joint of the entity or avatar that the avatar is parented to. 65535 or + * -1 if parented to the entity or avatar's position and orientation rather than a joint. */ // This calls through to the SpatiallyNestable versions, but is here to expose these to JavaScript. Q_INVOKABLE virtual quint16 getParentJointIndex() const override { return SpatiallyNestable::getParentJointIndex(); } /**jsdoc + * sets the joint of the entity or avatar that the avatar is parented to. * @function MyAvatar.setParentJointIndex - * @param {number} parentJointIndex + * @param {number} parentJointIndex - he joint of the entity or avatar that the avatar should be parented to. Use + * 65535 or -1 to parent to the entity or avatar's position and orientation rather than a + * joint. */ // This calls through to the SpatiallyNestable versions, but is here to expose these to JavaScript. Q_INVOKABLE virtual void setParentJointIndex(quint16 parentJointIndex) override; @@ -466,8 +495,9 @@ public: /**jsdoc * @function MyAvatar.getSimulationRate - * @param {string} [rateName=""] - * @returns {number} + * @param {string} [rateName=""] - Rate name. + * @returns {number} Simulation rate. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE float getSimulationRate(const QString& rateName = QString("")) const; @@ -522,8 +552,10 @@ public: signals: /**jsdoc + * Triggered when the avatar's target scale is changed. The target scale is the desired scale of the avatar without any + * restrictions on permissible scale values imposed by the domain. * @function MyAvatar.targetScaleChanged - * @param {number} targetScale + * @param {number} targetScale - The avatar's target scale. * @returns Signal */ void targetScaleChanged(float targetScale); @@ -572,6 +604,7 @@ public slots: /**jsdoc * @function MyAvatar.setModelURLFinished * @param {boolean} success + * @deprecated This function is deprecated and will be removed. */ // hooked up to Model::setURLFinished signal void setModelURLFinished(bool success); diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index 614858a77d..79085e05ba 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -1069,13 +1069,14 @@ void pickRayFromScriptValue(const QScriptValue& object, PickRay& pickRay) { } /**jsdoc + * Details of a collision between avatars and entities. * @typedef {object} Collision * @property {ContactEventType} type - The contact type of the collision event. - * @property {Uuid} idA - The ID of one of the entities in the collision. - * @property {Uuid} idB - The ID of the other of the entities in the collision. - * @property {Vec3} penetration - The amount of penetration between the two entities. + * @property {Uuid} idA - The ID of one of the avatars or entities in the collision. + * @property {Uuid} idB - The ID of the other of the avatars or entities in the collision. + * @property {Vec3} penetration - The amount of penetration between the two items. * @property {Vec3} contactPoint - The point of contact. - * @property {Vec3} velocityChange - The change in relative velocity of the two entities, in m/s. + * @property {Vec3} velocityChange - The change in relative velocity of the two items, in m/s. */ QScriptValue collisionToScriptValue(QScriptEngine* engine, const Collision& collision) { QScriptValue obj = engine->newObject();