From 50a1e07ed275fec230f771663bea8536b81317bb Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 18 Feb 2019 18:32:49 +1300 Subject: [PATCH 01/21] Stub missing MyAvatar, Avatar, and Agent functions and properties JSDoc --- .../src/avatars/ScriptableAvatar.h | 3 + interface/src/avatar/MyAvatar.h | 76 ++++++++++++++----- .../src/avatars-renderer/Avatar.h | 6 ++ 3 files changed, 68 insertions(+), 17 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index e93be897d5..4562ad6134 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -213,6 +213,9 @@ public: Q_INVOKABLE void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData) override; public slots: + /**jsdoc + * @function MyAvatar.update + */ void update(float deltatime); /**jsdoc diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 984d7b297b..4e75c93403 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -69,6 +69,7 @@ class MyAvatar : public Avatar { * @hifi-avatar * * @property {Vec3} qmlPosition - A synonym for position for use by QML. + * * @property {boolean} shouldRenderLocally=true - If true then your avatar is rendered for you in Interface, * otherwise it is not rendered for you (but it is still rendered for other users). * @property {Vec3} motorVelocity=Vec3.ZERO - The target velocity of your avatar to be achieved by a scripted motor. @@ -90,29 +91,38 @@ class MyAvatar : public Avatar { * @property {number} audioListenerModeCamera=1 - The audio listening position is at the camera. Read-only. * @property {number} audioListenerModeCustom=2 - The audio listening position is at a the position specified by set by the * customListenPosition and customListenOrientation property values. Read-only. + * @property {Vec3} customListenPosition=Vec3.ZERO - The listening position used when the audioListenerMode + * property value is audioListenerModeCustom. + * @property {Quat} customListenOrientation=Quat.IDENTITY - The listening orientation used when the + * audioListenerMode property value is audioListenerModeCustom. * @property {boolean} hasScriptedBlendshapes=false - Blendshapes will be transmitted over the network if set to true. * @property {boolean} hasProceduralBlinkFaceMovement=true - procedural blinking will be turned on if set to true. * @property {boolean} hasProceduralEyeFaceMovement=true - procedural eye movement will be turned on if set to true. * @property {boolean} hasAudioEnabledFaceMovement=true - If set to true, voice audio will move the mouth Blendshapes while MyAvatar.hasScriptedBlendshapes is enabled. - * @property {Vec3} customListenPosition=Vec3.ZERO - The listening position used when the audioListenerMode - * property value is audioListenerModeCustom. - * @property {Quat} customListenOrientation=Quat.IDENTITY - The listening orientation used when the - * audioListenerMode property value is audioListenerModeCustom. + * @property {number} rotationRecenterFilterLength + * @property {number} rotationThreshold + * @property {boolean} enableStepResetRotation + * @property {boolean} enableDrawAverageFacing + * * @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 {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 {number} energy + * @property {boolean} isAway + * * @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. @@ -122,30 +132,38 @@ class MyAvatar : public Avatar { * @property {boolean} collisionsEnabled - Set to true to enable collisions for the avatar, false * to disable collisions. May return true even though the value was set false because the * zone may disallow collisionless avatars. + * @property {boolean} otherAvatarsCollisionsEnabled * @property {boolean} characterControllerEnabled - Synonym of collisionsEnabled. * Deprecated: Use collisionsEnabled instead. * @property {boolean} useAdvancedMovementControls - Returns and sets the value of the Interface setting, Settings > * Walking and teleporting. Note: Setting the value has no effect unless Interface is restarted. * @property {boolean} showPlayArea - Returns and sets the value of the Interface setting, Settings > Show room boundaries * while teleporting. Note: Setting the value has no effect unless Interface is restarted. + * * @property {number} yawSpeed=75 * @property {number} pitchSpeed=50 + * * @property {boolean} hmdRollControlEnabled=true - If true, the roll angle of your HMD turns your avatar * while flying. * @property {number} hmdRollControlDeadZone=8 - The amount of HMD roll, in degrees, required before your avatar turns if * hmdRollControlEnabled is enabled. * @property {number} hmdRollControlRate If hmdRollControlEnabled is true, this value determines the maximum turn rate of * your avatar when rolling your HMD in degrees per second. + * * @property {number} userHeight=1.75 - The height of the user in sensor space. * @property {number} userEyeHeight=1.65 - The estimated height of the user's eyes in sensor space. Read-only. + * * @property {Uuid} SELF_ID - UUID representing "my avatar". Only use for local-only entities in situations * 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 {number} userRecenterModel + * @property {MyAvatar.SitStandModelType} userRecenterModel + * @property {boolean} isSitStandStateLocked + * @property {boolean} allowTeleporting * * @property {Vec3} skeletonOffset - Can be used to apply a translation offset between the avatar's position and the * registration point of the 3D model. @@ -160,6 +178,7 @@ class MyAvatar : public Avatar { * sometimes called "elevation". * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is * sometimes called "bank". + * * @property {Quat} orientation * @property {Quat} headOrientation - The orientation of the avatar's head. * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is @@ -168,18 +187,24 @@ class MyAvatar : public Avatar { * head. Yaw is sometimes called "heading". * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is * sometimes called "bank". + * * @property {Vec3} velocity * @property {Vec3} angularVelocity + * * @property {number} audioLoudness * @property {number} audioAverageLoudness + * * @property {string} displayName * @property {string} sessionDisplayName - Sanitized, defaulted version displayName that is defined by the AvatarMixer * rather than by Interface clients. The result is unique among all avatars present at the time. * @property {boolean} lookAtSnappingEnabled * @property {string} skeletonModelURL * @property {AttachmentData[]} attachmentData + * * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. + * * @property {Uuid} sessionUUID Read-only. + * * @property {Mat4} sensorToWorldMatrix Read-only. * @property {Mat4} controllerLeftHandMatrix Read-only. * @property {Mat4} controllerRightHandMatrix Read-only. @@ -196,11 +221,11 @@ class MyAvatar : public Avatar { Q_PROPERTY(QString motorMode READ getScriptedMotorMode WRITE setScriptedMotorMode) Q_PROPERTY(QString collisionSoundURL READ getCollisionSoundURL WRITE setCollisionSoundURL) Q_PROPERTY(AudioListenerMode audioListenerMode READ getAudioListenerMode WRITE setAudioListenerMode) - Q_PROPERTY(glm::vec3 customListenPosition READ getCustomListenPosition WRITE setCustomListenPosition) - Q_PROPERTY(glm::quat customListenOrientation READ getCustomListenOrientation WRITE setCustomListenOrientation) Q_PROPERTY(AudioListenerMode audioListenerModeHead READ getAudioListenerModeHead) Q_PROPERTY(AudioListenerMode audioListenerModeCamera READ getAudioListenerModeCamera) Q_PROPERTY(AudioListenerMode audioListenerModeCustom READ getAudioListenerModeCustom) + Q_PROPERTY(glm::vec3 customListenPosition READ getCustomListenPosition WRITE setCustomListenPosition) + Q_PROPERTY(glm::quat customListenOrientation READ getCustomListenOrientation WRITE setCustomListenOrientation) Q_PROPERTY(bool hasScriptedBlendshapes READ getHasScriptedBlendshapes WRITE setHasScriptedBlendshapes) Q_PROPERTY(bool hasProceduralBlinkFaceMovement READ getHasProceduralBlinkFaceMovement WRITE setHasProceduralBlinkFaceMovement) Q_PROPERTY(bool hasProceduralEyeFaceMovement READ getHasProceduralEyeFaceMovement WRITE setHasProceduralEyeFaceMovement) @@ -277,6 +302,9 @@ public: }; Q_ENUM(DriveKeys) + /**jsdoc + * @typedef {number} MyAvatar.SitStandModelType + */ enum SitStandModelType { ForceSit = 0, ForceStand, @@ -491,6 +519,9 @@ public: // adding one of the other handlers. While any handler may change a value in animStateDictionaryIn (or supply different values in animStateDictionaryOut) // 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 + * @function MyAvatar.addAnimationStateHandler + */ Q_INVOKABLE QScriptValue addAnimationStateHandler(QScriptValue handler, QScriptValue propertiesList) { return _skeletonModel->getRig().addAnimationStateHandler(handler, propertiesList); } /**jsdoc @@ -530,7 +561,7 @@ public: */ Q_INVOKABLE void setHmdAvatarAlignmentType(const QString& hand); /**jsdoc - * @function MyAvatar.setHmdAvatarAlignmentType + * @function MyAvatar.getHmdAvatarAlignmentType * @returns {string} */ Q_INVOKABLE QString getHmdAvatarAlignmentType() const; @@ -649,7 +680,7 @@ public: /**jsdoc * Recenter the avatar in the horizontal direction, if {@link MyAvatar|MyAvatar.hmdLeanRecenterEnabled} is * false. - * @ function MyAvatar.triggerHorizontalRecenter + * @function MyAvatar.triggerHorizontalRecenter */ Q_INVOKABLE void triggerHorizontalRecenter(); @@ -935,7 +966,7 @@ public: /**jsdoc * Function returns list of avatar entities - * @function MyAvatar.getAvatarEntitiesVariant() + * @function MyAvatar.getAvatarEntitiesVariant * @returns {object[]} */ Q_INVOKABLE QVariantList getAvatarEntitiesVariant(); @@ -1244,7 +1275,6 @@ public slots: * @param {boolean} [shouldFaceLocation=false] - Set to true to position the avatar a short distance away from * the new position and orientate the avatar to face the position. */ - void goToFeetLocation(const glm::vec3& newPosition, bool hasOrientation, const glm::quat& newOrientation, bool shouldFaceLocation); @@ -1382,8 +1412,20 @@ public slots: */ bool getEnableMeshVisible() const override; + /**jsdoc + * @function MyAvatar.storeAvatarEntityDataPayload + */ void storeAvatarEntityDataPayload(const QUuid& entityID, const QByteArray& payload) override; + + /**jsdoc + * @function MyAvatar.clearAvatarEntity + * @param {Uuid} entityID + * @param {boolean} requiresRemovalFromTree + */ void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true) override; + /**jsdoc + * @function MyAvatar.sanitizeAvatarEntityProperties + */ void sanitizeAvatarEntityProperties(EntityItemProperties& properties) const; /**jsdoc @@ -1489,11 +1531,11 @@ signals: void collisionsEnabledChanged(bool enabled); /**jsdoc - * Triggered when collisions with other avatars enabled or disabled - * @function MyAvatar.otherAvatarsCollisionsEnabledChanged - * @param {boolean} enabled - * @returns {Signal} - */ + * Triggered when collisions with other avatars enabled or disabled + * @function MyAvatar.otherAvatarsCollisionsEnabledChanged + * @param {boolean} enabled + * @returns {Signal} + */ void otherAvatarsCollisionsEnabledChanged(bool enabled); /**jsdoc diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 06942a13d8..7ebb8cad01 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -499,6 +499,9 @@ public: void tearDownGrabs(); signals: + /**jsdoc + * @function MyAvatar.targetScaleChanged + */ void targetScaleChanged(float targetScale); public slots: @@ -541,6 +544,9 @@ public slots: */ glm::quat getRightPalmRotation() const; + /**jsdoc + * @function MyAvatar.setModelURLFinished + */ // hooked up to Model::setURLFinished signal void setModelURLFinished(bool success); From f58a5db0b0931ce0244007a748ed545d51196194 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 19 Feb 2019 09:47:51 +1300 Subject: [PATCH 02/21] Reorganize JSDoc inheritance for MyAvatar and Avatar --- .../src/avatars/ScriptableAvatar.h | 109 +++------- interface/src/avatar/MyAvatar.h | 146 +++++++++----- .../src/avatars-renderer/Avatar.h | 7 +- libraries/avatars/src/AvatarData.h | 189 ++++++++++++------ 4 files changed, 262 insertions(+), 189 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 4562ad6134..b2ad4527b0 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -22,17 +22,16 @@ * The Avatar API is used to manipulate scriptable avatars on the domain. This API is a subset of the * {@link MyAvatar} API. * - *

Note: In the examples, use "Avatar" instead of "MyAvatar".

- * * @namespace Avatar * * @hifi-assignment-client * + * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. * @property {Vec3} position - * @property {number} scale + * @property {number} scale - Returns the clamped scale of the avatar. * @property {number} density Read-only. * @property {Vec3} handPosition - * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. + * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. * Yaw is sometimes called "heading". * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is * sometimes called "elevation". @@ -63,62 +62,6 @@ * @property {Mat4} controllerRightHandMatrix Read-only. * @property {number} sensorToWorldScale Read-only. * - * @borrows MyAvatar.getDomainMinScale as getDomainMinScale - * @borrows MyAvatar.getDomainMaxScale as getDomainMaxScale - * @borrows MyAvatar.canMeasureEyeHeight as canMeasureEyeHeight - * @borrows MyAvatar.getEyeHeight as getEyeHeight - * @borrows MyAvatar.getHeight as getHeight - * @borrows MyAvatar.setHandState as setHandState - * @borrows MyAvatar.getHandState as getHandState - * @borrows MyAvatar.setRawJointData as setRawJointData - * @borrows MyAvatar.setJointData as setJointData - * @borrows MyAvatar.setJointRotation as setJointRotation - * @borrows MyAvatar.setJointTranslation as setJointTranslation - * @borrows MyAvatar.clearJointData as clearJointData - * @borrows MyAvatar.isJointDataValid as isJointDataValid - * @borrows MyAvatar.getJointRotation as getJointRotation - * @borrows MyAvatar.getJointTranslation as getJointTranslation - * @borrows MyAvatar.getJointRotations as getJointRotations - * @borrows MyAvatar.getJointTranslations as getJointTranslations - * @borrows MyAvatar.setJointRotations as setJointRotations - * @borrows MyAvatar.setJointTranslations as setJointTranslations - * @borrows MyAvatar.clearJointsData as clearJointsData - * @borrows MyAvatar.getJointIndex as getJointIndex - * @borrows MyAvatar.getJointNames as getJointNames - * @borrows MyAvatar.setBlendshape as setBlendshape - * @borrows MyAvatar.getAttachmentsVariant as getAttachmentsVariant - * @borrows MyAvatar.setAttachmentsVariant as setAttachmentsVariant - * @borrows MyAvatar.updateAvatarEntity as updateAvatarEntity - * @borrows MyAvatar.clearAvatarEntity as clearAvatarEntity - * @borrows MyAvatar.setForceFaceTrackerConnected as setForceFaceTrackerConnected - * @borrows MyAvatar.getAttachmentData as getAttachmentData - * @borrows MyAvatar.setAttachmentData as setAttachmentData - * @borrows MyAvatar.attach as attach - * @borrows MyAvatar.detachOne as detachOne - * @borrows MyAvatar.detachAll as detachAll - * @borrows MyAvatar.getAvatarEntityData as getAvatarEntityData - * @borrows MyAvatar.setAvatarEntityData as setAvatarEntityData - * @borrows MyAvatar.getSensorToWorldMatrix as getSensorToWorldMatrix - * @borrows MyAvatar.getSensorToWorldScale as getSensorToWorldScale - * @borrows MyAvatar.getControllerLeftHandMatrix as getControllerLeftHandMatrix - * @borrows MyAvatar.getControllerRightHandMatrix as getControllerRightHandMatrix - * @borrows MyAvatar.getDataRate as getDataRate - * @borrows MyAvatar.getUpdateRate as getUpdateRate - * @borrows MyAvatar.displayNameChanged as displayNameChanged - * @borrows MyAvatar.sessionDisplayNameChanged as sessionDisplayNameChanged - * @borrows MyAvatar.skeletonModelURLChanged as skeletonModelURLChanged - * @borrows MyAvatar.lookAtSnappingChanged as lookAtSnappingChanged - * @borrows MyAvatar.sessionUUIDChanged as sessionUUIDChanged - * @borrows MyAvatar.sendAvatarDataPacket as sendAvatarDataPacket - * @borrows MyAvatar.sendIdentityPacket as sendIdentityPacket - * @borrows MyAvatar.setJointMappingsFromNetworkReply as setJointMappingsFromNetworkReply - * @borrows MyAvatar.setSessionUUID as setSessionUUID - * @borrows MyAvatar.getAbsoluteJointRotationInObjectFrame as getAbsoluteJointRotationInObjectFrame - * @borrows MyAvatar.getAbsoluteJointTranslationInObjectFrame as getAbsoluteJointTranslationInObjectFrame - * @borrows MyAvatar.setAbsoluteJointRotationInObjectFrame as setAbsoluteJointRotationInObjectFrame - * @borrows MyAvatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame - * @borrows MyAvatar.getTargetScale as getTargetScale - * @borrows MyAvatar.resetLastSent as resetLastSent */ class ScriptableAvatar : public AvatarData, public Dependency { @@ -159,23 +102,25 @@ public: Q_INVOKABLE AnimationDetails getAnimationDetails(); /**jsdoc - * Get the names of all the joints in the current avatar. - * @function MyAvatar.getJointNames - * @returns {string[]} The joint names. - * @example Report the names of all the joints in your current avatar. - * print(JSON.stringify(MyAvatar.getJointNames())); - */ + * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc.
+ * Get the names of all the joints in the current avatar. + * @function Avatar.getJointNames + * @returns {string[]} The joint names. + * @example Report the names of all the joints in your current avatar. + * print(JSON.stringify(Avatar.getJointNames())); + */ Q_INVOKABLE virtual QStringList getJointNames() const override; /**jsdoc - * Get the joint index for a named joint. The joint index value is the position of the joint in the array returned by - * {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. - * @function MyAvatar.getJointIndex - * @param {string} name - The name of the joint. - * @returns {number} The index of the joint. - * @example Report the index of your avatar's left arm joint. - * print(JSON.stringify(MyAvatar.getJointIndex("LeftArm")); - */ + * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc.
+ * Get the joint index for a named joint. The joint index value is the position of the joint in the array returned by + * {@link Avatar.getJointNames}. + * @function Avatar.getJointIndex + * @param {string} name - The name of the joint. + * @returns {number} The index of the joint. + * @example Report the index of your avatar's left arm joint. + * print(JSON.stringify(Avatar.getJointIndex("LeftArm")); + */ /// Returns the index of the joint with the specified name, or -1 if not found/unknown. Q_INVOKABLE virtual int getJointIndex(const QString& name) const override; @@ -193,6 +138,8 @@ public: bool getHasAudioEnabledFaceMovement() const override { return _headData->getHasAudioEnabledFaceMovement(); } /**jsdoc + * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc.
+ * ####### Also need to resolve with MyAvatar.
* Potentially Very Expensive. Do not use. * @function Avatar.getAvatarEntityData * @returns {object} @@ -200,13 +147,15 @@ public: Q_INVOKABLE AvatarEntityMap getAvatarEntityData() const override; /**jsdoc - * @function MyAvatar.setAvatarEntityData - * @param {object} avatarEntityData - */ + * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc. + * @function Avatar.setAvatarEntityData + * @param {object} avatarEntityData + */ Q_INVOKABLE void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; /**jsdoc - * @function MyAvatar.updateAvatarEntity + * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc. + * @function Avatar.updateAvatarEntity * @param {Uuid} entityID * @param {string} entityData */ @@ -214,12 +163,12 @@ public: public slots: /**jsdoc - * @function MyAvatar.update + * @function Avatar.update */ void update(float deltatime); /**jsdoc - * @function MyAvatar.setJointMappingsFromNetworkReply + * @function Avatar.setJointMappingsFromNetworkReply */ void setJointMappingsFromNetworkReply(); diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 4e75c93403..d689d2f215 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -68,6 +68,46 @@ class MyAvatar : public Avatar { * @hifi-client-entity * @hifi-avatar * + * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. + * @property {Vec3} position + * @property {number} scale - Returns the clamped scale of the avatar. + * @property {number} density Read-only. + * @property {Vec3} handPosition + * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. + * Yaw is sometimes called "heading". + * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is + * sometimes called "elevation". + * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is + * sometimes called "bank". + * @property {Quat} orientation + * @property {Quat} headOrientation - The orientation of the avatar's head. + * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is + * sometimes called "elevation". + * @property {number} headYaw - The rotation left or right about an axis running from the base to the crown of the avatar's + * head. Yaw is sometimes called "heading". + * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is + * sometimes called "bank". + * @property {Vec3} velocity + * @property {Vec3} angularVelocity + * @property {number} audioLoudness + * @property {number} audioAverageLoudness + * @property {string} displayName + * @property {string} sessionDisplayName - Sanitized, defaulted version displayName that is defined by the AvatarMixer + * rather than by Interface clients. The result is unique among all avatars present at the time. + * @property {boolean} lookAtSnappingEnabled + * @property {string} skeletonModelURL + * @property {AttachmentData[]} attachmentData + * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. + * @property {Uuid} sessionUUID Read-only. + * @property {Mat4} sensorToWorldMatrix Read-only. + * @property {Mat4} controllerLeftHandMatrix Read-only. + * @property {Mat4} controllerRightHandMatrix Read-only. + * @property {number} sensorToWorldScale Read-only. + * + * @comment IMPORTANT: This group of properties is copied from Avatar.h; they should NOT be edited here. + * @property {Vec3} skeletonOffset - Can be used to apply a translation offset between the avatar's position and the + * registration point of the 3D model. + * * @property {Vec3} qmlPosition - A synonym for position for use by QML. * * @property {boolean} shouldRenderLocally=true - If true then your avatar is rendered for you in Interface, @@ -165,50 +205,60 @@ class MyAvatar : public Avatar { * @property {boolean} isSitStandStateLocked * @property {boolean} allowTeleporting * - * @property {Vec3} skeletonOffset - Can be used to apply a translation offset between the avatar's position and the - * registration point of the 3D model. - * - * @property {Vec3} position - * @property {number} scale - Returns the clamped scale of the avatar. - * @property {number} density Read-only. - * @property {Vec3} handPosition - * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. - * Yaw is sometimes called "heading". - * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is - * sometimes called "elevation". - * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is - * sometimes called "bank". - * - * @property {Quat} orientation - * @property {Quat} headOrientation - The orientation of the avatar's head. - * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is - * sometimes called "elevation". - * @property {number} headYaw - The rotation left or right about an axis running from the base to the crown of the avatar's - * head. Yaw is sometimes called "heading". - * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is - * sometimes called "bank". - * - * @property {Vec3} velocity - * @property {Vec3} angularVelocity - * - * @property {number} audioLoudness - * @property {number} audioAverageLoudness - * - * @property {string} displayName - * @property {string} sessionDisplayName - Sanitized, defaulted version displayName that is defined by the AvatarMixer - * rather than by Interface clients. The result is unique among all avatars present at the time. - * @property {boolean} lookAtSnappingEnabled - * @property {string} skeletonModelURL - * @property {AttachmentData[]} attachmentData - * - * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. - * - * @property {Uuid} sessionUUID Read-only. - * - * @property {Mat4} sensorToWorldMatrix Read-only. - * @property {Mat4} controllerLeftHandMatrix Read-only. - * @property {Mat4} controllerRightHandMatrix Read-only. - * @property {number} sensorToWorldScale Read-only. + * @borrows Avatar.getDomainMinScale as getDomainMinScale + * @borrows Avatar.getDomainMaxScale as getDomainMaxScale + * @borrows Avatar.getEyeHeight as getEyeHeight + * @borrows Avatar.getHeight as getHeight + * @borrows Avatar.setHandState as setHandState + * @borrows Avatar.getHandState as getHandState + * @borrows Avatar.setRawJointData as setRawJointData + * @borrows Avatar.setJointData as setJointData + * @borrows Avatar.setJointRotation as setJointRotation + * @borrows Avatar.setJointTranslation as setJointTranslation + * @borrows Avatar.clearJointData as clearJointData + * @borrows Avatar.isJointDataValid as isJointDataValid + * @borrows Avatar.getJointRotation as getJointRotation + * @borrows Avatar.getJointTranslation as getJointTranslation + * @borrows Avatar.getJointRotations as getJointRotations + * @borrows Avatar.getJointTranslations as getJointTranslations + * @borrows Avatar.setJointRotations as setJointRotations + * @borrows Avatar.setJointTranslations as setJointTranslations + * @borrows Avatar.clearJointsData as clearJointsData + * @borrows Avatar.getJointIndex as getJointIndex + * @borrows Avatar.getJointNames as getJointNames + * @borrows Avatar.setBlendshape as setBlendshape + * @borrows Avatar.getAttachmentsVariant as getAttachmentsVariant + * @borrows Avatar.setAttachmentsVariant as setAttachmentsVariant + * @borrows Avatar.updateAvatarEntity as updateAvatarEntity + * @borrows Avatar.clearAvatarEntity as clearAvatarEntity + * @borrows Avatar.setForceFaceTrackerConnected as setForceFaceTrackerConnected + * @borrows Avatar.getAttachmentData as getAttachmentData + * @borrows Avatar.setAttachmentData as setAttachmentData + * @borrows Avatar.attach as attach + * @borrows Avatar.detachOne as detachOne + * @borrows Avatar.detachAll as detachAll + * @borrows Avatar.getAvatarEntityData as getAvatarEntityData + * @borrows Avatar.setAvatarEntityData as setAvatarEntityData + * @borrows Avatar.getSensorToWorldMatrix as getSensorToWorldMatrix + * @borrows Avatar.getSensorToWorldScale as getSensorToWorldScale + * @borrows Avatar.getControllerLeftHandMatrix as getControllerLeftHandMatrix + * @borrows Avatar.getControllerRightHandMatrix as getControllerRightHandMatrix + * @borrows Avatar.getDataRate as getDataRate + * @borrows Avatar.getUpdateRate as getUpdateRate + * @borrows Avatar.displayNameChanged as displayNameChanged + * @borrows Avatar.sessionDisplayNameChanged as sessionDisplayNameChanged + * @borrows Avatar.skeletonModelURLChanged as skeletonModelURLChanged + * @borrows Avatar.lookAtSnappingChanged as lookAtSnappingChanged + * @borrows Avatar.sessionUUIDChanged as sessionUUIDChanged + * @borrows Avatar.sendAvatarDataPacket as sendAvatarDataPacket + * @borrows Avatar.sendIdentityPacket as sendIdentityPacket + * @borrows Avatar.setSessionUUID as setSessionUUID + * @borrows Avatar.getAbsoluteJointRotationInObjectFrame as getAbsoluteJointRotationInObjectFrame + * @borrows Avatar.getAbsoluteJointTranslationInObjectFrame as getAbsoluteJointTranslationInObjectFrame + * @borrows Avatar.setAbsoluteJointRotationInObjectFrame as setAbsoluteJointRotationInObjectFrame + * @borrows Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame + * @borrows Avatar.getTargetScale as getTargetScale + * @borrows Avatar.resetLastSent as resetLastSent */ // FIXME: `glm::vec3 position` is not accessible from QML, so this exposes position in a QML-native type Q_PROPERTY(QVector3D qmlPosition READ getQmlPosition) @@ -1314,7 +1364,7 @@ public slots: /**jsdoc * @function MyAvatar.restrictScaleFromDomainSettings - * @param {objecct} domainSettingsObject + * @param {object} domainSettingsObject */ void restrictScaleFromDomainSettings(const QJsonObject& domainSettingsObject); @@ -1345,6 +1395,7 @@ public slots: /**jsdoc + * ####### Why Q_INVOKABLE? * @function MyAvatar.updateMotionBehaviorFromMenu */ Q_INVOKABLE void updateMotionBehaviorFromMenu(); @@ -1413,16 +1464,19 @@ public slots: bool getEnableMeshVisible() const override; /**jsdoc + * ####### TODO; Should this really be exposed in the API? * @function MyAvatar.storeAvatarEntityDataPayload */ void storeAvatarEntityDataPayload(const QUuid& entityID, const QByteArray& payload) override; /**jsdoc + * ####### Does override change functionality? If so, document here and don't borrow; if not, borrow and don't document here. * @function MyAvatar.clearAvatarEntity * @param {Uuid} entityID - * @param {boolean} requiresRemovalFromTree + * @param {boolean} [requiresRemovalFromTree] */ void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true) override; + /**jsdoc * @function MyAvatar.sanitizeAvatarEntityProperties */ diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 7ebb8cad01..1aa6829160 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -127,7 +127,12 @@ private: class Avatar : public AvatarData, public scriptable::ModelProvider, public MetaModelPayload { Q_OBJECT - // This property has JSDoc in MyAvatar.h. + /*jsdoc + * @comment IMPORTANT: The JSDoc for the following properties should be copied to MyAvatar.h. + * + * @property {Vec3} skeletonOffset - Can be used to apply a translation offset between the avatar's position and the + * registration point of the 3D model. + */ Q_PROPERTY(glm::vec3 skeletonOffset READ getSkeletonOffset WRITE setSkeletonOffset) public: diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 63396a59ac..7a4d235565 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -411,7 +411,43 @@ class ClientTraitsHandler; class AvatarData : public QObject, public SpatiallyNestable { Q_OBJECT - // The following properties have JSDoc in MyAvatar.h and ScriptableAvatar.h + // IMPORTANT: The JSDoc for the following properties should be copied to MyAvatar.h and ScriptableAvatar.h. + /* + * @property {Vec3} position + * @property {number} scale - Returns the clamped scale of the avatar. + * @property {number} density Read-only. + * @property {Vec3} handPosition + * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. + * Yaw is sometimes called "heading". + * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is + * sometimes called "elevation". + * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is + * sometimes called "bank". + * @property {Quat} orientation + * @property {Quat} headOrientation - The orientation of the avatar's head. + * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is + * sometimes called "elevation". + * @property {number} headYaw - The rotation left or right about an axis running from the base to the crown of the avatar's + * head. Yaw is sometimes called "heading". + * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is + * sometimes called "bank". + * @property {Vec3} velocity + * @property {Vec3} angularVelocity + * @property {number} audioLoudness + * @property {number} audioAverageLoudness + * @property {string} displayName + * @property {string} sessionDisplayName - Sanitized, defaulted version displayName that is defined by the AvatarMixer + * rather than by Interface clients. The result is unique among all avatars present at the time. + * @property {boolean} lookAtSnappingEnabled + * @property {string} skeletonModelURL + * @property {AttachmentData[]} attachmentData + * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. + * @property {Uuid} sessionUUID Read-only. + * @property {Mat4} sensorToWorldMatrix Read-only. + * @property {Mat4} controllerLeftHandMatrix Read-only. + * @property {Mat4} controllerRightHandMatrix Read-only. + * @property {number} sensorToWorldScale Read-only. + */ Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) Q_PROPERTY(float scale READ getDomainLimitedScale WRITE setTargetScale) Q_PROPERTY(float density READ getDensity) @@ -567,7 +603,7 @@ public: /**jsdoc * Returns the minimum scale allowed for this avatar in the current domain. * This value can change as the user changes avatars or when changing domains. - * @function MyAvatar.getDomainMinScale + * @function Avatar.getDomainMinScale * @returns {number} minimum scale allowed for this avatar in the current domain. */ Q_INVOKABLE float getDomainMinScale() const; @@ -575,7 +611,7 @@ public: /**jsdoc * Returns the maximum scale allowed for this avatar in the current domain. * This value can change as the user changes avatars or when changing domains. - * @function MyAvatar.getDomainMaxScale + * @function Avatar.getDomainMaxScale * @returns {number} maximum scale allowed for this avatar in the current domain. */ Q_INVOKABLE float getDomainMaxScale() const; @@ -591,7 +627,7 @@ public: /**jsdoc * Provides read only access to the current eye height of the avatar. * This height is only an estimate and might be incorrect for avatars that are missing standard joints. - * @function MyAvatar.getEyeHeight + * @function Avatar.getEyeHeight * @returns {number} Eye height of avatar in meters. */ Q_INVOKABLE virtual float getEyeHeight() const { return _targetScale * getUnscaledEyeHeight(); } @@ -599,7 +635,7 @@ public: /**jsdoc * Provides read only access to the current height of the avatar. * This height is only an estimate and might be incorrect for avatars that are missing standard joints. - * @function MyAvatar.getHeight + * @function Avatar.getHeight * @returns {number} Height of avatar in meters. */ Q_INVOKABLE virtual float getHeight() const; @@ -610,13 +646,13 @@ public: void setDomainMaximumHeight(float domainMaximumHeight); /**jsdoc - * @function MyAvatar.setHandState + * @function Avatar.setHandState * @param {string} state */ Q_INVOKABLE void setHandState(char s) { _handState = s; } /**jsdoc - * @function MyAvatar.getHandState + * @function Avatar.getHandState * @returns {string} */ Q_INVOKABLE char getHandState() const { return _handState; } @@ -624,7 +660,7 @@ public: const QVector& getRawJointData() const { return _jointData; } /**jsdoc - * @function MyAvatar.setRawJointData + * @function Avatar.setRawJointData * @param {JointData[]} data */ Q_INVOKABLE void setRawJointData(QVector data); @@ -636,7 +672,7 @@ public: * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

- * @function MyAvatar.setJointData + * @function Avatar.setJointData * @param {number} index - The index of the joint. * @param {Quat} rotation - The rotation of the joint relative to its parent. * @param {Vec3} translation - The translation of the joint relative to its parent. @@ -654,6 +690,8 @@ public: * Script.setTimeout(function () { * MyAvatar.clearJointsData(); * }, 5000); + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void setJointData(int index, const glm::quat& rotation, const glm::vec3& translation); @@ -664,7 +702,7 @@ public: * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

- * @function MyAvatar.setJointRotation + * @function Avatar.setJointRotation * @param {number} index - The index of the joint. * @param {Quat} rotation - The rotation of the joint relative to its parent. */ @@ -677,7 +715,7 @@ public: * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

- * @function MyAvatar.setJointTranslation + * @function Avatar.setJointTranslation * @param {number} index - The index of the joint. * @param {Vec3} translation - The translation of the joint relative to its parent. */ @@ -687,13 +725,13 @@ public: * Clear joint translations and rotations set by script for a specific joint. This restores all motion from the default * animation system including inverse kinematics for that joint. *

Note: This is slightly faster than the function variation that specifies the joint name.

- * @function MyAvatar.clearJointData + * @function Avatar.clearJointData * @param {number} index - The index of the joint. */ Q_INVOKABLE virtual void clearJointData(int index); /**jsdoc - * @function MyAvatar.isJointDataValid + * @function Avatar.isJointDataValid * @param {number} index * @returns {boolean} */ @@ -702,7 +740,7 @@ public: /**jsdoc * Get the rotation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. - * @function MyAvatar.getJointRotation + * @function Avatar.getJointRotation * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to its parent. */ @@ -711,7 +749,7 @@ public: /**jsdoc * Get the translation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. - * @function MyAvatar.getJointTranslation + * @function Avatar.getJointTranslation * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to its parent. */ @@ -724,7 +762,7 @@ public: * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

- * @function MyAvatar.setJointData + * @function Avatar.setJointData * @param {string} name - The name of the joint. * @param {Quat} rotation - The rotation of the joint relative to its parent. * @param {Vec3} translation - The translation of the joint relative to its parent. @@ -738,7 +776,7 @@ public: * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

- * @function MyAvatar.setJointRotation + * @function Avatar.setJointRotation * @param {string} name - The name of the joint. * @param {Quat} rotation - The rotation of the joint relative to its parent. * @example Set your avatar to its default T-pose then rotate its right arm.
@@ -759,6 +797,8 @@ public: * Script.setTimeout(function () { * MyAvatar.clearJointsData(); * }, 5000); + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void setJointRotation(const QString& name, const glm::quat& rotation); @@ -769,7 +809,7 @@ public: * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

- * @function MyAvatar.setJointTranslation + * @function Avatar.setJointTranslation * @param {string} name - The name of the joint. * @param {Vec3} translation - The translation of the joint relative to its parent. * @example Stretch your avatar's neck. Depending on the avatar you are using, you will either see a gap between @@ -782,6 +822,8 @@ public: * Script.setTimeout(function () { * MyAvatar.clearJointData("Neck"); * }, 5000); + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void setJointTranslation(const QString& name, const glm::vec3& translation); @@ -789,7 +831,7 @@ public: * Clear joint translations and rotations set by script for a specific joint. This restores all motion from the default * animation system including inverse kinematics for that joint. *

Note: This is slightly slower than the function variation that specifies the joint index.

- * @function MyAvatar.clearJointData + * @function Avatar.clearJointData * @param {string} name - The name of the joint. * @example Offset and restore the position of your avatar's head. * // Move your avatar's head up by 25cm from where it should be. @@ -799,11 +841,13 @@ public: * Script.setTimeout(function () { * MyAvatar.clearJointData("Neck"); * }, 5000); + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void clearJointData(const QString& name); /**jsdoc - * @function MyAvatar.isJointDataValid + * @function Avatar.isJointDataValid * @param {string} name * @returns {boolean} */ @@ -812,37 +856,43 @@ public: /**jsdoc * Get the rotation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. - * @function MyAvatar.getJointRotation + * @function Avatar.getJointRotation * @param {string} name - The name of the joint. * @returns {Quat} The rotation of the joint relative to its parent. * @example Report the rotation of your avatar's hips joint. * print(JSON.stringify(MyAvatar.getJointRotation("Hips"))); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual glm::quat getJointRotation(const QString& name) const; /**jsdoc * Get the translation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. - * @function MyAvatar.getJointTranslation + * @function Avatar.getJointTranslation * @param {number} name - The name of the joint. * @returns {Vec3} The translation of the joint relative to its parent. * @example Report the translation of your avatar's hips joint. * print(JSON.stringify(MyAvatar.getJointRotation("Hips"))); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual glm::vec3 getJointTranslation(const QString& name) const; /**jsdoc * Get the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. - * @function MyAvatar.getJointRotations + * @function Avatar.getJointRotations * @returns {Quat[]} The rotations of all joints relative to each's parent. The values are in the same order as the array * returned by {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. * @example Report the rotations of all your avatar's joints. * print(JSON.stringify(MyAvatar.getJointRotations())); + * + * // Note: If using from the Avatar API, replace all "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual QVector getJointRotations() const; /**jsdoc - * @function MyAvatar.getJointTranslations + * @function Avatar.getJointTranslations * @returns {Vec3[]} */ Q_INVOKABLE virtual QVector getJointTranslations() const; @@ -854,7 +904,7 @@ public: * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

- * @function MyAvatar.setJointRotations + * @function Avatar.setJointRotations * @param {Quat[]} jointRotations - The rotations for all joints in the avatar. The values are in the same order as the * array returned by {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. * @example Set your avatar to its default T-pose then rotate its right arm.
@@ -880,11 +930,13 @@ public: * Script.setTimeout(function () { * MyAvatar.clearJointsData(); * }, 5000); + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void setJointRotations(const QVector& jointRotations); /**jsdoc - * @function MyAvatar.setJointTranslations + * @function Avatar.setJointTranslations * @param {Vec3[]} translations */ Q_INVOKABLE virtual void setJointTranslations(const QVector& jointTranslations); @@ -892,7 +944,7 @@ public: /**jsdoc * Clear all joint translations and rotations that have been set by script. This restores all motion from the default * animation system including inverse kinematics for all joints. - * @function MyAvatar.clearJointsData + * @function Avatar.clearJointsData * @example Set your avatar to it's default T-pose for a while. * // Set all joint translations and rotations to defaults. * var i, length, rotation, translation; @@ -906,33 +958,39 @@ public: * Script.setTimeout(function () { * MyAvatar.clearJointsData(); * }, 5000); + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void clearJointsData(); /**jsdoc * Get the joint index for a named joint. The joint index value is the position of the joint in the array returned by * {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. - * @function MyAvatar.getJointIndex + * @function Avatar.getJointIndex * @param {string} name - The name of the joint. * @returns {number} The index of the joint. * @example Report the index of your avatar's left arm joint. * print(JSON.stringify(MyAvatar.getJointIndex("LeftArm")); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ /// Returns the index of the joint with the specified name, or -1 if not found/unknown. Q_INVOKABLE virtual int getJointIndex(const QString& name) const; /**jsdoc * Get the names of all the joints in the current avatar. - * @function MyAvatar.getJointNames + * @function Avatar.getJointNames * @returns {string[]} The joint names. * @example Report the names of all the joints in your current avatar. * print(JSON.stringify(MyAvatar.getJointNames())); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual QStringList getJointNames() const; /**jsdoc - * @function MyAvatar.setBlendshape + * @function Avatar.setBlendshape * @param {string} name * @param {number} value */ @@ -940,14 +998,14 @@ public: /**jsdoc - * @function MyAvatar.getAttachmentsVariant + * @function Avatar.getAttachmentsVariant * @returns {object} */ // FIXME: Can this name be improved? Can it be deprecated? Q_INVOKABLE virtual QVariantList getAttachmentsVariant() const; /**jsdoc - * @function MyAvatar.setAttachmentsVariant + * @function Avatar.setAttachmentsVariant * @param {object} variant */ // FIXME: Can this name be improved? Can it be deprecated? @@ -956,21 +1014,22 @@ public: virtual void storeAvatarEntityDataPayload(const QUuid& entityID, const QByteArray& payload); /**jsdoc - * @function MyAvatar.updateAvatarEntity + * @function Avatar.updateAvatarEntity * @param {Uuid} entityID * @param {string} entityData */ Q_INVOKABLE virtual void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData); /**jsdoc - * @function MyAvatar.clearAvatarEntity + * @function Avatar.clearAvatarEntity * @param {Uuid} entityID + * @param {boolean} [requiresRemovalFromTree] */ Q_INVOKABLE virtual void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true); /**jsdoc - * @function MyAvatar.setForceFaceTrackerConnected + * @function Avatar.setForceFaceTrackerConnected * @param {boolean} connected */ Q_INVOKABLE void setForceFaceTrackerConnected(bool connected) { _forceFaceTrackerConnected = connected; } @@ -1023,13 +1082,15 @@ public: /**jsdoc * Get information about all models currently attached to your avatar. - * @function MyAvatar.getAttachmentData + * @function Avatar.getAttachmentData * @returns {AttachmentData[]} Information about all models attached to your avatar. * @example Report the URLs of all current attachments. * var attachments = MyAvatar.getaAttachmentData(); * for (var i = 0; i < attachments.length; i++) { * print (attachments[i].modelURL); * } + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual QVector getAttachmentData() const; @@ -1037,7 +1098,7 @@ public: * Set all models currently attached to your avatar. For example, if you retrieve attachment data using * {@link MyAvatar.getAttachmentData} or {@link Avatar.getAttachmentData}, make changes to it, and then want to update your avatar's attachments per the * changed data. You can also remove all attachments by using setting attachmentData to null. - * @function MyAvatar.setAttachmentData + * @function Avatar.setAttachmentData * @param {AttachmentData[]} attachmentData - The attachment data defining the models to have attached to your avatar. Use * null to remove all attachments. * @example Remove a hat attachment if your avatar is wearing it. @@ -1051,6 +1112,8 @@ public: * break; * } * } + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void setAttachmentData(const QVector& attachmentData); @@ -1059,7 +1122,7 @@ public: * stand on. *

Note: Attached models are models only; they are not entities and can not be manipulated using the {@link Entities} API. * Nor can you use this function to attach an entity (such as a sphere or a box) to your avatar.

- * @function MyAvatar.attach + * @function Avatar.attach * @param {string} modelURL - The URL of the model to attach. Models can be .FBX or .OBJ format. * @param {string} [jointName=""] - The name of the avatar joint (see {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}) to attach the model * to. @@ -1089,6 +1152,8 @@ public: * attachment.rotation, * attachment.scale, * attachment.isSoft); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ Q_INVOKABLE virtual void attach(const QString& modelURL, const QString& jointName = QString(), const glm::vec3& translation = glm::vec3(), const glm::quat& rotation = glm::quat(), @@ -1097,7 +1162,7 @@ public: /**jsdoc * Detach the most recently attached instance of a particular model from either a specific joint or any joint. - * @function MyAvatar.detachOne + * @function Avatar.detachOne * @param {string} modelURL - The URL of the model to detach. * @param {string} [jointName=""] - The name of the joint to detach the model from. If "", then the most * recently attached model is removed from which ever joint it was attached to. @@ -1106,7 +1171,7 @@ public: /**jsdoc * Detach all instances of a particular model from either a specific joint or all joints. - * @function MyAvatar.detachAll + * @function Avatar.detachAll * @param {string} modelURL - The URL of the model to detach. * @param {string} [jointName=""] - The name of the joint to detach the model from. If "", then the model is * detached from all joints. @@ -1136,13 +1201,13 @@ public: AABox getDefaultBubbleBox() const; /**jsdoc - * @function MyAvatar.getAvatarEntityData + * @function Avatar.getAvatarEntityData * @returns {object} */ Q_INVOKABLE virtual AvatarEntityMap getAvatarEntityData() const; /**jsdoc - * @function MyAvatar.setAvatarEntityData + * @function Avatar.setAvatarEntityData * @param {object} avatarEntityData */ Q_INVOKABLE virtual void setAvatarEntityData(const AvatarEntityMap& avatarEntityData); @@ -1151,28 +1216,28 @@ public: AvatarEntityIDs getAndClearRecentlyRemovedIDs(); /**jsdoc - * @function MyAvatar.getSensorToWorldMatrix + * @function Avatar.getSensorToWorldMatrix * @returns {Mat4} */ // thread safe Q_INVOKABLE glm::mat4 getSensorToWorldMatrix() const; /**jsdoc - * @function MyAvatar.getSensorToWorldScale + * @function Avatar.getSensorToWorldScale * @returns {number} */ // thread safe Q_INVOKABLE float getSensorToWorldScale() const; /**jsdoc - * @function MyAvatar.getControllerLeftHandMatrix + * @function Avatar.getControllerLeftHandMatrix * @returns {Mat4} */ // thread safe Q_INVOKABLE glm::mat4 getControllerLeftHandMatrix() const; /**jsdoc - * @function MyAvatar.getControllerRightHandMatrix + * @function Avatar.getControllerRightHandMatrix * @returns {Mat4} */ // thread safe @@ -1180,14 +1245,14 @@ public: /**jsdoc - * @function MyAvatar.getDataRate + * @function Avatar.getDataRate * @param {string} [rateName=""] * @returns {number} */ Q_INVOKABLE float getDataRate(const QString& rateName = QString("")) const; /**jsdoc - * @function MyAvatar.getUpdateRate + * @function Avatar.getUpdateRate * @param {string} [rateName=""] * @returns {number} */ @@ -1235,32 +1300,32 @@ public: signals: /**jsdoc - * @function MyAvatar.displayNameChanged + * @function Avatar.displayNameChanged * @returns {Signal} */ void displayNameChanged(); /**jsdoc - * @function MyAvatar.sessionDisplayNameChanged + * @function Avatar.sessionDisplayNameChanged * @returns {Signal} */ void sessionDisplayNameChanged(); /**jsdoc - * @function MyAvatar.skeletonModelURLChanged + * @function Avatar.skeletonModelURLChanged * @returns {Signal} */ void skeletonModelURLChanged(); /**jsdoc - * @function MyAvatar.lookAtSnappingChanged + * @function Avatar.lookAtSnappingChanged * @param {boolean} enabled * @returns {Signal} */ void lookAtSnappingChanged(bool enabled); /**jsdoc - * @function MyAvatar.sessionUUIDChanged + * @function Avatar.sessionUUIDChanged * @returns {Signal} */ void sessionUUIDChanged(); @@ -1268,18 +1333,18 @@ signals: public slots: /**jsdoc - * @function MyAvatar.sendAvatarDataPacket + * @function Avatar.sendAvatarDataPacket * @param {boolean} [sendAll=false] */ virtual int sendAvatarDataPacket(bool sendAll = false); /**jsdoc - * @function MyAvatar.sendIdentityPacket + * @function Avatar.sendIdentityPacket */ int sendIdentityPacket(); /**jsdoc - * @function MyAvatar.setSessionUUID + * @function Avatar.setSessionUUID * @param {Uuid} sessionUUID */ virtual void setSessionUUID(const QUuid& sessionUUID) { @@ -1294,21 +1359,21 @@ public slots: } /**jsdoc - * @function MyAvatar.getAbsoluteJointRotationInObjectFrame + * @function Avatar.getAbsoluteJointRotationInObjectFrame * @param {number} index * @returns {Quat} */ virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override; /**jsdoc - * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame + * @function Avatar.getAbsoluteJointTranslationInObjectFrame * @param {number} index * @returns {Vec3} */ virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override; /**jsdoc - * @function MyAvatar.setAbsoluteJointRotationInObjectFrame + * @function Avatar.setAbsoluteJointRotationInObjectFrame * @param {number} index * @param {Quat} rotation * @returns {boolean} @@ -1316,7 +1381,7 @@ public slots: virtual bool setAbsoluteJointRotationInObjectFrame(int index, const glm::quat& rotation) override { return false; } /**jsdoc - * @function MyAvatar.setAbsoluteJointTranslationInObjectFrame + * @function Avatar.setAbsoluteJointTranslationInObjectFrame * @param {number} index * @param {Vec3} translation * @returns {boolean} @@ -1324,13 +1389,13 @@ public slots: virtual bool setAbsoluteJointTranslationInObjectFrame(int index, const glm::vec3& translation) override { return false; } /**jsdoc - * @function MyAvatar.getTargetScale + * @function Avatar.getTargetScale * @returns {number} */ float getTargetScale() const { return _targetScale; } // why is this a slot? /**jsdoc - * @function MyAvatar.resetLastSent + * @function Avatar.resetLastSent */ void resetLastSent() { _lastToByteArray = 0; } From 01119a5b5d980be426bcb20bb773d2be6591ed9e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 21 Feb 2019 11:19:29 +1300 Subject: [PATCH 03/21] Fill in Agent API JSDoc --- .../src/AgentScriptingInterface.h | 31 +++++++++++++------ .../src/avatars/ScriptableAvatar.h | 2 +- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/assignment-client/src/AgentScriptingInterface.h b/assignment-client/src/AgentScriptingInterface.h index 9fa7688778..1f592a9f18 100644 --- a/assignment-client/src/AgentScriptingInterface.h +++ b/assignment-client/src/AgentScriptingInterface.h @@ -18,16 +18,25 @@ #include "Agent.h" /**jsdoc + * The Agent API enables an assignment client to emulate an avatar. In particular, setting isAvatar = + * true connects the assignment client to the avatar and audio mixers and enables the {@link Avatar} API to be used. + * * @namespace Agent * * @hifi-assignment-client * - * @property {boolean} isAvatar - * @property {boolean} isPlayingAvatarSound Read-only. - * @property {boolean} isListeningToAudioStream - * @property {boolean} isNoiseGateEnabled - * @property {number} lastReceivedAudioLoudness Read-only. - * @property {Uuid} sessionUUID Read-only. + * @property {boolean} isAvatar - true if the assignment client script is emulating an avatar, otherwise + * false. + * @property {boolean} isPlayingAvatarSound - true if the script has a sound to play, otherwise false. + * Sounds are played when isAvatar is true, from the position and with the orientation of the + * scripted avatar's head.Read-only. + * @property {boolean} isListeningToAudioStream - true if the agent is "listening" to the audio stream from the + * domain, otherwise false. + * @property {boolean} isNoiseGateEnabled - true if the noise gate is enabled, otherwise false. When + * enabled, the input audio stream is blocked (fully attenuated) if it falls below an adaptive threshold. + * @property {number} lastReceivedAudioLoudness - The current loudness of the audio input, nominal range 0.0 (no + * sound) – 1.0 (the onset of clipping). Read-only. + * @property {Uuid} sessionUUID - The unique ID associated with the agent's current session in the domain. Read-only. */ class AgentScriptingInterface : public QObject { Q_OBJECT @@ -54,20 +63,24 @@ public: public slots: /**jsdoc + * Set whether or not the script should emulate an avatar. * @function Agent.setIsAvatar - * @param {boolean} isAvatar + * @param {boolean} isAvatar - true if the script should act as if an avatar, otherwise false. */ void setIsAvatar(bool isAvatar) const { _agent->setIsAvatar(isAvatar); } /**jsdoc + * Check whether or not the script is emulating an avatar. * @function Agent.isAvatar - * @returns {boolean} + * @returns {boolean} true if the script is acting as if an avatar, otherwise false. */ bool isAvatar() const { return _agent->isAvatar(); } /**jsdoc + * Play a sound from the position and with the orientation of the emulated avatar's head. No sound is played unless + * isAvatar == true. * @function Agent.playAvatarSound - * @param {object} avatarSound + * @param {SoundObject} avatarSound - The sound to play. */ void playAvatarSound(SharedSoundPointer avatarSound) const { _agent->playAvatarSound(avatarSound); } diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index b2ad4527b0..6b78f666e1 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -20,7 +20,7 @@ /**jsdoc * The Avatar API is used to manipulate scriptable avatars on the domain. This API is a subset of the - * {@link MyAvatar} API. + * {@link MyAvatar} API. To enable this API, set {@link Agent|Agent.isAvatatr} to true. * * @namespace Avatar * From 7f1ae634391eb8dce84f086ad60835b109c93b2f Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 21 Feb 2019 14:30:38 +1300 Subject: [PATCH 04/21] Revise current Avatar API JSDoc --- .../src/avatars/ScriptableAvatar.h | 48 +++++++---------- libraries/avatars/src/AvatarData.h | 54 ++++++++++--------- 2 files changed, 47 insertions(+), 55 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 6b78f666e1..3cf10cc129 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -28,7 +28,8 @@ * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. * @property {Vec3} position - * @property {number} scale - Returns the clamped scale of the avatar. + * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 + * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. * @property {number} density Read-only. * @property {Vec3} handPosition * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. @@ -50,8 +51,9 @@ * @property {number} audioLoudness * @property {number} audioAverageLoudness * @property {string} displayName - * @property {string} sessionDisplayName - Sanitized, defaulted version displayName that is defined by the AvatarMixer - * rather than by Interface clients. The result is unique among all avatars present at the time. + * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the + * avatar mixer rather than by Interface clients. The result is unique among all avatars present on the domain at the + * time. * @property {boolean} lookAtSnappingEnabled * @property {string} skeletonModelURL * @property {AttachmentData[]} attachmentData @@ -102,24 +104,12 @@ public: Q_INVOKABLE AnimationDetails getAnimationDetails(); /**jsdoc - * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc.
- * Get the names of all the joints in the current avatar. - * @function Avatar.getJointNames - * @returns {string[]} The joint names. - * @example Report the names of all the joints in your current avatar. - * print(JSON.stringify(Avatar.getJointNames())); + * @comment Uses the base class's JSDoc. */ Q_INVOKABLE virtual QStringList getJointNames() const override; /**jsdoc - * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc.
- * Get the joint index for a named joint. The joint index value is the position of the joint in the array returned by - * {@link Avatar.getJointNames}. - * @function Avatar.getJointIndex - * @param {string} name - The name of the joint. - * @returns {number} The index of the joint. - * @example Report the index of your avatar's left arm joint. - * print(JSON.stringify(Avatar.getJointIndex("LeftArm")); + * @comment Uses the base class's JSDoc. */ /// Returns the index of the joint with the specified name, or -1 if not found/unknown. Q_INVOKABLE virtual int getJointIndex(const QString& name) const override; @@ -137,39 +127,37 @@ public: void setHasAudioEnabledFaceMovement(bool hasAudioEnabledFaceMovement); bool getHasAudioEnabledFaceMovement() const override { return _headData->getHasAudioEnabledFaceMovement(); } - /**jsdoc - * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc.
- * ####### Also need to resolve with MyAvatar.
- * Potentially Very Expensive. Do not use. + /**jsdoc + * Get the avatar entities as binary data. + *

Warning: Potentially a very expensive call. Do not use if possible.

* @function Avatar.getAvatarEntityData - * @returns {object} + * @returns {AvatarEntityMap} */ Q_INVOKABLE AvatarEntityMap getAvatarEntityData() const override; /**jsdoc - * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc. + * Set the avatar entities from binary data. + *

Warning: Potentially an expensive call. Do not use if possible.

* @function Avatar.setAvatarEntityData - * @param {object} avatarEntityData + * @param {AvatarEntityMap} avatarEntityData */ Q_INVOKABLE void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; /**jsdoc - * ####### TODO: If this override changes the function use @override and do JSDoc here, otherwise @comment that uses base class's JSDoc. - * @function Avatar.updateAvatarEntity - * @param {Uuid} entityID - * @param {string} entityData + * @comment Uses the base class's JSDoc. */ Q_INVOKABLE void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData) override; public slots: /**jsdoc * @function Avatar.update + * @param {number} deltaTime */ void update(float deltatime); /**jsdoc - * @function Avatar.setJointMappingsFromNetworkReply - */ + * @function Avatar.setJointMappingsFromNetworkReply + */ void setJointMappingsFromNetworkReply(); private: diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 7a4d235565..0a5509f46c 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -61,6 +61,10 @@ using AvatarSharedPointer = std::shared_ptr; using AvatarWeakPointer = std::weak_ptr; using AvatarHash = QHash; +/**jsdoc + * An object with the UUIDs of avatar entities as keys and binary blobs, being the entity properties, as values. + * @typedef {Object.>} AvatarEntityMap + */ using AvatarEntityMap = QMap; using PackedAvatarEntityMap = QMap; // similar to AvatarEntityMap, but different internal format using AvatarEntityIDs = QSet; @@ -414,7 +418,8 @@ class AvatarData : public QObject, public SpatiallyNestable { // IMPORTANT: The JSDoc for the following properties should be copied to MyAvatar.h and ScriptableAvatar.h. /* * @property {Vec3} position - * @property {number} scale - Returns the clamped scale of the avatar. + * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 + * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. * @property {number} density Read-only. * @property {Vec3} handPosition * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. @@ -436,8 +441,9 @@ class AvatarData : public QObject, public SpatiallyNestable { * @property {number} audioLoudness * @property {number} audioAverageLoudness * @property {string} displayName - * @property {string} sessionDisplayName - Sanitized, defaulted version displayName that is defined by the AvatarMixer - * rather than by Interface clients. The result is unique among all avatars present at the time. + * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the + * avatar mixer rather than by Interface clients. The result is unique among all avatars present on the domain at the + * time. * @property {boolean} lookAtSnappingEnabled * @property {string} skeletonModelURL * @property {AttachmentData[]} attachmentData @@ -601,18 +607,18 @@ public: virtual bool getHasAudioEnabledFaceMovement() const { return false; } /**jsdoc - * Returns the minimum scale allowed for this avatar in the current domain. + * Get the minimum scale allowed for this avatar in the current domain. * This value can change as the user changes avatars or when changing domains. * @function Avatar.getDomainMinScale - * @returns {number} minimum scale allowed for this avatar in the current domain. + * @returns {number} The minimum scale allowed for this avatar in the current domain. */ Q_INVOKABLE float getDomainMinScale() const; /**jsdoc - * Returns the maximum scale allowed for this avatar in the current domain. + * Get the maximum scale allowed for this avatar in the current domain. * This value can change as the user changes avatars or when changing domains. * @function Avatar.getDomainMaxScale - * @returns {number} maximum scale allowed for this avatar in the current domain. + * @returns {number} The maximum scale allowed for this avatar in the current domain. */ Q_INVOKABLE float getDomainMaxScale() const; @@ -625,18 +631,18 @@ public: virtual bool canMeasureEyeHeight() const { return false; } /**jsdoc - * Provides read only access to the current eye height of the avatar. + * Get the current eye height of the avatar. * This height is only an estimate and might be incorrect for avatars that are missing standard joints. * @function Avatar.getEyeHeight - * @returns {number} Eye height of avatar in meters. + * @returns {number} The eye height of the avatar. */ Q_INVOKABLE virtual float getEyeHeight() const { return _targetScale * getUnscaledEyeHeight(); } /**jsdoc - * Provides read only access to the current height of the avatar. + * Get the current height of the avatar. * This height is only an estimate and might be incorrect for avatars that are missing standard joints. * @function Avatar.getHeight - * @returns {number} Height of avatar in meters. + * @returns {number} The height of the avatar. */ Q_INVOKABLE virtual float getHeight() const; @@ -739,7 +745,7 @@ public: /**jsdoc * Get the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -748,7 +754,7 @@ public: /**jsdoc * Get the translation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointTranslation * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to its parent. @@ -855,7 +861,7 @@ public: /**jsdoc * Get the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {string} name - The name of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -868,7 +874,7 @@ public: /**jsdoc * Get the translation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointTranslation * @param {number} name - The name of the joint. * @returns {Vec3} The translation of the joint relative to its parent. @@ -883,7 +889,7 @@ public: * Get the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. * @function Avatar.getJointRotations * @returns {Quat[]} The rotations of all joints relative to each's parent. The values are in the same order as the array - * returned by {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. + * returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. * @example Report the rotations of all your avatar's joints. * print(JSON.stringify(MyAvatar.getJointRotations())); * @@ -906,7 +912,7 @@ public: * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

* @function Avatar.setJointRotations * @param {Quat[]} jointRotations - The rotations for all joints in the avatar. The values are in the same order as the - * array returned by {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. + * array returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. * @example Set your avatar to its default T-pose then rotate its right arm.
* Avatar in T-pose * // Set all joint translations and rotations to defaults. @@ -965,10 +971,10 @@ public: /**jsdoc * Get the joint index for a named joint. The joint index value is the position of the joint in the array returned by - * {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. + * {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. * @function Avatar.getJointIndex * @param {string} name - The name of the joint. - * @returns {number} The index of the joint. + * @returns {number} The index of the joint if valid, otherwise -1. * @example Report the index of your avatar's left arm joint. * print(JSON.stringify(MyAvatar.getJointIndex("LeftArm")); * @@ -1016,14 +1022,14 @@ public: /**jsdoc * @function Avatar.updateAvatarEntity * @param {Uuid} entityID - * @param {string} entityData + * @param {Array.} entityData */ Q_INVOKABLE virtual void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData); /**jsdoc * @function Avatar.clearAvatarEntity * @param {Uuid} entityID - * @param {boolean} [requiresRemovalFromTree] + * @param {boolean} [requiresRemovalFromTree=true] */ Q_INVOKABLE virtual void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true); @@ -1201,14 +1207,12 @@ public: AABox getDefaultBubbleBox() const; /**jsdoc - * @function Avatar.getAvatarEntityData - * @returns {object} + * @comment Documented in derived classes' JSDoc. */ Q_INVOKABLE virtual AvatarEntityMap getAvatarEntityData() const; /**jsdoc - * @function Avatar.setAvatarEntityData - * @param {object} avatarEntityData + * @comment Documented in derived classes' JSDoc. */ Q_INVOKABLE virtual void setAvatarEntityData(const AvatarEntityMap& avatarEntityData); From 0c59f983daacdd96ab12939e90361ce2a3186756 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 27 Feb 2019 09:34:05 +1300 Subject: [PATCH 05/21] Agent JSDoc tidying --- assignment-client/src/AgentScriptingInterface.h | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/assignment-client/src/AgentScriptingInterface.h b/assignment-client/src/AgentScriptingInterface.h index 1f592a9f18..1242634dd5 100644 --- a/assignment-client/src/AgentScriptingInterface.h +++ b/assignment-client/src/AgentScriptingInterface.h @@ -63,21 +63,27 @@ public: public slots: /**jsdoc - * Set whether or not the script should emulate an avatar. + * Sets whether or not the script should emulate an avatar. * @function Agent.setIsAvatar * @param {boolean} isAvatar - true if the script should act as if an avatar, otherwise false. + * @example Make an assignment client script emulate an avatar. + * (function () { + * Agent.setIsAvatar(true); + * Avatar.displayName = "AC avatar"; + * print("Position: " + JSON.stringify(Avatar.position)); // 0, 0, 0 + * }()); */ void setIsAvatar(bool isAvatar) const { _agent->setIsAvatar(isAvatar); } /**jsdoc - * Check whether or not the script is emulating an avatar. + * Checks whether or not the script is emulating an avatar. * @function Agent.isAvatar * @returns {boolean} true if the script is acting as if an avatar, otherwise false. */ bool isAvatar() const { return _agent->isAvatar(); } /**jsdoc - * Play a sound from the position and with the orientation of the emulated avatar's head. No sound is played unless + * Plays a sound from the position and with the orientation of the emulated avatar's head. No sound is played unless * isAvatar == true. * @function Agent.playAvatarSound * @param {SoundObject} avatarSound - The sound to play. From e79594ef53458f33f63ea5c135b48ce2d9698152 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 27 Feb 2019 09:53:11 +1300 Subject: [PATCH 06/21] Fill in and tidy Avatar JSDoc --- .../src/avatars/ScriptableAvatar.h | 82 ++++-- .../src/avatars-renderer/Avatar.h | 22 +- libraries/avatars/src/AvatarData.cpp | 85 +++++- libraries/avatars/src/AvatarData.h | 277 ++++++++++++------ libraries/shared/src/RegisteredMetaTypes.cpp | 26 +- 5 files changed, 352 insertions(+), 140 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 3cf10cc129..2d8dce23de 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -22,23 +22,27 @@ * The Avatar API is used to manipulate scriptable avatars on the domain. This API is a subset of the * {@link MyAvatar} API. To enable this API, set {@link Agent|Agent.isAvatatr} to true. * + *

For Interface, client entity, and avatar scripts, see {@link MyAvatar}.

+ * * @namespace Avatar * * @hifi-assignment-client * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. - * @property {Vec3} position + * @property {Vec3} position - The position of the avatar. * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. - * @property {number} density Read-only. - * @property {Vec3} handPosition + * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in + * the application of physics. Read-only. + * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar + * but is otherwise not used or changed by Interface. * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. * Yaw is sometimes called "heading". * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is * sometimes called "elevation". * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is * sometimes called "bank". - * @property {Quat} orientation + * @property {Quat} orientation - The orientation of the avatar. * @property {Quat} headOrientation - The orientation of the avatar's head. * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is * sometimes called "elevation". @@ -46,24 +50,31 @@ * head. Yaw is sometimes called "heading". * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is * sometimes called "bank". - * @property {Vec3} velocity - * @property {Vec3} angularVelocity - * @property {number} audioLoudness - * @property {number} audioAverageLoudness - * @property {string} displayName + * @property {Vec3} velocity - The current velocity of the avatar. + * @property {Vec3} angularVelocity - The current angular velocity of the avatar. + * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the + * domain. + * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting + * into the domain. + * @property {string} displayName - The avatar's display name. * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the - * avatar mixer rather than by Interface clients. The result is unique among all avatars present on the domain at the + * avatar mixer rather than by Interface clients. The result is unique among all avatars present in the domain at the * time. - * @property {boolean} lookAtSnappingEnabled - * @property {string} skeletonModelURL - * @property {AttachmentData[]} attachmentData + * @property {boolean} lookAtSnappingEnabled=true - If true, the avatar's eyes snap to look at another avatar's + * eyes if generally in the line of sight and the other avatar also has lookAtSnappingEnabled == true. + * @property {string} skeletonModelURL - The URL of the avatar model's .fst file. + * @property {AttachmentData[]} attachmentData - Information on the attachments worn by the avatar.
+ * Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. - * @property {Uuid} sessionUUID Read-only. - * @property {Mat4} sensorToWorldMatrix Read-only. - * @property {Mat4} controllerLeftHandMatrix Read-only. - * @property {Mat4} controllerRightHandMatrix Read-only. - * @property {number} sensorToWorldScale Read-only. - * + * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. + * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the + * avatar's size, orientation, and position in the virtual world. Read-only. + * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the + * avatar. Read-only. + * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the + * avatar. Read-only. + * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's + * size in the virtual world. Read-only. */ class ScriptableAvatar : public AvatarData, public Dependency { @@ -77,15 +88,17 @@ public: ScriptableAvatar(); /**jsdoc + * Starts playing an animation on the avatar. * @function Avatar.startAnimation - * @param {string} url - * @param {number} [fps=30] - * @param {number} [priority=1] - * @param {boolean} [loop=false] - * @param {boolean} [hold=false] - * @param {number} [firstFrame=0] - * @param {number} [lastFrame=3.403e+38] - * @param {string[]} [maskedJoints=[]] + * @param {string} url - The URL to the animation file. Animation files need to be .FBX format but only need to contain + * the avatar skeleton and animation data. + * @param {number} [fps=30] - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. + * @param {number} [priority=1] - Not used. + * @param {boolean} [loop=false] - true if the animation should loop, false if it shouldn't. + * @param {boolean} [hold=false] - Not used. + * @param {number} [firstFrame=0] - The frame the animation should start at. + * @param {number} [lastFrame=3.403e+38] - The frame the animation should stop at. + * @param {string[]} [maskedJoints=[]] - The names of joints that should not be animated. */ /// Allows scripts to run animations. Q_INVOKABLE void startAnimation(const QString& url, float fps = 30.0f, float priority = 1.0f, bool loop = false, @@ -93,13 +106,15 @@ public: const QStringList& maskedJoints = QStringList()); /**jsdoc + * Stops playing the current animation. * @function Avatar.stopAnimation */ Q_INVOKABLE void stopAnimation(); /**jsdoc + * Gets the details of the current avatar animation that is being or was recently played. * @function Avatar.getAnimationDetails - * @returns {Avatar.AnimationDetails} + * @returns {Avatar.AnimationDetails} The current or recent avatar animation. */ Q_INVOKABLE AnimationDetails getAnimationDetails(); @@ -116,6 +131,9 @@ public: virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override; + /**jsdoc + * @comment Uses the base class's JSDoc. + */ int sendAvatarDataPacket(bool sendAll = false) override; virtual QByteArray toByteArrayStateful(AvatarDataDetail dataDetail, bool dropFaceTracking = false) override; @@ -128,7 +146,7 @@ public: bool getHasAudioEnabledFaceMovement() const override { return _headData->getHasAudioEnabledFaceMovement(); } /**jsdoc - * Get the avatar entities as binary data. + * Gets the avatar entities as binary data. *

Warning: Potentially a very expensive call. Do not use if possible.

* @function Avatar.getAvatarEntityData * @returns {AvatarEntityMap} @@ -136,7 +154,7 @@ public: Q_INVOKABLE AvatarEntityMap getAvatarEntityData() const override; /**jsdoc - * Set the avatar entities from binary data. + * Sets the avatar entities from binary data. *

Warning: Potentially an expensive call. Do not use if possible.

* @function Avatar.setAvatarEntityData * @param {AvatarEntityMap} avatarEntityData @@ -151,12 +169,14 @@ public: public slots: /**jsdoc * @function Avatar.update - * @param {number} deltaTime + * @param {number} deltaTime - Delta time. + * @deprecated This function is deprecated and will be removed. */ void update(float deltatime); /**jsdoc * @function Avatar.setJointMappingsFromNetworkReply + * @deprecated This function is deprecated and will be removed. */ void setJointMappingsFromNetworkReply(); diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 1aa6829160..98aa255641 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -219,7 +219,7 @@ public: * The default pose of the avatar is defined by the position and orientation of all bones * in the avatar's model file. Typically this is a T-pose. * @function MyAvatar.getAbsoluteDefaultJointRotationInObjectFrame - * @param index {number} index number + * @param index {number} -The joint index. * @returns {Quat} The rotation of this joint in avatar coordinates. */ Q_INVOKABLE virtual glm::quat getAbsoluteDefaultJointRotationInObjectFrame(int index) const; @@ -229,7 +229,7 @@ public: * The default pose of the avatar is defined by the position and orientation of all bones * in the avatar's model file. Typically this is a T-pose. * @function MyAvatar.getAbsoluteDefaultJointTranslationInObjectFrame - * @param index {number} index number + * @param index {number} - The joint index. * @returns {Vec3} The position of this joint in avatar coordinates. */ Q_INVOKABLE virtual glm::vec3 getAbsoluteDefaultJointTranslationInObjectFrame(int index) const; @@ -238,7 +238,25 @@ public: virtual glm::vec3 getAbsoluteJointScaleInObjectFrame(int index) const override; virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override; virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override; + + /**jsdoc + * Sets the rotation of a joint relative to the avatar. + *

Warning: Not able to be used in the MyAvatar API.

+ * @function MyAvatar.setAbsoluteJointRotationInObjectFrame + * @param {number} index - The index of the joint. Not used. + * @param {Quat} rotation - The rotation of the joint relative to the avatar. Not used. + * @returns {boolean} false. + */ virtual bool setAbsoluteJointRotationInObjectFrame(int index, const glm::quat& rotation) override { return false; } + + /**jsdoc + * Sets the translation of a joint relative to the avatar. + *

Warning: Not able to be used in the MyAvatar API.

+ * @function MyAvatar.setAbsoluteJointTranslationInObjectFrame + * @param {number} index - The index of the joint. Not used. + * @param {Vec3} translation - The translation of the joint relative to the avatar. Not used. + * @returns {boolean} false. + */ virtual bool setAbsoluteJointTranslationInObjectFrame(int index, const glm::vec3& translation) override { return false; } // world-space to avatar-space rigconversion functions diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index c733cfa291..88949900ce 100755 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -1425,6 +1425,47 @@ int AvatarData::parseDataFromBuffer(const QByteArray& buffer) { return numBytesRead; } +/**jsdoc + * The avatar mixer data comprises different types of data, with the data rates of each being tracked in kbps. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Rate NameDescription
"globalPosition"Incoming global position.
"localPosition"Incoming local position.
"avatarBoundingBox"Incoming avatar bounding box.
"avatarOrientation"Incoming avatar orientation.
"avatarScale"Incoming avatar scale.
"lookAtPosition"Incoming look-at position.
"audioLoudness"Incoming audio loudness.
"sensorToWorkMatrix"Incoming sensor-to-world matrix.
"additionalFlags"Incoming additional avatar flags.
"parentInfo"Incoming parent information.
"faceTracker"Incoming face tracker data.
"jointData"Incoming joint data.
"jointDefaultPoseFlagsRate"Incoming joint default pose flags.
"farGrabJointRate"Incoming far grab joint.
"globalPositionOutbound"Outgoing global position.
"localPositionOutbound"Outgoing local position.
"avatarBoundingBoxOutbound"Outgoing avatar bounding box.
"avatarOrientationOutbound"Outgoing avatar orientation.
"avatarScaleOutbound"Outgoing avatar scale.
"lookAtPositionOutbound"Outgoing look-at position.
"audioLoudnessOutbound"Outgoing audio loudness.
"sensorToWorkMatrixOutbound"Outgoing sensor-to-world matrix.
"additionalFlagsOutbound"Outgoing additional avatar flags.
"parentInfoOutbound"Outgoing parent information.
"faceTrackerOutbound"Outgoing face tracker data.
"jointDataOutbound"Outgoing joint data.
"jointDefaultPoseFlagsOutbound"Outgoing joint default pose flags.
""When no rate name is specified, the total incoming data rate is provided.
+ * + * @typedef {string} AvatarDataRate + */ float AvatarData::getDataRate(const QString& rateName) const { if (rateName == "") { return _parseBufferRate.rate() / BYTES_PER_KILOBIT; @@ -1486,6 +1527,35 @@ float AvatarData::getDataRate(const QString& rateName) const { return 0.0f; } +/**jsdoc + * The avatar mixer data comprises different types of data updated at different rates, in Hz. + * + * + * + * + * + * + + * + * + * + * + * + * + * + * + * + * + * + * + * + + * + * + *
Rate NameDescription
"globalPosition"Global position.
"localPosition"Local position.
"avatarBoundingBox"Avatar bounding box.
"avatarOrientation"Avatar orientation.
"avatarScale"Avatar scale.
"lookAtPosition"Look-at position.
"audioLoudness"Audio loudness.
"sensorToWorkMatrix"Sensor-to-world matrix.
"additionalFlags"Additional avatar flags.
"parentInfo"Parent information.
"faceTracker"Face tracker data.
"jointData"Joint data.
"farGrabJointData"Far grab joint data.
""When no rate name is specified, the overall update rate is provided.
+ * + * @typedef {string} AvatarUpdateRate + */ float AvatarData::getUpdateRate(const QString& rateName) const { if (rateName == "") { return _parseBufferUpdateRate.rate(); @@ -2721,13 +2791,16 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const } /**jsdoc + * Information on an attachment worn by the avatar. * @typedef {object} AttachmentData - * @property {string} modelUrl - * @property {string} jointName - * @property {Vec3} translation - * @property {Vec3} rotation - * @property {number} scale - * @property {boolean} soft + * @property {string} modelUrl - The URL of the model file. Models can be .FBX or .OBJ format. + * @property {string} jointName - The offset to apply to the model relative to the joint position. + * @property {Vec3} translation - The offset from the joint that the attachment is positioned at. + * @property {Vec3} rotation - The rotation applied to the model relative to the joint orientation. + * @property {number} scale - The scale applied to the attachment model. + * @property {boolean} soft - If true and the model has a skeleton, the bones of the attached model's skeleton are + * rotated to fit the avatar's current pose. If true, the translation, rotation, and + * scale parameters are ignored. */ QVariant AttachmentData::toVariant() const { QVariantMap result; diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 0a5509f46c..a20518076f 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -116,7 +116,24 @@ const int PROCEDURAL_EYE_FACE_MOVEMENT = 9; // 10th bit const int PROCEDURAL_BLINK_FACE_MOVEMENT = 10; // 11th bit const int COLLIDE_WITH_OTHER_AVATARS = 11; // 12th bit - +/**jsdoc + *

The pointing state of the hands is specified by the following values: +

+ * + * + * + * + * + * + * + * + * + * + *
ValueDescription
0No hand is pointing.
1The left hand is pointing.
2The right hand is pointing.
4It is the index finger that is pointing.
+ *

The values for the hand states are added together to give the HandState value. For example, if the left + * hand's finger is pointing, the value is 1 + 4 == 5. + * @typedef {number} HandState + */ const char HAND_STATE_NULL = 0; const char LEFT_HAND_POINTING_FLAG = 1; const char RIGHT_HAND_POINTING_FLAG = 2; @@ -417,18 +434,20 @@ class AvatarData : public QObject, public SpatiallyNestable { // IMPORTANT: The JSDoc for the following properties should be copied to MyAvatar.h and ScriptableAvatar.h. /* - * @property {Vec3} position + * @property {Vec3} position - The position of the avatar. * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. - * @property {number} density Read-only. - * @property {Vec3} handPosition + * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in + * the application of physics. Read-only. + * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar + * but is otherwise not used or changed by Interface. * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. * Yaw is sometimes called "heading". * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is * sometimes called "elevation". * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is * sometimes called "bank". - * @property {Quat} orientation + * @property {Quat} orientation - The orientation of the avatar. * @property {Quat} headOrientation - The orientation of the avatar's head. * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is * sometimes called "elevation". @@ -436,23 +455,31 @@ class AvatarData : public QObject, public SpatiallyNestable { * head. Yaw is sometimes called "heading". * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is * sometimes called "bank". - * @property {Vec3} velocity - * @property {Vec3} angularVelocity - * @property {number} audioLoudness - * @property {number} audioAverageLoudness - * @property {string} displayName + * @property {Vec3} velocity - The current velocity of the avatar. + * @property {Vec3} angularVelocity - The current angular velocity of the avatar. + * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the + * domain. + * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting + * into the domain. + * @property {string} displayName - The avatar's display name. * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the - * avatar mixer rather than by Interface clients. The result is unique among all avatars present on the domain at the + * avatar mixer rather than by Interface clients. The result is unique among all avatars present in the domain at the * time. - * @property {boolean} lookAtSnappingEnabled - * @property {string} skeletonModelURL - * @property {AttachmentData[]} attachmentData + * @property {boolean} lookAtSnappingEnabled=true - If true, the avatar's eyes snap to look at another avatar's + * eyes if generally in the line of sight and the other avatar also has lookAtSnappingEnabled == true. + * @property {string} skeletonModelURL - The URL of the avatar model's .fst file. + * @property {AttachmentData[]} attachmentData - Information on the attachments worn by the avatar.
+ * Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. - * @property {Uuid} sessionUUID Read-only. - * @property {Mat4} sensorToWorldMatrix Read-only. - * @property {Mat4} controllerLeftHandMatrix Read-only. - * @property {Mat4} controllerRightHandMatrix Read-only. - * @property {number} sensorToWorldScale Read-only. + * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. + * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the + * avatar's size, orientation, and position in the virtual world. Read-only. + * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the + * avatar. Read-only. + * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the + * avatar. Read-only. + * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's + * size in the virtual world. Read-only. */ Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) Q_PROPERTY(float scale READ getDomainLimitedScale WRITE setTargetScale) @@ -607,7 +634,7 @@ public: virtual bool getHasAudioEnabledFaceMovement() const { return false; } /**jsdoc - * Get the minimum scale allowed for this avatar in the current domain. + * Gets the minimum scale allowed for this avatar in the current domain. * This value can change as the user changes avatars or when changing domains. * @function Avatar.getDomainMinScale * @returns {number} The minimum scale allowed for this avatar in the current domain. @@ -615,7 +642,7 @@ public: Q_INVOKABLE float getDomainMinScale() const; /**jsdoc - * Get the maximum scale allowed for this avatar in the current domain. + * Gets the maximum scale allowed for this avatar in the current domain. * This value can change as the user changes avatars or when changing domains. * @function Avatar.getDomainMaxScale * @returns {number} The maximum scale allowed for this avatar in the current domain. @@ -631,7 +658,7 @@ public: virtual bool canMeasureEyeHeight() const { return false; } /**jsdoc - * Get the current eye height of the avatar. + * Gets the current eye height of the avatar. * This height is only an estimate and might be incorrect for avatars that are missing standard joints. * @function Avatar.getEyeHeight * @returns {number} The eye height of the avatar. @@ -639,7 +666,7 @@ public: Q_INVOKABLE virtual float getEyeHeight() const { return _targetScale * getUnscaledEyeHeight(); } /**jsdoc - * Get the current height of the avatar. + * Gets the current height of the avatar. * This height is only an estimate and might be incorrect for avatars that are missing standard joints. * @function Avatar.getHeight * @returns {number} The height of the avatar. @@ -652,27 +679,33 @@ public: void setDomainMaximumHeight(float domainMaximumHeight); /**jsdoc + * Sets the pointing state of the hands to control where the laser emanates from. If the right index finger is pointing, the + * laser emanates from the tip of that finger, otherwise it emanates from the palm. * @function Avatar.setHandState - * @param {string} state + * @param {HandState} state - The pointing state of the hand. */ Q_INVOKABLE void setHandState(char s) { _handState = s; } /**jsdoc + * Gets the pointing state of the hands to control where the laser emanates from. If the right index finger is pointing, the + * laser emanates from the tip of that finger, otherwise it emanates from the palm. * @function Avatar.getHandState - * @returns {string} + * @returns {HandState} The pointing state of the hand. */ Q_INVOKABLE char getHandState() const { return _handState; } const QVector& getRawJointData() const { return _jointData; } /**jsdoc + * Sets joint translations and rotations from raw joint data. * @function Avatar.setRawJointData - * @param {JointData[]} data + * @param {JointData[]} data - The raw joint data. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE void setRawJointData(QVector data); /**jsdoc - * Set a specific joint's rotation and position relative to its parent. + * Sets a specific joint's rotation and position relative to its parent. *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate @@ -702,7 +735,7 @@ public: Q_INVOKABLE virtual void setJointData(int index, const glm::quat& rotation, const glm::vec3& translation); /**jsdoc - * Set a specific joint's rotation relative to its parent. + * Sets a specific joint's rotation relative to its parent. *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate @@ -715,7 +748,7 @@ public: Q_INVOKABLE virtual void setJointRotation(int index, const glm::quat& rotation); /**jsdoc - * Set a specific joint's translation relative to its parent. + * Sets a specific joint's translation relative to its parent. *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate @@ -728,7 +761,7 @@ public: Q_INVOKABLE virtual void setJointTranslation(int index, const glm::vec3& translation); /**jsdoc - * Clear joint translations and rotations set by script for a specific joint. This restores all motion from the default + * Clears joint translations and rotations set by script for a specific joint. This restores all motion from the default * animation system including inverse kinematics for that joint. *

Note: This is slightly faster than the function variation that specifies the joint name.

* @function Avatar.clearJointData @@ -737,14 +770,15 @@ public: Q_INVOKABLE virtual void clearJointData(int index); /**jsdoc + * Checks that the data for a joint are valid. * @function Avatar.isJointDataValid - * @param {number} index - * @returns {boolean} + * @param {number} index - The index of the joint. + * @returns {boolean} true if the joint data is valid, false if not. */ Q_INVOKABLE bool isJointDataValid(int index) const; /**jsdoc - * Get the rotation of a joint relative to its parent. For information on the joint hierarchy used, see + * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. * @function Avatar.getJointRotation * @param {number} index - The index of the joint. @@ -753,7 +787,7 @@ public: Q_INVOKABLE virtual glm::quat getJointRotation(int index) const; /**jsdoc - * Get the translation of a joint relative to its parent. For information on the joint hierarchy used, see + * Gets the translation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. * @function Avatar.getJointTranslation * @param {number} index - The index of the joint. @@ -762,7 +796,7 @@ public: Q_INVOKABLE virtual glm::vec3 getJointTranslation(int index) const; /**jsdoc - * Set a specific joint's rotation and position relative to its parent. + * Sets a specific joint's rotation and position relative to its parent. *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate @@ -776,7 +810,7 @@ public: Q_INVOKABLE virtual void setJointData(const QString& name, const glm::quat& rotation, const glm::vec3& translation); /**jsdoc - * Set a specific joint's rotation relative to its parent. + * Sets a specific joint's rotation relative to its parent. *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate @@ -809,7 +843,7 @@ public: Q_INVOKABLE virtual void setJointRotation(const QString& name, const glm::quat& rotation); /**jsdoc - * Set a specific joint's translation relative to its parent. + * Sets a specific joint's translation relative to its parent. *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate @@ -834,7 +868,7 @@ public: Q_INVOKABLE virtual void setJointTranslation(const QString& name, const glm::vec3& translation); /**jsdoc - * Clear joint translations and rotations set by script for a specific joint. This restores all motion from the default + * Clears joint translations and rotations set by script for a specific joint. This restores all motion from the default * animation system including inverse kinematics for that joint. *

Note: This is slightly slower than the function variation that specifies the joint index.

* @function Avatar.clearJointData @@ -853,14 +887,15 @@ public: Q_INVOKABLE virtual void clearJointData(const QString& name); /**jsdoc + * Checks that the data for a joint are valid. * @function Avatar.isJointDataValid - * @param {string} name - * @returns {boolean} + * @param {string} name - The name of the joint. + * @returns {boolean} true if the joint data is valid, false if not. */ Q_INVOKABLE virtual bool isJointDataValid(const QString& name) const; /**jsdoc - * Get the rotation of a joint relative to its parent. For information on the joint hierarchy used, see + * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. * @function Avatar.getJointRotation * @param {string} name - The name of the joint. @@ -873,7 +908,7 @@ public: Q_INVOKABLE virtual glm::quat getJointRotation(const QString& name) const; /**jsdoc - * Get the translation of a joint relative to its parent. For information on the joint hierarchy used, see + * Gets the translation of a joint relative to its parent. For information on the joint hierarchy used, see * Avatar Standards. * @function Avatar.getJointTranslation * @param {number} name - The name of the joint. @@ -886,7 +921,7 @@ public: Q_INVOKABLE virtual glm::vec3 getJointTranslation(const QString& name) const; /**jsdoc - * Get the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. + * Gets the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. * @function Avatar.getJointRotations * @returns {Quat[]} The rotations of all joints relative to each's parent. The values are in the same order as the array * returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. @@ -898,13 +933,15 @@ public: Q_INVOKABLE virtual QVector getJointRotations() const; /**jsdoc + * Gets the translations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. * @function Avatar.getJointTranslations - * @returns {Vec3[]} + * @returns {Vec3[]} The translations of all joints relative to each's parent. The values are in the same order as the array + * returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. */ Q_INVOKABLE virtual QVector getJointTranslations() const; /**jsdoc - * Set the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. + * Sets the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate @@ -942,13 +979,20 @@ public: Q_INVOKABLE virtual void setJointRotations(const QVector& jointRotations); /**jsdoc + * Sets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint. + *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse + * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, + * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate + * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set + * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

* @function Avatar.setJointTranslations - * @param {Vec3[]} translations + * @param {Vec3[]} translations - The translations for all joints in the avatar. The values are in the same order as the + * array returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. */ Q_INVOKABLE virtual void setJointTranslations(const QVector& jointTranslations); /**jsdoc - * Clear all joint translations and rotations that have been set by script. This restores all motion from the default + * Clears all joint translations and rotations that have been set by script. This restores all motion from the default * animation system including inverse kinematics for all joints. * @function Avatar.clearJointsData * @example Set your avatar to it's default T-pose for a while. @@ -970,7 +1014,7 @@ public: Q_INVOKABLE virtual void clearJointsData(); /**jsdoc - * Get the joint index for a named joint. The joint index value is the position of the joint in the array returned by + * Gets the joint index for a named joint. The joint index value is the position of the joint in the array returned by * {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. * @function Avatar.getJointIndex * @param {string} name - The name of the joint. @@ -984,7 +1028,7 @@ public: Q_INVOKABLE virtual int getJointIndex(const QString& name) const; /**jsdoc - * Get the names of all the joints in the current avatar. + * Gets the names of all the joints in the current avatar. * @function Avatar.getJointNames * @returns {string[]} The joint names. * @example Report the names of all the joints in your current avatar. @@ -996,23 +1040,32 @@ public: /**jsdoc + * Sets the value of a blendshape to animate your avatar's face. To enable other users to see the resulting animation of + * your avatar's face, use {@link Avatar.setForceFaceTrackerConnected} or {@link MyAvatar.setForceFaceTrackerConnected}. * @function Avatar.setBlendshape - * @param {string} name - * @param {number} value + * @param {string} name - The name of the blendshape, per the + * {@link https://docs.highfidelity.com/create/avatars/create-avatars/avatar-standards.html#blendshapes Avatar Standards}. + * @param {number} value - A value between 0.0 and 1.0. */ Q_INVOKABLE void setBlendshape(QString name, float val) { _headData->setBlendshape(name, val); } /**jsdoc + * Gets information about the models currently attached to your avatar. * @function Avatar.getAttachmentsVariant - * @returns {object} + * @returns {AttachmentData[]} Information about all models attached to your avatar. + * @deprecated Use avatar entities instead. */ // FIXME: Can this name be improved? Can it be deprecated? Q_INVOKABLE virtual QVariantList getAttachmentsVariant() const; /**jsdoc + * Sets all models currently attached to your avatar. For example, if you retrieve attachment data using + * {@link MyAvatar.getAttachmentsVariant} or {@link Avatar.getAttachmentsVariant}, make changes to it, and then want to + * update your avatar's attachments per the changed data. * @function Avatar.setAttachmentsVariant - * @param {object} variant + * @param {AttachmentData[]} variant - The attachment data defining the models to have attached to your avatar. + * @deprecated Use avatar entities instead. */ // FIXME: Can this name be improved? Can it be deprecated? Q_INVOKABLE virtual void setAttachmentsVariant(const QVariantList& variant); @@ -1021,22 +1074,27 @@ public: /**jsdoc * @function Avatar.updateAvatarEntity - * @param {Uuid} entityID - * @param {Array.} entityData + * @param {Uuid} entityID - The entity ID. + * @param {Array.} entityData - Entity data. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE virtual void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData); /**jsdoc * @function Avatar.clearAvatarEntity - * @param {Uuid} entityID - * @param {boolean} [requiresRemovalFromTree=true] + * @param {Uuid} entityID - The entity ID. + * @param {boolean} [requiresRemovalFromTree=true] - Requires removal from tree. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE virtual void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true); /**jsdoc + * Enables blendshapes set using {@link Avatar.setBlendshape} or {@link MyAvatar.setBlendshape} to be transmitted to other + * users so that they can see the animation of your avatar's face. * @function Avatar.setForceFaceTrackerConnected - * @param {boolean} connected + * @param {boolean} connected - true to enable blendshape changes to be transmitted to other users, + * false to disable. */ Q_INVOKABLE void setForceFaceTrackerConnected(bool connected) { _forceFaceTrackerConnected = connected; } @@ -1087,9 +1145,10 @@ public: } /**jsdoc - * Get information about all models currently attached to your avatar. + * Gets information about the models currently attached to your avatar. * @function Avatar.getAttachmentData * @returns {AttachmentData[]} Information about all models attached to your avatar. + * @deprecated Use avatar entities instead. * @example Report the URLs of all current attachments. * var attachments = MyAvatar.getaAttachmentData(); * for (var i = 0; i < attachments.length; i++) { @@ -1101,12 +1160,13 @@ public: Q_INVOKABLE virtual QVector getAttachmentData() const; /**jsdoc - * Set all models currently attached to your avatar. For example, if you retrieve attachment data using + * Sets all models currently attached to your avatar. For example, if you retrieve attachment data using * {@link MyAvatar.getAttachmentData} or {@link Avatar.getAttachmentData}, make changes to it, and then want to update your avatar's attachments per the * changed data. You can also remove all attachments by using setting attachmentData to null. * @function Avatar.setAttachmentData - * @param {AttachmentData[]} attachmentData - The attachment data defining the models to have attached to your avatar. Use + * @param {AttachmentData[]} attachmentData - The attachment data defining the models to have attached to your avatar. Use * null to remove all attachments. + * @deprecated Use avatar entities instead. * @example Remove a hat attachment if your avatar is wearing it. * var hatURL = "https://s3.amazonaws.com/hifi-public/tony/cowboy-hat.fbx"; * var attachments = MyAvatar.getAttachmentData(); @@ -1124,7 +1184,7 @@ public: Q_INVOKABLE virtual void setAttachmentData(const QVector& attachmentData); /**jsdoc - * Attach a model to your avatar. For example, you can give your avatar a hat to wear, a guitar to hold, or a surfboard to + * Attaches a model to your avatar. For example, you can give your avatar a hat to wear, a guitar to hold, or a surfboard to * stand on. *

Note: Attached models are models only; they are not entities and can not be manipulated using the {@link Entities} API. * Nor can you use this function to attach an entity (such as a sphere or a box) to your avatar.

@@ -1136,12 +1196,14 @@ public: * @param {Quat} [rotation=Quat.IDENTITY] - The rotation to apply to the model relative to the joint orientation. * @param {number} [scale=1.0] - The scale to apply to the model. * @param {boolean} [isSoft=false] - If the model has a skeleton, set this to true so that the bones of the - * attached model's skeleton are be rotated to fit the avatar's current pose. isSoft is used, for example, + * attached model's skeleton are rotated to fit the avatar's current pose. isSoft is used, for example, * to have clothing that moves with the avatar.
* If true, the translation, rotation, and scale parameters are * ignored. - * @param {boolean} [allowDuplicates=false] - * @param {boolean} [useSaved=true] + * @param {boolean} [allowDuplicates=false] - If true then more than one copy of any particular model may be + * attached to the same joint; if false then the same model cannot be attached to the same joint. + * @param {boolean} [useSaved=true] - Not used. + * @deprecated Use avatar entities instead. * @example Attach a cowboy hat to your avatar's head. * var attachment = { * modelURL: "https://s3.amazonaws.com/hifi-public/tony/cowboy-hat.fbx", @@ -1167,20 +1229,22 @@ public: bool allowDuplicates = false, bool useSaved = true); /**jsdoc - * Detach the most recently attached instance of a particular model from either a specific joint or any joint. + * Detaches the most recently attached instance of a particular model from either a specific joint or any joint. * @function Avatar.detachOne * @param {string} modelURL - The URL of the model to detach. * @param {string} [jointName=""] - The name of the joint to detach the model from. If "", then the most * recently attached model is removed from which ever joint it was attached to. + * @deprecated Use avatar entities instead. */ Q_INVOKABLE virtual void detachOne(const QString& modelURL, const QString& jointName = QString()); /**jsdoc - * Detach all instances of a particular model from either a specific joint or all joints. + * Detaches all instances of a particular model from either a specific joint or all joints. * @function Avatar.detachAll * @param {string} modelURL - The URL of the model to detach. * @param {string} [jointName=""] - The name of the joint to detach the model from. If "", then the model is * detached from all joints. + * @deprecated Use avatar entities instead. */ Q_INVOKABLE virtual void detachAll(const QString& modelURL, const QString& jointName = QString()); @@ -1220,45 +1284,53 @@ public: AvatarEntityIDs getAndClearRecentlyRemovedIDs(); /**jsdoc + * Gets the transform from the user's real world to the avatar's size, orientation, and position in the virtual world. * @function Avatar.getSensorToWorldMatrix - * @returns {Mat4} + * @returns {Mat4} The scale, rotation, and translation transform from the user's real world to the avatar's size, + * orientation, and position in the virtual world. */ // thread safe Q_INVOKABLE glm::mat4 getSensorToWorldMatrix() const; /**jsdoc + * Gets the scale that transforms dimensions in the user's real world to the avatar's size in the virtual world. * @function Avatar.getSensorToWorldScale - * @returns {number} + * @returns {number} The scale that transforms dimensions in the user's real world to the avatar's size in the virtual + * world. */ // thread safe Q_INVOKABLE float getSensorToWorldScale() const; /**jsdoc + * Gets the rotation and translation of the left hand controller relative to the avatar. * @function Avatar.getControllerLeftHandMatrix - * @returns {Mat4} + * @returns {Mat4} The rotation and translation of the left hand controller relative to the avatar. */ // thread safe Q_INVOKABLE glm::mat4 getControllerLeftHandMatrix() const; /**jsdoc + * Gets the rotation and translation of the right hand controller relative to the avatar. * @function Avatar.getControllerRightHandMatrix - * @returns {Mat4} + * @returns {Mat4} The rotation and translation of the right hand controller relative to the avatar. */ // thread safe Q_INVOKABLE glm::mat4 getControllerRightHandMatrix() const; /**jsdoc + * Gets the amount of avatar mixer data being generated by the avatar. * @function Avatar.getDataRate - * @param {string} [rateName=""] - * @returns {number} + * @param {AvatarDataRate} [rateName=""] - The type of avatar mixer data to get the data rate of. + * @returns {number} The data rate in kbps. */ Q_INVOKABLE float getDataRate(const QString& rateName = QString("")) const; /**jsdoc + * Gets the update rate of avatar mixer data being generated by the avatar. * @function Avatar.getUpdateRate - * @param {string} [rateName=""] - * @returns {number} + * @param {AvatarUpdateRate} [rateName=""] - The type of avatar mixer data to get the update rate of. + * @returns {number} The update rate in Hz. */ Q_INVOKABLE float getUpdateRate(const QString& rateName = QString("")) const; @@ -1304,31 +1376,36 @@ public: signals: /**jsdoc + * Triggered when the avatar's displayName property value changes. * @function Avatar.displayNameChanged * @returns {Signal} */ void displayNameChanged(); /**jsdoc + * Triggered when the avattr's sessionDisplayName property value changes. * @function Avatar.sessionDisplayNameChanged * @returns {Signal} */ void sessionDisplayNameChanged(); /**jsdoc + * Triggered when the avatar's skeletonModelURL property value changes. * @function Avatar.skeletonModelURLChanged * @returns {Signal} */ void skeletonModelURLChanged(); /**jsdoc + * Triggered when the avatar's lookAtSnappingEnabled property value changes. * @function Avatar.lookAtSnappingChanged - * @param {boolean} enabled + * @param {boolean} enabled - true if look-at snapping is enabled, false if not. * @returns {Signal} */ void lookAtSnappingChanged(bool enabled); /**jsdoc + * Triggered when the avatar's sessionUUID property value changes. * @function Avatar.sessionUUIDChanged * @returns {Signal} */ @@ -1338,18 +1415,23 @@ public slots: /**jsdoc * @function Avatar.sendAvatarDataPacket - * @param {boolean} [sendAll=false] + * @param {boolean} [sendAll=false] - Send all. + * @returns {number} + * @deprecated This function is deprecated and will be removed. */ virtual int sendAvatarDataPacket(bool sendAll = false); /**jsdoc * @function Avatar.sendIdentityPacket + * @returns {number} + * @deprecated This function is deprecated and will be removed. */ int sendIdentityPacket(); /**jsdoc * @function Avatar.setSessionUUID - * @param {Uuid} sessionUUID + * @param {Uuid} sessionUUID - Session UUID. + * @deprecated This function is deprecated and will be removed. */ virtual void setSessionUUID(const QUuid& sessionUUID) { if (sessionUUID != getID()) { @@ -1362,44 +1444,61 @@ public slots: } } + /**jsdoc + * Gets the rotation of a joint relative to the avatar. + *

Warning: Not able to be used in the Avatar API.

* @function Avatar.getAbsoluteJointRotationInObjectFrame - * @param {number} index - * @returns {Quat} + * @param {number} index - The index of the joint. Not used. + * @returns {Quat} Quat.IDENTITY. */ virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override; /**jsdoc + * Gets the translation of a joint relative to the avatar. + *

Warning: Not able to be used in the Avatar API.

* @function Avatar.getAbsoluteJointTranslationInObjectFrame - * @param {number} index - * @returns {Vec3} + * @param {number} index - The index of the joint. Not used. + * @returns {Vec3} Vec3.ZERO. */ virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override; /**jsdoc + * Sets the rotation of a joint relative to the avatar. + *

Warning: Not able to be used in the Avatar API.

* @function Avatar.setAbsoluteJointRotationInObjectFrame - * @param {number} index - * @param {Quat} rotation - * @returns {boolean} + * @param {number} index - The index of the joint. Not used. + * @param {Quat} rotation - The rotation of the joint relative to the avatar. Not used. + * @returns {boolean} false. */ virtual bool setAbsoluteJointRotationInObjectFrame(int index, const glm::quat& rotation) override { return false; } /**jsdoc + * Sets the translation of a joint relative to the avatar. + *

Warning: Not able to be used in the Avatar API.

* @function Avatar.setAbsoluteJointTranslationInObjectFrame - * @param {number} index - * @param {Vec3} translation - * @returns {boolean} + * @param {number} index - The index of the joint. Not used. + * @param {Vec3} translation - The translation of the joint relative to the avatar. Not used. + * @returns {boolean} false. */ virtual bool setAbsoluteJointTranslationInObjectFrame(int index, const glm::vec3& translation) override { return false; } /**jsdoc + * Gets the target scale of the avatar without any restrictions on permissible values imposed by the domain. In contrast, the + * scale property's value may be limited by the domain's settings. * @function Avatar.getTargetScale - * @returns {number} + * @returns {number} The target scale of the avatar. + * @example Compare the target and current avatar scales. + * print("Current avatar scale: " + MyAvatar.scale); + * print("Target avatar scale: " + MyAvatar.getTargetScale()); + * + * // Note: If using from the Avatar API, replace all occurrences of "MyAvatar" with "Avatar". */ float getTargetScale() const { return _targetScale; } // why is this a slot? /**jsdoc * @function Avatar.resetLastSent + * @deprecated This function is deprecated and will be removed. */ void resetLastSent() { _lastToByteArray = 0; } diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index ec1126c92f..614858a77d 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -1147,19 +1147,21 @@ AnimationDetails::AnimationDetails(QString role, QUrl url, float fps, float prio } /**jsdoc + * The details of an animation that is playing. * @typedef {object} Avatar.AnimationDetails - * @property {string} role - * @property {string} url - * @property {number} fps - * @property {number} priority - * @property {boolean} loop - * @property {boolean} hold - * @property {boolean} startAutomatically - * @property {number} firstFrame - * @property {number} lastFrame - * @property {boolean} running - * @property {number} currentFrame - * @property {boolean} allowTranslation + * @property {string} role - Not used. + * @property {string} url - The URL to the animation file. Animation files need to be in .FBX format but only need to contain +* the avatar skeleton and animation data. + * @property {number} fps - The frames per second(FPS) rate for the animation playback. 30 FPS is normal speed. + * @property {number} priority - Not used. + * @property {boolean} loop - true if the animation should loop, false if it shouldn't. + * @property {boolean} hold - Not used. + * @property {number} firstFrame - The frame the animation should start at. + * @property {number} lastFrame - The frame the animation should stop at. + * @property {boolean} running - Not used. + * @property {number} currentFrame - The current frame being played. + * @property {boolean} startAutomatically - Not used. + * @property {boolean} allowTranslation - Not used. */ QScriptValue animationDetailsToScriptValue(QScriptEngine* engine, const AnimationDetails& details) { QScriptValue obj = engine->newObject(); From aa53ab7492b15f183754fc11f7886539364ae29a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 27 Feb 2019 09:54:11 +1300 Subject: [PATCH 07/21] Distinguish between Mat4 type and Mat4 API in JSDoc --- libraries/script-engine/src/Mat4.h | 33 +++++++++++----------- libraries/shared/src/RegisteredMetaTypes.h | 21 ++++++++++++++ 2 files changed, 38 insertions(+), 16 deletions(-) diff --git a/libraries/script-engine/src/Mat4.h b/libraries/script-engine/src/Mat4.h index 7ad77b9b24..0cdc70e79c 100644 --- a/libraries/script-engine/src/Mat4.h +++ b/libraries/script-engine/src/Mat4.h @@ -23,6 +23,7 @@ /**jsdoc * @namespace Mat4 + * @variation 0 * * @hifi-interface * @hifi-client-entity @@ -38,7 +39,7 @@ class Mat4 : public QObject, protected QScriptable { public slots: /**jsdoc - * @function Mat4.multiply + * @function Mat4(0).multiply * @param {Mat4} m1 * @param {Mat4} m2 * @returns {Mat4} @@ -47,7 +48,7 @@ public slots: /**jsdoc - * @function Mat4.createFromRotAndTrans + * @function Mat4(0).createFromRotAndTrans * @param {Quat} rot * @param {Vec3} trans * @returns {Mat4} @@ -55,7 +56,7 @@ public slots: glm::mat4 createFromRotAndTrans(const glm::quat& rot, const glm::vec3& trans) const; /**jsdoc - * @function Mat4.createFromScaleRotAndTrans + * @function Mat4(0).createFromScaleRotAndTrans * @param {Vec3} scale * @param {Quat} rot * @param {Vec3} trans @@ -64,7 +65,7 @@ public slots: glm::mat4 createFromScaleRotAndTrans(const glm::vec3& scale, const glm::quat& rot, const glm::vec3& trans) const; /**jsdoc - * @function Mat4.createFromColumns + * @function Mat4(0).createFromColumns * @param {Vec4} col0 * @param {Vec4} col1 * @param {Vec4} col2 @@ -74,7 +75,7 @@ public slots: glm::mat4 createFromColumns(const glm::vec4& col0, const glm::vec4& col1, const glm::vec4& col2, const glm::vec4& col3) const; /**jsdoc - * @function Mat4.createFromArray + * @function Mat4(0).createFromArray * @param {number[]} numbers * @returns {Mat4} */ @@ -82,21 +83,21 @@ public slots: /**jsdoc - * @function Mat4.extractTranslation + * @function Mat4(0).extractTranslation * @param {Mat4} m * @returns {Vec3} */ glm::vec3 extractTranslation(const glm::mat4& m) const; /**jsdoc - * @function Mat4.extractRotation + * @function Mat4(0).extractRotation * @param {Mat4} m * @returns {Vec3} */ glm::quat extractRotation(const glm::mat4& m) const; /**jsdoc - * @function Mat4.extractScale + * @function Mat4(0).extractScale * @param {Mat4} m * @returns {Vec3} */ @@ -104,7 +105,7 @@ public slots: /**jsdoc - * @function Mat4.transformPoint + * @function Mat4(0).transformPoint * @param {Mat4} m * @param {Vec3} point * @returns {Vec3} @@ -112,7 +113,7 @@ public slots: glm::vec3 transformPoint(const glm::mat4& m, const glm::vec3& point) const; /**jsdoc - * @function Mat4.transformVector + * @function Mat4(0).transformVector * @param {Mat4} m * @param {Vec3} vector * @returns {Vec3} @@ -121,7 +122,7 @@ public slots: /**jsdoc - * @function Mat4.inverse + * @function Mat4(0).inverse * @param {Mat4} m * @returns {Mat4} */ @@ -129,7 +130,7 @@ public slots: /**jsdoc - * @function Mat4.getFront + * @function Mat4(0).getFront * @param {Mat4} m * @returns {Vec3} */ @@ -137,28 +138,28 @@ public slots: glm::vec3 getFront(const glm::mat4& m) const { return getForward(m); } /**jsdoc - * @function Mat4.getForward + * @function Mat4(0).getForward * @param {Mat4} m * @returns {Vec3} */ glm::vec3 getForward(const glm::mat4& m) const; /**jsdoc - * @function Mat4.getRight + * @function Mat4(0).getRight * @param {Mat4} m * @returns {Vec3} */ glm::vec3 getRight(const glm::mat4& m) const; /**jsdoc - * @function Mat4.getUp + * @function Mat4(0).getUp * @param {Mat4} m * @returns {Vec3} */ glm::vec3 getUp(const glm::mat4& m) const; /**jsdoc - * @function Mat4.print + * @function Mat4(0).print * @param {string} label * @param {Mat4} m * @param {boolean} [transpose=false] diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 1edb303455..ea2c5b8354 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -43,6 +43,27 @@ Q_DECLARE_METATYPE(std::function); void registerMetaTypes(QScriptEngine* engine); // Mat4 +/**jsdoc + * A 4 x 4 matrix, typically containing a scale, rotation, and translation transform. See also the {@link Mat4(0)|Mat4} object. + * + * @typedef {object} Mat4 + * @property {number} r0c0 - Row 0, column 0 value. + * @property {number} r1c0 - Row 1, column 0 value. + * @property {number} r2c0 - Row 2, column 0 value. + * @property {number} r3c0 - Row 3, column 0 value. + * @property {number} r0c1 - Row 0, column 1 value. + * @property {number} r1c1 - Row 1, column 1 value. + * @property {number} r2c1 - Row 2, column 1 value. + * @property {number} r3c1 - Row 3, column 1 value. + * @property {number} r0c2 - Row 0, column 2 value. + * @property {number} r1c2 - Row 1, column 2 value. + * @property {number} r2c2 - Row 2, column 2 value. + * @property {number} r3c2 - Row 3, column 2 value. + * @property {number} r0c3 - Row 0, column 3 value. + * @property {number} r1c3 - Row 1, column 3 value. + * @property {number} r2c3 - Row 2, column 3 value. + * @property {number} r3c3 - Row 3, column 3 value. + */ QScriptValue mat4toScriptValue(QScriptEngine* engine, const glm::mat4& mat4); void mat4FromScriptValue(const QScriptValue& object, glm::mat4& mat4); From d73ff2e8558b27b861d1602c63b05cfbffa89587 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 28 Feb 2019 10:40:10 +1300 Subject: [PATCH 08/21] Revise current MyAvatar API JSDoc --- interface/src/avatar/MyAvatar.cpp | 14 +- interface/src/avatar/MyAvatar.h | 425 +++++++++++------- .../src/avatars-renderer/Avatar.h | 99 ++-- 3 files changed, 326 insertions(+), 212 deletions(-) diff --git a/interface/src/avatar/MyAvatar.cpp b/interface/src/avatar/MyAvatar.cpp index afb7a218f6..30e8733a42 100755 --- a/interface/src/avatar/MyAvatar.cpp +++ b/interface/src/avatar/MyAvatar.cpp @@ -2381,7 +2381,19 @@ void MyAvatar::clearWornAvatarEntities() { } } - +/**jsdoc + * Information about an avatar entity. + * + * + * + * + * + * + * + * + *
PropertyTypeDescription
idUuidEntity ID.
properties{@link Entities.EntityProperties}Entity properties.
+ * @typedef {object} MyAvatar.AvatarEntityData + */ QVariantList MyAvatar::getAvatarEntitiesVariant() { // NOTE: this method is NOT efficient QVariantList avatarEntitiesData; diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index d689d2f215..a0f1531e64 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -60,7 +60,9 @@ class MyAvatar : public Avatar { /**jsdoc * Your avatar is your in-world representation of you. The MyAvatar API is used to manipulate the avatar. * For example, you can customize the avatar's appearance, run custom avatar animations, - * change the avatar's position within the domain, or manage the avatar's collisions with other objects. + * change the avatar's position within the domain, or manage the avatar's collisions with the environment and other avatars. + * + *

For assignment client scripts, see {@link Avatar}.

* * @namespace MyAvatar * @@ -69,17 +71,20 @@ class MyAvatar : public Avatar { * @hifi-avatar * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. - * @property {Vec3} position - * @property {number} scale - Returns the clamped scale of the avatar. - * @property {number} density Read-only. - * @property {Vec3} handPosition + * @property {Vec3} position - The position of the avatar. + * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 + * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. + * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in + * the application of physics. Read-only. + * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar + * but is otherwise not used or changed by Interface. * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. * Yaw is sometimes called "heading". * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is * sometimes called "elevation". * @property {number} bodyRoll - The rotation about an axis running from the chest to the back of the avatar. Roll is * sometimes called "bank". - * @property {Quat} orientation + * @property {Quat} orientation - The orientation of the avatar. * @property {Quat} headOrientation - The orientation of the avatar's head. * @property {number} headPitch - The rotation about an axis running from ear to ear of the avatar's head. Pitch is * sometimes called "elevation". @@ -87,22 +92,31 @@ class MyAvatar : public Avatar { * head. Yaw is sometimes called "heading". * @property {number} headRoll - The rotation about an axis running from the nose to the back of the avatar's head. Roll is * sometimes called "bank". - * @property {Vec3} velocity - * @property {Vec3} angularVelocity - * @property {number} audioLoudness - * @property {number} audioAverageLoudness - * @property {string} displayName - * @property {string} sessionDisplayName - Sanitized, defaulted version displayName that is defined by the AvatarMixer - * rather than by Interface clients. The result is unique among all avatars present at the time. - * @property {boolean} lookAtSnappingEnabled - * @property {string} skeletonModelURL - * @property {AttachmentData[]} attachmentData + * @property {Vec3} velocity - The current velocity of the avatar. + * @property {Vec3} angularVelocity - The current angular velocity of the avatar. + * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the + * domain. + * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting + * into the domain. + * @property {string} displayName - The avatar's display name. + * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the + * avatar mixer rather than by Interface clients. The result is unique among all avatars present in the domain at the + * time. + * @property {boolean} lookAtSnappingEnabled=true - If true, the avatar's eyes snap to look at another avatar's + * eyes if generally in the line of sight and the other avatar also has lookAtSnappingEnabled == true. + * @property {string} skeletonModelURL - The URL of the avatar model's .fst file. + * @property {AttachmentData[]} attachmentData - Information on the attachments worn by the avatar.
+ * Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. - * @property {Uuid} sessionUUID Read-only. - * @property {Mat4} sensorToWorldMatrix Read-only. - * @property {Mat4} controllerLeftHandMatrix Read-only. - * @property {Mat4} controllerRightHandMatrix Read-only. - * @property {number} sensorToWorldScale Read-only. + * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. + * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the + * avatar's size, orientation, and position in the virtual world. Read-only. + * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the + * avatar. Read-only. + * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the + * avatar. Read-only. + * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's + * size in the virtual world. Read-only. * * @comment IMPORTANT: This group of properties is copied from Avatar.h; they should NOT be edited here. * @property {Vec3} skeletonOffset - Can be used to apply a translation offset between the avatar's position and the @@ -124,9 +138,9 @@ class MyAvatar : public Avatar { * by the audio mixer, so all audio effectively plays back at a 24khz. 48kHz RAW files are also supported. * @property {number} audioListenerMode=0 - Specifies the listening position when hearing spatialized audio. Must be one * of the following property values:
- * audioListenerModeHead
- * audioListenerModeCamera
- * audioListenerModeCustom + * Myavatar.audioListenerModeHead
+ * Myavatar.audioListenerModeCamera
+ * Myavatar.audioListenerModeCustom * @property {number} audioListenerModeHead=0 - The audio listening position is at the avatar's head. Read-only. * @property {number} audioListenerModeCamera=1 - The audio listening position is at the camera. Read-only. * @property {number} audioListenerModeCustom=2 - The audio listening position is at a the position specified by set by the @@ -135,10 +149,12 @@ class MyAvatar : public Avatar { * property value is audioListenerModeCustom. * @property {Quat} customListenOrientation=Quat.IDENTITY - The listening orientation used when the * audioListenerMode property value is audioListenerModeCustom. - * @property {boolean} hasScriptedBlendshapes=false - Blendshapes will be transmitted over the network if set to true. - * @property {boolean} hasProceduralBlinkFaceMovement=true - procedural blinking will be turned on if set to true. - * @property {boolean} hasProceduralEyeFaceMovement=true - procedural eye movement will be turned on if set to true. - * @property {boolean} hasAudioEnabledFaceMovement=true - If set to true, voice audio will move the mouth Blendshapes while MyAvatar.hasScriptedBlendshapes is enabled. + * @property {boolean} hasScriptedBlendshapes=false - Blendshapes will be transmitted over the network if set to true.
+ * Note: Currently doesn't work. Use {@link MyAvatar.setForceFaceTrackerConnected} instead. + * @property {boolean} hasProceduralBlinkFaceMovement=true - If true then procedural blinking is turned on. + * @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 @@ -169,16 +185,18 @@ class MyAvatar : public Avatar { * @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. - * @property {boolean} collisionsEnabled - Set to true to enable collisions for the avatar, false - * to disable collisions. May return true even though the value was set false because the - * zone may disallow collisionless avatars. - * @property {boolean} otherAvatarsCollisionsEnabled - * @property {boolean} characterControllerEnabled - Synonym of collisionsEnabled. + * @property {boolean} collisionsEnabled - Set to true to enable the avatar to collide with the environment, + * false to disable collisions with the environment. May return true even though the value + * was set false because the zone may disallow collisionless avatars. + * @property {boolean} otherAvatarsCollisionsEnabled - Set to true to enable the avatar to collide with other + * avatars, false to disable collisions with other avatars. + * @property {boolean} characterControllerEnabled - Synonym of collisionsEnabled.
* Deprecated: Use collisionsEnabled instead. * @property {boolean} useAdvancedMovementControls - Returns and sets the value of the Interface setting, Settings > - * Walking and teleporting. Note: Setting the value has no effect unless Interface is restarted. - * @property {boolean} showPlayArea - Returns and sets the value of the Interface setting, Settings > Show room boundaries - * while teleporting. Note: Setting the value has no effect unless Interface is restarted. + * Controls > Walking. Note: Setting the value has no effect unless Interface is restarted. + * @property {boolean} showPlayArea - Returns and sets the value of the Interface setting, Settings > Controls > Show room + * boundaries while teleporting.
+ * Note: Setting the value has no effect unless Interface is restarted. * * @property {number} yawSpeed=75 * @property {number} pitchSpeed=50 @@ -187,8 +205,8 @@ class MyAvatar : public Avatar { * while flying. * @property {number} hmdRollControlDeadZone=8 - The amount of HMD roll, in degrees, required before your avatar turns if * hmdRollControlEnabled is enabled. - * @property {number} hmdRollControlRate If hmdRollControlEnabled is true, this value determines the maximum turn rate of - * your avatar when rolling your HMD in degrees per second. + * @property {number} hmdRollControlRate If MyAvatar.hmdRollControlEnabled is true, this value determines the + * maximum turn rate of your avatar when rolling your HMD in degrees per second. * * @property {number} userHeight=1.75 - The height of the user in sensor space. * @property {number} userEyeHeight=1.65 - The estimated height of the user's eyes in sensor space. Read-only. @@ -237,8 +255,8 @@ class MyAvatar : public Avatar { * @borrows Avatar.attach as attach * @borrows Avatar.detachOne as detachOne * @borrows Avatar.detachAll as detachAll - * @borrows Avatar.getAvatarEntityData as getAvatarEntityData - * @borrows Avatar.setAvatarEntityData as setAvatarEntityData + * @comment Avatar.getAvatarEntityData as getAvatarEntityData - Don't borrow because implementation is different. + * @comment Avatar.setAvatarEntityData as setAvatarEntityData - Don't borrow because implementation is different. * @borrows Avatar.getSensorToWorldMatrix as getSensorToWorldMatrix * @borrows Avatar.getSensorToWorldScale as getSensorToWorldScale * @borrows Avatar.getControllerLeftHandMatrix as getControllerLeftHandMatrix @@ -253,10 +271,10 @@ class MyAvatar : public Avatar { * @borrows Avatar.sendAvatarDataPacket as sendAvatarDataPacket * @borrows Avatar.sendIdentityPacket as sendIdentityPacket * @borrows Avatar.setSessionUUID as setSessionUUID - * @borrows Avatar.getAbsoluteJointRotationInObjectFrame as getAbsoluteJointRotationInObjectFrame - * @borrows Avatar.getAbsoluteJointTranslationInObjectFrame as getAbsoluteJointTranslationInObjectFrame - * @borrows Avatar.setAbsoluteJointRotationInObjectFrame as setAbsoluteJointRotationInObjectFrame - * @borrows Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame + * @comment Avatar.getAbsoluteJointRotationInObjectFrame as getAbsoluteJointRotationInObjectFrame - Don't borrow because implementation is different. + * @comment Avatar.getAbsoluteJointTranslationInObjectFrame as getAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different. + * @comment Avatar.setAbsoluteJointRotationInObjectFrame as setAbsoluteJointRotationInObjectFrame - Don't borrow because implementation is different. + * @comment Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different. * @borrows Avatar.getTargetScale as getTargetScale * @borrows Avatar.resetLastSent as resetLastSent */ @@ -393,8 +411,9 @@ public: /**jsdoc - * The internal inverse-kinematics system maintains a record of which joints are "locked". Sometimes it is useful to forget this history, to prevent - * contorted joints. + * Clears inverse kinematics joint limit history. + *

The internal inverse-kinematics system maintains a record of which joints are "locked". Sometimes it is useful to + * forget this history, to prevent contorted joints.

* @function MyAvatar.clearIKJointLimitHistory */ Q_INVOKABLE void clearIKJointLimitHistory(); // thread-safe @@ -441,7 +460,7 @@ public: void setRealWorldFieldOfView(float realWorldFov) { _realWorldFieldOfView.set(realWorldFov); } /**jsdoc - * Get the position in world coordinates of the point directly between your avatar's eyes assuming your avatar was in its + * Gets the position in world coordinates of the point directly between your avatar's eyes assuming your avatar was in its * default pose. This is a reference position; it does not change as your avatar's head moves relative to the avatar * position. * @function MyAvatar.getDefaultEyePosition @@ -455,15 +474,16 @@ public: float getRealWorldFieldOfView() { return _realWorldFieldOfView.get(); } /**jsdoc - * The avatar animation system includes a set of default animations along with rules for how those animations are blended - * together with procedural data (such as look at vectors, hand sensors etc.). overrideAnimation() is used to completely - * override all motion from the default animation system (including inverse kinematics for hand and head controllers) and - * play a set of specified animations. To end these animations and restore the default animations, use - * {@link MyAvatar.restoreAnimation}.
+ * Overrides the default avatar animations. + *

The avatar animation system includes a set of default animations along with rules for how those animations are blended + * together with procedural data (such as look at vectors, hand sensors etc.). overrideAnimation() is used to + * completely override all motion from the default animation system (including inverse kinematics for hand and head + * controllers) and play a set of specified animations. To end these animations and restore the default animations, use + * {@link MyAvatar.restoreAnimation}.

*

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards.

+ * Avatar Standards.

* @function MyAvatar.overrideAnimation * @param url {string} The URL to the animation file. Animation files need to be .FBX format, but only need to contain the * avatar skeleton and animation data. @@ -482,10 +502,12 @@ public: Q_INVOKABLE void overrideAnimation(const QString& url, float fps, bool loop, float firstFrame, float lastFrame); /**jsdoc - * The avatar animation system includes a set of default animations along with rules for how those animations are blended together with - * procedural data (such as look at vectors, hand sensors etc.). Playing your own custom animations will override the default animations. - * restoreAnimation() is used to restore all motion from the default animation system including inverse kinematics for hand and head - * controllers. If you aren't currently playing an override animation, this function will have no effect. + * Restores the default animations. + *

The avatar animation system includes a set of default animations along with rules for how those animations are blended + * together with procedural data (such as look at vectors, hand sensors etc.). Playing your own custom animations will + * override the default animations. restoreAnimation() is used to restore all motion from the default + * animation system including inverse kinematics for hand and head controllers. If you aren't currently playing an override + * animation, this function has no effect.

* @function MyAvatar.restoreAnimation * @example Play a clapping animation on your avatar for three seconds. * // Clap your hands for 3 seconds then restore animation back to the avatar. @@ -498,10 +520,12 @@ public: Q_INVOKABLE void restoreAnimation(); /**jsdoc - * Each avatar has an avatar-animation.json file that defines which animations are used and how they are blended together with procedural data - * (such as look at vectors, hand sensors etc.). Each animation specified in the avatar-animation.json file is known as an animation role. - * Animation roles map to easily understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or "walkFwd." - * getAnimationRoles() is used get the list of animation roles defined in the avatar-animation.json. + * Gets the current animation roles. + *

Each avatar has an avatar-animation.json file that defines which animations are used and how they are blended together + * with procedural data (such as look at vectors, hand sensors etc.). Each animation specified in the avatar-animation.json + * file is known as an animation role. Animation roles map to easily understandable actions that the avatar can perform, + * such as "idleStand", "idleTalk", or "walkFwd". getAnimationRoles() + * is used get the list of animation roles defined in the avatar-animation.json.

* @function MyAvatar.getAnimationRoles * @returns {string[]} Array of role strings. * @example Print the list of animation roles defined in the avatar's avatar-animation.json file to the debug log. @@ -514,17 +538,19 @@ public: Q_INVOKABLE QStringList getAnimationRoles(); /**jsdoc - * Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily understandable actions - * that the avatar can perform, such as "idleStand", "idleTalk", or "walkFwd". To get the full list of roles, use getAnimationRoles(). - * For each role, the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how animations are blended - * together with procedural data (such as look at vectors, hand sensors etc.). - * overrideRoleAnimation() is used to change the animation clip (.FBX) associated with a specified animation role. To end - * the animations and restore the default animations, use {@link MyAvatar.restoreRoleAnimation}.
+ * Overrides a specific animation role. + *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily + * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or + * "walkFwd". To get the full list of roles, use {@ link MyAvatar.getAnimationRoles}. + * For each role, the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how + * animations are blended together with procedural data (such as look at vectors, hand sensors etc.). + * overrideRoleAnimation() is used to change the animation clip (.FBX) associated with a specified animation + * role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.

*

Note: Hand roles only affect the hand. Other 'main' roles, like 'idleStand', 'idleTalk', 'takeoffStand' are full body.

*

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards. + * Avatar Standards. * @function MyAvatar.overrideRoleAnimation * @param role {string} The animation role to override * @param url {string} The URL to the animation file. Animation files need to be .FBX format, but only need to contain the avatar skeleton and animation data. @@ -548,13 +574,15 @@ public: Q_INVOKABLE void overrideRoleAnimation(const QString& role, const QString& url, float fps, bool loop, float firstFrame, float lastFrame); /**jsdoc - * Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily understandable actions that - * the avatar can perform, such as "idleStand", "idleTalk", or "walkFwd". To get the full list of roles, use getAnimationRoles(). For each role, - * the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how animations are blended together with - * procedural data (such as look at vectors, hand sensors etc.). You can change the animation clip (.FBX) associated with a specified animation - * role using overrideRoleAnimation(). - * restoreRoleAnimation() is used to restore a specified animation role's default animation clip. If you have not specified an override animation - * for the specified role, this function will have no effect. + * Restores a default role animation. + *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily + * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or + * "walkFwd". To get the full list of roles, use {#link MyAvatar.getAnimationRoles}. For each role, + * the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how animations are + * blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation clip + * (.FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. + * restoreRoleAnimation() is used to restore a specified animation role's default animation clip. If you have + * not specified an override animation for the specified role, this function has no effect. * @function MyAvatar.restoreRoleAnimation * @param role {string} The animation role clip to restore. */ @@ -599,6 +627,7 @@ public: * @param {string} hand */ Q_INVOKABLE void setDominantHand(const QString& hand); + /**jsdoc * @function MyAvatar.getDominantHand * @returns {string} @@ -610,6 +639,7 @@ public: * @param {string} hand */ Q_INVOKABLE void setHmdAvatarAlignmentType(const QString& hand); + /**jsdoc * @function MyAvatar.getHmdAvatarAlignmentType * @returns {string} @@ -617,45 +647,61 @@ public: Q_INVOKABLE QString getHmdAvatarAlignmentType() const; /**jsdoc - * @function MyAvatar.setCenterOfGravityModelEnabled - * @param {boolean} enabled - */ + * @function MyAvatar.setCenterOfGravityModelEnabled + * @param {boolean} enabled + */ Q_INVOKABLE void setCenterOfGravityModelEnabled(bool value) { _centerOfGravityModelEnabled = value; } + /**jsdoc - * @function MyAvatar.getCenterOfGravityModelEnabled - * @returns {boolean} - */ + * @function MyAvatar.getCenterOfGravityModelEnabled + * @returns {boolean} + */ Q_INVOKABLE bool getCenterOfGravityModelEnabled() const { return _centerOfGravityModelEnabled; } /**jsdoc * @function MyAvatar.setHMDLeanRecenterEnabled * @param {boolean} enabled */ Q_INVOKABLE void setHMDLeanRecenterEnabled(bool value) { _hmdLeanRecenterEnabled = value; } + /**jsdoc * @function MyAvatar.getHMDLeanRecenterEnabled * @returns {boolean} */ Q_INVOKABLE bool getHMDLeanRecenterEnabled() const { return _hmdLeanRecenterEnabled; } + /**jsdoc - * Request to enable hand touch effect globally + * Requests that the hand touch effect is disabled for your avatar. Any resulting change in the status of the hand touch + * effect will be signaled by {@link MyAvatar.shouldDisableHandTouchChanged}. + *

The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.

* @function MyAvatar.requestEnableHandTouch */ Q_INVOKABLE void requestEnableHandTouch(); + /**jsdoc - * Request to disable hand touch effect globally + * Requests that the hand touch effect is enabled for your avatar. Any resulting change in the status of the hand touch + * effect will be signaled by {@link MyAvatar.shouldDisableHandTouchChanged}. + *

The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.

* @function MyAvatar.requestDisableHandTouch */ Q_INVOKABLE void requestDisableHandTouch(); + /**jsdoc - * Disables hand touch effect on a specific entity + * Disables the hand touch effect on a specific entity. + *

The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.

* @function MyAvatar.disableHandTouchForID - * @param {Uuid} entityID - ID of the entity that will disable hand touch effect + * @param {Uuid} entityID - The entity that the hand touch effect will be disabled for. */ Q_INVOKABLE void disableHandTouchForID(const QUuid& entityID); + /**jsdoc - * Enables hand touch effect on a specific entity + * Enables the hand touch effect on a specific entity. + *

The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.

* @function MyAvatar.enableHandTouchForID - * @param {Uuid} entityID - ID of the entity that will enable hand touch effect + * @param {Uuid} entityID - The entity that the hand touch effect will be enabled for. */ Q_INVOKABLE void enableHandTouchForID(const QUuid& entityID); @@ -712,6 +758,7 @@ public: * @param {DriveKeys} key */ Q_INVOKABLE void enableDriveKey(DriveKeys key); + /**jsdoc * @function MyAvatar.isDriveKeyDisabled * @param {DriveKeys} key @@ -741,10 +788,10 @@ public: Q_INVOKABLE void triggerRotationRecenter(); /**jsdoc - *The isRecenteringHorizontally function returns true if MyAvatar - *is translating the root of the Avatar to keep the center of gravity under the head. - *isActive(Horizontal) is returned. - *@function MyAvatar.isRecenteringHorizontally + * Gets whether or not the avatar is configured to keep its center of gravity under its head. + * @function MyAvatar.isRecenteringHorizontally + * @returns {boolean} true if the avatar is keeping its center of gravity under its head position, + * false if not. */ Q_INVOKABLE bool isRecenteringHorizontally() const; @@ -753,7 +800,7 @@ public: const MyHead* getMyHead() const; /**jsdoc - * Get the current position of the avatar's "Head" joint. + * Gets the current position of the avatar's "Head" joint. * @function MyAvatar.getHeadPosition * @returns {Vec3} The current position of the avatar's "Head" joint. * @example Report the current position of your avatar's head. @@ -786,7 +833,7 @@ public: Q_INVOKABLE float getHeadDeltaPitch() const { return getHead()->getDeltaPitch(); } /**jsdoc - * Get the current position of the point directly between the avatar's eyes. + * Gets the current position of the point directly between the avatar's eyes. * @function MyAvatar.getEyePosition * @returns {Vec3} The current position of the point directly between the avatar's eyes. * @example Report your avatar's current eye position. @@ -796,8 +843,9 @@ public: Q_INVOKABLE glm::vec3 getEyePosition() const { return getHead()->getEyePosition(); } /**jsdoc + * Gets the position of the avatar your avatar is currently looking at. * @function MyAvatar.getTargetAvatarPosition - * @returns {Vec3} The position of the avatar you're currently looking at. + * @returns {Vec3} The position of the avatar your avatar is currently looking at. * @example Report the position of the avatar you're currently looking at. * print(JSON.stringify(MyAvatar.getTargetAvatarPosition())); */ @@ -811,7 +859,7 @@ public: /**jsdoc - * Get 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 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 @@ -823,7 +871,7 @@ public: Q_INVOKABLE glm::vec3 getLeftHandPosition() const; /**jsdoc - * Get 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 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 @@ -848,7 +896,7 @@ public: /**jsdoc - * Get the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a + * 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).
*

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 @@ -861,7 +909,7 @@ public: Q_INVOKABLE controller::Pose getLeftHandPose() const; /**jsdoc - * Get the pose (position, rotation, velocity, and angular velocity) of the avatar's left hand as positioned by a + * 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).
*

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 @@ -935,7 +983,7 @@ public: Q_INVOKABLE void useFullAvatarURL(const QUrl& fullAvatarURL, const QString& modelName = QString()); /**jsdoc - * Get the complete URL for the current avatar. + * Gets the complete URL for the current avatar. * @function MyAvatar.getFullAvatarURLFromPreferences * @returns {string} The full avatar model name. * @example Report the URL for the current avatar. @@ -944,7 +992,7 @@ public: Q_INVOKABLE QUrl getFullAvatarURLFromPreferences() const { return _fullAvatarURLFromPreferences; } /**jsdoc - * Get the full avatar model name for the current avatar. + * Gets the full avatar model name for the current avatar. * @function MyAvatar.getFullAvatarModelName * @returns {string} The full avatar model name. * @example Report the current full avatar model name. @@ -1015,24 +1063,24 @@ public: bool hasDriveInput() const; /**jsdoc - * Function returns list of avatar entities - * @function MyAvatar.getAvatarEntitiesVariant - * @returns {object[]} - */ + * Gets the list of avatar entities and their properties. + * @function MyAvatar.getAvatarEntitiesVariant + * @returns {MyAvatar.AvatarEntityData[]} + */ Q_INVOKABLE QVariantList getAvatarEntitiesVariant(); + void removeWornAvatarEntity(const EntityItemID& entityID); void clearWornAvatarEntities(); /**jsdoc - * Check whether your avatar is flying or not. + * Checks whether your avatar is flying or not. * @function MyAvatar.isFlying - * @returns {boolean} true if your avatar is flying and not taking off or falling, otherwise - * false. + * @returns {boolean} true if your avatar is flying and not taking off or falling, false if not. */ Q_INVOKABLE bool isFlying(); /**jsdoc - * Check whether your avatar is in the air or not. + * Checks whether your avatar is in the air or not. * @function MyAvatar.isInAir * @returns {boolean} true if your avatar is taking off, flying, or falling, otherwise false * because your avatar is on the ground. @@ -1040,7 +1088,7 @@ public: Q_INVOKABLE bool isInAir(); /**jsdoc - * Set your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends + * Sets your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends * on whether the domain you're in allows you to fly. * @function MyAvatar.setFlyingEnabled * @param {boolean} enabled - Set true if you want to enable flying in your current desktop or HMD display @@ -1049,7 +1097,7 @@ public: Q_INVOKABLE void setFlyingEnabled(bool enabled); /**jsdoc - * Get your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends + * Gets your preference for flying in your current desktop or HMD display mode. Note that your ability to fly also depends * on whether the domain you're in allows you to fly. * @function MyAvatar.getFlyingEnabled * @returns {boolean} true if your preference is to enable flying in your current desktop or HMD display mode, @@ -1058,7 +1106,7 @@ public: Q_INVOKABLE bool getFlyingEnabled(); /**jsdoc - * Set your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain + * Sets your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain * you're in allows you to fly. * @function MyAvatar.setFlyingDesktopPref * @param {boolean} enabled - Set true if you want to enable flying in desktop display mode, otherwise set @@ -1067,7 +1115,7 @@ public: Q_INVOKABLE void setFlyingDesktopPref(bool enabled); /**jsdoc - * Get your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain + * Gets your preference for flying in desktop display mode. Note that your ability to fly also depends on whether the domain * you're in allows you to fly. * @function MyAvatar.getFlyingDesktopPref * @returns {boolean} true if your preference is to enable flying in desktop display mode, otherwise @@ -1076,7 +1124,7 @@ public: Q_INVOKABLE bool getFlyingDesktopPref(); /**jsdoc - * Set your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain + * Sets your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain * you're in allows you to fly. * @function MyAvatar.setFlyingHMDPref * @param {boolean} enabled - Set true if you want to enable flying in HMD display mode, otherwise set @@ -1085,7 +1133,7 @@ public: Q_INVOKABLE void setFlyingHMDPref(bool enabled); /**jsdoc - * Get your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain + * Gets your preference for flying in HMD display mode. Note that your ability to fly also depends on whether the domain * you're in allows you to fly. * @function MyAvatar.getFlyingHMDPref * @returns {boolean} true if your preference is to enable flying in HMD display mode, otherwise @@ -1120,38 +1168,53 @@ public: Q_INVOKABLE bool getCollisionsEnabled(); /**jsdoc - * @function MyAvatar.setOtherAvatarsCollisionsEnabled - * @param {boolean} enabled - */ + * @function MyAvatar.setOtherAvatarsCollisionsEnabled + * @param {boolean} enabled + */ Q_INVOKABLE void setOtherAvatarsCollisionsEnabled(bool enabled); /**jsdoc - * @function MyAvatar.getOtherAvatarsCollisionsEnabled - * @returns {boolean} - */ + * @function MyAvatar.getOtherAvatarsCollisionsEnabled + * @returns {boolean} + */ Q_INVOKABLE bool getOtherAvatarsCollisionsEnabled(); /**jsdoc - * @function MyAvatar.getCollisionCapsule - * @returns {object} - */ + * @function MyAvatar.getCollisionCapsule + * @returns {object} + */ Q_INVOKABLE QVariantMap getCollisionCapsule() const; /**jsdoc * @function MyAvatar.setCharacterControllerEnabled * @param {boolean} enabled - * @deprecated + * @deprecated Use {@link MyAvatar.setCollisionsEnabled} instead. */ Q_INVOKABLE void setCharacterControllerEnabled(bool enabled); // deprecated /**jsdoc * @function MyAvatar.getCharacterControllerEnabled * @returns {boolean} - * @deprecated + * @deprecated Use {@link MyAvatar.getCollisionsEnabled} instead. */ Q_INVOKABLE bool getCharacterControllerEnabled(); // deprecated + /**jsdoc + * @comment Different behavior to the Avatar version of this method. + * Gets the rotation of a joint relative to the avatar. + * @function MyAvatar.getAbsoluteJointRotationInObjectFrame + * @param {number} index - The index of the joint. + * @returns {Quat} The rotation of the joint relative to the avatar. + */ virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override; + + /**jsdoc + * @comment Different behavior to the Avatar version of this method. + * Gets the translation of a joint relative to the avatar. + * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame + * @param {number} index - The index of the joint. + * @returns {Vec3} The translation of the joint relative to the avatar. + */ virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override; // all calibration matrices are in absolute sensor space. @@ -1241,34 +1304,56 @@ public: void prepareAvatarEntityDataForReload(); /**jsdoc - * Create a new grab. + * Creates a new grab, that grabs an entity. * @function MyAvatar.grab - * @param {Uuid} targetID - id of grabbed thing - * @param {number} parentJointIndex - avatar joint being used to grab - * @param {Vec3} offset - target's positional offset from joint - * @param {Quat} rotationalOffset - target's rotational offset from joint - * @returns {Uuid} id of the new grab + * @param {Uuid} targetID - The ID of the entity to grab. + * @param {number} parentJointIndex - The avatar joint to use to grab the entity. + * @param {Vec3} offset - The target's local positional relative to the joint. + * @param {Quat} rotationalOffset - The target's local rotation relative to the joint. + * @returns {Uuid} The ID of the new grab. */ Q_INVOKABLE const QUuid grab(const QUuid& targetID, int parentJointIndex, glm::vec3 positionalOffset, glm::quat rotationalOffset); /**jsdoc - * Release (delete) a grab. + * Releases (deletes) a grab, to stop grabbing an entity. * @function MyAvatar.releaseGrab - * @param {Uuid} grabID - id of grabbed thing + * @param {Uuid} grabID - The ID of the grab to release. */ Q_INVOKABLE void releaseGrab(const QUuid& grabID); + /**jsdoc + * Gets the avatar entities as binary data. + * @function MyAvatar.getAvatarEntityData + * @override + * @returns {AvatarEntityMap} + */ AvatarEntityMap getAvatarEntityData() const override; + + /**jsdoc + * Sets the avatar entities from binary data. + * @function MyAvatar.setAvatarEntityData + * @param {AvatarEntityMap} avatarEntityData + */ void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; + + /**jsdoc + * @comment Uses the base class's JSDoc. + */ void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData) override; + void avatarEntityDataToJson(QJsonObject& root) const override; + + /**jsdoc + * @function MyAvatar.sendAvatarDataPacket + * @param {boolean} sendAll + */ int sendAvatarDataPacket(bool sendAll = false) override; public slots: /**jsdoc - * Increase the avatar's scale by five percent, up to a minimum scale of 1000. + * Increases the avatar's scale by five percent, up to a minimum scale of 1000. * @function MyAvatar.increaseSize * @example Reset your avatar's size to default then grow it 5 times. * MyAvatar.resetSize(); @@ -1281,7 +1366,7 @@ public slots: void increaseSize(); /**jsdoc - * Decrease the avatar's scale by five percent, down to a minimum scale of 0.25. + * Decreases the avatar's scale by five percent, down to a minimum scale of 0.25. * @function MyAvatar.decreaseSize * @example Reset your avatar's size to default then shrink it 5 times. * MyAvatar.resetSize(); @@ -1294,7 +1379,7 @@ public slots: void decreaseSize(); /**jsdoc - * Reset the avatar's scale back to the default scale of 1.0. + * Resets the avatar's scale back to the default scale of 1.0. * @function MyAvatar.resetSize */ void resetSize(); @@ -1317,7 +1402,7 @@ public slots: float getGravity(); /**jsdoc - * Move the avatar to a new position and/or orientation in the domain, while taking into account Avatar leg-length. + * Moves the avatar to a new position and/or orientation in the domain, while taking into account Avatar leg-length. * @function MyAvatar.goToFeetLocation * @param {Vec3} position - The new position for the avatar, in world coordinates. * @param {boolean} [hasOrientation=false] - Set to true to set the orientation of the avatar. @@ -1330,7 +1415,7 @@ public slots: bool shouldFaceLocation); /**jsdoc - * Move the avatar to a new position and/or orientation in the domain. + * Moves the avatar to a new position and/or orientation in the domain. * @function MyAvatar.goToLocation * @param {Vec3} position - The new position for the avatar, in world coordinates. * @param {boolean} [hasOrientation=false] - Set to true to set the orientation of the avatar. @@ -1395,61 +1480,70 @@ public slots: /**jsdoc - * ####### Why Q_INVOKABLE? * @function MyAvatar.updateMotionBehaviorFromMenu */ Q_INVOKABLE void updateMotionBehaviorFromMenu(); /**jsdoc - * @function MyAvatar.setToggleHips - * @param {boolean} enabled - */ + * @function MyAvatar.setToggleHips + * @param {boolean} enabled + */ void setToggleHips(bool followHead); + /**jsdoc - * @function MyAvatar.setEnableDebugDrawBaseOfSupport - * @param {boolean} enabled - */ + * @function MyAvatar.setEnableDebugDrawBaseOfSupport + * @param {boolean} enabled + */ void setEnableDebugDrawBaseOfSupport(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawDefaultPose * @param {boolean} enabled */ void setEnableDebugDrawDefaultPose(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawAnimPose * @param {boolean} enabled */ void setEnableDebugDrawAnimPose(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawPosition * @param {boolean} enabled */ void setEnableDebugDrawPosition(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawHandControllers * @param {boolean} enabled */ void setEnableDebugDrawHandControllers(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawSensorToWorldMatrix * @param {boolean} enabled */ void setEnableDebugDrawSensorToWorldMatrix(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawIKTargets * @param {boolean} enabled */ void setEnableDebugDrawIKTargets(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawIKConstraints * @param {boolean} enabled */ void setEnableDebugDrawIKConstraints(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawIKChains * @param {boolean} enabled */ void setEnableDebugDrawIKChains(bool isEnabled); + /**jsdoc * @function MyAvatar.setEnableDebugDrawDetailedCollision * @param {boolean} enabled @@ -1457,23 +1551,20 @@ public slots: void setEnableDebugDrawDetailedCollision(bool isEnabled); /**jsdoc - * Get whether or not your avatar mesh is visible. + * Gets whether or not your avatar mesh is visible. * @function MyAvatar.getEnableMeshVisible * @returns {boolean} true if your avatar's mesh is visible, otherwise false. */ bool getEnableMeshVisible() const override; /**jsdoc - * ####### TODO; Should this really be exposed in the API? * @function MyAvatar.storeAvatarEntityDataPayload + * @deprecated This function is deprecated and will be removed. */ void storeAvatarEntityDataPayload(const QUuid& entityID, const QByteArray& payload) override; /**jsdoc - * ####### Does override change functionality? If so, document here and don't borrow; if not, borrow and don't document here. - * @function MyAvatar.clearAvatarEntity - * @param {Uuid} entityID - * @param {boolean} [requiresRemovalFromTree] + * @comment Uses the base class's JSDoc. */ void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true) override; @@ -1483,7 +1574,7 @@ public slots: void sanitizeAvatarEntityProperties(EntityItemProperties& properties) const; /**jsdoc - * Set whether or not your avatar mesh is visible. + * Sets whether or not your avatar mesh is visible. * @function MyAvatar.setEnableMeshVisible * @param {boolean} visible - true to set your avatar mesh visible; false to set it invisible. * @example Make your avatar invisible for 10s. @@ -1577,25 +1668,27 @@ signals: void collisionWithEntity(const Collision& collision); /**jsdoc - * Triggered when collisions with avatar enabled or disabled + * Triggered when collisions with the environment are enabled or disabled. * @function MyAvatar.collisionsEnabledChanged - * @param {boolean} enabled + * @param {boolean} enabled - true if collisions with the environment are enabled, false if + * they're not. * @returns {Signal} */ void collisionsEnabledChanged(bool enabled); /**jsdoc - * Triggered when collisions with other avatars enabled or disabled + * Triggered when collisions with other avatars are enabled or disabled. * @function MyAvatar.otherAvatarsCollisionsEnabledChanged - * @param {boolean} enabled + * @param {boolean} enabled - true if collisions with other avatars are enabled, false if they're + * not. * @returns {Signal} */ void otherAvatarsCollisionsEnabledChanged(bool enabled); /**jsdoc - * Triggered when avatar's animation url changes + * Triggered when the avatar's animation changes. * @function MyAvatar.animGraphUrlChanged - * @param {url} url + * @param {url} url - The URL of the new animation. * @returns {Signal} */ void animGraphUrlChanged(const QUrl& url); @@ -1672,18 +1765,24 @@ signals: void scaleChanged(); /**jsdoc - * Triggered when hand touch is globally enabled or disabled + * Triggered when the hand touch effect is enabled or disabled for the avatar. + *

The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.

* @function MyAvatar.shouldDisableHandTouchChanged - * @param {boolean} shouldDisable + * @param {boolean} disabled - true if the hand touch effect is disabled for the avatar, + * false if it isn't disabled. * @returns {Signal} */ void shouldDisableHandTouchChanged(bool shouldDisable); /**jsdoc - * Triggered when hand touch is enabled or disabled for an specific entity + * Triggered when the hand touch is enabled or disabled on a specific entity. + *

The hand touch effect makes the avatar's fingers adapt to the shape of any object grabbed, creating the effect that + * it is really touching that object.

* @function MyAvatar.disableHandTouchForIDChanged - * @param {Uuid} entityID - ID of the entity that will enable hand touch effect - * @param {boolean} disable + * @param {Uuid} entityID - The entity that the hand touch effect has been enabled or disabled for. + * @param {boolean} disabled - true if the hand touch effect is disabled for the entity, + * false if it isn't disabled. * @returns {Signal} */ void disableHandTouchForIDChanged(const QUuid& entityID, bool disable); diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 98aa255641..11940ad76a 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -215,17 +215,17 @@ public: Q_INVOKABLE virtual glm::vec3 getDefaultJointTranslation(int index) const; /**jsdoc - * Provides read only access to the default joint rotations in avatar coordinates. + * Provides read-only access to the default joint rotations in avatar coordinates. * The default pose of the avatar is defined by the position and orientation of all bones * in the avatar's model file. Typically this is a T-pose. * @function MyAvatar.getAbsoluteDefaultJointRotationInObjectFrame - * @param index {number} -The joint index. + * @param index {number} - The joint index. * @returns {Quat} The rotation of this joint in avatar coordinates. */ Q_INVOKABLE virtual glm::quat getAbsoluteDefaultJointRotationInObjectFrame(int index) const; /**jsdoc - * Provides read only access to the default joint translations in avatar coordinates. + * Provides read-only access to the default joint translations in avatar coordinates. * The default pose of the avatar is defined by the position and orientation of all bones * in the avatar's model file. Typically this is a T-pose. * @function MyAvatar.getAbsoluteDefaultJointTranslationInObjectFrame @@ -261,52 +261,51 @@ public: // world-space to avatar-space rigconversion functions /**jsdoc - * @function MyAvatar.worldToJointPoint - * @param {Vec3} position - * @param {number} [jointIndex=-1] - * @returns {Vec3} - */ + * @function MyAvatar.worldToJointPoint + * @param {Vec3} position + * @param {number} [jointIndex=-1] + * @returns {Vec3} + */ Q_INVOKABLE glm::vec3 worldToJointPoint(const glm::vec3& position, const int jointIndex = -1) const; /**jsdoc - * @function MyAvatar.worldToJointDirection - * @param {Vec3} direction - * @param {number} [jointIndex=-1] - * @returns {Vec3} - */ + * @function MyAvatar.worldToJointDirection + * @param {Vec3} direction + * @param {number} [jointIndex=-1] + * @returns {Vec3} + */ Q_INVOKABLE glm::vec3 worldToJointDirection(const glm::vec3& direction, const int jointIndex = -1) const; /**jsdoc - * @function MyAvatar.worldToJointRotation - * @param {Quat} rotation - * @param {number} [jointIndex=-1] - * @returns {Quat} + * @function MyAvatar.worldToJointRotation + * @param {Quat} rotation + * @param {number} [jointIndex=-1] + * @returns {Quat} */ Q_INVOKABLE glm::quat worldToJointRotation(const glm::quat& rotation, const int jointIndex = -1) const; - /**jsdoc - * @function MyAvatar.jointToWorldPoint - * @param {vec3} position - * @param {number} [jointIndex=-1] - * @returns {Vec3} - */ + * @function MyAvatar.jointToWorldPoint + * @param {vec3} position + * @param {number} [jointIndex=-1] + * @returns {Vec3} + */ Q_INVOKABLE glm::vec3 jointToWorldPoint(const glm::vec3& position, const int jointIndex = -1) const; /**jsdoc - * @function MyAvatar.jointToWorldDirection - * @param {Vec3} direction - * @param {number} [jointIndex=-1] - * @returns {Vec3} - */ + * @function MyAvatar.jointToWorldDirection + * @param {Vec3} direction + * @param {number} [jointIndex=-1] + * @returns {Vec3} + */ Q_INVOKABLE glm::vec3 jointToWorldDirection(const glm::vec3& direction, const int jointIndex = -1) const; /**jsdoc - * @function MyAvatar.jointToWorldRotation - * @param {Quat} rotation - * @param {number} [jointIndex=-1] - * @returns {Quat} - */ + * @function MyAvatar.jointToWorldRotation + * @param {Quat} rotation + * @param {number} [jointIndex=-1] + * @returns {Quat} + */ Q_INVOKABLE glm::quat jointToWorldRotation(const glm::quat& rotation, const int jointIndex = -1) const; virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override; @@ -321,7 +320,7 @@ public: float radius1, float radius2, const glm::vec4& color); /**jsdoc - * Set the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example, + * Sets the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example, * with an offset of { x: 0, y: 0.1, z: 0 }, your avatar will appear to be raised off the ground slightly. * @function MyAvatar.setSkeletonOffset * @param {Vec3} offset - The skeleton offset to set. @@ -337,7 +336,7 @@ public: Q_INVOKABLE void setSkeletonOffset(const glm::vec3& offset); /**jsdoc - * Get the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example, + * Gets the offset applied to the current avatar. The offset adjusts the position that the avatar is rendered. For example, * with an offset of { x: 0, y: 0.1, z: 0 }, your avatar will appear to be raised off the ground slightly. * @function MyAvatar.getSkeletonOffset * @returns {Vec3} The current skeleton offset. @@ -349,7 +348,7 @@ public: virtual glm::vec3 getSkeletonPosition() const; /**jsdoc - * Get the position of a joint in the current avatar. + * Gets the position of a joint in the current avatar. * @function MyAvatar.getJointPosition * @param {number} index - The index of the joint. * @returns {Vec3} The position of the joint in world coordinates. @@ -357,7 +356,7 @@ public: Q_INVOKABLE glm::vec3 getJointPosition(int index) const; /**jsdoc - * Get the position of a joint in the current avatar. + * Gets the position of a joint in the current avatar. * @function MyAvatar.getJointPosition * @param {string} name - The name of the joint. * @returns {Vec3} The position of the joint in world coordinates. @@ -367,7 +366,7 @@ public: Q_INVOKABLE glm::vec3 getJointPosition(const QString& name) const; /**jsdoc - * Get the position of the current avatar's neck in world coordinates. + * Gets the position of the current avatar's neck in world coordinates. * @function MyAvatar.getNeckPosition * @returns {Vec3} The position of the neck in world coordinates. * @example Report the position of your avatar's neck. @@ -401,10 +400,10 @@ public: void getCapsule(glm::vec3& start, glm::vec3& end, float& radius); float computeMass(); /**jsdoc - * Get the position of the current avatar's feet (or rather, bottom of its collision capsule) in world coordinates. + * Gets the position of the current avatar's feet (or rather, bottom of its collision capsule) in world coordinates. * @function MyAvatar.getWorldFeetPosition * @returns {Vec3} The position of the avatar's feet in world coordinates. - */ + */ Q_INVOKABLE glm::vec3 getWorldFeetPosition(); void setPositionViaScript(const glm::vec3& position) override; @@ -439,9 +438,9 @@ public: Q_INVOKABLE virtual void setParentJointIndex(quint16 parentJointIndex) override; /**jsdoc - * Returns an array of joints, where each joint is an object containing name, index, and parentIndex fields. + * Gets information on all the joints in the avatar's skeleton. * @function MyAvatar.getSkeleton - * @returns {MyAvatar.SkeletonJoint[]} A list of information about each joint in this avatar's skeleton. + * @returns {MyAvatar.SkeletonJoint[]} Information about each joint in the avatar's skeleton. */ /**jsdoc * Information about a single joint in an Avatar's skeleton hierarchy. @@ -524,6 +523,8 @@ public: signals: /**jsdoc * @function MyAvatar.targetScaleChanged + * @param {number} targetScale + * @returns Signal */ void targetScaleChanged(float targetScale); @@ -533,7 +534,7 @@ public slots: // thread safe, will return last valid palm from cache /**jsdoc - * Get the position of the left palm in world coordinates. + * Gets the position of the left palm in world coordinates. * @function MyAvatar.getLeftPalmPosition * @returns {Vec3} The position of the left palm in world coordinates. * @example Report the position of your avatar's left palm. @@ -542,15 +543,16 @@ public slots: glm::vec3 getLeftPalmPosition() const; /**jsdoc - * Get the rotation of the left palm in world coordinates. + * Gets the rotation of the left palm in world coordinates. * @function MyAvatar.getLeftPalmRotation * @returns {Quat} The rotation of the left palm in world coordinates. * @example Report the rotation of your avatar's left palm. * print(JSON.stringify(MyAvatar.getLeftPalmRotation())); */ glm::quat getLeftPalmRotation() const; + /**jsdoc - * Get the position of the right palm in world coordinates. + * Gets the position of the right palm in world coordinates. * @function MyAvatar.getRightPalmPosition * @returns {Vec3} The position of the right palm in world coordinates. * @example Report the position of your avatar's right palm. @@ -569,22 +571,23 @@ public slots: /**jsdoc * @function MyAvatar.setModelURLFinished + * @param {boolean} success */ // hooked up to Model::setURLFinished signal void setModelURLFinished(bool success); /**jsdoc * @function MyAvatar.rigReady - * @returns {Signal} + * @deprecated This function is deprecated and will be removed. */ // Hooked up to Model::rigReady signal void rigReady(); /**jsdoc * @function MyAvatar.rigReset - * @returns {Signal} + * @deprecated This function is deprecated and will be removed. */ - // Jooked up to Model::rigReset signal + // Hooked up to Model::rigReset signal void rigReset(); protected: From 0b7cddb886ffd24f7e150b9150fe7a582626be77 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 8 Mar 2019 13:49:10 +1300 Subject: [PATCH 09/21] 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(); From eba89e8a80ff0d49a3ef3350b079ee486ec42f69 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 8 Mar 2019 13:50:03 +1300 Subject: [PATCH 10/21] Revise Avatar JSDoc as a result of MyAvatar JSDoc work --- .../src/avatars/ScriptableAvatar.h | 4 +- libraries/avatars/src/AvatarData.h | 84 +++++++++++-------- 2 files changed, 51 insertions(+), 37 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 2d8dce23de..37e82947ae 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -149,7 +149,7 @@ public: * Gets the avatar entities as binary data. *

Warning: Potentially a very expensive call. Do not use if possible.

* @function Avatar.getAvatarEntityData - * @returns {AvatarEntityMap} + * @returns {AvatarEntityMap} The avatar entities as binary data. */ Q_INVOKABLE AvatarEntityMap getAvatarEntityData() const override; @@ -157,7 +157,7 @@ public: * Sets the avatar entities from binary data. *

Warning: Potentially an expensive call. Do not use if possible.

* @function Avatar.setAvatarEntityData - * @param {AvatarEntityMap} avatarEntityData + * @param {AvatarEntityMap} avatarEntityData - The avatar entities as binary data. */ Q_INVOKABLE void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index a20518076f..858af7ba3c 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -131,7 +131,7 @@ const int COLLIDE_WITH_OTHER_AVATARS = 11; // 12th bit * * *

The values for the hand states are added together to give the HandState value. For example, if the left - * hand's finger is pointing, the value is 1 + 4 == 5. + * hand's finger is pointing, the value is 1 + 4 == 5. * @typedef {number} HandState */ const char HAND_STATE_NULL = 0; @@ -705,8 +705,9 @@ public: Q_INVOKABLE void setRawJointData(QVector data); /**jsdoc - * Sets a specific joint's rotation and position relative to its parent. - *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse + * Sets a specific joint's rotation and position relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set @@ -714,7 +715,7 @@ public: * @function Avatar.setJointData * @param {number} index - The index of the joint. * @param {Quat} rotation - The rotation of the joint relative to its parent. - * @param {Vec3} translation - The translation of the joint relative to its parent. + * @param {Vec3} translation - The translation of the joint relative to its parent, in model coordinates. * @example Set your avatar to it's default T-pose for a while.
* Avatar in T-pose * // Set all joint translations and rotations to defaults. @@ -748,15 +749,16 @@ public: Q_INVOKABLE virtual void setJointRotation(int index, const glm::quat& rotation); /**jsdoc - * Sets a specific joint's translation relative to its parent. - *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse + * Sets a specific joint's translation relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

* @function Avatar.setJointTranslation * @param {number} index - The index of the joint. - * @param {Vec3} translation - The translation of the joint relative to its parent. + * @param {Vec3} translation - The translation of the joint relative to its parent, in model coordinates. */ Q_INVOKABLE virtual void setJointTranslation(int index, const glm::vec3& translation); @@ -773,7 +775,7 @@ public: * Checks that the data for a joint are valid. * @function Avatar.isJointDataValid * @param {number} index - The index of the joint. - * @returns {boolean} true if the joint data is valid, false if not. + * @returns {boolean} true if the joint data are valid, false if not. */ Q_INVOKABLE bool isJointDataValid(int index) const; @@ -787,17 +789,20 @@ public: Q_INVOKABLE virtual glm::quat getJointRotation(int index) const; /**jsdoc - * Gets the translation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Gets the translation of a joint 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 Avatar.getJointTranslation * @param {number} index - The index of the joint. - * @returns {Vec3} The translation of the joint relative to its parent. + * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. */ Q_INVOKABLE virtual glm::vec3 getJointTranslation(int index) const; /**jsdoc - * Sets a specific joint's rotation and position relative to its parent. - *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse + * Sets a specific joint's rotation and position relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set @@ -805,7 +810,7 @@ public: * @function Avatar.setJointData * @param {string} name - The name of the joint. * @param {Quat} rotation - The rotation of the joint relative to its parent. - * @param {Vec3} translation - The translation of the joint relative to its parent. + * @param {Vec3} translation - The translation of the joint relative to its parent, in model coordinates. */ Q_INVOKABLE virtual void setJointData(const QString& name, const glm::quat& rotation, const glm::vec3& translation); @@ -843,20 +848,21 @@ public: Q_INVOKABLE virtual void setJointRotation(const QString& name, const glm::quat& rotation); /**jsdoc - * Sets a specific joint's translation relative to its parent. - *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse + * Sets a specific joint's translation relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

* @function Avatar.setJointTranslation * @param {string} name - The name of the joint. - * @param {Vec3} translation - The translation of the joint relative to its parent. + * @param {Vec3} translation - The translation of the joint relative to its parent, in model coordinates. * @example Stretch your avatar's neck. Depending on the avatar you are using, you will either see a gap between * the head and body or you will see the neck stretched.
* Avatar with neck stretched * // Stretch your avatar's neck. - * MyAvatar.setJointTranslation("Neck", { x: 0, y: 25, z: 0 }); + * MyAvatar.setJointTranslation("Neck", Vec3.multiply(2, MyAvatar.getJointTranslation("Neck"))); * * // Restore your avatar's neck after 5s. * Script.setTimeout(function () { @@ -874,10 +880,10 @@ public: * @function Avatar.clearJointData * @param {string} name - The name of the joint. * @example Offset and restore the position of your avatar's head. - * // Move your avatar's head up by 25cm from where it should be. - * MyAvatar.setJointTranslation("Neck", { x: 0, y: 0.25, z: 0 }); + * // Stretch your avatar's neck. + * MyAvatar.setJointTranslation("Neck", Vec3.multiply(2, MyAvatar.getJointTranslation("Neck"))); * - * // Restore your avatar's head to its default position after 5s. + * // Restore your avatar's neck after 5s. * Script.setTimeout(function () { * MyAvatar.clearJointData("Neck"); * }, 5000); @@ -890,7 +896,7 @@ public: * Checks that the data for a joint are valid. * @function Avatar.isJointDataValid * @param {string} name - The name of the joint. - * @returns {boolean} true if the joint data is valid, false if not. + * @returns {boolean} true if the joint data are valid, false if not. */ Q_INVOKABLE virtual bool isJointDataValid(const QString& name) const; @@ -908,11 +914,13 @@ public: Q_INVOKABLE virtual glm::quat getJointRotation(const QString& name) const; /**jsdoc - * Gets the translation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Gets the translation of a joint 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 Avatar.getJointTranslation * @param {number} name - The name of the joint. - * @returns {Vec3} The translation of the joint relative to its parent. + * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. * @example Report the translation of your avatar's hips joint. * print(JSON.stringify(MyAvatar.getJointRotation("Hips"))); * @@ -933,10 +941,13 @@ public: Q_INVOKABLE virtual QVector getJointRotations() const; /**jsdoc - * Gets the translations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. + * Gets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint, in + * model coordinates. + *

Warning: These coordinates are not necessarily in meters.

* @function Avatar.getJointTranslations - * @returns {Vec3[]} The translations of all joints relative to each's parent. The values are in the same order as the array - * returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. + * @returns {Vec3[]} The translations of all joints relative to each's parent, in model coordinates. The values are in the + * same order as the array returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the + * Avatar API. */ Q_INVOKABLE virtual QVector getJointTranslations() const; @@ -979,15 +990,18 @@ public: Q_INVOKABLE virtual void setJointRotations(const QVector& jointRotations); /**jsdoc - * Sets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint. + * Sets the translations of all joints in the current avatar. Each joint's translation is relative to its parent joint, in + * model coordinates. + *

Warning: These coordinates are not necessarily in meters.

*

Setting joint data completely overrides/replaces all motion from the default animation system including inverse * kinematics, but just for the specified joint. So for example, if you were to procedurally manipulate the finger joints, * the avatar's hand and head would still do inverse kinematics properly. However, as soon as you start to manipulate * joints in the inverse kinematics chain, the inverse kinematics might not function as you expect. For example, if you set * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

* @function Avatar.setJointTranslations - * @param {Vec3[]} translations - The translations for all joints in the avatar. The values are in the same order as the - * array returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the Avatar API. + * @param {Vec3[]} translations - The translations for all joints in the avatar, in model coordinates. The values are in + * the same order as the array returned by {@link MyAvatar.getJointNames}, or {@link Avatar.getJointNames} if using the + * Avatar API. */ Q_INVOKABLE virtual void setJointTranslations(const QVector& jointTranslations); @@ -1271,12 +1285,12 @@ public: AABox getDefaultBubbleBox() const; /**jsdoc - * @comment Documented in derived classes' JSDoc. + * @comment Documented in derived classes' JSDoc because implementations are different. */ Q_INVOKABLE virtual AvatarEntityMap getAvatarEntityData() const; /**jsdoc - * @comment Documented in derived classes' JSDoc. + * @comment Documented in derived classes' JSDoc because implementations are different. */ Q_INVOKABLE virtual void setAvatarEntityData(const AvatarEntityMap& avatarEntityData); @@ -1383,14 +1397,14 @@ signals: void displayNameChanged(); /**jsdoc - * Triggered when the avattr's sessionDisplayName property value changes. + * Triggered when the avatar's sessionDisplayName property value changes. * @function Avatar.sessionDisplayNameChanged * @returns {Signal} */ void sessionDisplayNameChanged(); /**jsdoc - * Triggered when the avatar's skeletonModelURL property value changes. + * Triggered when the avatar's model (i.e., skeletonModelURL property value) is changed. * @function Avatar.skeletonModelURLChanged * @returns {Signal} */ From 5068075645c8c1511d2cc99c94c78dec68f0f325 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 9 Mar 2019 07:42:55 +1300 Subject: [PATCH 11/21] Fill in MyAvatar animation JSDoc --- .../animation/src/AnimInverseKinematics.h | 41 ++++ libraries/animation/src/AnimOverlay.h | 27 +++ libraries/animation/src/IKTarget.h | 21 ++ libraries/animation/src/Rig.cpp | 211 ++++++++++++++++++ libraries/script-engine/src/ScriptEngine.h | 11 +- 5 files changed, 306 insertions(+), 5 deletions(-) diff --git a/libraries/animation/src/AnimInverseKinematics.h b/libraries/animation/src/AnimInverseKinematics.h index 0136b7d125..d5a110ea76 100644 --- a/libraries/animation/src/AnimInverseKinematics.h +++ b/libraries/animation/src/AnimInverseKinematics.h @@ -59,6 +59,47 @@ public: float getMaxErrorOnLastSolve() { return _maxErrorOnLastSolve; } + /**jsdoc + *

Specifies the initial conditions of the IK solver.

+ * + * + * + * + * + * + * + * + * + * + * + *
ValueName

Description
0RelaxToUnderPosesThis is a blend between PreviousSolution and + * UnderPoses: it is 15/16 PreviousSolution and 1/16 UnderPoses. This + * provides some of the benefits of using UnderPoses so that the underlying animation is still visible, + * while at the same time converging faster then using the UnderPoses only initial solution.
1RelaxToLimitCenterPosesThis is a blend between + * Previous Solution and LimitCenterPoses: it is 15/16 PreviousSolution and + * 1/16 LimitCenterPoses. This should converge quickly because it is close to the previous solution, but + * still provides the benefits of avoiding limb locking.
2PreviousSolutionThe IK system will begin to solve from the same position and + * orientations for each joint that was the result from the previous frame.
+ * Pros: because the end effectors typically do not move much from frame to frame, this is likely to converge quickly + * to a valid solution.
+ * Cons: If the previous solution resulted in an awkward or uncomfortable posture, the next frame will also be + * awkward and uncomfortable. It can also result in locked elbows and knees.
3UnderPosesThe IK occurs at one of the top-most layers, it has access to the + * full posture that was computed via canned animations and blends. We call this animated set of poses the "under + * pose". The under poses are what would be visible if IK was completely disabled. Using the under poses as the + * initial conditions of the CCD solve will cause some of the animated motion to be blended in to the result of the + * IK. This can result in very natural results, especially if there are only a few IK targets enabled. On the other + * hand, because the under poses might be quite far from the desired end effector, it can converge slowly in some + * cases, causing it to never reach the IK target in the allotted number of iterations. Also, in situations where all + * of the IK targets are being controlled by external sensors, sometimes starting from the under poses can cause + * awkward motions from the underlying animations to leak into the IK result.
4LimitCenterPosesThis pose is taken to be the center of all the joint + * constraints. This can prevent the IK solution from getting locked or stuck at a particular constraint. For + * example, if the arm is pointing straight outward from the body, as the end effector moves towards the body, at + * some point the elbow should bend to accommodate. However, because the CCD solver is stuck at a local maximum, it + * will not rotate the elbow, unless the initial conditions already has the elbow bent, which is the case for + * LimitCenterPoses. When all the IK targets are enabled, this result will provide a consistent starting + * point for each IK solve, hopefully resulting in a consistent, natural result.
+ * @typedef {number} MyAvatar.AnimIKSolutionSource + */ enum class SolutionSource { RelaxToUnderPoses = 0, RelaxToLimitCenterPoses, diff --git a/libraries/animation/src/AnimOverlay.h b/libraries/animation/src/AnimOverlay.h index 70929bd4e4..623672143e 100644 --- a/libraries/animation/src/AnimOverlay.h +++ b/libraries/animation/src/AnimOverlay.h @@ -24,6 +24,33 @@ class AnimOverlay : public AnimNode { public: friend class AnimTests; + /**jsdoc + *

Specifies sets of joints.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueName

Description
0FullBodyBoneSetAll joints.
1UpperBodyBoneSetOnly the "Spine" joint and its children.
2LowerBodyBoneSetOnly the leg joints and their children.
3LeftArmBoneSetJoints that are children of the "LeftShoulder" joint.
4RightArmBoneSetJoints that are children of the "RightShoulder" + * joint.
5AboveTheHeadBoneSetJoints that are children of the "Head" joint.
6BelowTheHeadBoneSetJoints that are NOT children of the "head" + * joint.
7HeadOnlyBoneSetThe "Head" joint.
8SpineOnlyBoneSetThe "Spine" joint.
9EmptyBoneSetNo joints.
10LeftHandBoneSetjoints that are children of the "LeftHand" joint.
11RightHandBoneSetJoints that are children of the "RightHand" joint.
12HipsOnlyBoneSetThe "Hips" joint.
13BothFeetBoneSetThe "LeftFoot" and "RightFoot" joints.
+ * @typedef {number} MyAvatar.AnimOverlayBoneSet + */ enum BoneSet { FullBodyBoneSet = 0, UpperBodyBoneSet, diff --git a/libraries/animation/src/IKTarget.h b/libraries/animation/src/IKTarget.h index 325a1b40b6..7e53e6a7ea 100644 --- a/libraries/animation/src/IKTarget.h +++ b/libraries/animation/src/IKTarget.h @@ -16,6 +16,27 @@ const float HACK_HMD_TARGET_WEIGHT = 8.0f; class IKTarget { public: + /**jsdoc + *

An IK target type.

+ * + * + * + * + * + * + * + * + * + * + * + * + *
ValueName

Description
0RotationAndPositionAttempt to reach the rotation and position end + * effector.
1RotationOnlyAttempt to reach the end effector rotation only.
2HmdHeadDeprecated: A special mode of IK that would attempt + * to prevent unnecessary bending of the spine.
3HipsRelativeRotationAndPositionAttempt to reach a rotation and position end + * effector that is not in absolute rig coordinates but is offset by the avatar hips translation.
4SplineUse a cubic Hermite spline to model the human spine. This prevents + * kinks in the spine and allows for a small amount of stretch and squash.
5UnknownIK is disabled.
+ * @typedef {number} MyAvatar.IKTargetType + */ enum class Type { RotationAndPosition, RotationOnly, diff --git a/libraries/animation/src/Rig.cpp b/libraries/animation/src/Rig.cpp index a9c57a4a15..1ab680fba2 100644 --- a/libraries/animation/src/Rig.cpp +++ b/libraries/animation/src/Rig.cpp @@ -75,6 +75,217 @@ static const QString MAIN_STATE_MACHINE_RIGHT_FOOT_ROTATION("mainStateMachineRig static const QString MAIN_STATE_MACHINE_RIGHT_FOOT_POSITION("mainStateMachineRightFootPosition"); +/**jsdoc + *

An AnimStateDictionary object may have the following properties. It may also have other properties, set by + * scripts.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + + * + * + * + * + * + * + * + * + * + + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameType

Description
userAnimNonebooleantrue when no user overrideAnimation is + * playing.
userAnimAbooleantrue when a user overrideAnimation is + * playing.
userAnimBbooleantrue when a user overrideAnimation is + * playing.
sinenumberOscillating sine wave.
moveForwardSpeednumberControls the blend between the various forward walking + * & running animations.
moveBackwardSpeednumberControls the blend between the various backward walking + * & running animations.
moveLateralSpeednumberControls the blend between the various sidestep walking + * & running animations.
isMovingForwardbooleantrue if the avatar is moving + * forward.
isMovingBackwardbooleantrue if the avatar is moving + * backward.
isMovingRightbooleantrue if the avatar is moving to the + * right.
isMovingLeftbooleantrue if the avatar is moving to the + * left.
isMovingRightHmdbooleantrue if the avatar is moving to the right + * while the user is in HMD mode.
isMovingLeftHmdbooleantrue if the avatar is moving to the left while + * the user is in HMD mode.
isNotMovingbooleantrue if the avatar is stationary.
isTurningRightbooleantrue if the avatar is turning + * clockwise.
isTurningLeftbooleantrue if the avatar is turning + * counter-clockwise.
isNotTurningbooleantrue if the avatar is not turning.
isFlyingbooleantrue if the avatar is flying.
isNotFlyingbooleantrue if the avatar is not flying.
isTakeoffStandbooleantrue if the avatar is about to execute a + * standing jump.
isTakeoffRunbooleantrue if the avatar is about to execute a running + * jump.
isNotTakeoffbooleantrue if the avatar is not jumping.
isInAirStandbooleantrue if the avatar is in the air after a standing + * jump.
isInAirRunbooleantrue if the avatar is in the air after a running + * jump.
isNotInAirbooleantrue if the avatar on the ground.
inAirAlphanumberUsed to interpolate between the up, apex, and down in-air + * animations.
ikOverlayAlphanumberThe blend between upper body and spline IK versus the + * underlying animation
headPosition{@link Vec3}The desired position of the Head joint in + * rig coordinates.
headRotation{@link Quat}The desired orientation of the Head joint in + * rig coordinates.
headType{@link MyAvatar.IKTargetType|IKTargetType}The type of IK used for the + * head.
headWeightnumberHow strongly the head chain blends with the other IK + * chains.
leftHandPosition{@link Vec3}The desired position of the LeftHand + * joint in rig coordinates.
leftHandRotation{@link Quat}The desired orientation of the LeftHand + * joint in rig coordinates.
leftHandType{@link MyAvatar.IKTargetType|IKTargetType}The type of IK used for the + * left arm.
leftHandPoleVectorEnabledbooleanWhen true, the elbow angle is + * controlled by the rightHandPoleVector property value. Otherwise the elbow direction comes from the + * underlying animation.
leftHandPoleReferenceVector{@link Vec3}The direction of the elbow in the local + * coordinate system of the elbow.
leftHandPoleVector{@link Vec3}The direction the elbow should point in rig + * coordinates.
rightHandPosition{@link Vec3}The desired position of the RightHand + * joint in rig coordinates.
rightHandRotation{@link Quat}The desired orientation of the + * RightHand joint in rig coordinates.
rightHandType{@link MyAvatar.IKTargetType|IKTargetType}The type of IK used for + * the right arm.
rightHandPoleVectorEnabledbooleanWhen true, the elbow angle is + * controlled by the rightHandPoleVector property value. Otherwise the elbow direction comes from the + * underlying animation.
rightHandPoleReferenceVector{@link Vec3}The direction of the elbow in the local + * coordinate system of the elbow.
rightHandPoleVector{@link Vec3}The direction the elbow should point in rig + * coordinates.
leftFootIKEnabledbooleantrue if IK is enabled for the left + * foot.
rightFootIKEnabledbooleantrue if IK is enabled for the right + * foot.
leftFootIKPositionVarstringThe name of the source for the desired position + * of the LeftFoot joint. If not set, the foot rotation of the underlying animation will be used.
leftFootIKRotationVarstringThe name of the source for the desired rotation + * of the LeftFoot joint. If not set, the foot rotation of the underlying animation will be used.
leftFootPoleVectorEnabledbooleanWhen true, the knee angle is + * controlled by the leftFootPoleVector property value. Otherwise the knee direction comes from the + * underlying animation.
leftFootPoleVector{@link Vec3}The direction the knee should face in rig + * coordinates.
rightFootIKPositionVarstringThe name of the source for the desired position + * of the RightFoot joint. If not set, the foot rotation of the underlying animation will be used.
rightFootIKRotationVarstringThe name of the source for the desired rotation + * of the RightFoot joint. If not set, the foot rotation of the underlying animation will be used.
rightFootPoleVectorEnabledbooleanWhen true, the knee angle is + * controlled by the rightFootPoleVector property value. Otherwise the knee direction comes from the + * underlying animation.
rightFootPoleVector{@link Vec3}The direction the knee should face in rig + * coordinates.
isTalkingbooleantrue if the avatar is talking.
notIsTalkingbooleantrue if the avatar is not talking.
solutionSource{@link MyAvatar.AnimIKSolutionSource|AnimIKSolutionSource}Determines the initial conditions of the IK solver.
defaultPoseOverlayAlphanumberControls the blend between the main animation state + * machine and the default pose. Mostly used during full body tracking so that walking & jumping animations do not + * affect the IK of the figure.
defaultPoseOverlayBoneSet{@link MyAvatar.AnimOverlayBoneSet|AnimOverlayBoneSet}Specifies which bones will be replace by the source overlay.
hipsType{@link MyAvatar.IKTargetType|IKTargetType}The type of IK used for the + * hips.
hipsPosition{@link Vec3}The desired position of Hips joint in rig + * coordinates.
hipsRotation{@link Quat}the desired orientation of the Hips joint in + * rig coordinates.
spine2Type{@link MyAvatar.IKTargetType|IKTargetType}The type of IK used for the + * Spine2 joint.
spine2Position{@link Vec3}The desired position of the Spine2 joint + * in rig coordinates.
spine2Rotation{@link Quat}The desired orientation of the Spine2 + * joint in rig coordinates.
leftFootIKAlphanumberBlends between full IK for the leg and the underlying + * animation.
rightFootIKAlphanumberBlends between full IK for the leg and the underlying + * animation.
hipsWeightnumberHow strongly the hips target blends with the IK solution for + * other IK chains.
leftHandWeightnumberHow strongly the left hand blends with IK solution of other + * IK chains.
rightHandWeightnumberHow strongly the right hand blends with IK solution of other + * IK chains.
spine2WeightnumberHow strongly the spine2 chain blends with the rest of the IK + * solution.
leftHandOverlayAlphanumberUsed to blend in the animated hand gesture poses, such + * as point and thumbs up.
leftHandGraspAlphanumberUsed to blend between an open hand and a closed hand. + * Usually changed as you squeeze the trigger of the hand controller.
rightHandOverlayAlphanumberUsed to blend in the animated hand gesture poses, + * such as point and thumbs up.
rightHandGraspAlphanumberUsed to blend between an open hand and a closed hand. + * Usually changed as you squeeze the trigger of the hand controller.
isLeftIndexPointbooleantrue if the left hand should be + * pointing.
isLeftThumbRaisebooleantrue if the left hand should be + * thumbs-up.
isLeftIndexPointAndThumbRaisebooleantrue if the left hand should be + * pointing and thumbs-up.
isLeftHandGraspbooleantrue if the left hand should be at rest, + * grasping the controller.
isRightIndexPointbooleantrue if the right hand should be + * pointing.
isRightThumbRaisebooleantrue if the right hand should be + * thumbs-up.
isRightIndexPointAndThumbRaisebooleantrue if the right hand should + * be pointing and thumbs-up.
isRightHandGraspbooleantrue if the right hand should be at rest, + * grasping the controller.
+ *

Note: Rig coordinates are +z forward and +y up.

+ * @typedef {object} MyAvatar.AnimStateDictionary + */ +// Note: The following animVars are intentionally not documented: +// - leftFootPosition +// - leftFootRotation +// - rightFooKPosition +// - rightFooKRotation +// Note: The following items aren't set in the code below but are still intentionally documented: +// - leftFootIKAlpha +// - rightFootIKAlpha +// - hipsWeight +// - leftHandWeight +// - rightHandWeight +// - spine2Weight +// - rightHandOverlayAlpha +// - rightHandGraspAlpha +// - leftHandOverlayAlpha +// - leftHandGraspAlpha +// - isRightIndexPoint +// - isRightThumbRaise +// - isRightIndexPointAndThumbRaise +// - isRightHandGrasp +// - isLeftIndexPoint +// - isLeftThumbRaise +// - isLeftIndexPointAndThumbRaise +// - isLeftHandGrasp Rig::Rig() { // Ensure thread-safe access to the rigRegistry. std::lock_guard guard(rigRegistryMutex); diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index 48fb4f0b83..3549578ed5 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -573,11 +573,12 @@ public slots: /**jsdoc * @function Script.callAnimationStateHandler - * @param {function} callback - * @param {object} parameters - * @param {string[]} names - * @param {boolean} useNames - * @param {object} resultHandler + * @param {function} callback - Callback. + * @param {object} parameters - Parameters. + * @param {string[]} names - Names. + * @param {boolean} useNames - Use names. + * @param {function} resultHandler - Result handler. + * @deprecated This function is deprecated and will be removed. */ void callAnimationStateHandler(QScriptValue callback, AnimVariantMap parameters, QStringList names, bool useNames, AnimVariantResultHandler resultHandler); From 24c7c8be190cd605f2531a6f2353e44aefb747e6 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 9 Mar 2019 12:03:59 +1300 Subject: [PATCH 12/21] Update JSDoc per merge from master --- interface/src/avatar/MyAvatar.cpp | 18 ++++++++++++++++++ interface/src/avatar/MyAvatar.h | 21 ++++++++++++--------- libraries/animation/src/Rig.cpp | 15 +++++++++++---- 3 files changed, 41 insertions(+), 13 deletions(-) diff --git a/interface/src/avatar/MyAvatar.cpp b/interface/src/avatar/MyAvatar.cpp index 3db1228796..710a0550c5 100644 --- a/interface/src/avatar/MyAvatar.cpp +++ b/interface/src/avatar/MyAvatar.cpp @@ -5358,6 +5358,24 @@ void MyAvatar::addAvatarHandsToFlow(const std::shared_ptr& otherAvatar) } } +/**jsdoc + * Physics options to use in the flow simulation of a joint. + * @typedef {object} MyAvatar.FlowPhysicsOptions + * @property {boolean} [active=true] - true to enable flow on the joint, false if it isn't., + * @property {number} [radius=0.01] - The thickness of segments and knots. (Needed for collisions.) + * @property {number} [gravity=-0.0096] - Y-value of the gravity vector. + * @property {number} [inertia=0.8] - Rotational inertia multiplier. + * @property {number} [damping=0.85] - The amount of damping on joint oscillation. + * @property {number} [stiffness=0.0] - How stiff each thread is. + * @property {number} [delta=0.55] - Delta time for every integration step. + */ +/**jsdoc + * Collision options to use in the flow simulation of a joint. + * @typedef {object} MyAvatar.FlowCollisionsOptions + * @property {string} [type="sphere"] - Currently, only "sphere" is supported. + * @property {number} [radius=0.05] - Collision sphere radius. + * @property {number} [offset=Vec3.ZERO] - Offset of the collision sphere from the joint. + */ void MyAvatar::useFlow(bool isActive, bool isCollidable, const QVariantMap& physicsConfig, const QVariantMap& collisionsConfig) { if (_skeletonModel->isLoaded()) { _skeletonModel->getRig().initFlow(isActive); diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 5e049c7a02..1c44db703f 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -1548,15 +1548,18 @@ public: void addAvatarHandsToFlow(const std::shared_ptr& otherAvatar); /**jsdoc - * Init flow simulation on avatar. - * @function MyAvatar.useFlow - * @param {boolean} - Set to true to activate flow simulation. - * @param {boolean} - Set to true to activate collisions. - * @param {Object} physicsConfig - object with the customized physic parameters - * i.e. {"hair": {"active": true, "stiffness": 0.0, "radius": 0.04, "gravity": -0.035, "damping": 0.8, "inertia": 0.8, "delta": 0.35}} - * @param {Object} collisionsConfig - object with the customized collision parameters - * i.e. {"Spine2": {"type": "sphere", "radius": 0.14, "offset": {"x": 0.0, "y": 0.2, "z": 0.0}}} - */ + * Enables and disables flow simulation of physics on the avatar's hair, clothes, and body parts. See + * {@link https://docs.highfidelity.com/create/avatars/create-avatars/add-flow.html|Add Flow to Your Avatar} for more + * information. + * @function MyAvatar.useFlow + * @param {boolean} isActive - true if flow simulation is enabled on the joint, false if it isn't. + * @param {boolean} isCollidable - true to enable collisions in the flow simulation, false to + * disable. + * @param {Object} [physicsConfig>] - Physic configurations for particular entity + * and avatar joints. + * @param {Object} [collisionsConfig] - Collision configurations for particular + * entity and avatar joints. + */ Q_INVOKABLE void useFlow(bool isActive, bool isCollidable, const QVariantMap& physicsConfig = QVariantMap(), const QVariantMap& collisionsConfig = QVariantMap()); public slots: diff --git a/libraries/animation/src/Rig.cpp b/libraries/animation/src/Rig.cpp index 2a4c2326db..e1ee134530 100644 --- a/libraries/animation/src/Rig.cpp +++ b/libraries/animation/src/Rig.cpp @@ -170,8 +170,13 @@ static const QString MAIN_STATE_MACHINE_RIGHT_HAND_POSITION("mainStateMachineRig * coordinate system of the elbow. * leftHandPoleVector{@link Vec3}The direction the elbow should point in rig * coordinates. - - * rightHandPosition{@link Vec3}The desired position of the RightHand + * + * leftHandIKEnabledbooleantrue if IK is enabled for the left + * hand. + * rightHandIKEnabledbooleantrue if IK is enabled for the right + * hand. + * + * rightHandPosition{@link Vec3}The desired position of the RightHand * joint in rig coordinates. * rightHandRotation{@link Quat}The desired orientation of the * RightHand joint in rig coordinates. @@ -189,7 +194,7 @@ static const QString MAIN_STATE_MACHINE_RIGHT_HAND_POSITION("mainStateMachineRig * foot. * rightFootIKEnabledbooleantrue if IK is enabled for the right * foot. - + * * leftFootIKPositionVarstringThe name of the source for the desired position * of the LeftFoot joint. If not set, the foot rotation of the underlying animation will be used. * leftFootIKRotationVarstringThe name of the source for the desired rotation @@ -199,7 +204,7 @@ static const QString MAIN_STATE_MACHINE_RIGHT_HAND_POSITION("mainStateMachineRig * underlying animation. * leftFootPoleVector{@link Vec3}The direction the knee should face in rig * coordinates. - * rightFootIKPositionVarstringThe name of the source for the desired position + * rightFootIKPositionVarstringThe name of the source for the desired position * of the RightFoot joint. If not set, the foot rotation of the underlying animation will be used. * rightFootIKRotationVarstringThe name of the source for the desired rotation * of the RightFoot joint. If not set, the foot rotation of the underlying animation will be used. @@ -209,6 +214,8 @@ static const QString MAIN_STATE_MACHINE_RIGHT_HAND_POSITION("mainStateMachineRig * rightFootPoleVector{@link Vec3}The direction the knee should face in rig * coordinates. * + * splineIKEnabledbooleantrue if IK is enabled for the spline. + * * isTalkingbooleantrue if the avatar is talking. * notIsTalkingbooleantrue if the avatar is not talking. * From 24286273b402d83009fa7387900514d68e6e73ef Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 9 Mar 2019 19:22:07 +1300 Subject: [PATCH 13/21] Miscellaneous JSDoc fixes --- interface/src/ui/overlays/Overlays.cpp | 48 +++++++++++++------------- libraries/avatars/src/AvatarData.h | 2 +- libraries/shared/src/BillboardMode.h | 8 +++-- 3 files changed, 30 insertions(+), 28 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index 1bcb040a77..eec6eddf44 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -1711,9 +1711,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if * parentID is an avatar skeleton. A value of 65535 means "no joint". * - * @property {boolean} isFacingAvatar - If true< / code>, the overlay is rotated to face the user's camera about an axis + * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis * parallel to the user's avatar's "up" direction. - * @property {string} text="" - The text to display.Text does not automatically wrap; use \n< / code> for a line break. + * @property {string} text="" - The text to display.Text does not automatically wrap; use \n for a line break. * @property {number} textAlpha=1 - The text alpha value. * @property {Color} backgroundColor=0,0,0 - The background color. * @property {number} backgroundAlpha=0.7 - The background alpha value. @@ -1929,39 +1929,39 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * * @property {number} startAt = 0 - The counter - clockwise angle from the overlay's x-axis that drawing starts at, in degrees. * @property {number} endAt = 360 - The counter - clockwise angle from the overlay's x-axis that drawing ends at, in degrees. - * @property {number} outerRadius = 1 - The outer radius of the overlay, in meters.Synonym: radius< / code>. + * @property {number} outerRadius = 1 - The outer radius of the overlay, in meters.Synonym: radius. * @property {number} innerRadius = 0 - The inner radius of the overlay, in meters. * @property {Color} color = 255, 255, 255 - The color of the overlay.Setting this value also sets the values of - * innerStartColor< / code>, innerEndColor< / code>, outerStartColor< / code>, and outerEndColor< / code>. - * @property {Color} startColor - Sets the values of innerStartColor< / code> and outerStartColor< / code>. - * Write - only.< / em> - * @property {Color} endColor - Sets the values of innerEndColor< / code> and outerEndColor< / code>. - * Write - only.< / em> - * @property {Color} innerColor - Sets the values of innerStartColor< / code> and innerEndColor< / code>. - * Write - only.< / em> - * @property {Color} outerColor - Sets the values of outerStartColor< / code> and outerEndColor< / code>. - * Write - only.< / em> + * innerStartColor, innerEndColor, outerStartColor, and outerEndColor. + * @property {Color} startColor - Sets the values of innerStartColor and outerStartColor. + * Write - only. + * @property {Color} endColor - Sets the values of innerEndColor and outerEndColor. + * Write - only. + * @property {Color} innerColor - Sets the values of innerStartColor and innerEndColor. + * Write - only. + * @property {Color} outerColor - Sets the values of outerStartColor and outerEndColor. + * Write - only. * @property {Color} innerStartcolor - The color at the inner start point of the overlay. * @property {Color} innerEndColor - The color at the inner end point of the overlay. * @property {Color} outerStartColor - The color at the outer start point of the overlay. * @property {Color} outerEndColor - The color at the outer end point of the overlay. - * @property {number} alpha = 0.5 - The opacity of the overlay, 0.0< / code> -1.0< / code>.Setting this value also sets - * the values of innerStartAlpha< / code>, innerEndAlpha< / code>, outerStartAlpha< / code>, and - * outerEndAlpha< / code>.Synonym: Alpha< / code>; write - only< / em>. - * @property {number} startAlpha - Sets the values of innerStartAlpha< / code> and outerStartAlpha< / code>. - * Write - only.< / em> - * @property {number} endAlpha - Sets the values of innerEndAlpha< / code> and outerEndAlpha< / code>. - * Write - only.< / em> - * @property {number} innerAlpha - Sets the values of innerStartAlpha< / code> and innerEndAlpha< / code>. - * Write - only.< / em> - * @property {number} outerAlpha - Sets the values of outerStartAlpha< / code> and outerEndAlpha< / code>. - * Write - only.< / em> + * @property {number} alpha = 0.5 - The opacity of the overlay, 0.0 -1.0.Setting this value also sets + * the values of innerStartAlpha, innerEndAlpha, outerStartAlpha, and + * outerEndAlpha.Synonym: Alpha; write - only. + * @property {number} startAlpha - Sets the values of innerStartAlpha and outerStartAlpha. + * Write - only. + * @property {number} endAlpha - Sets the values of innerEndAlpha and outerEndAlpha. + * Write - only. + * @property {number} innerAlpha - Sets the values of innerStartAlpha and innerEndAlpha. + * Write - only. + * @property {number} outerAlpha - Sets the values of outerStartAlpha and outerEndAlpha. + * Write - only. * @property {number} innerStartAlpha = 0 - The alpha at the inner start point of the overlay. * @property {number} innerEndAlpha = 0 - The alpha at the inner end point of the overlay. * @property {number} outerStartAlpha = 0 - The alpha at the outer start point of the overlay. * @property {number} outerEndAlpha = 0 - The alpha at the outer end point of the overlay. * - * @property {boolean} hasTickMarks = false - If true< / code>, tick marks are drawn. + * @property {boolean} hasTickMarks = false - If true, tick marks are drawn. * @property {number} majorTickMarksAngle = 0 - The angle between major tick marks, in degrees. * @property {number} minorTickMarksAngle = 0 - The angle between minor tick marks, in degrees. * @property {number} majorTickMarksLength = 0 - The length of the major tick marks, in meters.A positive value draws tick marks diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 858af7ba3c..e0437cfeb1 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -1034,7 +1034,7 @@ public: * @param {string} name - The name of the joint. * @returns {number} The index of the joint if valid, otherwise -1. * @example Report the index of your avatar's left arm joint. - * print(JSON.stringify(MyAvatar.getJointIndex("LeftArm")); + * print(JSON.stringify(MyAvatar.getJointIndex("LeftArm"))); * * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ diff --git a/libraries/shared/src/BillboardMode.h b/libraries/shared/src/BillboardMode.h index 050f939941..700127aff1 100644 --- a/libraries/shared/src/BillboardMode.h +++ b/libraries/shared/src/BillboardMode.h @@ -18,9 +18,11 @@ * ValueDescription * * - * noneThe entity will not be billboarded. - * yawThe entity will yaw, but not pitch, to face the camera. Its actual rotation will be ignored. - * fullThe entity will be billboarded to face the camera. Its actual rotation will be ignored. + * "none"The entity will not be billboarded. + * "yaw"The entity will yaw, but not pitch, to face the camera. Its actual rotation will be + * ignored. + * "full"The entity will be billboarded to face the camera. Its actual rotation will be + * ignored. * * * @typedef {string} BillboardMode From ea84847950e61db2534e86fd7487004b45e78559 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 13 Mar 2019 16:20:38 +1300 Subject: [PATCH 14/21] Update AnimStateDictionary JSDoc per feedback --- libraries/animation/src/Rig.cpp | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/libraries/animation/src/Rig.cpp b/libraries/animation/src/Rig.cpp index 74fd5d600b..82ab067472 100644 --- a/libraries/animation/src/Rig.cpp +++ b/libraries/animation/src/Rig.cpp @@ -91,6 +91,7 @@ static const QString MAIN_STATE_MACHINE_RIGHT_HAND_POSITION("mainStateMachineRig /**jsdoc *

An AnimStateDictionary object may have the following properties. It may also have other properties, set by * scripts.

+ *

Warning: These properties are subject to change. * * * @@ -171,11 +172,6 @@ static const QString MAIN_STATE_MACHINE_RIGHT_HAND_POSITION("mainStateMachineRig * * - * - * - * * * * - * - * * * * From 277ef56f4941e9d7d9742be7a23406b3b05fd516 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 14 Mar 2019 10:24:19 +1300 Subject: [PATCH 15/21] Fill in JSDoc for new flow functions --- interface/src/avatar/MyAvatar.cpp | 33 +++++++++++++++++++++++++++++++ interface/src/avatar/MyAvatar.h | 15 +++++++------- 2 files changed, 41 insertions(+), 7 deletions(-) diff --git a/interface/src/avatar/MyAvatar.cpp b/interface/src/avatar/MyAvatar.cpp index e0353da1b4..e0e9b5b648 100644 --- a/interface/src/avatar/MyAvatar.cpp +++ b/interface/src/avatar/MyAvatar.cpp @@ -5443,6 +5443,39 @@ void MyAvatar::useFlow(bool isActive, bool isCollidable, const QVariantMap& phys } } +/**jsdoc + * Flow options currently used in flow simulation. + * @typedef {object} MyAvatar.FlowData + * @property {boolean} initialized - true if flow has been initialized for the current avatar, false + * if it hasn't. + * @property {boolean} active - true if flow is enabled, false if it isn't. + * @property {boolean} colliding - true if collisions are enabled, false if they aren't. + * @property {Object} physicsData - The physics configuration for each group of joints + * that has been configured. + * @property {Object} collisions - The collisions configuration for each joint that + * has collisions configured. + * @property {Object} threads - The threads hat have been configured, with the name of the first joint as + * the ThreadName and an array of the indexes of all the joints in the thread as the value. + */ +/**jsdoc + * A set of physics options currently used in flow simulation. + * @typedef {object} MyAvatar.FlowPhysicsData + * @property {boolean} active - true to enable flow on the joint, false if it isn't., + * @property {number} radius - The thickness of segments and knots. (Needed for collisions.) + * @property {number} gravity - Y-value of the gravity vector. + * @property {number} inertia - Rotational inertia multiplier. + * @property {number} damping - The amount of damping on joint oscillation. + * @property {number} stiffness - How stiff each thread is. + * @property {number} delta - Delta time for every integration step. + * @property {number[]} jointIndices - The indexes of the joints the options are applied to. + */ +/**jsdoc + * A set of collision options currently used in flow simulation. + * @typedef {object} MyAvatar.FlowCollisionsData + * @property {number} radius - Collision sphere radius. + * @property {number} offset - Offset of the collision sphere from the joint. + * @property {number} jointIndex - The index of the joint the options are applied to. + */ QVariantMap MyAvatar::getFlowData() { QVariantMap result; if (QThread::currentThread() != thread()) { diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index c7585311b8..bd112bfacc 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -1563,16 +1563,17 @@ public: Q_INVOKABLE void useFlow(bool isActive, bool isCollidable, const QVariantMap& physicsConfig = QVariantMap(), const QVariantMap& collisionsConfig = QVariantMap()); /**jsdoc - * @function MyAvatar.getFlowData - * @returns {object} - */ + * Gets the current flow configuration. + * @function MyAvatar.getFlowData + * @returns {MyAvatar.FlowData} + */ Q_INVOKABLE QVariantMap getFlowData(); /**jsdoc - * returns the indices of every colliding flow joint - * @function MyAvatar.getCollidingFlowJoints - * @returns {int[]} - */ + * Gets the indexes of currently colliding flow joints. + * @function MyAvatar.getCollidingFlowJoints + * @returns {number[]} The indexes of currently colliding flow joints. + */ Q_INVOKABLE QVariantList getCollidingFlowJoints(); public slots: From 74edea80346209b6d7c7665360e78d2a212bef25 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 14 Mar 2019 10:25:31 +1300 Subject: [PATCH 16/21] Miscellaneous JSDoc fixes --- interface/src/avatar/MyAvatar.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index bd112bfacc..8951bc7fed 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -652,7 +652,7 @@ public: * Restores a default role animation. *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or - * "walkFwd". To get the full list of roles, use {#link MyAvatar.getAnimationRoles}. For each role, + * "walkFwd". To get the full list of roles, use {@link MyAvatar.getAnimationRoles}. For each role, * the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how animations are * blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation clip * (.FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. @@ -1555,7 +1555,7 @@ public: * @param {boolean} isActive - true if flow simulation is enabled on the joint, false if it isn't. * @param {boolean} isCollidable - true to enable collisions in the flow simulation, false to * disable. - * @param {Object} [physicsConfig>] - Physic configurations for particular entity + * @param {Object} [physicsConfig>] - Physics configurations for particular entity * and avatar joints. * @param {Object} [collisionsConfig] - Collision configurations for particular * entity and avatar joints. From 53b5a599b1c7600908ed5d41ddb27886c2eb814a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 15 Mar 2019 09:12:16 +1300 Subject: [PATCH 17/21] Reinstate avatar script type tag --- tools/jsdoc/plugins/hifi.js | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index b4350ddbdb..184da9b618 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -107,6 +107,9 @@ exports.handlers = { if (e.doclet.hifiClientEntity) { rows.push("Client Entity Scripts"); } + if (e.doclet.hifiAvatar) { + rows.push("Avatar Scripts"); + } if (e.doclet.hifiServerEntity) { rows.push("Server Entity Scripts"); } @@ -155,6 +158,13 @@ exports.defineTags = function (dictionary) { } }); + // @hifi-avatar-script + dictionary.defineTag("hifi-avatar", { + onTagged: function (doclet, tag) { + doclet.hifiAvatar = true; + } + }); + // @hifi-client-entity dictionary.defineTag("hifi-client-entity", { onTagged: function (doclet, tag) { From f0bbd8954657c26cc45ae1c77f504116035f198d Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 15 Mar 2019 11:05:58 +1300 Subject: [PATCH 18/21] Update JSDoc README with solution for out-of-memory problem --- tools/jsdoc/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tools/jsdoc/README.md b/tools/jsdoc/README.md index f9864a21e4..f3dda84291 100644 --- a/tools/jsdoc/README.md +++ b/tools/jsdoc/README.md @@ -15,6 +15,13 @@ To generate html documentation for the High Fidelity JavaScript API: The out folder should contain index.html. +If you get a "JavaScript heap out of memory" error when running the `jsdoc` command you need to increase the amount of memory +available to it. For example, to increase the memory available to 2GB on Windows: +* `where jsdoc` to find the `jsdoc.cmd` file. +* Edit the `jsdoc.cmd` file to add `--max-old-space-size=2048` after the `node` and/or `node.exe` commands. + +Reference: https://medium.com/@vuongtran/how-to-solve-process-out-of-memory-in-node-js-5f0de8f8464c + To generate the grav automation files, run node gravPrep.js after you have made a JSdoc output folder. This will create files that are needed for hifi-grav and hifi-grav-content repos From b78ae80ae621fc657f6882faa8ff8e84e6f282a9 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 26 Mar 2019 09:40:47 +1300 Subject: [PATCH 19/21] Address review comments and add further examples --- .../src/AgentScriptingInterface.h | 33 ++- .../src/avatars/ScriptableAvatar.h | 49 ++-- interface/src/avatar/MyAvatar.cpp | 21 +- interface/src/avatar/MyAvatar.h | 225 ++++++++++-------- .../animation/src/AnimInverseKinematics.h | 23 +- libraries/animation/src/AnimOverlay.h | 16 +- .../src/avatars-renderer/Avatar.h | 22 +- libraries/avatars/src/AvatarData.cpp | 6 +- libraries/avatars/src/AvatarData.h | 104 +++++--- 9 files changed, 310 insertions(+), 189 deletions(-) diff --git a/assignment-client/src/AgentScriptingInterface.h b/assignment-client/src/AgentScriptingInterface.h index 1242634dd5..b1a8aaff96 100644 --- a/assignment-client/src/AgentScriptingInterface.h +++ b/assignment-client/src/AgentScriptingInterface.h @@ -18,8 +18,8 @@ #include "Agent.h" /**jsdoc - * The Agent API enables an assignment client to emulate an avatar. In particular, setting isAvatar = - * true connects the assignment client to the avatar and audio mixers and enables the {@link Avatar} API to be used. + * The Agent API enables an assignment client to emulate an avatar. Setting isAvatar = true connects + * the assignment client to the avatar and audio mixers, and enables the {@link Avatar} API to be used. * * @namespace Agent * @@ -29,13 +29,13 @@ * false. * @property {boolean} isPlayingAvatarSound - true if the script has a sound to play, otherwise false. * Sounds are played when isAvatar is true, from the position and with the orientation of the - * scripted avatar's head.Read-only. + * scripted avatar's head. Read-only. * @property {boolean} isListeningToAudioStream - true if the agent is "listening" to the audio stream from the * domain, otherwise false. * @property {boolean} isNoiseGateEnabled - true if the noise gate is enabled, otherwise false. When * enabled, the input audio stream is blocked (fully attenuated) if it falls below an adaptive threshold. - * @property {number} lastReceivedAudioLoudness - The current loudness of the audio input, nominal range 0.0 (no - * sound) – 1.0 (the onset of clipping). Read-only. + * @property {number} lastReceivedAudioLoudness - The current loudness of the audio input. Nominal range [0.0 (no + * sound) – 1.0 (the onset of clipping)]. Read-only. * @property {Uuid} sessionUUID - The unique ID associated with the agent's current session in the domain. Read-only. */ class AgentScriptingInterface : public QObject { @@ -63,9 +63,9 @@ public: public slots: /**jsdoc - * Sets whether or not the script should emulate an avatar. + * Sets whether the script should emulate an avatar. * @function Agent.setIsAvatar - * @param {boolean} isAvatar - true if the script should act as if an avatar, otherwise false. + * @param {boolean} isAvatar - true if the script emulates an avatar, otherwise false. * @example

* (function () { * Agent.setIsAvatar(true); @@ -76,9 +76,14 @@ public slots: void setIsAvatar(bool isAvatar) const { _agent->setIsAvatar(isAvatar); } /**jsdoc - * Checks whether or not the script is emulating an avatar. + * Checks whether the script is emulating an avatar. * @function Agent.isAvatar - * @returns {boolean} true if the script is acting as if an avatar, otherwise false. + * @returns {boolean} true if the script is emulating an avatar, otherwise false. + * @example + * (function () { + * print("Agent is avatar: " + Agent.isAvatar()); + * print("Agent is avatar: " + Agent.isAvatar); // Same result. + * }()); */ bool isAvatar() const { return _agent->isAvatar(); } @@ -86,7 +91,15 @@ public slots: * Plays a sound from the position and with the orientation of the emulated avatar's head. No sound is played unless * isAvatar == true. * @function Agent.playAvatarSound - * @param {SoundObject} avatarSound - The sound to play. + * @param {SoundObject} avatarSound - The sound played. + * @example + * (function () { + * Agent.isAvatar = true; + * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav"); + * Script.setTimeout(function () { // Give the sound time to load. + * Agent.playAvatarSound(sound); + * }, 1000); + * }()); */ void playAvatarSound(SharedSoundPointer avatarSound) const { _agent->playAvatarSound(avatarSound); } diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 37e82947ae..fbe5675bd8 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -20,7 +20,7 @@ /**jsdoc * The Avatar API is used to manipulate scriptable avatars on the domain. This API is a subset of the - * {@link MyAvatar} API. To enable this API, set {@link Agent|Agent.isAvatatr} to true. + * {@link MyAvatar} API. To enable this API, set {@link Agent|Agent.isAvatar} to true. * *

For Interface, client entity, and avatar scripts, see {@link MyAvatar}.

* @@ -30,13 +30,13 @@ * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. * @property {Vec3} position - The position of the avatar. - * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 - * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. + * @property {number} scale=1.0 - The scale of the avatar. The value can be set to anything between 0.005 and + * 1000.0. When the scale value is fetched, it may temporarily be further limited by the domain's settings. * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in * the application of physics. Read-only. * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar * but is otherwise not used or changed by Interface. - * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. + * @property {number} bodyYaw - The left or right rotation about an axis running from the head to the feet of the avatar. * Yaw is sometimes called "heading". * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is * sometimes called "elevation". @@ -57,13 +57,12 @@ * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting * into the domain. * @property {string} displayName - The avatar's display name. - * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the - * avatar mixer rather than by Interface clients. The result is unique among all avatars present in the domain at the - * time. - * @property {boolean} lookAtSnappingEnabled=true - If true, the avatar's eyes snap to look at another avatar's - * eyes if generally in the line of sight and the other avatar also has lookAtSnappingEnabled == true. - * @property {string} skeletonModelURL - The URL of the avatar model's .fst file. - * @property {AttachmentData[]} attachmentData - Information on the attachments worn by the avatar.
+ * @property {string} sessionDisplayName - displayName's sanitized and default version defined by the avatar mixer + * rather than Interface clients. The result is unique among all avatars present in the domain at the time. + * @property {boolean} lookAtSnappingEnabled=true - true if the avatar's eyes snap to look at another avatar's + * eyes when the other avatar is in the line of sight and also has lookAtSnappingEnabled == true. + * @property {string} skeletonModelURL - The avatar's FST file. + * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. @@ -75,6 +74,12 @@ * avatar. Read-only. * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's * size in the virtual world. Read-only. + * + * @example + * (function () { + * Agent.setIsAvatar(true); + * print("Position: " + JSON.stringify(Avatar.position)); // 0, 0, 0 + * }()); */ class ScriptableAvatar : public AvatarData, public Dependency { @@ -90,14 +95,14 @@ public: /**jsdoc * Starts playing an animation on the avatar. * @function Avatar.startAnimation - * @param {string} url - The URL to the animation file. Animation files need to be .FBX format but only need to contain + * @param {string} url - The animation file's URL. Animation files need to be in the FBX format but only need to contain * the avatar skeleton and animation data. * @param {number} [fps=30] - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {number} [priority=1] - Not used. * @param {boolean} [loop=false] - true if the animation should loop, false if it shouldn't. * @param {boolean} [hold=false] - Not used. - * @param {number} [firstFrame=0] - The frame the animation should start at. - * @param {number} [lastFrame=3.403e+38] - The frame the animation should stop at. + * @param {number} [firstFrame=0] - The frame at which the animation starts. + * @param {number} [lastFrame=3.403e+38] - The frame at which the animation stops. * @param {string[]} [maskedJoints=[]] - The names of joints that should not be animated. */ /// Allows scripts to run animations. @@ -115,6 +120,9 @@ public: * Gets the details of the current avatar animation that is being or was recently played. * @function Avatar.getAnimationDetails * @returns {Avatar.AnimationDetails} The current or recent avatar animation. + * @example + * var animationDetails = Avatar.getAnimationDetails(); + * print("Animation details: " + JSON.stringify(animationDetails)); */ Q_INVOKABLE AnimationDetails getAnimationDetails(); @@ -146,18 +154,21 @@ public: bool getHasAudioEnabledFaceMovement() const override { return _headData->getHasAudioEnabledFaceMovement(); } /**jsdoc - * Gets the avatar entities as binary data. - *

Warning: Potentially a very expensive call. Do not use if possible.

+ * Gets details of all avatar entities. + *

Warning: Potentially an expensive call. Do not use if possible.

* @function Avatar.getAvatarEntityData - * @returns {AvatarEntityMap} The avatar entities as binary data. + * @returns {AvatarEntityMap} Details of the avatar entities. + * @example + * var avatarEntityData = Avatar.getAvatarEntityData(); + * print("Avatar entities: " + JSON.stringify(avatarEntityData)); */ Q_INVOKABLE AvatarEntityMap getAvatarEntityData() const override; /**jsdoc - * Sets the avatar entities from binary data. + * Sets all avatar entities from an object. *

Warning: Potentially an expensive call. Do not use if possible.

* @function Avatar.setAvatarEntityData - * @param {AvatarEntityMap} avatarEntityData - The avatar entities as binary data. + * @param {AvatarEntityMap} avatarEntityData - Details of the avatar entities. */ Q_INVOKABLE void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; diff --git a/interface/src/avatar/MyAvatar.cpp b/interface/src/avatar/MyAvatar.cpp index e0e9b5b648..12c260ccde 100644 --- a/interface/src/avatar/MyAvatar.cpp +++ b/interface/src/avatar/MyAvatar.cpp @@ -3542,8 +3542,8 @@ void MyAvatar::clearScaleRestriction() { /**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. + * @property {Vec3} position - The avatar's new position. + * @property {Quat} [orientation] - The avatar's new orientation. */ void MyAvatar::goToLocation(const QVariant& propertiesVar) { qCDebug(interfaceapp, "MyAvatar QML goToLocation"); @@ -3902,8 +3902,7 @@ void MyAvatar::setCollisionWithOtherAvatarsFlags() { } /**jsdoc - * A collision capsule is a cylinder with hemispherical ends. It is used, in particular, to approximate the extents of an - * avatar. + * A collision capsule is a cylinder with hemispherical ends. It is often used 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. @@ -5361,12 +5360,12 @@ void MyAvatar::addAvatarHandsToFlow(const std::shared_ptr& otherAvatar) /**jsdoc * Physics options to use in the flow simulation of a joint. * @typedef {object} MyAvatar.FlowPhysicsOptions - * @property {boolean} [active=true] - true to enable flow on the joint, false if it isn't., - * @property {number} [radius=0.01] - The thickness of segments and knots. (Needed for collisions.) + * @property {boolean} [active=true] - true to enable flow on the joint, otherwise false. + * @property {number} [radius=0.01] - The thickness of segments and knots (needed for collisions). * @property {number} [gravity=-0.0096] - Y-value of the gravity vector. * @property {number} [inertia=0.8] - Rotational inertia multiplier. * @property {number} [damping=0.85] - The amount of damping on joint oscillation. - * @property {number} [stiffness=0.0] - How stiff each thread is. + * @property {number} [stiffness=0.0] - The stiffness of each thread. * @property {number} [delta=0.55] - Delta time for every integration step. */ /**jsdoc @@ -5454,18 +5453,18 @@ void MyAvatar::useFlow(bool isActive, bool isCollidable, const QVariantMap& phys * that has been configured. * @property {Object} collisions - The collisions configuration for each joint that * has collisions configured. - * @property {Object} threads - The threads hat have been configured, with the name of the first joint as - * the ThreadName and an array of the indexes of all the joints in the thread as the value. + * @property {Object} threads - The threads that have been configured, with the first joint's name as the + * ThreadName and value as an array of the indexes of all the joints in the thread. */ /**jsdoc * A set of physics options currently used in flow simulation. * @typedef {object} MyAvatar.FlowPhysicsData - * @property {boolean} active - true to enable flow on the joint, false if it isn't., + * @property {boolean} active - true to enable flow on the joint, otherwise false. * @property {number} radius - The thickness of segments and knots. (Needed for collisions.) * @property {number} gravity - Y-value of the gravity vector. * @property {number} inertia - Rotational inertia multiplier. * @property {number} damping - The amount of damping on joint oscillation. - * @property {number} stiffness - How stiff each thread is. + * @property {number} stiffness - The stiffness of each thread. * @property {number} delta - Delta time for every integration step. * @property {number[]} jointIndices - The indexes of the joints the options are applied to. */ diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 8951bc7fed..3159348871 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -72,13 +72,13 @@ class MyAvatar : public Avatar { * * @comment IMPORTANT: This group of properties is copied from AvatarData.h; they should NOT be edited here. * @property {Vec3} position - The position of the avatar. - * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 - * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. + * @property {number} scale=1.0 - The scale of the avatar. The value can be set to anything between 0.005 and + * 1000.0. When the scale value is fetched, it may temporarily be further limited by the domain's settings. * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in * the application of physics. Read-only. * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar * but is otherwise not used or changed by Interface. - * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. + * @property {number} bodyYaw - The left or right rotation about an axis running from the head to the feet of the avatar. * Yaw is sometimes called "heading". * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is * sometimes called "elevation". @@ -99,13 +99,12 @@ class MyAvatar : public Avatar { * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting * into the domain. * @property {string} displayName - The avatar's display name. - * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the - * avatar mixer rather than by Interface clients. The result is unique among all avatars present in the domain at the - * time. - * @property {boolean} lookAtSnappingEnabled=true - If true, the avatar's eyes snap to look at another avatar's - * eyes if generally in the line of sight and the other avatar also has lookAtSnappingEnabled == true. - * @property {string} skeletonModelURL - The URL of the avatar model's .fst file. - * @property {AttachmentData[]} attachmentData - Information on the attachments worn by the avatar.
+ * @property {string} sessionDisplayName - displayName's sanitized and default version defined by the avatar + * mixer rather than Interface clients. The result is unique among all avatars present in the domain at the time. + * @property {boolean} lookAtSnappingEnabled=true - true if the avatar's eyes snap to look at another avatar's + * eyes when the other avatar is in the line of sight and also has lookAtSnappingEnabled == true. + * @property {string} skeletonModelURL - The avatar's FST file. + * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. @@ -149,12 +148,12 @@ class MyAvatar : public Avatar { * property value is audioListenerModeCustom. * @property {Quat} customListenOrientation=Quat.IDENTITY - The listening orientation used when the * audioListenerMode property value is audioListenerModeCustom. - * @property {boolean} hasScriptedBlendshapes=false - Blendshapes will be transmitted over the network if set to true.
+ * @property {boolean} hasScriptedBlendshapes=false - true to transmit blendshapes over the network.
* Note: Currently doesn't work. Use {@link MyAvatar.setForceFaceTrackerConnected} instead. - * @property {boolean} hasProceduralBlinkFaceMovement=true - If true then procedural blinking is turned on. - * @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 {boolean} hasProceduralBlinkFaceMovement=true - true if procedural blinking is turned on. + * @property {boolean} hasProceduralEyeFaceMovement=true - true if procedural eye movement is turned on. + * @property {boolean} hasAudioEnabledFaceMovement=true - true to move the mouth blendshapes with voice audio + * when MyAvatar.hasScriptedBlendshapes is enabled. * @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. @@ -178,23 +177,23 @@ class MyAvatar : public Avatar { * 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, relative to the avatar. + * @property {Pose} leftHandPose - The left hand's pose 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 {Pose} rightHandPose - The right hand's pose as determined by the hand controllers, relative to the avatar. + * Read-only. + * @property {Pose} leftHandTipPose - The left hand's pose 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 {Pose} rightHandTipPose - The right hand's pose 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 - 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 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 + * @property {boolean} centerOfGravityModelEnabled=true - true if 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. Set the + * value to false for default behavior where the hips are positioned under the head. + * @property {boolean} hmdLeanRecenterEnabled=true - true IF 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. * @property {boolean} collisionsEnabled - Set to true to enable the avatar to collide with the environment, @@ -227,9 +226,9 @@ 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 - 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 {number} walkSpeed - The walk speed of your avatar. + * @property {number} walkBackwardSpeed - The walk backward speed of your avatar. + * @property {number} sprintSpeed - 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 @@ -237,8 +236,8 @@ class MyAvatar : public Avatar { * 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} isSitStandStateLocked - true to lock the avatar sitting/standing state, i.e., use this + * to disable automatically changing state. * @property {boolean} allowTeleporting - true if teleporting is enabled in the Interface settings, * false if it isn't. Read-only. * @@ -396,7 +395,7 @@ public: * - * + * * * * function animStateHandler(dictionary) { * print("Anim state dictionary: " + JSON.stringify(dictionary)); @@ -715,7 +715,7 @@ public: /**jsdoc - * Gets whether or not you do snap turns in HMD mode. + * Gets whether you do snap turns in HMD mode. * @function MyAvatar.getSnapTurn * @returns {boolean} true if you do snap turns in HMD mode; false if you do smooth turns in HMD * mode. @@ -761,7 +761,7 @@ public: Q_INVOKABLE QString getHmdAvatarAlignmentType() const; /**jsdoc - * Sets whether the avatar hips are balanced over the feet or positioned under the head. + * Sets whether the avatar's hips are balanced over the feet or positioned under the head. * @function MyAvatar.setCenterOfGravityModelEnabled * @param {boolean} enabled - true to balance the hips over the feet, false to position the hips * under the head. @@ -777,7 +777,7 @@ public: 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 + * Sets whether 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 @@ -787,7 +787,7 @@ public: 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 + * Gets whether 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} true if recentering is enabled, false if not. @@ -864,7 +864,7 @@ public: float getDriveKey(DriveKeys key) const; /**jsdoc - * Gets the value of a drive key, regardless of whether or not it is disabled. + * Gets the value of a drive key, regardless of whether it is disabled. * @function MyAvatar.getRawDriveKey * @param {MyAvatar.DriveKeys} key - The drive key. * @returns {number} The value of the drive key. @@ -889,14 +889,15 @@ public: Q_INVOKABLE void disableDriveKey(DriveKeys key); /**jsdoc - * Enables the acction associated with a drive key. + * Enables the action associated with a drive key. The action may have been disabled with + * {@link MyAvatar.disableDriveKey|disableDriveKey}. * @function MyAvatar.enableDriveKey * @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. + * Checks whether a drive key is disabled. * @function MyAvatar.isDriveKeyDisabled * @param {DriveKeys} key - The drive key to check. * @returns {boolean} true if the drive key is disabled, false if it isn't. @@ -925,7 +926,7 @@ public: Q_INVOKABLE void triggerRotationRecenter(); /**jsdoc - * Gets whether or not the avatar is configured to keep its center of gravity under its head. + * Gets whether the avatar is configured to keep its center of gravity under its head. * @function MyAvatar.isRecenteringHorizontally * @returns {boolean} true if the avatar is keeping its center of gravity under its head position, * false if not. @@ -967,8 +968,8 @@ public: 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. + * If a face tracker is connected and being used, gets the estimated pitch of the user's head scaled. This is scale 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} The pitch that the avatar's head should be if a face tracker is connected and being used, otherwise * 0, in degrees. @@ -1080,8 +1081,8 @@ public: /**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 + *

Note: 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 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} The pose of the avatar's left hand, relative to the avatar, as positioned by a hand controller, and @@ -1092,8 +1093,8 @@ public: /**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 + *

Note: 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 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} The pose of the avatar's right hand, relative to the avatar, as positioned by a hand controller, and @@ -1247,14 +1248,14 @@ public: void clearWornAvatarEntities(); /**jsdoc - * Checks whether your avatar is flying or not. + * Checks whether your avatar is flying. * @function MyAvatar.isFlying * @returns {boolean} true if your avatar is flying and not taking off or falling, false if not. */ Q_INVOKABLE bool isFlying(); /**jsdoc - * Checks whether your avatar is in the air or not. + * Checks whether your avatar is in the air. * @function MyAvatar.isInAir * @returns {boolean} true if your avatar is taking off, flying, or falling, otherwise false * because your avatar is on the ground. @@ -1332,9 +1333,9 @@ public: Q_INVOKABLE void setAvatarScale(float scale); /**jsdoc - * Sets whether or not the avatar should collide with entities. + * Sets whether 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 + * 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 - true to enable the avatar to collide with entities, false to @@ -1343,7 +1344,7 @@ public: Q_INVOKABLE void setCollisionsEnabled(bool enabled); /**jsdoc - * Gets whether or not the avatar will currently collide with entities. + * Gets whether 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} true if the avatar will currently collide with entities, false if it won't. @@ -1351,7 +1352,7 @@ public: Q_INVOKABLE bool getCollisionsEnabled(); /**jsdoc - * Sets whether or not the avatar should collide with other avatars. + * Sets whether the avatar should collide with other avatars. * @function MyAvatar.setOtherAvatarsCollisionsEnabled * @param {boolean} enabled - true to enable the avatar to collide with other avatars, false * to disable. @@ -1359,7 +1360,7 @@ public: Q_INVOKABLE void setOtherAvatarsCollisionsEnabled(bool enabled); /**jsdoc - * Gets whether or not the avatar will collide with other avatars. + * Gets whether the avatar will collide with other avatars. * @function MyAvatar.getOtherAvatarsCollisionsEnabled * @returns {boolean} true if the avatar will collide with other avatars, false if it won't. */ @@ -1395,6 +1396,10 @@ public: * @function MyAvatar.getAbsoluteJointRotationInObjectFrame * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to the avatar. + * @example

+ * var headIndex = MyAvatar.getJointIndex("Head"); + * var headRotation = MyAvatar.getAbsoluteJointRotationInObjectFrame(headIndex); + * print("Head rotation: " + JSON.stringify(Quat.safeEulerAngles(headRotation))); // Degrees */ virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override; @@ -1404,6 +1409,10 @@ public: * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to the avatar. + * @example + * var headIndex = MyAvatar.getJointIndex("Head"); + * var headTranslation = MyAvatar.getAbsoluteJointTranslationInObjectFrame(headIndex); + * print("Head translation: " + JSON.stringify(headTranslation)); */ virtual glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const override; @@ -1500,36 +1509,56 @@ public: void prepareAvatarEntityDataForReload(); /**jsdoc - * Creates a new grab, that grabs an entity. + * Creates a new grab that grabs an entity. * @function MyAvatar.grab * @param {Uuid} targetID - The ID of the entity to grab. * @param {number} parentJointIndex - The avatar joint to use to grab the entity. - * @param {Vec3} offset - The target's local positional relative to the joint. + * @param {Vec3} offset - The target's local position relative to the joint. * @param {Quat} rotationalOffset - The target's local rotation relative to the joint. * @returns {Uuid} The ID of the new grab. + * @example + * var entityPosition = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })); + * var entityRotation = MyAvatar.orientation; + * var entityID = Entities.addEntity({ + * type: "Box", + * position: entityPosition, + * rotation: entityRotation, + * dimensions: { x: 0.5, y: 0.5, z: 0.5 } + * }); + * var rightHandJoint = MyAvatar.getJointIndex("RightHand"); + * var relativePosition = Entities.worldToLocalPosition(entityPosition, MyAvatar.SELF_ID, rightHandJoint); + * var relativeRotation = Entities.worldToLocalRotation(entityRotation, MyAvatar.SELF_ID, rightHandJoint); + * var grabID = MyAvatar.grab(entityID, rightHandJoint, relativePosition, relativeRotation); + * + * Script.setTimeout(function () { + * MyAvatar.releaseGrab(grabID); + * Entities.deleteEntity(entityID); + * }, 10000); */ Q_INVOKABLE const QUuid grab(const QUuid& targetID, int parentJointIndex, glm::vec3 positionalOffset, glm::quat rotationalOffset); /**jsdoc - * Releases (deletes) a grab, to stop grabbing an entity. + * Releases (deletes) a grab to stop grabbing an entity. * @function MyAvatar.releaseGrab * @param {Uuid} grabID - The ID of the grab to release. */ Q_INVOKABLE void releaseGrab(const QUuid& grabID); /**jsdoc - * Gets the avatar entities as binary data. + * Gets details of all avatar entities. * @function MyAvatar.getAvatarEntityData - * @override - * @returns {AvatarEntityMap} The avatar entities as binary data. + * @returns {AvatarEntityMap} Details of the avatar entities. + * @example + * var avatarEntityData = MyAvatar.getAvatarEntityData(); + * print("Avatar entities: " + JSON.stringify(avatarEntityData)); */ AvatarEntityMap getAvatarEntityData() const override; /**jsdoc - * Sets the avatar entities from binary data. + * Sets all avatar entities from an object. * @function MyAvatar.setAvatarEntityData - * @param {AvatarEntityMap} avatarEntityData - The avatar entities as binary data. + * @param {AvatarEntityMap} avatarEntityData - Details of the avatar entities. */ void setAvatarEntityData(const AvatarEntityMap& avatarEntityData) override; @@ -1549,7 +1578,7 @@ public: /**jsdoc * Enables and disables flow simulation of physics on the avatar's hair, clothes, and body parts. See - * {@link https://docs.highfidelity.com/create/avatars/create-avatars/add-flow.html|Add Flow to Your Avatar} for more + * {@link https://docs.highfidelity.com/create/avatars/add-flow.html|Add Flow to Your Avatar} for more * information. * @function MyAvatar.useFlow * @param {boolean} isActive - true if flow simulation is enabled on the joint, false if it isn't. @@ -1585,7 +1614,7 @@ public slots: * MyAvatar.resetSize(); * * for (var i = 0; i < 5; i++){ - * print ("Growing by 5 percent"); + * print("Growing by 5 percent"); * MyAvatar.increaseSize(); * } */ @@ -1598,7 +1627,7 @@ public slots: * MyAvatar.resetSize(); * * for (var i = 0; i < 5; i++){ - * print ("Shrinking by 5 percent"); + * print("Shrinking by 5 percent"); * MyAvatar.decreaseSize(); * } */ @@ -1695,7 +1724,7 @@ public slots: /**jsdoc - * Adds a thrust to your avatar's current thrust, to be applied for a short while. + * Adds a thrust to your avatar's current thrust to be applied for a short while. * @function MyAvatar.addThrust * @param {Vec3} thrust - The thrust direction and magnitude. * @deprecated Use {@link MyAvatar|MyAvatar.motorVelocity} and related properties instead. @@ -1735,7 +1764,9 @@ public slots: void setToggleHips(bool followHead); /**jsdoc - * Displays base of support of feet debug graphics. + * Displays the base of support area debug graphics if in HMD mode. If your head goes outside this area your avatar's hips + * are moved to counterbalance your avatar, and if your head moves too far then your avatar's position is moved (i.e., a + * step happens). * @function MyAvatar.setEnableDebugDrawBaseOfSupport * @param {boolean} enabled - true to show the debug graphics, false to hide. */ @@ -1805,7 +1836,7 @@ public slots: void setEnableDebugDrawDetailedCollision(bool isEnabled); /**jsdoc - * Gets whether or not your avatar mesh is visible. + * Gets whether your avatar mesh is visible. * @function MyAvatar.getEnableMeshVisible * @returns {boolean} true if your avatar's mesh is visible, otherwise false. */ @@ -1830,7 +1861,7 @@ public slots: void sanitizeAvatarEntityProperties(EntityItemProperties& properties) const; /**jsdoc - * Sets whether or not your avatar mesh is visible to you. + * Sets whether your avatar mesh is visible to you. * @function MyAvatar.setEnableMeshVisible * @param {boolean} enabled - true to show your avatar mesh, false to hide. * @example @@ -1842,7 +1873,7 @@ public slots: virtual void setEnableMeshVisible(bool isEnabled) override; /**jsdoc - * Sets whether or not inverse kinematics (IK) for your avatar. + * Sets whether inverse kinematics (IK) is enabled for your avatar. * @function MyAvatar.setEnableInverseKinematics * @param {boolean} enabled - true to enable IK, false to disable. */ @@ -1854,7 +1885,8 @@ public slots: *

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

* @function MyAvatar.getAnimGraphOverrideUrl - * @returns {string} The URL of the override animation graph. "" if there is no override animation graph. + * @returns {string} The URL of the override animation graph JSON file. "" if there is no override animation + * graph. */ QUrl getAnimGraphOverrideUrl() const; // thread-safe @@ -1863,25 +1895,27 @@ public slots: *

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 - The URL of the animation graph to use. Set to "" to clear an override. + * @param {string} url - The URL of the animation graph JSON file 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. + * Gets the URL of animation graph (i.e., the avatar animation JSON) 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} The URL of the current animation graph. + * @returns {string} The URL of the current animation graph JSON file. + * @Example + * print(MyAvatar.getAnimGraphUrl()); */ QUrl getAnimGraphUrl() const; // thread-safe /**jsdoc - * Sets the current animation graph to use for avatar animations and makes it the default. + * Sets the current animation graph (i.e., the avatar animation JSON) 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 - The URL of the animation graph to use. + * @param {string} url - The URL of the animation graph JSON file to use. */ void setAnimGraphUrl(const QUrl& url); // thread-safe @@ -1963,11 +1997,14 @@ signals: void otherAvatarsCollisionsEnabledChanged(bool enabled); /**jsdoc - * Triggered when the avatar's animation graph URL changes. + * Triggered when the avatar's animation graph being used changes. * @function MyAvatar.animGraphUrlChanged - * @param {string} url - The URL of the new animation graph. + * @param {string} url - The URL of the new animation graph JSON file. * @returns {Signal} - */ + * @example + * MyAvatar.animGraphUrlChanged.connect(function (url) { + * print("Avatar animation JSON changed to: " + url); + * }); */ void animGraphUrlChanged(const QUrl& url); /**jsdoc diff --git a/libraries/animation/src/AnimInverseKinematics.h b/libraries/animation/src/AnimInverseKinematics.h index d5a110ea76..6d58ecedec 100644 --- a/libraries/animation/src/AnimInverseKinematics.h +++ b/libraries/animation/src/AnimInverseKinematics.h @@ -66,24 +66,23 @@ public: * * * - * - * + * + * * - * * diff --git a/libraries/animation/src/AnimOverlay.h b/libraries/animation/src/AnimOverlay.h index 623672143e..1ad4e100db 100644 --- a/libraries/animation/src/AnimOverlay.h +++ b/libraries/animation/src/AnimOverlay.h @@ -34,17 +34,21 @@ public: * * * - * - * - * - * + * + * * * * - * - * + * + * * * * diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index cec440eb1a..87e6af5bb3 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -203,7 +203,7 @@ public: /**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.

+ * Avatar Standards.

* @function MyAvatar.getDefaultJointRotation * @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}. @@ -214,7 +214,7 @@ public: * 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.

+ * Avatar Standards.

* @function MyAvatar.getDefaultJointTranslation * @param {number} index - The joint index. * @returns {Vec3} The default translation of the joint (in model coordinates) if the joint index is valid, otherwise @@ -223,22 +223,30 @@ public: Q_INVOKABLE virtual glm::vec3 getDefaultJointTranslation(int index) const; /**jsdoc - * Provides read-only access to the default joint rotations in avatar coordinates. + * Gets the default joint rotations in avatar coordinates. * The default pose of the avatar is defined by the position and orientation of all bones * in the avatar's model file. Typically this is a T-pose. * @function MyAvatar.getAbsoluteDefaultJointRotationInObjectFrame * @param index {number} - The joint index. - * @returns {Quat} The rotation of this joint in avatar coordinates. + * @returns {Quat} The default rotation of the joint in avatar coordinates. + * @example + * var headIndex = MyAvatar.getJointIndex("Head"); + * var defaultHeadRotation = MyAvatar.getAbsoluteDefaultJointRotationInObjectFrame(headIndex); + * print("Default head rotation: " + JSON.stringify(Quat.safeEulerAngles(defaultHeadRotation))); // Degrees */ Q_INVOKABLE virtual glm::quat getAbsoluteDefaultJointRotationInObjectFrame(int index) const; /**jsdoc - * Provides read-only access to the default joint translations in avatar coordinates. + * Gets the default joint translations in avatar coordinates. * The default pose of the avatar is defined by the position and orientation of all bones * in the avatar's model file. Typically this is a T-pose. * @function MyAvatar.getAbsoluteDefaultJointTranslationInObjectFrame * @param index {number} - The joint index. - * @returns {Vec3} The position of this joint in avatar coordinates. + * @returns {Vec3} The default position of the joint in avatar coordinates. + * @example + * var headIndex = MyAvatar.getJointIndex("Head"); + * var defaultHeadTranslation = MyAvatar.getAbsoluteDefaultJointTranslationInObjectFrame(headIndex); + * print("Default head translation: " + JSON.stringify(defaultHeadTranslation)); */ Q_INVOKABLE virtual glm::vec3 getAbsoluteDefaultJointTranslationInObjectFrame(int index) const; @@ -459,7 +467,7 @@ public: 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. + * Sets the joint of the entity or avatar that the avatar is parented to. * @function MyAvatar.setParentJointIndex * @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 diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index 317d9ec903..39dfaa8a1a 100755 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -2802,7 +2802,7 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const /**jsdoc * Information on an attachment worn by the avatar. * @typedef {object} AttachmentData - * @property {string} modelUrl - The URL of the model file. Models can be .FBX or .OBJ format. + * @property {string} modelUrl - The URL of the model file. Models can be FBX or OBJ format. * @property {string} jointName - The offset to apply to the model relative to the joint position. * @property {Vec3} translation - The offset from the joint that the attachment is positioned at. * @property {Vec3} rotation - The rotation applied to the model relative to the joint orientation. @@ -3015,6 +3015,10 @@ float AvatarData::_avatarSortCoefficientSize { 8.0f }; float AvatarData::_avatarSortCoefficientCenter { 0.25f }; float AvatarData::_avatarSortCoefficientAge { 1.0f }; +/**jsdoc + * An object with the UUIDs of avatar entities as keys and avatar entity properties objects as values. + * @typedef {Object.} AvatarEntityMap + */ QScriptValue AvatarEntityMapToScriptValue(QScriptEngine* engine, const AvatarEntityMap& value) { QScriptValue obj = engine->newObject(); for (auto entityID : value.keys()) { diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index e2d24465cb..00e7e67923 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -61,10 +61,6 @@ using AvatarSharedPointer = std::shared_ptr; using AvatarWeakPointer = std::weak_ptr; using AvatarHash = QHash; -/**jsdoc - * An object with the UUIDs of avatar entities as keys and binary blobs, being the entity properties, as values. - * @typedef {Object.>} AvatarEntityMap - */ using AvatarEntityMap = QMap; using PackedAvatarEntityMap = QMap; // similar to AvatarEntityMap, but different internal format using AvatarEntityIDs = QSet; @@ -439,13 +435,13 @@ class AvatarData : public QObject, public SpatiallyNestable { // IMPORTANT: The JSDoc for the following properties should be copied to MyAvatar.h and ScriptableAvatar.h. /* * @property {Vec3} position - The position of the avatar. - * @property {number} scale=1.0 - The scale of the avatar. When setting, the value is limited to between 0.005 - * and 1000.0. When getting, the value may temporarily be further limited by the domain's settings. - * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in + * @property {number} scale=1.0 - The scale of the avatar. The value can be set to anything between 0.005 and + * 1000.0. When the scale value is fetched, it may temporarily be further limited by the domain's settings. + * @property {number} density - The density of the avatar in kg/m3. The density is used to work out its mass in * the application of physics. Read-only. - * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar + * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar * but is otherwise not used or changed by Interface. - * @property {number} bodyYaw - The rotation left or right about an axis running from the head to the feet of the avatar. + * @property {number} bodyYaw - The left or right rotation about an axis running from the head to the feet of the avatar. * Yaw is sometimes called "heading". * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of the avatar. Pitch is * sometimes called "elevation". @@ -461,28 +457,27 @@ class AvatarData : public QObject, public SpatiallyNestable { * sometimes called "bank". * @property {Vec3} velocity - The current velocity of the avatar. * @property {Vec3} angularVelocity - The current angular velocity of the avatar. - * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the + * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the * domain. - * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting + * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting * into the domain. * @property {string} displayName - The avatar's display name. - * @property {string} sessionDisplayName - Sanitized, defaulted version of displayName that is defined by the - * avatar mixer rather than by Interface clients. The result is unique among all avatars present in the domain at the - * time. - * @property {boolean} lookAtSnappingEnabled=true - If true, the avatar's eyes snap to look at another avatar's - * eyes if generally in the line of sight and the other avatar also has lookAtSnappingEnabled == true. - * @property {string} skeletonModelURL - The URL of the avatar model's .fst file. - * @property {AttachmentData[]} attachmentData - Information on the attachments worn by the avatar.
+ * @property {string} sessionDisplayName - displayName's sanitized and default version defined by the avatar + * mixer rather than Interface clients. The result is unique among all avatars present in the domain at the time. + * @property {boolean} lookAtSnappingEnabled=true - true if the avatar's eyes snap to look at another avatar's + * eyes when the other avatar is in the line of sight and also has lookAtSnappingEnabled == true. + * @property {string} skeletonModelURL - The avatar's FST file. + * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* Deprecated: Use avatar entities instead. * @property {string[]} jointNames - The list of joints in the current avatar model. Read-only. * @property {Uuid} sessionUUID - Unique ID of the avatar in the domain. Read-only. - * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the + * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the * avatar's size, orientation, and position in the virtual world. Read-only. - * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the + * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the * avatar. Read-only. - * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the + * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the * avatar. Read-only. - * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's + * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's * size in the virtual world. Read-only. */ Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) @@ -785,7 +780,7 @@ public: /**jsdoc * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -796,7 +791,7 @@ public: * Gets the translation of a joint 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.

+ * Avatar Standards.

* @function Avatar.getJointTranslation * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. @@ -897,7 +892,7 @@ public: Q_INVOKABLE virtual void clearJointData(const QString& name); /**jsdoc - * Checks that the data for a joint are valid. + * Checks if the data for a joint are valid. * @function Avatar.isJointDataValid * @param {string} name - The name of the joint. * @returns {boolean} true if the joint data are valid, false if not. @@ -906,7 +901,7 @@ public: /**jsdoc * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {string} name - The name of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -921,7 +916,7 @@ public: * Gets the translation of a joint 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.

+ * Avatar Standards.

* @function Avatar.getJointTranslation * @param {number} name - The name of the joint. * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. @@ -1062,8 +1057,13 @@ public: * your avatar's face, use {@link Avatar.setForceFaceTrackerConnected} or {@link MyAvatar.setForceFaceTrackerConnected}. * @function Avatar.setBlendshape * @param {string} name - The name of the blendshape, per the - * {@link https://docs.highfidelity.com/create/avatars/create-avatars/avatar-standards.html#blendshapes Avatar Standards}. + * {@link https://docs.highfidelity.com/create/avatars/avatar-standards.html#blendshapes Avatar Standards}. * @param {number} value - A value between 0.0 and 1.0. + * @example + * MyAvatar.setForceFaceTrackerConnected(true); + * MyAvatar.setBlendshape("JawOpen", 1.0); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ Q_INVOKABLE void setBlendshape(QString name, float val) { _headData->setBlendshape(name, val); } @@ -1170,7 +1170,7 @@ public: * @example * var attachments = MyAvatar.getaAttachmentData(); * for (var i = 0; i < attachments.length; i++) { - * print (attachments[i].modelURL); + * print(attachments[i].modelURL); * } * * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". @@ -1318,6 +1318,14 @@ public: * @function Avatar.getSensorToWorldMatrix * @returns {Mat4} The scale, rotation, and translation transform from the user's real world to the avatar's size, * orientation, and position in the virtual world. + * @example + * var sensorToWorldMatrix = MyAvatar.getSensorToWorldMatrix(); + * print("Sensor to woprld matrix: " + JSON.stringify(sensorToWorldMatrix)); + * print("Rotation: " + JSON.stringify(Mat4.extractRotation(sensorToWorldMatrix))); + * print("Translation: " + JSON.stringify(Mat4.extractTranslation(sensorToWorldMatrix))); + * print("Scale: " + JSON.stringify(Mat4.extractScale(sensorToWorldMatrix))); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ // thread safe Q_INVOKABLE glm::mat4 getSensorToWorldMatrix() const; @@ -1335,6 +1343,14 @@ public: * Gets the rotation and translation of the left hand controller relative to the avatar. * @function Avatar.getControllerLeftHandMatrix * @returns {Mat4} The rotation and translation of the left hand controller relative to the avatar. + * @example + * var leftHandMatrix = MyAvatar.getControllerLeftHandMatrix(); + * print("Controller left hand matrix: " + JSON.stringify(leftHandMatrix)); + * print("Rotation: " + JSON.stringify(Mat4.extractRotation(leftHandMatrix))); + * print("Translation: " + JSON.stringify(Mat4.extractTranslation(leftHandMatrix))); + * print("Scale: " + JSON.stringify(Mat4.extractScale(leftHandMatrix))); // Always 1,1,1. + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ // thread safe Q_INVOKABLE glm::mat4 getControllerLeftHandMatrix() const; @@ -1409,6 +1425,12 @@ signals: * Triggered when the avatar's displayName property value changes. * @function Avatar.displayNameChanged * @returns {Signal} + * @example + * MyAvatar.displayNameChanged.connect(function () { + * print("Avatar display name changed to: " + MyAvatar.displayName); + * }); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ void displayNameChanged(); @@ -1416,6 +1438,12 @@ signals: * Triggered when the avatar's sessionDisplayName property value changes. * @function Avatar.sessionDisplayNameChanged * @returns {Signal} + * @example + * MyAvatar.sessionDisplayNameChanged.connect(function () { + * print("Avatar session display name changed to: " + MyAvatar.sessionDisplayName); + * }); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ void sessionDisplayNameChanged(); @@ -1423,6 +1451,12 @@ signals: * Triggered when the avatar's model (i.e., skeletonModelURL property value) is changed. * @function Avatar.skeletonModelURLChanged * @returns {Signal} + * @example + * MyAvatar.skeletonModelURLChanged.connect(function () { + * print("Skeleton model changed to: " + MyAvatar.skeletonModelURL); + * }); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ void skeletonModelURLChanged(); @@ -1431,6 +1465,12 @@ signals: * @function Avatar.lookAtSnappingChanged * @param {boolean} enabled - true if look-at snapping is enabled, false if not. * @returns {Signal} + * @example + * MyAvatar.lookAtSnappingChanged.connect(function () { + * print("Avatar look-at snapping changed to: " + MyAvatar.lookAtSnappingEnabled); + * }); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ void lookAtSnappingChanged(bool enabled); @@ -1438,6 +1478,12 @@ signals: * Triggered when the avatar's sessionUUID property value changes. * @function Avatar.sessionUUIDChanged * @returns {Signal} + * @example + * MyAvatar.sessionUUIDChanged.connect(function () { + * print("Avatar session UUID changed to: " + MyAvatar.sessionUUID); + * }); + * + * // Note: If using from the Avatar API, replace "MyAvatar" with "Avatar". */ void sessionUUIDChanged(); From 839a03ebe6daa68be3ca5c34155fc3e8109a57d0 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 26 Mar 2019 09:41:07 +1300 Subject: [PATCH 20/21] Miscellaneous JSDoc fixes noticed in passing --- interface/src/ui/overlays/Overlays.cpp | 22 +++++++++++----------- libraries/shared/src/shared/Camera.h | 2 +- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index eec6eddf44..2ade5edda5 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -1876,7 +1876,7 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @property {Vec3} localPosition - The local position of the overlay relative to its parent if the overlay has a * parentID set, otherwise the same value as position. * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a - * parentID set, otherwise the same value as rotation. Synonym: localOrientation. + * parentID set, otherwise the same value as rotation. Synonym: localOrientation. * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD. * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD. @@ -1916,7 +1916,7 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @property {Vec3} localPosition - The local position of the overlay relative to its parent if the overlay has a * parentID set, otherwise the same value as position. * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a - * parentID set, otherwise the same value as rotation. Synonym: localOrientation. + * parentID set, otherwise the same value as rotation. Synonym: localOrientation. * @property {boolean} isSolid=false - Synonyms: solid, isFilled, and filled. * Antonyms: isWire and wire. * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym. @@ -1927,11 +1927,11 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if * parentID is an avatar skeleton. A value of 65535 means "no joint". * - * @property {number} startAt = 0 - The counter - clockwise angle from the overlay's x-axis that drawing starts at, in degrees. - * @property {number} endAt = 360 - The counter - clockwise angle from the overlay's x-axis that drawing ends at, in degrees. - * @property {number} outerRadius = 1 - The outer radius of the overlay, in meters.Synonym: radius. - * @property {number} innerRadius = 0 - The inner radius of the overlay, in meters. - * @property {Color} color = 255, 255, 255 - The color of the overlay.Setting this value also sets the values of + * @property {number} startAt = 0 - The counter - clockwise angle from the overlay's x-axis that drawing starts at in degrees. + * @property {number} endAt = 360 - The counter - clockwise angle from the overlay's x-axis that drawing ends at in degrees. + * @property {number} outerRadius = 1 - The outer radius of the overlay in meters. Synonym: radius. + * @property {number} innerRadius = 0 - The inner radius of the overlay in meters. + * @property {Color} color = 255, 255, 255 - The color of the overlay. Setting this value also sets the values of * innerStartColor, innerEndColor, outerStartColor, and outerEndColor. * @property {Color} startColor - Sets the values of innerStartColor and outerStartColor. * Write - only. @@ -1945,9 +1945,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @property {Color} innerEndColor - The color at the inner end point of the overlay. * @property {Color} outerStartColor - The color at the outer start point of the overlay. * @property {Color} outerEndColor - The color at the outer end point of the overlay. - * @property {number} alpha = 0.5 - The opacity of the overlay, 0.0 -1.0.Setting this value also sets + * @property {number} alpha = 0.5 - The opacity of the overlay, 0.0 -1.0. Setting this value also sets * the values of innerStartAlpha, innerEndAlpha, outerStartAlpha, and - * outerEndAlpha.Synonym: Alpha; write - only. + * outerEndAlpha. Synonym: Alpha; write - only. * @property {number} startAlpha - Sets the values of innerStartAlpha and outerStartAlpha. * Write - only. * @property {number} endAlpha - Sets the values of innerEndAlpha and outerEndAlpha. @@ -1964,9 +1964,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @property {boolean} hasTickMarks = false - If true, tick marks are drawn. * @property {number} majorTickMarksAngle = 0 - The angle between major tick marks, in degrees. * @property {number} minorTickMarksAngle = 0 - The angle between minor tick marks, in degrees. - * @property {number} majorTickMarksLength = 0 - The length of the major tick marks, in meters.A positive value draws tick marks + * @property {number} majorTickMarksLength = 0 - The length of the major tick marks, in meters. A positive value draws tick marks * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. - * @property {number} minorTickMarksLength = 0 - The length of the minor tick marks, in meters.A positive value draws tick marks + * @property {number} minorTickMarksLength = 0 - The length of the minor tick marks, in meters. A positive value draws tick marks * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. * @property {Color} majorTickMarksColor = 0, 0, 0 - The color of the major tick marks. * @property {Color} minorTickMarksColor = 0, 0, 0 - The color of the minor tick marks. diff --git a/libraries/shared/src/shared/Camera.h b/libraries/shared/src/shared/Camera.h index 31e6228bb9..0132e58d18 100644 --- a/libraries/shared/src/shared/Camera.h +++ b/libraries/shared/src/shared/Camera.h @@ -138,7 +138,7 @@ public slots: * var pickRay = Camera.computePickRay(event.x, event.y); * var intersection = Entities.findRayIntersection(pickRay); * if (intersection.intersects) { - * print ("You clicked on entity " + intersection.entityID); + * print("You clicked on entity " + intersection.entityID); * } * } * From 4a832be8c65efb9bc5504a802702427bed58c34b Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 26 Mar 2019 10:03:30 +1300 Subject: [PATCH 21/21] Fix JSDoc post-merge --- interface/src/avatar/MyAvatar.h | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index f95ea898ba..edb686a6a6 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -1609,8 +1609,7 @@ public: public slots: /**jsdoc - * @function MyAvatar.setSessionUUID - * @param {Uuid} sessionUUID + * @comment Uses the base class's JSDoc. */ virtual void setSessionUUID(const QUuid& sessionUUID) override;
NameType

Description
leftHandPoleVector{@link Vec3}The direction the elbow should point in rig * coordinates.
leftHandIKEnabledbooleantrue if IK is enabled for the left - * hand.
rightHandIKEnabledbooleantrue if IK is enabled for the right - * hand.
rightHandPosition{@link Vec3}The desired position of the RightHand * joint in rig coordinates.
rightHandRotation{@link Quat}The desired orientation of the @@ -214,8 +210,6 @@ static const QString MAIN_STATE_MACHINE_RIGHT_HAND_POSITION("mainStateMachineRig *
rightFootPoleVector{@link Vec3}The direction the knee should face in rig * coordinates.
splineIKEnabledbooleantrue if IK is enabled for the spline.
isTalkingbooleantrue if the avatar is talking.
notIsTalkingbooleantrue if the avatar is not talking.
Make an assignment client script emulate an avatar.Check whether the agent is emulating an avatar.Play a sound from an emulated avatar.Create a scriptable avatar.Report the current animation details.Report the current avatar entities.
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.
9ZOOMZoom 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 @@ -471,13 +470,14 @@ public: void setCollisionWithOtherAvatarsFlags() override; /**jsdoc - * Resets the sensor positioning of your HMD (if used) and recenters your avatar body and head. + * Resets the sensor positioning of your HMD (if in use) and recenters your avatar body and head. * @function MyAvatar.resetSensorsAndBody */ Q_INVOKABLE void resetSensorsAndBody(); /**jsdoc - * Moves and orients the avatar, such that it is directly underneath the HMD, with toes pointed forward. + * Moves and orients the avatar, such that it is directly underneath the HMD, with toes pointed forward in the direction of + * the HMD. * @function MyAvatar.centerBody */ Q_INVOKABLE void centerBody(); // thread-safe @@ -486,7 +486,7 @@ public: /**jsdoc * Clears inverse kinematics joint limit history. *

The internal inverse-kinematics system maintains a record of which joints are "locked". Sometimes it is useful to - * forget this history, to prevent contorted joints.

+ * forget this history to prevent contorted joints, e.g., after finishing with an override animation.

* @function MyAvatar.clearIKJointLimitHistory */ Q_INVOKABLE void clearIKJointLimitHistory(); // thread-safe @@ -502,14 +502,14 @@ public: /**jsdoc * Gets the avatar orientation. Suitable for use in QML. * @function MyAvatar.setOrientationVar - * @param {object} newOrientationVar - The avatar orientation. + * @param {object} newOrientationVar - The avatar's orientation. */ Q_INVOKABLE void setOrientationVar(const QVariant& newOrientationVar); /**jsdoc * Gets the avatar orientation. Suitable for use in QML. * @function MyAvatar.getOrientationVar - * @returns {object} The avatar orientation. + * @returns {object} The avatar's orientation. */ Q_INVOKABLE QVariant getOrientationVar() const; @@ -558,9 +558,9 @@ public: *

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards.

+ * Avatar Standards.

* @function MyAvatar.overrideAnimation - * @param url {string} The URL to the animation file. Animation files need to be .FBX format, but only need to contain the + * @param url {string} The URL to the animation file. Animation files need to be FBX format, but only need to contain the * avatar skeleton and animation data. * @param fps {number} The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param loop {boolean} Set to true if the animation should loop. @@ -572,6 +572,7 @@ public: * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53); * Script.setTimeout(function () { * MyAvatar.restoreAnimation(); + * MyAvatar.clearIKJointLimitHistory(); * }, 3000); */ Q_INVOKABLE void overrideAnimation(const QString& url, float fps, bool loop, float firstFrame, float lastFrame); @@ -617,18 +618,18 @@ public: *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or * "walkFwd". To get the full list of roles, use {@ link MyAvatar.getAnimationRoles}. - * For each role, the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how + * For each role, the avatar-animation.json defines when the animation is used, the animation clip (FBX) used, and how * animations are blended together with procedural data (such as look at vectors, hand sensors etc.). - * overrideRoleAnimation() is used to change the animation clip (.FBX) associated with a specified animation + * overrideRoleAnimation() is used to change the animation clip (FBX) associated with a specified animation * role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.

*

Note: Hand roles only affect the hand. Other 'main' roles, like 'idleStand', 'idleTalk', 'takeoffStand' are full body.

*

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards. + * Avatar Standards. * @function MyAvatar.overrideRoleAnimation * @param role {string} The animation role to override - * @param url {string} The URL to the animation file. Animation files need to be .FBX format, but only need to contain the avatar skeleton and animation data. + * @param url {string} The URL to the animation file. Animation files need to be in FBX format, but only need to contain the avatar skeleton and animation data. * @param fps {number} The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param loop {boolean} Set to true if the animation should loop * @param firstFrame {number} The frame the animation should start at @@ -653,9 +654,9 @@ public: *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or * "walkFwd". To get the full list of roles, use {@link MyAvatar.getAnimationRoles}. For each role, - * the avatar-animation.json defines when the animation is used, the animation clip (.FBX) used, and how animations are + * the avatar-animation.json defines when the animation is used, the animation clip (FBX) used, and how animations are * blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation clip - * (.FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. + * (FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. * restoreRoleAnimation() is used to restore a specified animation role's default animation clip. If you have * not specified an override animation for the specified role, this function has no effect. * @function MyAvatar.restoreRoleAnimation @@ -688,10 +689,9 @@ public: * @function MyAvatar.addAnimationStateHandler * @param {function} handler - The animation state handler function to add. * @param {Array|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 + * properties that should be included in the 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. + * @returns {number} The ID of the animation state handler function if successfully added, undefined if not. * @example

Log all the animation state dictionary parameters for a short while.Report the rotation of your avatar's head joint relative to your avatar.Report the translation of your avatar's head joint relative to your avatar.Create and grab an entity for a short while.Report the current avatar entities.Make your avatar invisible for 10s.Report the current avatar animation JSON being used.Report when the current avatar animation JSON being used changes.
ValueName

Description
0RelaxToUnderPosesThis is a blend between PreviousSolution and - * UnderPoses: it is 15/16 PreviousSolution and 1/16 UnderPoses. This - * provides some of the benefits of using UnderPoses so that the underlying animation is still visible, - * while at the same time converging faster then using the UnderPoses only initial solution.
1RelaxToLimitCenterPosesThis is a blend between - * Previous Solution and LimitCenterPoses: it is 15/16 PreviousSolution and - * 1/16 LimitCenterPoses. This should converge quickly because it is close to the previous solution, but - * still provides the benefits of avoiding limb locking.
0RelaxToUnderPosesThis is a blend: it is 15/16 PreviousSolution + * and 1/16 UnderPoses. This provides some of the benefits of using UnderPoses so that the + * underlying animation is still visible, while at the same time converging faster then using the + * UnderPoses as the only initial solution.
1RelaxToLimitCenterPosesThis is a blend: it is 15/16 + * PreviousSolution and 1/16 LimitCenterPoses. This should converge quickly because it is + * close to the previous solution, but still provides the benefits of avoiding limb locking.
2PreviousSolutionThe IK system will begin to solve from the same position and * orientations for each joint that was the result from the previous frame.
- * Pros: because the end effectors typically do not move much from frame to frame, this is likely to converge quickly + * Pros: As the end effectors typically do not move much from frame to frame, this is likely to converge quickly * to a valid solution.
* Cons: If the previous solution resulted in an awkward or uncomfortable posture, the next frame will also be * awkward and uncomfortable. It can also result in locked elbows and knees.
3UnderPosesThe IK occurs at one of the top-most layers, it has access to the + *
3UnderPosesThe IK occurs at one of the top-most layers. It has access to the * full posture that was computed via canned animations and blends. We call this animated set of poses the "under * pose". The under poses are what would be visible if IK was completely disabled. Using the under poses as the - * initial conditions of the CCD solve will cause some of the animated motion to be blended in to the result of the + * initial conditions of the CCD solve will cause some of the animated motion to be blended into the result of the * IK. This can result in very natural results, especially if there are only a few IK targets enabled. On the other * hand, because the under poses might be quite far from the desired end effector, it can converge slowly in some * cases, causing it to never reach the IK target in the allotted number of iterations. Also, in situations where all @@ -93,7 +92,7 @@ public: * constraints. This can prevent the IK solution from getting locked or stuck at a particular constraint. For * example, if the arm is pointing straight outward from the body, as the end effector moves towards the body, at * some point the elbow should bend to accommodate. However, because the CCD solver is stuck at a local maximum, it - * will not rotate the elbow, unless the initial conditions already has the elbow bent, which is the case for + * will not rotate the elbow, unless the initial conditions already have the elbow bent, which is the case for * LimitCenterPoses. When all the IK targets are enabled, this result will provide a consistent starting * point for each IK solve, hopefully resulting in a consistent, natural result.
0FullBodyBoneSetAll joints.
1UpperBodyBoneSetOnly the "Spine" joint and its children.
2LowerBodyBoneSetOnly the leg joints and their children.
3LeftArmBoneSetJoints that are children of the "LeftShoulder" joint.
4RightArmBoneSetJoints that are children of the "RightShoulder" + *
3LeftArmBoneSetJoints that are the children of the "LeftShoulder" * joint.
5AboveTheHeadBoneSetJoints that are children of the "Head" joint.
6BelowTheHeadBoneSetJoints that are NOT children of the "head" + *
4RightArmBoneSetJoints that are the children of the "RightShoulder" + * joint.
5AboveTheHeadBoneSetJoints that are the children of the "Head" + * joint.
6BelowTheHeadBoneSetJoints that are NOT the children of the "head" * joint.
7HeadOnlyBoneSetThe "Head" joint.
8SpineOnlyBoneSetThe "Spine" joint.
9EmptyBoneSetNo joints.
10LeftHandBoneSetjoints that are children of the "LeftHand" joint.
11RightHandBoneSetJoints that are children of the "RightHand" joint.
10LeftHandBoneSetjoints that are the children of the "LeftHand" + * joint.
11RightHandBoneSetJoints that are the children of the "RightHand" + * joint.
12HipsOnlyBoneSetThe "Hips" joint.
13BothFeetBoneSetThe "LeftFoot" and "RightFoot" joints.
Report the default rotation of your avatar's head joint relative to your avatar.Report the default translation of your avatar's head joint relative to your avatar.Open your avatar's mouth wide.Report the URLs of all current attachments.Report the sensor to world matrix.Report the left hand controller matrix.Report when your avatar display name changes.Report when your avatar's session display name changes.Report when your avatar's skeleton model changes.Report when your look-at snapping setting changes.Report when your avatar's session UUID changes.