From 2a17ad3da5120b6688108cdf937d086f46537975 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 4 Apr 2019 10:11:54 +1300 Subject: [PATCH 1/2] AvatarList and AvatarManager JSDoc --- interface/src/avatar/AvatarManager.cpp | 12 ++ interface/src/avatar/AvatarManager.h | 133 ++++++++++++------ .../src/avatars-renderer/Avatar.cpp | 20 +++ .../src/avatars-renderer/Avatar.h | 4 +- libraries/avatars/src/AvatarData.cpp | 16 ++- libraries/avatars/src/AvatarData.h | 3 +- libraries/avatars/src/AvatarHashMap.h | 94 +++++++++---- libraries/avatars/src/ScriptAvatarData.h | 46 ++++++ libraries/render-utils/src/Model.cpp | 13 ++ libraries/shared/src/GeometryUtil.h | 7 + tools/jsdoc/plugins/hifi.js | 1 + 11 files changed, 277 insertions(+), 72 deletions(-) diff --git a/interface/src/avatar/AvatarManager.cpp b/interface/src/avatar/AvatarManager.cpp index 69f7054953..35022c882f 100755 --- a/interface/src/avatar/AvatarManager.cpp +++ b/interface/src/avatar/AvatarManager.cpp @@ -946,6 +946,18 @@ void AvatarManager::setAvatarSortCoefficient(const QString& name, const QScriptV } } +/**jsdoc + * PAL (People Access List) data for an avatar. + * @typedef {object} AvatarManager.PalData + * @property {Uuid} sessionUUID - The avatar's session ID. "" if the avatar is your own. + * @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 {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the + * domain. + * @property {boolean} isReplicated - Deprecated. + * @property {Vec3} position - The position of the avatar. + * @property {number} palOrbOffset - The vertical offset from the avatar's position that an overlay orb should be displayed at. + */ QVariantMap AvatarManager::getPalData(const QStringList& specificAvatarIdentifiers) { QJsonArray palData; diff --git a/interface/src/avatar/AvatarManager.h b/interface/src/avatar/AvatarManager.h index 0468fbd809..64bcb8dceb 100644 --- a/interface/src/avatar/AvatarManager.h +++ b/interface/src/avatar/AvatarManager.h @@ -37,10 +37,11 @@ using SortedAvatar = std::pair>; /**jsdoc - * The AvatarManager API has properties and methods which manage Avatars within the same domain. + * The AvatarManager API provides information about avatars within the domain. The avatars available are those + * that Interface has displayed and so knows about. * - *

Note: This API is also provided to Interface and client entity scripts as the synonym, - * AvatarList. For assignment client scripts, see the separate {@link AvatarList} API. + *

Warning: This API is also provided to Interface, client entity, and avatar scripts as the synonym, + * "AvatarList". For assignment client scripts, see the separate {@link AvatarList} API.

* * @namespace AvatarManager * @@ -48,8 +49,9 @@ using SortedAvatar = std::pair>; * @hifi-client-entity * @hifi-avatar * - * @borrows AvatarList.getAvatarIdentifiers as getAvatarIdentifiers - * @borrows AvatarList.getAvatarsInRange as getAvatarsInRange + * @borrows AvatarList.getAvatar as getAvatar + * @comment AvatarList.getAvatarIdentifiers as getAvatarIdentifiers - Don't borrow because behavior is slightly different. + * @comment AvatarList.getAvatarsInRange as getAvatarsInRange - Don't borrow because behavior is slightly different. * @borrows AvatarList.avatarAddedEvent as avatarAddedEvent * @borrows AvatarList.avatarRemovedEvent as avatarRemovedEvent * @borrows AvatarList.avatarSessionChangedEvent as avatarSessionChangedEvent @@ -67,6 +69,31 @@ class AvatarManager : public AvatarHashMap { public: + /**jsdoc + * Gets the IDs of all avatars known about in the domain. + * Your own avatar is included in the list as a null value. + * @function AvatarManager.getAvatarIdentifiers + * @returns {Uuid[]} The IDs of all known avatars in the domain. + * @example Report the IDS of all avatars within the domain. + * var avatars = AvatarManager.getAvatarIdentifiers(); + * print("Avatars in the domain: " + JSON.stringify(avatars)); + * // A null item is included for your avatar. + */ + + /**jsdoc + * Gets the IDs of all avatars known about within a specified distance from a point. + * Your own avatar's ID is included in the list if it is in range. + * @function AvatarManager.getAvatarsInRange + * @param {Vec3} position - The point about which the search is performed. + * @param {number} range - The search radius. + * @returns {Uuid[]} The IDs of all known avatars within the search distance from the position. + * @example Report the IDs of all avatars within 10m of your avatar. + * var RANGE = 10; + * var avatars = AvatarManager.getAvatarsInRange(MyAvatar.position, RANGE); + * print("Nearby avatars: " + JSON.stringify(avatars)); + * print("Own avatar: " + MyAvatar.sessionUUID); + */ + /// Registers the script types associated with the avatar manager. static void registerMetaTypes(QScriptEngine* engine); @@ -79,9 +106,7 @@ public: glm::vec3 getMyAvatarPosition() const { return _myAvatar->getWorldPosition(); } /**jsdoc - * @function AvatarManager.getAvatar - * @param {Uuid} avatarID - * @returns {AvatarData} + * @comment Uses the base class's JSDoc. */ // Null/Default-constructed QUuids will return MyAvatar Q_INVOKABLE virtual ScriptAvatarData* getAvatar(QUuid avatarID) override { return new ScriptAvatar(getAvatarBySessionID(avatarID)); } @@ -112,36 +137,53 @@ public: void handleCollisionEvents(const CollisionEvents& collisionEvents); /**jsdoc + * Gets the amount of avatar mixer data being generated by an avatar other than your own. * @function AvatarManager.getAvatarDataRate - * @param {Uuid} sessionID - * @param {string} [rateName=""] - * @returns {number} + * @param {Uuid} sessionID - The ID of the avatar to get the data rate for. + * @param {AvatarDataRate} [rateName=""] - The type of avatar mixer data to get the data rate of. + * @returns {number} The data rate in kbps; 0 if the avatar is your own. */ Q_INVOKABLE float getAvatarDataRate(const QUuid& sessionID, const QString& rateName = QString("")) const; /**jsdoc + * Gets the update rate of avatar mixer data being generated by an avatar other than your own. * @function AvatarManager.getAvatarUpdateRate - * @param {Uuid} sessionID - * @param {string} [rateName=""] - * @returns {number} + * @param {Uuid} sessionID - The ID of the avatar to get the update rate for. + * @param {AvatarUpdateRate} [rateName=""] - The type of avatar mixer data to get the update rate of. + * @returns {number} The update rate in Hz; 0 if the avatar is your own. */ Q_INVOKABLE float getAvatarUpdateRate(const QUuid& sessionID, const QString& rateName = QString("")) const; /**jsdoc + * Gets the simulation rate of an avatar other than your own. * @function AvatarManager.getAvatarSimulationRate - * @param {Uuid} sessionID - * @param {string} [rateName=""] - * @returns {number} + * @param {Uuid} sessionID - The ID of the avatar to get the simulation rate for. + * @param {AvatarSimulationRate} [rateName=""] - The type of avatar data to get the simulation rate of. + * @returns {number} The simulation rate in Hz; 0 if the avatar is your own. */ Q_INVOKABLE float getAvatarSimulationRate(const QUuid& sessionID, const QString& rateName = QString("")) const; /**jsdoc + * Find the first avatar intersected by a {@link PickRay}. * @function AvatarManager.findRayIntersection - * @param {PickRay} ray - * @param {Uuid[]} [avatarsToInclude=[]] - * @param {Uuid[]} [avatarsToDiscard=[]] - * @param {boolean} pickAgainstMesh - * @returns {RayToAvatarIntersectionResult} + * @param {PickRay} ray - The ray to use for finding avatars. + * @param {Uuid[]} [avatarsToInclude=[]] - If not empty then search is restricted to these avatars. + * @param {Uuid[]} [avatarsToDiscard=[]] - Avatars to ignore in the search. + * @param {boolean} [pickAgainstMesh=true] - If true then the exact intersection with the avatar mesh is + * calculated, if false then the intersection is approximate. + * @returns {RayToAvatarIntersectionResult} The result of the search for the first intersected avatar. + * @example Find the first avatar directly in front of you. + * var pickRay = { + * origin: MyAvatar.position, + * direction: Quat.getFront(MyAvatar.orientation) + * }; + * + * var intersection = AvatarManager.findRayIntersection(pickRay); + * if (intersection.intersects) { + * print("Avatar found: " + JSON.stringify(intersection)); + * } else { + * print("No avatar found."); + * } */ Q_INVOKABLE RayToAvatarIntersectionResult findRayIntersection(const PickRay& ray, const QScriptValue& avatarIdsToInclude = QScriptValue(), @@ -149,11 +191,12 @@ public: bool pickAgainstMesh = true); /**jsdoc * @function AvatarManager.findRayIntersectionVector - * @param {PickRay} ray - * @param {Uuid[]} avatarsToInclude - * @param {Uuid[]} avatarsToDiscard - * @param {boolean} pickAgainstMesh - * @returns {RayToAvatarIntersectionResult} + * @param {PickRay} ray - Ray. + * @param {Uuid[]} avatarsToInclude - Avatars to include. + * @param {Uuid[]} avatarsToDiscard - Avatars to discard. + * @param {boolean} pickAgainstMesh - Pick against mesh. + * @returns {RayToAvatarIntersectionResult} Intersection result. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE RayToAvatarIntersectionResult findRayIntersectionVector(const PickRay& ray, const QVector& avatarsToInclude, @@ -162,10 +205,11 @@ public: /**jsdoc * @function AvatarManager.findParabolaIntersectionVector - * @param {PickParabola} pick - * @param {Uuid[]} avatarsToInclude - * @param {Uuid[]} avatarsToDiscard - * @returns {ParabolaToAvatarIntersectionResult} + * @param {PickParabola} pick - Pick. + * @param {Uuid[]} avatarsToInclude - Avatars to include. + * @param {Uuid[]} avatarsToDiscard - Avatars to discard. + * @returns {ParabolaToAvatarIntersectionResult} Intersection result. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE ParabolaToAvatarIntersectionResult findParabolaIntersectionVector(const PickParabola& pick, const QVector& avatarsToInclude, @@ -173,27 +217,31 @@ public: /**jsdoc * @function AvatarManager.getAvatarSortCoefficient - * @param {string} name - * @returns {number} + * @param {string} name - Name. + * @returns {number} Value. + * @deprecated This function is deprecated and will be removed. */ // TODO: remove this HACK once we settle on optimal default sort coefficients Q_INVOKABLE float getAvatarSortCoefficient(const QString& name); /**jsdoc * @function AvatarManager.setAvatarSortCoefficient - * @param {string} name - * @param {number} value + * @param {string} name - Name + * @param {number} value - Value. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE void setAvatarSortCoefficient(const QString& name, const QScriptValue& value); /**jsdoc - * Used in the PAL for getting PAL-related data about avatars nearby. Using this method is faster - * than iterating over each avatar and obtaining data about them in JavaScript, as that method - * locks and unlocks each avatar's data structure potentially hundreds of times per update tick. + * Gets PAL (People Access List) data for one or more avatars. Using this method is faster than iterating over each avatar + * and obtaining data about each individually. * @function AvatarManager.getPalData - * @param {string[]} [specificAvatarIdentifiers=[]] - The list of IDs of the avatars you want the PAL data for. - * If an empty list, the PAL data for all nearby avatars is returned. - * @returns {object[]} An array of objects, each object being the PAL data for an avatar. + * @param {string[]} [avatarIDs=[]] - The IDs of the avatars to get the PAL data for. If empty then PAL + * data is obtained for all avatars. + * @returns {object<"data", AvatarManager.PalData[]>} An array of objects, each object being the PAL data for an avatar. + * @example Report the PAL data for one nearby avatar. + * var palData = AvatarManager.getPalData(); + * print("PAL data for one avatar: " + JSON.stringify(palData.data[0])); */ Q_INVOKABLE QVariantMap getPalData(const QStringList& specificAvatarIdentifiers = QStringList()); @@ -209,7 +257,8 @@ public: public slots: /**jsdoc * @function AvatarManager.updateAvatarRenderStatus - * @param {boolean} shouldRenderAvatars + * @param {boolean} shouldRenderAvatars - Should render avatars. + * @deprecated This function is deprecated and will be removed. */ void updateAvatarRenderStatus(bool shouldRenderAvatars); diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp index 839c4ed1d9..d083dfb41b 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp @@ -509,6 +509,26 @@ void Avatar::relayJointDataToChildren() { _reconstructSoftEntitiesJointMap = false; } +/**jsdoc + * An avatar has different types of data simulated at different rates, in Hz. + * + * + * + * + * + * + * + * + * + * + * + * + *
Rate NameDescription
"avatar" or ""The rate at which the avatar is updated even if not in view.
"avatarInView"The rate at which the avatar is updated if in view.
"skeletonModel"The rate at which the skeleton model is being updated, even if there are no + * joint data available.
"jointData"The rate at which joint data are being updated.
""When no rate name is specified, the "avatar" update rate is + * provided.
+ * + * @typedef {string} AvatarSimulationRate + */ float Avatar::getSimulationRate(const QString& rateName) const { if (rateName == "") { return _simulationRate.rate(); diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 974fae2034..7c4cde1f4d 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -501,8 +501,8 @@ public: /**jsdoc * @function MyAvatar.getSimulationRate - * @param {string} [rateName=""] - Rate name. - * @returns {number} Simulation rate. + * @param {AvatarSimulationRate} [rateName=""] - Rate name. + * @returns {number} Simulation rate in Hz. * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE float getSimulationRate(const QString& rateName = QString("")) const; diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index a2b0b808ba..404d5c57af 100755 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -1545,7 +1545,6 @@ float AvatarData::getDataRate(const QString& rateName) const { * Rate NameDescription * * - * "globalPosition"Global position. * "localPosition"Local position. * "avatarBoundingBox"Avatar bounding box. @@ -1559,7 +1558,6 @@ float AvatarData::getDataRate(const QString& rateName) const { * "faceTracker"Face tracker data. * "jointData"Joint data. * "farGrabJointData"Far grab joint data. - * ""When no rate name is specified, the overall update rate is provided. * * @@ -2905,6 +2903,20 @@ glm::mat4 AvatarData::getControllerRightHandMatrix() const { return _controllerRightHandMatrixCache.get(); } +/**jsdoc + * Information about a ray-to-avatar intersection. + * @typedef {object} RayToAvatarIntersectionResult + * @property {boolean} intersects - true if an avatar is intersected, false if it isn't. + * @property {string} avatarID - The ID of the avatar that is intersected. + * @property {number} distance - The distance from the ray origin to the intersection. + * @property {string} face - The name of the box face that is intersected; "UNKNOWN_FACE" if mesh was picked + * against. + * @property {Vec3} intersection - The ray intersection point in world coordinates. + * @property {Vec3} surfaceNormal - The surface normal at the intersection point. + * @property {number} jointIndex - The index of the joint intersected. + * @property {SubmeshIntersection} extraInfo - Extra information on the mesh intersected if mesh was picked against, + * {} if it wasn't. + */ QScriptValue RayToAvatarIntersectionResultToScriptValue(QScriptEngine* engine, const RayToAvatarIntersectionResult& value) { QScriptValue obj = engine->newObject(); obj.setProperty("intersects", value.intersects); diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index caa1f9f892..802e5c953e 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -479,7 +479,8 @@ class AvatarData : public QObject, public SpatiallyNestable { * 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. */ Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) Q_PROPERTY(float scale READ getDomainLimitedScale WRITE setTargetScale) diff --git a/libraries/avatars/src/AvatarHashMap.h b/libraries/avatars/src/AvatarHashMap.h index 8395651d6b..3340635c82 100644 --- a/libraries/avatars/src/AvatarHashMap.h +++ b/libraries/avatars/src/AvatarHashMap.h @@ -36,8 +36,10 @@ const int CLIENT_TO_AVATAR_MIXER_BROADCAST_FRAMES_PER_SECOND = 50; const quint64 MIN_TIME_BETWEEN_MY_AVATAR_DATA_SENDS = USECS_PER_SECOND / CLIENT_TO_AVATAR_MIXER_BROADCAST_FRAMES_PER_SECOND; /**jsdoc - * Note: An AvatarList API is also provided for Interface and client entity scripts: it is a - * synonym for the {@link AvatarManager} API. + * The AvatarList API provides information about avatars within the domain. + * + *

Warning: An API named "AvatarList" is also provided for Interface, client entity, and avatar + * scripts, however, it is a synonym for the {@link AvatarManager} API.

* * @namespace AvatarList * @@ -78,23 +80,37 @@ public: // Currently, your own avatar will be included as the null avatar id. /**jsdoc + * Gets the IDs of all avatars in the domain. + *

Warning: If the AC script is acting as an avatar (i.e., Agent.isAvatar == true) the + * avatar's ID is NOT included in results.

* @function AvatarList.getAvatarIdentifiers - * @returns {Uuid[]} + * @returns {Uuid[]} The IDs of all avatars in the domain (excluding AC script's avatar). + * @example Report the IDS of all avatars within the domain. + * var avatars = AvatarList.getAvatarIdentifiers(); + * print("Avatars in the domain: " + JSON.stringify(avatars)); */ Q_INVOKABLE QVector getAvatarIdentifiers(); /**jsdoc + * Gets the IDs of all avatars within a specified distance from a point. + *

Warning: If the AC script is acting as an avatar (i.e., Agent.isAvatar == true) the + * avatar's ID is NOT included in results.

* @function AvatarList.getAvatarsInRange - * @param {Vec3} position - * @param {number} range - * @returns {Uuid[]} + * @param {Vec3} position - The point about which the search is performed. + * @param {number} range - The search radius. + * @returns {Uuid[]} The IDs of all avatars within the search distance from the position (excluding AC script's avatar). + * @example Report the IDs of all avatars within 10m of the origin. + * var RANGE = 10; + * var avatars = AvatarList.getAvatarsInRange(Vec3.ZERO, RANGE); + * print("Avatars near the origin: " + JSON.stringify(avatars)); */ Q_INVOKABLE QVector getAvatarsInRange(const glm::vec3& position, float rangeMeters) const; /**jsdoc + * Gets information about an avatar. * @function AvatarList.getAvatar - * @param {Uuid} avatarID - * @returns {AvatarData} + * @param {Uuid} avatarID - The ID of the avatar. + * @returns {AvatarData} Information about the avatar. */ // Null/Default-constructed QUuids will return MyAvatar Q_INVOKABLE virtual ScriptAvatarData* getAvatar(QUuid avatarID) { return new ScriptAvatarData(getAvatarBySessionID(avatarID)); } @@ -110,34 +126,57 @@ public: signals: /**jsdoc + * Triggered when an avatar arrives in the domain. * @function AvatarList.avatarAddedEvent - * @param {Uuid} sessionUUID + * @param {Uuid} sessionUUID - The ID of the avatar that arrived in the domain. * @returns {Signal} + * @example Report when an avatar arrives in the domain. + * AvatarManager.avatarAddedEvent.connect(function (sessionID) { + * print("Avatar arrived: " + sessionID); + * }); + * + * // Note: If using from the AvatarList API, replace "AvatarManager" with "AvatarList". */ void avatarAddedEvent(const QUuid& sessionUUID); /**jsdoc + * Triggered when an avatar leaves the domain. * @function AvatarList.avatarRemovedEvent - * @param {Uuid} sessionUUID + * @param {Uuid} sessionUUID - The ID of the avatar that left the domain. * @returns {Signal} + * @example Report when an avatar leaves the domain. + * AvatarManager.avatarRemovedEvent.connect(function (sessionID) { + * print("Avatar left: " + sessionID); + * }); + * + * // Note: If using from the AvatarList API, replace "AvatarManager" with "AvatarList". */ void avatarRemovedEvent(const QUuid& sessionUUID); /**jsdoc + * Triggered when an avatar's session ID changes. * @function AvatarList.avatarSessionChangedEvent - * @param {Uuid} sessionUUID - * @param {Uuid} oldSessionUUID + * @param {Uuid} newSessionUUID - The new session ID. + * @param {Uuid} oldSessionUUID - The old session ID. * @returns {Signal} + * @example Report when an avatar's session ID changes. + * AvatarManager.avatarSessionChangedEvent.connect(function (newSessionID, oldSessionID) { + * print("Avatar session ID changed from " + oldSessionID + " to " + newSessionID); + * }); + * + * // Note: If using from the AvatarList API, replace "AvatarManager" with "AvatarList". */ void avatarSessionChangedEvent(const QUuid& sessionUUID,const QUuid& oldUUID); public slots: /**jsdoc + * Checks whether there is an avatar within a specified distance from a point. * @function AvatarList.isAvatarInRange - * @param {string} position - * @param {string} range - * @returns {boolean} + * @param {string} position - The test position. + * @param {string} range - The test distance. + * @returns {boolean} true if there's an avatar within the specified distance of the point, false + * if not. */ bool isAvatarInRange(const glm::vec3 & position, const float range); @@ -145,36 +184,41 @@ protected slots: /**jsdoc * @function AvatarList.sessionUUIDChanged - * @param {Uuid} sessionUUID - * @param {Uuid} oldSessionUUID + * @param {Uuid} sessionUUID - New session ID. + * @param {Uuid} oldSessionUUID - Old session ID. + * @deprecated This function is deprecated and will be removed. */ void sessionUUIDChanged(const QUuid& sessionUUID, const QUuid& oldUUID); /**jsdoc * @function AvatarList.processAvatarDataPacket - * @param {} message - * @param {} sendingNode + * @param {object} message - Message. + * @param {object} sendingNode - Sending node. + * @deprecated This function is deprecated and will be removed. */ void processAvatarDataPacket(QSharedPointer message, SharedNodePointer sendingNode); /**jsdoc * @function AvatarList.processAvatarIdentityPacket - * @param {} message - * @param {} sendingNode + * @param {object} message - Message. + * @param {object} sendingNode - Sending node. + * @deprecated This function is deprecated and will be removed. */ void processAvatarIdentityPacket(QSharedPointer message, SharedNodePointer sendingNode); /**jsdoc * @function AvatarList.processBulkAvatarTraits - * @param {} message - * @param {} sendingNode + * @param {object} message - Message. + * @param {object} sendingNode - Sending node. + * @deprecated This function is deprecated and will be removed. */ void processBulkAvatarTraits(QSharedPointer message, SharedNodePointer sendingNode); /**jsdoc * @function AvatarList.processKillAvatar - * @param {} message - * @param {} sendingNode + * @param {object} message - Message. + * @param {object} sendingNode - Sending node. + * @deprecated This function is deprecated and will be removed. */ void processKillAvatar(QSharedPointer message, SharedNodePointer sendingNode); diff --git a/libraries/avatars/src/ScriptAvatarData.h b/libraries/avatars/src/ScriptAvatarData.h index 01f7ff360a..61ceb88480 100644 --- a/libraries/avatars/src/ScriptAvatarData.h +++ b/libraries/avatars/src/ScriptAvatarData.h @@ -16,6 +16,52 @@ #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. + * @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: Use avatar entities insteada. + * @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 diff --git a/libraries/render-utils/src/Model.cpp b/libraries/render-utils/src/Model.cpp index 89a9c7cf47..9c7df54cda 100644 --- a/libraries/render-utils/src/Model.cpp +++ b/libraries/render-utils/src/Model.cpp @@ -442,6 +442,19 @@ bool Model::findRayIntersectionAgainstSubMeshes(const glm::vec3& origin, const g } } + /**jsdoc + * Information about a submesh intersection point. + * @typedef {object} SubmeshIntersection + * @property {Vec3} worldIntersectionPoint - The intersection point in world coordinates. + * @property {Vec3} meshIntersectionPoint - The intersection point in model coordinates. + * @property {number} partIndex - The index of the intersected mesh part within the submesh. + * @property {number} shapeID - The index of the mesh part within the model. + * @property {number} subMeshIndex - The index of the intersected submesh within the model. + * @property {string} subMeshName - The name of the intersected submesh. + * @property {Triangle} subMeshTriangleWorld - The vertexes of the intersected mesh part triangle in world coordinates. + * @property {Vec3} subMeshNormal - The normal of the intersected mesh part triangle in model coordinates. + * @property {Triangle} subMeshTriangle - The vertexes of the intersected mesh part triangle in model coordinates. + */ if (intersectedSomething) { distance = bestDistance; face = bestFace; diff --git a/libraries/shared/src/GeometryUtil.h b/libraries/shared/src/GeometryUtil.h index 8ec75f71bd..ce25a4f559 100644 --- a/libraries/shared/src/GeometryUtil.h +++ b/libraries/shared/src/GeometryUtil.h @@ -119,6 +119,13 @@ void swingTwistDecomposition(const glm::quat& rotation, glm::quat& swing, glm::quat& twist); +/**jsdoc + * A triangle in a mesh. + * @typedef {object} Triangle + * @property {Vec3} v0 - The position of vertex 0 in the triangle. + * @property {Vec3} v1 - The position of vertex 1 in the triangle. + * @property {Vec3} v2 - The position of vertex 2 in the triangle. + */ class Triangle { public: glm::vec3 v0; diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index 5ec94b46aa..6624301cf3 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -56,6 +56,7 @@ exports.handlers = { '../../libraries/physics/src', '../../libraries/plugins/src/plugins', '../../libraries/pointers/src', + '../../libraries/render-utils/src', '../../libraries/script-engine/src', '../../libraries/shared/src', '../../libraries/shared/src/shared', From 38e21dcaa20b08819911d8d424bd8fa0733e28b5 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 11 Apr 2019 11:04:02 +1200 Subject: [PATCH 2/2] Doc review --- interface/src/avatar/AvatarManager.h | 16 ++++++++-------- libraries/avatars/src/AvatarHashMap.h | 2 +- libraries/avatars/src/ScriptAvatarData.h | 2 +- libraries/render-utils/src/Model.cpp | 4 ++-- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/interface/src/avatar/AvatarManager.h b/interface/src/avatar/AvatarManager.h index 678dc5a3e2..1bddaedc42 100644 --- a/interface/src/avatar/AvatarManager.h +++ b/interface/src/avatar/AvatarManager.h @@ -37,8 +37,8 @@ using SortedAvatar = std::pair>; /**jsdoc - * The AvatarManager API provides information about avatars within the domain. The avatars available are those - * that Interface has displayed and so knows about. + * The AvatarManager API provides information about avatars within the current domain. The avatars available are + * those that Interface has displayed and therefore knows about. * *

Warning: This API is also provided to Interface, client entity, and avatar scripts as the synonym, * "AvatarList". For assignment client scripts, see the separate {@link AvatarList} API.

@@ -139,7 +139,7 @@ public: /**jsdoc * Gets the amount of avatar mixer data being generated by an avatar other than your own. * @function AvatarManager.getAvatarDataRate - * @param {Uuid} sessionID - The ID of the avatar to get the data rate for. + * @param {Uuid} sessionID - The ID of the avatar whose data rate you're retrieving. * @param {AvatarDataRate} [rateName=""] - The type of avatar mixer data to get the data rate of. * @returns {number} The data rate in kbps; 0 if the avatar is your own. */ @@ -148,7 +148,7 @@ public: /**jsdoc * Gets the update rate of avatar mixer data being generated by an avatar other than your own. * @function AvatarManager.getAvatarUpdateRate - * @param {Uuid} sessionID - The ID of the avatar to get the update rate for. + * @param {Uuid} sessionID - The ID of the avatar whose update rate you're retrieving. * @param {AvatarUpdateRate} [rateName=""] - The type of avatar mixer data to get the update rate of. * @returns {number} The update rate in Hz; 0 if the avatar is your own. */ @@ -157,7 +157,7 @@ public: /**jsdoc * Gets the simulation rate of an avatar other than your own. * @function AvatarManager.getAvatarSimulationRate - * @param {Uuid} sessionID - The ID of the avatar to get the simulation rate for. + * @param {Uuid} sessionID - The ID of the avatar whose simulation you're retrieving. * @param {AvatarSimulationRate} [rateName=""] - The type of avatar data to get the simulation rate of. * @returns {number} The simulation rate in Hz; 0 if the avatar is your own. */ @@ -236,10 +236,10 @@ public: * Gets PAL (People Access List) data for one or more avatars. Using this method is faster than iterating over each avatar * and obtaining data about each individually. * @function AvatarManager.getPalData - * @param {string[]} [avatarIDs=[]] - The IDs of the avatars to get the PAL data for. If empty then PAL - * data is obtained for all avatars. + * @param {string[]} [avatarIDs=[]] - The IDs of the avatars to get the PAL data for. If empty, then PAL data is obtained + * for all avatars. * @returns {object<"data", AvatarManager.PalData[]>} An array of objects, each object being the PAL data for an avatar. - * @example Report the PAL data for one nearby avatar. + * @example Report the PAL data for an avatar nearby. * var palData = AvatarManager.getPalData(); * print("PAL data for one avatar: " + JSON.stringify(palData.data[0])); */ diff --git a/libraries/avatars/src/AvatarHashMap.h b/libraries/avatars/src/AvatarHashMap.h index 3340635c82..17a3d28eb0 100644 --- a/libraries/avatars/src/AvatarHashMap.h +++ b/libraries/avatars/src/AvatarHashMap.h @@ -36,7 +36,7 @@ const int CLIENT_TO_AVATAR_MIXER_BROADCAST_FRAMES_PER_SECOND = 50; const quint64 MIN_TIME_BETWEEN_MY_AVATAR_DATA_SENDS = USECS_PER_SECOND / CLIENT_TO_AVATAR_MIXER_BROADCAST_FRAMES_PER_SECOND; /**jsdoc - * The AvatarList API provides information about avatars within the domain. + * The AvatarList API provides information about avatars within the current domain. * *

Warning: An API named "AvatarList" is also provided for Interface, client entity, and avatar * scripts, however, it is a synonym for the {@link AvatarManager} API.

diff --git a/libraries/avatars/src/ScriptAvatarData.h b/libraries/avatars/src/ScriptAvatarData.h index 61ceb88480..7e33618ba9 100644 --- a/libraries/avatars/src/ScriptAvatarData.h +++ b/libraries/avatars/src/ScriptAvatarData.h @@ -46,7 +46,7 @@ * * @property {string} skeletonModelURL - The avatar's FST file. * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
- * Deprecated: Use avatar entities insteada. + * Deprecated: 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 diff --git a/libraries/render-utils/src/Model.cpp b/libraries/render-utils/src/Model.cpp index ff0fa4ac3b..2a35b0d161 100644 --- a/libraries/render-utils/src/Model.cpp +++ b/libraries/render-utils/src/Model.cpp @@ -453,9 +453,9 @@ bool Model::findRayIntersectionAgainstSubMeshes(const glm::vec3& origin, const g * @property {number} shapeID - The index of the mesh part within the model. * @property {number} subMeshIndex - The index of the intersected submesh within the model. * @property {string} subMeshName - The name of the intersected submesh. - * @property {Triangle} subMeshTriangleWorld - The vertexes of the intersected mesh part triangle in world coordinates. + * @property {Triangle} subMeshTriangleWorld - The vertices of the intersected mesh part triangle in world coordinates. * @property {Vec3} subMeshNormal - The normal of the intersected mesh part triangle in model coordinates. - * @property {Triangle} subMeshTriangle - The vertexes of the intersected mesh part triangle in model coordinates. + * @property {Triangle} subMeshTriangle - The vertices of the intersected mesh part triangle in model coordinates. */ if (intersectedSomething) { distance = bestDistance;