From eba89e8a80ff0d49a3ef3350b079ee486ec42f69 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 8 Mar 2019 13:50:03 +1300 Subject: [PATCH] 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} */