null if no avatar is 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.
diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp
index d0ab314edf..a9e16e9ff1 100644
--- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp
+++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp
@@ -1920,6 +1920,13 @@ void Avatar::setParentJointIndex(quint16 parentJointIndex) {
}
}
+/**jsdoc
+ * Information about a joint in an avatar's skeleton hierarchy.
+ * @typedef {object} SkeletonJoint
+ * @property {string} name - Joint name.
+ * @property {number} index - Joint index.
+ * @property {number} parentIndex - Index of this joint's parent (-1 if no parent).
+ */
QListCreated using {@link MyAvatar.getTargetAvatar} or {@link AvatarList.getAvatar}.
+ * + * @class ScriptAvatar + * @hideconstructor + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * @hifi-assignment-client + * @hifi-server-entity + * + * @property {Vec3} position - The avatar's position. + * @property {number} scale - The target scale of the avatar without any restrictions on permissible values imposed by the + * domain. + * @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} bodyPitch - The pitch of the avatar's body, in degrees. + * @property {number} bodyYaw - The yaw of the avatar's body, in degrees. + * @property {number} bodyRoll - The roll of the avatar's body, in degrees. + * @property {Quat} orientation - The orientation of the avatar's body. + * @property {Quat} headOrientation - The orientation of the avatar's head. + * @property {number} headPitch - The pitch of the avatar's head relative to the body, in degrees. + * @property {number} headYaw - The yaw of the avatar's head relative to the body, in degrees. + * @property {number} headRoll - The roll of the avatar's head relative to the body, in degrees. + * + * @property {Vec3} velocity - The linear velocity of the avatar. + * @property {Vec3} angularVelocity - The angular velocity of the avatar. + * + * @property {Uuid} sessionUUID - The avatar's session ID. + * @property {string} displayName - The avatar's display name. + * @property {string} sessionDisplayName - The avatar's display name, sanitized and versioned, as defined by the avatar mixer. + * It is unique among all avatars present in the domain at the time. + * @property {boolean} isReplicated - Deprecated: This property is deprecated and will be + * removed. + * @property {boolean} lookAtSnappingEnabled -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: This property is deprecated and will be removed. Use avatar entities instead.
+ * @property {string[]} jointNames - The list of joints in the avatar model. + * + * @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 {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. + * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the avatar. + * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the + * avatar. + * + * @property {Vec3} skeletonOffset - The rendering offset of the avatar. + */ class ScriptAvatar : public ScriptAvatarData { Q_OBJECT @@ -26,27 +84,138 @@ public: public slots: + /**jsdoc + * Gets the default rotation of a joint in the avatar relative to its parent. + *For information on the joint hierarchy used, see + * Avatar Standards.
+ * @function ScriptAvatar.getDefaultJointRotation + * @param {number} index - The joint index. + * @returns {Quat} The default rotation of the joint if avatar data are available and the joint index is valid, otherwise + * {@link Quat(0)|Quat.IDENTITY}. + */ glm::quat getDefaultJointRotation(int index) const; + + /**jsdoc + * Gets the default translation of a joint in the 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 ScriptAvatar.getDefaultJointTranslation + * @param {number} index - The joint index. + * @returns {Vec3} The default translation of the joint (in model coordinates) if avatar data are available and the joint + * index is valid, otherwise {@link Vec3(0)|Vec3.ZERO}. + */ glm::vec3 getDefaultJointTranslation(int index) const; + + /**jsdoc + * Gets the offset applied to the avatar for rendering. + * @function ScriptAvatar.getSkeletonOffset + * @returns {Vec3} The skeleton offset if avatar data are available, otherwise {@link Vec3(0)|Vec3.ZERO}. + */ glm::vec3 getSkeletonOffset() const; + + /**jsdoc + * Gets the position of a joint in the avatar. + * @function ScriptAvatar.getJointPosition + * @param {number} index - The index of the joint. + * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getJointPosition(int index) const; + + /**jsdoc + * Gets the position of a joint in the current avatar. + * @function ScriptAvatar.getJointPosition + * @param {string} name - The name of the joint. + * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getJointPosition(const QString& name) const; + + /**jsdoc + * Gets the position of the current avatar's neck in world coordinates. + * @function ScriptAvatar.getNeckPosition + * @returns {Vec3} The position of the neck in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getNeckPosition() const; + + /**jsdoc + * Gets the current acceleration of the avatar. + * @function ScriptAvatar.getAcceleration + * @returns {Vec3} The current acceleration of the avatar, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't available.. + */ glm::vec3 getAcceleration() const; + + /**jsdoc + * Gets the ID of the entity of avatar that the avatar is parented to. + * @function ScriptAvatar.getParentID + * @returns {Uuid} The ID of the entity or avatar that the avatar is parented to. {@link Uuid(0)|Uuid.NULL} if not parented + * or avatar data aren't available. + */ QUuid getParentID() const; + + /**jsdoc + * Gets the joint of the entity or avatar that the avatar is parented to. + * @function ScriptAvatar.getParentJointIndex + * @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, or avatar data
+ * aren't available.
+ */
quint16 getParentJointIndex() const;
+
+ /**jsdoc
+ * Gets information on all the joints in the avatar's skeleton.
+ * @function ScriptAvatar.getSkeleton
+ * @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton.
+ */
QVariantList getSkeleton() const;
+
+ /**jsdoc
+ * @function ScriptAvatar.getSimulationRate
+ * @param {AvatarSimulationRate} [rateName=""] - Rate name.
+ * @returns {number} Simulation rate in Hz, or 0.0 if avatar data aren't available.
+ * @deprecated This function is deprecated and will be removed.
+ */
float getSimulationRate(const QString& rateName = QString("")) const;
+
+ /**jsdoc
+ * Gets the position of the left palm in world coordinates.
+ * @function ScriptAvatar.getLeftPalmPosition
+ * @returns {Vec3} The position of the left palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
+ * available.
+ */
glm::vec3 getLeftPalmPosition() const;
+
+ /**jsdoc
+ * Gets the rotation of the left palm in world coordinates.
+ * @function ScriptAvatar.getLeftPalmRotation
+ * @returns {Quat} The rotation of the left palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
+ * aren't available.
+ */
glm::quat getLeftPalmRotation() const;
+
+ /**jsdoc
+ * Gets the position of the right palm in world coordinates.
+ * @function ScriptAvatar.getLeftPalmPosition
+ * @returns {Vec3} The position of the right palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
+ * available.
+ */
glm::vec3 getRightPalmPosition() const;
+
+ /**jsdoc
+ * Gets the rotation of the right palm in world coordinates.
+ * @function ScriptAvatar.getLeftPalmRotation
+ * @returns {Quat} The rotation of the right palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
+ * aren't available.
+ */
glm::quat getRightPalmRotation() const;
private:
diff --git a/libraries/avatars/src/AvatarHashMap.h b/libraries/avatars/src/AvatarHashMap.h
index c474353451..e12e5b4649 100644
--- a/libraries/avatars/src/AvatarHashMap.h
+++ b/libraries/avatars/src/AvatarHashMap.h
@@ -111,7 +111,7 @@ public:
* Gets information about an avatar.
* @function AvatarList.getAvatar
* @param {Uuid} avatarID - The ID of the avatar.
- * @returns {AvatarData} Information about the avatar.
+ * @returns {ScriptAvatar} Information about the avatar.
*/
// Null/Default-constructed QUuids will return MyAvatar
Q_INVOKABLE virtual ScriptAvatarData* getAvatar(QUuid avatarID) { return new ScriptAvatarData(getAvatarBySessionID(avatarID)); }
diff --git a/libraries/avatars/src/ScriptAvatarData.h b/libraries/avatars/src/ScriptAvatarData.h
index 9c5c2c6918..7dcd7cc7e1 100644
--- a/libraries/avatars/src/ScriptAvatarData.h
+++ b/libraries/avatars/src/ScriptAvatarData.h
@@ -16,53 +16,6 @@
#include "AvatarData.h"
-/**jsdoc
- * Information about an avatar.
- * @typedef {object} AvatarData
- * @property {Vec3} position - The avatar's position.
- * @property {number} scale - The target scale of the avatar without any restrictions on permissible values imposed by the
- * domain.
- * @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} bodyPitch - The pitch of the avatar's body, in degrees.
- * @property {number} bodyYaw - The yaw of the avatar's body, in degrees.
- * @property {number} bodyRoll - The roll of the avatar's body, in degrees.
- * @property {Quat} orientation - The orientation of the avatar's body.
- * @property {Quat} headOrientation - The orientation of the avatar's head.
- * @property {number} headPitch - The pitch of the avatar's head relative to the body, in degrees.
- * @property {number} headYaw - The yaw of the avatar's head relative to the body, in degrees.
- * @property {number} headRoll - The roll of the avatar's head relative to the body, in degrees.
- *
- * @property {Vec3} velocity - The linear velocity of the avatar.
- * @property {Vec3} angularVelocity - The angular velocity of the avatar.
- *
- * @property {Uuid} sessionUUID - The avatar's session ID.
- * @property {string} displayName - The avatar's display name.
- * @property {string} sessionDisplayName - The avatar's display name, sanitized and versioned, as defined by the avatar mixer.
- * It is unique among all avatars present in the domain at the time.
- * @property {boolean} isReplicated - Deprecated: This property is deprecated and will be
- * removed.
- * @property {boolean} lookAtSnappingEnabled - 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: This property is deprecated and will be removed. Use avatar entities instead.
- * @property {string[]} jointNames - The list of joints in the current avatar model. - * - * @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 {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. - * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the avatar. - * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the - * avatar. - * - * @property {boolean} hasPriority -true if the avatar is in a "hero" zone, false if it isn't.
- */
class ScriptAvatarData : public QObject {
Q_OBJECT
@@ -153,16 +106,110 @@ public:
// ATTACHMENT AND JOINT PROPERTIES
//
QString getSkeletonModelURLFromScript() const;
+
+ /**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 ScriptAvatar.getHandState
+ * @returns {HandState|number} The pointing state of the hand, or -1 if the avatar data aren't available.
+ */
Q_INVOKABLE char getHandState() const;
+
+ /**jsdoc
+ * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see
+ * Avatar Standards.
+ * @function ScriptAvatar.getJointRotation
+ * @param {number} index - The index of the joint.
+ * @returns {Quat} The rotation of the joint relative to its parent, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
+ * aren't available.
+ */
Q_INVOKABLE glm::quat getJointRotation(int index) const;
+
+ /**jsdoc
+ * 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 ScriptAvatar.getJointTranslation + * @param {number} index - The index of the joint. + * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates, or {@link Vec3(0)|Vec3.ZERO} + * if the avatar data aren't available. + */ Q_INVOKABLE glm::vec3 getJointTranslation(int index) const; + + /**jsdoc + * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see + * Avatar Standards. + * @function ScriptAvatar.getJointRotation + * @param {string} name - The name of the joint. + * @returns {Quat} The rotation of the joint relative to its parent, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ Q_INVOKABLE glm::quat getJointRotation(const QString& name) const; + + /**jsdoc + * 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 ScriptAvatar.getJointTranslation + * @param {number} name - The name of the joint. + * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates, or {@link Vec3(0)|Vec3.ZERO} + * if the avatar data aren't available. + */ Q_INVOKABLE glm::vec3 getJointTranslation(const QString& name) const; + + /**jsdoc + * Gets the rotations of all joints in the avatar. Each joint's rotation is relative to its parent joint. + * @function ScriptAvatar.getJointRotations + * @returns {Quat[]} The rotations of all joints relative to each's parent, or[] if the avatar data aren't
+ * available. The values are in the same order as the array returned by {@link ScriptAvatar.getJointNames}.
+ */
Q_INVOKABLE QVectorWarning: These coordinates are not necessarily in meters.
+ * @function ScriptAvatar.getJointTranslations + * @returns {Vec3[]} The translations of all joints relative to each's parent, in model coordinates, or[] if
+ * the avatar data aren't available. The values are in the same order as the array returned by
+ * {@link ScriptAvatar.getJointNames}.
+ */
Q_INVOKABLE QVectortrue if the joint data are valid, false if not or the avatar data aren't
+ * available.
+ */
Q_INVOKABLE bool isJointDataValid(const QString& name) const;
+
+ /**jsdoc
+ * Gets the joint index for a named joint. The joint index value is the position of the joint in the array returned by
+ * {@linkScriptAvatar.getJointNames}.
+ * @function ScriptAvatar.getJointIndex
+ * @param {string} name - The name of the joint.
+ * @returns {number} The index of the joint if valid and avatar data are available, otherwise -1.
+ */
Q_INVOKABLE int getJointIndex(const QString& name) const;
+
+ /**jsdoc
+ * Gets the names of all the joints in the avatar.
+ * @function ScriptAvatar.getJointNames
+ * @returns {string[]} The joint names, or [] if the avatar data aren't available.
+ */
Q_INVOKABLE QStringList getJointNames() const;
+
+ /**jsdoc
+ * Gets information about the models currently attached to the avatar.
+ * @function ScriptAvatar.getAttachmentData
+ * @returns {AttachmentData[]} Information about all models attached to the avatar, or [] if the avatar data
+ * aren't available.
+ * @deprecated This function is deprecated and will be removed. Use avatar entities instead.
+ */
Q_INVOKABLE QVectordisplayName property value changes.
+ * @function ScriptAvatar.displayNameChanged
+ * @returns {Signal}
+ */
void displayNameChanged();
+
+ /**jsdoc
+ * Triggered when the avatar's sessionDisplayName property value changes.
+ * @function ScriptAvatar.sessionDisplayNameChanged
+ * @returns {Signal}
+ */
void sessionDisplayNameChanged();
+
+ /**jsdoc
+ * Triggered when the avatar's model (i.e., skeletonModelURL property value) is changed.
+ * @function ScriptAvatar.skeletonModelURLChanged
+ * @returns {Signal}
+ */
void skeletonModelURLChanged();
+
+ /**jsdoc
+ * Triggered when the avatar's lookAtSnappingEnabled property value changes.
+ * @function ScriptAvatar.lookAtSnappingChanged
+ * @param {boolean} enabled - true if look-at snapping is enabled, false if not.
+ * @returns {Signal}
+ */
void lookAtSnappingChanged(bool enabled);
public slots:
+
+ /**jsdoc
+ * Gets the rotation of a joint relative to the avatar.
+ * @function ScriptAvatar.getAbsoluteJointRotationInObjectFrame
+ * @param {number} index - The index of the joint.
+ * @returns {Quat} The rotation of the joint relative to the avatar, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
+ * aren't available.
+ */
glm::quat getAbsoluteJointRotationInObjectFrame(int index) const;
+
+ /**jsdoc
+ * Gets the translation of a joint relative to the avatar.
+ * @function ScriptAvatar.getAbsoluteJointTranslationInObjectFrame
+ * @param {number} index - The index of the joint.
+ * @returns {Vec3} The translation of the joint relative to the avatar, or {@link Vec3(0)|Vec3.ZERO} if the avatar data
+ * aren't available.
+ */
glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const;
protected: