From fdeb0e3305b4cfe002dd7d958b425a5f767dfcc8 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 16 May 2018 09:20:54 +1200 Subject: [PATCH] Avatar API JSDoc stubs --- .../src/avatars/ScriptableAvatar.h | 130 +++++++++++++++++- interface/src/avatar/MyAvatar.h | 6 +- libraries/avatars/src/AvatarData.cpp | 2 +- libraries/avatars/src/AvatarData.h | 22 +-- libraries/shared/src/RegisteredMetaTypes.cpp | 16 ++- tools/jsdoc/plugins/hifi.js | 7 +- 6 files changed, 161 insertions(+), 22 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index b1039b5ac0..d34ad2d21e 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -17,20 +17,144 @@ #include #include +/**jsdoc + * 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 + * + * @property {Vec3} position + * @property {number} scale + * @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 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 { Q_OBJECT public: - + + /**jsdoc + * @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=[]] + */ /// Allows scripts to run animations. Q_INVOKABLE void startAnimation(const QString& url, float fps = 30.0f, float priority = 1.0f, bool loop = false, - bool hold = false, float firstFrame = 0.0f, float lastFrame = FLT_MAX, const QStringList& maskedJoints = QStringList()); + bool hold = false, float firstFrame = 0.0f, float lastFrame = FLT_MAX, + const QStringList& maskedJoints = QStringList()); + + /**jsdoc + * @function Avatar.stopAnimation + */ Q_INVOKABLE void stopAnimation(); + + /**jsdoc + * @function Avatar.getAnimationDetails + * @returns {Avatar.AnimationDetails} + */ Q_INVOKABLE AnimationDetails getAnimationDetails(); + virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override; virtual QByteArray toByteArrayStateful(AvatarDataDetail dataDetail, bool dropFaceTracking = false) override; - private slots: void update(float deltatime); diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 154e2e4d09..fa6a675d99 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -137,9 +137,9 @@ class MyAvatar : public Avatar { * @property {number} scale * @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 MyAvatar. Yaw - * is sometimes called "heading". - * @property {number} bodyPitch - The rotation about an axis running from shoulder to shoulder of MyAvatar. Pitch is + * @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". diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index db38999481..7a28686f8c 100644 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -2363,7 +2363,7 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const } /**jsdoc - * @typedef MyAvatar.AttachmentData + * @typedef AttachmentData * @property {string} modelUrl * @property {string} jointName * @property {Vec3} translation diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index bbcdd3693d..62a14ec51e 100644 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -351,7 +351,7 @@ public: class AvatarData : public QObject, public SpatiallyNestable { Q_OBJECT - // The following properties have JSDoc in MyAvatar.h. + // The following properties have JSDoc in MyAvatar.h and ScriptableAvatar.h Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) Q_PROPERTY(float scale READ getTargetScale WRITE setTargetScale) Q_PROPERTY(float density READ getDensity) @@ -502,7 +502,7 @@ public: float getDomainLimitedScale() const; /**jsdoc - * returns the minimum scale allowed for this avatar in the current domain. + * 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 * @returns {number} minimum scale allowed for this avatar in the current domain. @@ -510,14 +510,14 @@ public: Q_INVOKABLE float getDomainMinScale() const; /**jsdoc - * returns the maximum scale allowed for this avatar in the current domain. + * 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 * @returns {number} maximum scale allowed for this avatar in the current domain. */ Q_INVOKABLE float getDomainMaxScale() const; - // returns eye height of avatar in meters, ignoreing avatar scale. + // Returns eye height of avatar in meters, ignoring avatar scale. // if _targetScale is 1 then this will be identical to getEyeHeight; virtual float getUnscaledEyeHeight() const { return DEFAULT_AVATAR_EYE_HEIGHT; } @@ -775,7 +775,7 @@ public: * Get the rotations of all joints in the current avatar. Each joint's rotation is relative to its parent joint. * @function MyAvatar.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}. + * returned by {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. * @example Report the rotations of all your avatar's joints. * print(JSON.stringify(MyAvatar.getJointRotations())); */ @@ -796,7 +796,7 @@ public: * the rotation of the elbow, the hand inverse kinematics position won't end up in the right place.

* @function MyAvatar.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}. + * array returned by {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}. * @example Set your avatar to its default T-pose then rotate its right arm.
* Avatar in T-pose * @@ -852,7 +852,7 @@ 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}. + * {@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. @@ -952,7 +952,7 @@ public: /**jsdoc * Get information about all models currently attached to your avatar. * @function MyAvatar.getAttachmentData - * @returns {MyAvatar.AttachmentData[]} Information about all models attached to your avatar. + * @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++) { @@ -963,10 +963,10 @@ public: /**jsdoc * Set all models currently attached to your avatar. For example, if you retrieve attachment data using - * {@link MyAvatar.getAttachmentData}, make changes to it, and then want to update your avatar's attachments per the + * {@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 - * @param {MyAvatar.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. * @example Remove a hat attachment if your avatar is wearing it. * var hatURL = "https://s3.amazonaws.com/hifi-public/tony/cowboy-hat.fbx"; @@ -989,7 +989,7 @@ public: * Nor can you use this function to attach an entity (such as a sphere or a box) to your avatar.

* @function MyAvatar.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}) to attach the model + * @param {string} [jointName=""] - The name of the avatar joint (see {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}) to attach the model * to. * @param {Vec3} [translation=Vec3.ZERO] - The offset to apply to the model relative to the joint position. * @param {Quat} [rotation=Quat.IDENTITY] - The rotation to apply to the model relative to the joint orientation. diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index a3d312b9c1..ed2a1d67eb 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -852,7 +852,21 @@ AnimationDetails::AnimationDetails(QString role, QUrl url, float fps, float prio running(running), currentFrame(currentFrame), allowTranslation(allowTranslation) { } - +/**jsdoc + * @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 + */ QScriptValue animationDetailsToScriptValue(QScriptEngine* engine, const AnimationDetails& details) { QScriptValue obj = engine->newObject(); obj.setProperty("role", details.role); diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index 21749c7fe2..4378c2b4cb 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -21,6 +21,7 @@ exports.handlers = { // directories to scan for jsdoc comments var dirList = [ '../../assignment-client/src', + '../../assignment-client/src/avatars', '../../assignment-client/src/entities', '../../assignment-client/src/octree', '../../interface/src', @@ -31,10 +32,10 @@ exports.handlers = { '../../interface/src/devices', '../../interface/src/java', '../../interface/src/networking', - '../../interface/src/ui/', - '../../interface/src/scripting', - '../../interface/src/ui/overlays', '../../interface/src/raypick', + '../../interface/src/scripting', + '../../interface/src/ui/', + '../../interface/src/ui/overlays', '../../libraries/animation/src', '../../libraries/audio-client/src', '../../libraries/audio/src',