Camera API provides access to the "camera" that defines your view in desktop and HMD display modes.
+ *
+ * @namespace Camera
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-avatar
+ *
+ * @property {Vec3} position - The position of the camera. You can set this value only when the camera is in independent
+ * mode.
+ * @property {Quat} orientation - The orientation of the camera. You can set this value only when the camera is in
+ * independent mode.
+ * @property {Camera.Mode} mode - The camera mode.
+ * @property {ViewFrustum} frustum - The camera frustum.
+ * @property {Uuid} cameraEntity - The ID of the entity that is used for the camera position and orientation when the
+ * camera is in entity mode.
*/
Q_PROPERTY(QUuid cameraEntity READ getCameraEntity WRITE setCameraEntity)
@@ -38,25 +46,25 @@ public:
public slots:
- /**jsdoc
- * Get the ID of the entity that the camera is set to use the position and orientation from when it's in entity mode. You can
- * also get the entity ID using the Camera.cameraEntity property.
- * @function Camera.getCameraEntity
- * @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; null if no camera
- * entity has been set.
- */
+ /**jsdoc
+ * Gets the ID of the entity that the camera is set to follow (i.e., use the position and orientation from) when it's in
+ * entity mode. You can also get the entity ID using the {@link Camera|Camera.cameraEntity} property.
+ * @function Camera.getCameraEntity
+ * @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; null if no
+ * camera entity has been set.
+ */
QUuid getCameraEntity() const;
/**jsdoc
- * Set the entity that the camera should use the position and orientation from when it's in entity mode. You can also set the
- * entity using the Camera.cameraEntity property.
- * @function Camera.setCameraEntity
- * @param {Uuid} entityID The entity that the camera should follow when it's in entity mode.
- * @example "" 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 f9b82da0c1..1bddaedc42 100644
--- a/interface/src/avatar/AvatarManager.h
+++ b/interface/src/avatar/AvatarManager.h
@@ -37,10 +37,11 @@
using SortedAvatar = std::pairAvatarManager API provides information about avatars within the current domain. The avatars available are
+ * those that Interface has displayed and therefore 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.
null value.
+ * @function AvatarManager.getAvatarIdentifiers
+ * @returns {Uuid[]} The IDs of all known avatars in the domain.
+ * @example 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 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.
*/
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 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.
*/
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 | Rate Name | Description |
|---|---|
"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. |
"globalPosition""localPosition""avatarBoundingBox""faceTracker""jointData""farGrabJointData"""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 1c4b0cfc53..79c82d4f29 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)
@@ -1751,14 +1752,11 @@ protected:
template 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 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.
Warning: If the AC script is acting as an avatar (i.e., Agent.isAvatar == true) the
+ * avatar's ID is NOT included in results.
Warning: If the AC script is acting as an avatar (i.e., Agent.isAvatar == true) the
+ * avatar's ID is NOT included in results.
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(QSharedPointertrue 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.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 b2fe4673af..2a35b0d161 100644
--- a/libraries/render-utils/src/Model.cpp
+++ b/libraries/render-utils/src/Model.cpp
@@ -444,6 +444,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 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 vertices 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 04c54fc32e..764eeb1500 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/libraries/shared/src/shared/Camera.h b/libraries/shared/src/shared/Camera.h
index 0132e58d18..f41183479c 100644
--- a/libraries/shared/src/shared/Camera.h
+++ b/libraries/shared/src/shared/Camera.h
@@ -36,25 +36,6 @@ static int cameraModeId = qRegisterMetaTypeCamera.mode property.
+ * Gets the current camera mode. You can also get the mode using the {@link Camera|Camera.mode} property.
* @function Camera.getModeString
* @returns {Camera.Mode} The current camera mode.
*/
QString getModeString() const;
/**jsdoc
- * Set the camera mode. You can also set the mode using the Camera.mode property.
- * @function Camera.setModeString
- * @param {Camera.Mode} mode - The mode to set the camera to.
- */
+ * Sets the camera mode. You can also set the mode using the {@link Camera|Camera.mode} property.
+ * @function Camera.setModeString
+ * @param {Camera.Mode} mode - The mode to set the camera to.
+ */
void setModeString(const QString& mode);
/**jsdoc
- * Get the current camera position. You can also get the position using the Camera.position property.
- * @function Camera.getPosition
- * @returns {Vec3} The current camera position.
- */
+ * Gets the current camera position. You can also get the position using the {@link Camera|Camera.position} property.
+ * @function Camera.getPosition
+ * @returns {Vec3} The current camera position.
+ */
glm::vec3 getPosition() const { return _position; }
/**jsdoc
- * Set the camera position. You can also set the position using the Camera.position property. Only works if the
- * camera is in independent mode.
- * @function Camera.setPosition
- * @param {Vec3} position - The position to set the camera at.
- */
+ * Sets the camera position. You can also set the position using the {@link Camera|Camera.position} property. Only works if
+ * the camera is in independent mode.
+ * @function Camera.setPosition
+ * @param {Vec3} position - The position to set the camera at.
+ */
void setPosition(const glm::vec3& position);
/**jsdoc
- * Get the current camera orientation. You can also get the orientation using the Camera.orientation property.
- * @function Camera.getOrientation
- * @returns {Quat} The current camera orientation.
- */
+ * Gets the current camera orientation. You can also get the orientation using the {@link Camera|Camera.orientation}
+ * property.
+ * @function Camera.getOrientation
+ * @returns {Quat} The current camera orientation.
+ */
glm::quat getOrientation() const { return _orientation; }
/**jsdoc
- * Set the camera orientation. You can also set the orientation using the Camera.orientation property. Only
- * works if the camera is in independent mode.
- * @function Camera.setOrientation
- * @param {Quat} orientation - The orientation to set the camera to.
- */
+ * Sets the camera orientation. You can also set the orientation using the {@link Camera|Camera.orientation} property. Only
+ * works if the camera is in independent mode.
+ * @function Camera.setOrientation
+ * @param {Quat} orientation - The orientation to set the camera to.
+ */
void setOrientation(const glm::quat& orientation);
/**jsdoc
- * Compute a {@link PickRay} based on the current camera configuration and the specified x, y position on the
- * screen. The {@link PickRay} can be used in functions such as {@link Entities.findRayIntersection} and
- * {@link Overlays.findRayIntersection}.
+ * Computes a {@link PickRay} based on the current camera configuration and the specified x, y position on the
+ * screen. The {@link PickRay} can be used in functions such as {@link Entities.findRayIntersection} and
+ * {@link Overlays.findRayIntersection}.
* @function Camera.computePickRay
* @param {number} x - X-coordinate on screen.
* @param {number} y - Y-coordinate on screen.
@@ -147,9 +129,9 @@ public slots:
virtual PickRay computePickRay(float x, float y) const = 0;
/**jsdoc
- * Rotate the camera to look at the specified position. Only works if the camera is in independent mode.
+ * Rotates the camera to look at the specified position. Only works if the camera is in independent mode.
* @function Camera.lookAt
- * @param {Vec3} position - Position to look at.
+ * @param {Vec3} position - The position to look at.
* @example position even while the camera moves. Only works if the
- * camera is in independent mode.
+ * Sets the camera to continue looking at the specified position even while the camera moves. Only works if
+ * the camera is in independent mode.
* @function Camera.keepLookingAt
- * @param {Vec3} position - Position to keep looking at.
+ * @param {Vec3} position - The position to keep looking at.
*/
void keepLookingAt(const glm::vec3& position);
/**jsdoc
- * Stops the camera from continually looking at the position that was set with Camera.keepLookingAt.
+ * Stops the camera from continually looking at the position that was set with {@link Camera.keepLookingAt}.
* @function Camera.stopLookingAt
*/
void stopLooking() { _isKeepLookingAt = false; }
diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js
index f8230b5dea..a7c62cfc6d 100644
--- a/tools/jsdoc/plugins/hifi.js
+++ b/tools/jsdoc/plugins/hifi.js
@@ -58,6 +58,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',