From 231d1373b6ac8c48c09f1e9d8e408fcb85fb9878 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 5 Jun 2019 08:38:34 +1200 Subject: [PATCH 1/3] Update MyAvatar, Avatar JSDoc per recent changes --- .../src/avatars/ScriptableAvatar.h | 6 +- interface/src/avatar/MyAvatar.h | 85 +++++++++++++------ libraries/avatars/src/AvatarData.h | 6 ++ 3 files changed, 68 insertions(+), 29 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 34dc25914f..3ef908bedb 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -74,7 +74,8 @@ * 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. - * @property {boolean} hasPriority - is the avatar in a Hero zone? Read-only. + * @property {boolean} hasPriority - true if the avatar is in a "hero" zone, false if it isn't. + * Read-only. * * @example Create a scriptable avatar. * (function () { @@ -138,6 +139,9 @@ public: /// 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; + /**jsdoc + * @comment Uses the base class's JSDoc. + */ Q_INVOKABLE virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override; /**jsdoc diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 058603f320..95f55c1cf0 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -39,6 +39,23 @@ class ModelItemID; class MyHead; class DetailedMotionState; +/**jsdoc + *

Locomotion control types.

+ * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0DefaultYour walking speed is constant; it doesn't change depending on how far + * forward you push your controller's joystick. Fully pushing your joystick forward makes your avatar run.
1AnalogYour walking speed changes in steps based on how far forward you push your + * controller's joystick. Fully pushing your joystick forward makes your avatar run.
2AnalogPlusYour walking speed changes proportionally to how far forward you push + * your controller's joystick. Fully pushing your joystick forward makes your avatar run.
+ * @typedef {number} MyAvatar.LocomotionControlsMode + */ enum LocomotionControlsMode { CONTROLS_DEFAULT = 0, CONTROLS_ANALOG, @@ -128,6 +145,8 @@ class MyAvatar : public Avatar { * 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. + * @property {boolean} hasPriority - true if the avatar is in a "hero" zone, false if it isn't. + * 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 @@ -239,9 +258,14 @@ 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 - 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 {number} walkSpeed - The walk speed of your avatar for the current control scheme (see + * {@link MyAvatar.getControlScheme|getControlScheme}). + * @property {number} walkBackwardSpeed - The walk backward speed of your avatar for the current control scheme (see + * {@link MyAvatar.getControlScheme|getControlScheme}). + * @property {number} sprintSpeed - The sprint (run) speed of your avatar for the current control scheme (see + * {@link MyAvatar.getControlScheme|getControlScheme}). + * @property {number} analogPlusWalkSpeed - The walk speed of your avatar for the "AnalogPlus" control scheme. + * @property {number} analogPlusSprintSpeed - The sprint speed of your avatar for the "AnalogPlus" control scheme. * @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 @@ -281,6 +305,7 @@ class MyAvatar : public Avatar { * @borrows Avatar.updateAvatarEntity as updateAvatarEntity * @borrows Avatar.clearAvatarEntity as clearAvatarEntity * @borrows Avatar.setForceFaceTrackerConnected as setForceFaceTrackerConnected + * @borrows Avatar.setSkeletonModelURL as setSkeletonModelURL * @borrows Avatar.getAttachmentData as getAttachmentData * @borrows Avatar.setAttachmentData as setAttachmentData * @borrows Avatar.attach as attach @@ -308,7 +333,6 @@ class MyAvatar : public Avatar { * @comment Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different. * @borrows Avatar.getTargetScale as getTargetScale * @borrows Avatar.resetLastSent as resetLastSent - * @borrows Avatar.hasPriority as hasPriority */ // FIXME: `glm::vec3 position` is not accessible from QML, so this exposes position in a QML-native type Q_PROPERTY(QVector3D qmlPosition READ getQmlPosition) @@ -789,26 +813,34 @@ public: */ Q_INVOKABLE void setSnapTurn(bool on) { _useSnapTurn = on; } - /** + /**jsdoc + * Gets the control scheme that is in use. * @function MyAvatar.getControlScheme - * @returns {number} - */ + * @returns {MyAvatar.LocomotionControlsMode} The control scheme that is in use. + */ Q_INVOKABLE int getControlScheme() const { return _controlSchemeIndex; } - /** + /**jsdoc + * Sets the control scheme to use. * @function MyAvatar.setControlScheme - * @param {number} index - */ + * @param {MyAvatar.LocomotionControlsMode} controlScheme - The control scheme to use. + */ Q_INVOKABLE void setControlScheme(int index) { _controlSchemeIndex = (index >= 0 && index <= 2) ? index : 0; } /**jsdoc + * Gets whether your avatar hovers when its feet are not on the ground. * @function MyAvatar.hoverWhenUnsupported - * @returns {boolean} + * @returns {boolean} true if your avatar hovers when its feet are not on the ground, false if it + * falls. */ + // FIXME: Should be named, getHoverWhenUnsupported(). Q_INVOKABLE bool hoverWhenUnsupported() const { return _hoverWhenUnsupported; } + /**jsdoc + * Sets whether your avatar hovers when its feet are not on the ground. * @function MyAvatar.setHoverWhenUnsupported - * @param {boolean} on + * @param {boolean} hover - true if your avatar hovers when its feet are not on the ground, false + * if it falls. */ Q_INVOKABLE void setHoverWhenUnsupported(bool on) { _hoverWhenUnsupported = on; } @@ -826,15 +858,19 @@ public: * @returns {string} "left" for the left hand, "right" for the right hand. */ Q_INVOKABLE QString getDominantHand() const; + /**jsdoc - * @function MyAVatar.setStrafeEnabled - * @param {bool} enabled - */ + * Sets whether strafing is enabled. + * @function MyAvatar.setStrafeEnabled + * @param {boolean} enabled - true if strafing is enabled, false if it isn't. + */ Q_INVOKABLE void setStrafeEnabled(bool enabled); + /**jsdoc - * @function MyAvatar.getStrafeEnabled - * @returns {bool} - */ + * Gets whether strafing is enabled. + * @function MyAvatar.getStrafeEnabled + * @returns {boolean} true if strafing is enabled, false if it isn't. + */ Q_INVOKABLE bool getStrafeEnabled() const; /**jsdoc * @function MyAvatar.setHmdAvatarAlignmentType @@ -1495,18 +1531,8 @@ public: */ Q_INVOKABLE float getDriveGear5(); - /**jsdoc - * Choose the control scheme. - * @function MyAvatar.setControlSchemeIndex - * @param {number} Choose the control scheme to be used. - */ void setControlSchemeIndex(int index); - /**jsdoc - * Check what control scheme is in use. - * @function MyAvatar.getControlSchemeIndex - * @returns {number} Returns the index associated with a given control scheme. - */ int getControlSchemeIndex(); /**jsdoc @@ -2409,6 +2435,9 @@ private: void updateEyeContactTarget(float deltaTime); // These are made private for MyAvatar so that you will use the "use" methods instead + /**jsdoc + * @comment Borrows the base class's JSDoc. + */ Q_INVOKABLE virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override; virtual void updatePalms() override {} diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index e5131ff94b..5c62e0b2c6 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -1211,6 +1211,12 @@ public: const QString& getDisplayName() const { return _displayName; } const QString& getSessionDisplayName() const { return _sessionDisplayName; } bool getLookAtSnappingEnabled() const { return _lookAtSnappingEnabled; } + + /**jsdoc + * Sets the avatar's skeleton model. + * @function Avatar.setSkeletonModelURL + * @param {string} url - The avatar's FST file. + */ Q_INVOKABLE virtual void setSkeletonModelURL(const QUrl& skeletonModelURL); virtual void setDisplayName(const QString& displayName); From f91c6dec3a24bfefc861ec9ef0c278e4c7973938 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 5 Jun 2019 08:38:52 +1200 Subject: [PATCH 2/3] Miscellaneous fixes noticed in passing --- interface/src/avatar/MyAvatar.h | 64 ++++++++++++++++----------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 95f55c1cf0..d78aebe0c1 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -607,14 +607,13 @@ public: * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see * 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 {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 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. - * @param lastFrame {number} The frame the animation should end at. + * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. + * @param {boolean} loop - true if the animation should loop, false if it shouldn't. + * @param {number} firstFrame - The frame to start the animation at. + * @param {number} lastFrame - The frame to end the animation at. * @example Play a clapping animation on your avatar for three seconds. - * // Clap your hands for 3 seconds then restore animation back to the avatar. * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx"; * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53); * Script.setTimeout(function () { @@ -625,18 +624,18 @@ public: Q_INVOKABLE void overrideAnimation(const QString& url, float fps, bool loop, float firstFrame, float lastFrame); /**jsdoc - * overrideHandAnimation() Gets the overrides the default hand poses that are triggered with controller buttons. - * use {@link MyAvatar.restoreHandAnimation}.

to restore the default poses. + * Overrides the default hand poses that are triggered with controller buttons. + * Use {@link MyAvatar.restoreHandAnimation} to restore the default poses. * @function MyAvatar.overrideHandAnimation - * @param isLeft {boolean} Set true if using the left hand - * @param url {string} The URL to the animation file. Animation files need to be FBX format, but only need to contain the + * @param isLeft {boolean} true to override the left hand, false to override the right hand. + * @param {string} url - The URL of 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. - * @param firstFrame {number} The frame the animation should start at. - * @param lastFrame {number} The frame the animation should end at - * @example Override left hand animation for three seconds. - * // Override the left hand pose then restore the default pose. + * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. + * @param {boolean} loop - true if the animation should loop, false if it shouldn't. + * @param {number} firstFrame - The frame to start the animation at. + * @param {number} lastFrame - The frame to end the animation at. + * @example Override left hand animation for three seconds. + * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx"; * MyAvatar.overrideHandAnimation(isLeft, ANIM_URL, 30, true, 0, 53); * Script.setTimeout(function () { * MyAvatar.restoreHandAnimation(); @@ -653,7 +652,6 @@ public: * 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. * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx"; * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53); * Script.setTimeout(function () { @@ -663,16 +661,15 @@ public: Q_INVOKABLE void restoreAnimation(); /**jsdoc - * Restores the default hand animation state machine that is driven by the state machine in the avatar-animation json. + * Restores the default hand animation state machine that is driven by the state machine in the avatar-animation JSON. *

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. restoreHandAnimation() is used to restore the default hand poses - * If you aren't currently playing an override hand - * animation, this function has no effect.

+ * If you aren't currently playing an override hand animation, this function has no effect.

* @function MyAvatar.restoreHandAnimation * @param isLeft {boolean} Set to true if using the left hand * @example Override left hand animation for three seconds. - * // Override the left hand pose then restore the default pose. + * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx"; * MyAvatar.overrideHandAnimation(isLeft, ANIM_URL, 30, true, 0, 53); * Script.setTimeout(function () { * MyAvatar.restoreHandAnimation(); @@ -713,12 +710,13 @@ public: * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see * 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 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 - * @param lastFrame {number} The frame the animation should end at + * @param {string} role - The animation role to override + * @param {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. + * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. + * @param {boolean} loop - true if the animation should loop, false if it shouldn't. + * @param {number} firstFrame - The frame the animation should start at. + * @param {number} lastFrame - The frame the animation should end at. * @example The default avatar-animation.json defines an "idleStand" animation role. This role specifies that when the avatar is not moving, * an animation clip of the avatar idling with hands hanging at its side will be used. It also specifies that when the avatar moves, the animation * will smoothly blend to the walking animation used by the "walkFwd" animation role. @@ -806,8 +804,9 @@ public: * mode. */ Q_INVOKABLE bool getSnapTurn() const { return _useSnapTurn; } + /**jsdoc - * Sets whether your should do snap turns or smooth turns in HMD mode. + * Sets whether you do snap turns or smooth turns in HMD mode. * @function MyAvatar.setSnapTurn * @param {boolean} on - true to do snap turns in HMD mode; false to do smooth turns in HMD mode. */ @@ -872,16 +871,17 @@ public: * @returns {boolean} true if strafing is enabled, false if it isn't. */ Q_INVOKABLE bool getStrafeEnabled() const; + /**jsdoc + * Sets the HMD alignment relative to your avatar. * @function MyAvatar.setHmdAvatarAlignmentType * @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& type); /**jsdoc - * Gets the HMD alignment for your avatar. + * Gets the HMD alignment relative to your avatar. * @function MyAvatar.getHmdAvatarAlignmentType * @returns {string} "head" if aligning your head and your avatar's head, "eyes" if aligning your * eyes and your avatar's eyes. @@ -1610,8 +1610,8 @@ public: 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. + * @comment Different behavior to the Avatar version of this method. * @function MyAvatar.getAbsoluteJointRotationInObjectFrame * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to the avatar. @@ -1623,8 +1623,8 @@ public: 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. + * @comment Different behavior to the Avatar version of this method. * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to the avatar. From caf29dc45a83ec0bb6e262c37943934f3df3a178 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 6 Jun 2019 11:24:10 +1200 Subject: [PATCH 3/3] Doc review --- interface/src/avatar/MyAvatar.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index d78aebe0c1..b02ff0d805 100755 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -265,6 +265,8 @@ class MyAvatar : public Avatar { * @property {number} sprintSpeed - The sprint (run) speed of your avatar for the current control scheme (see * {@link MyAvatar.getControlScheme|getControlScheme}). * @property {number} analogPlusWalkSpeed - The walk speed of your avatar for the "AnalogPlus" control scheme. + *

Warning: Setting this value also sets the value of analogPlusSprintSpeed to twice + * the value.

* @property {number} analogPlusSprintSpeed - The sprint speed of your avatar for the "AnalogPlus" control scheme. * @property {MyAvatar.SitStandModelType} userRecenterModel - Controls avatar leaning and recentering behavior. * @property {number} isInSittingState - true if your avatar is sitting (avatar leaning is disabled, @@ -664,7 +666,7 @@ public: * Restores the default hand animation state machine that is driven by the state machine in the avatar-animation JSON. *

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. restoreHandAnimation() is used to restore the default hand poses + * override the default animations. restoreHandAnimation() is used to restore the default hand poses. * If you aren't currently playing an override hand animation, this function has no effect.

* @function MyAvatar.restoreHandAnimation * @param isLeft {boolean} Set to true if using the left hand