From 638e040e17d51177253c1bd6c96079ad3a9bce5a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 30 Apr 2019 12:13:08 +1200 Subject: [PATCH 1/2] Quat JSDoc update --- libraries/script-engine/src/Quat.h | 70 +++++++++++++++--------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/libraries/script-engine/src/Quat.h b/libraries/script-engine/src/Quat.h index d24db786d0..0a5e58ac26 100644 --- a/libraries/script-engine/src/Quat.h +++ b/libraries/script-engine/src/Quat.h @@ -23,7 +23,7 @@ #include /**jsdoc - * A quaternion value. See also the {@link Quat(0)|Quat} object. + * A quaternion value. See also the {@link Quat(0)|Quat} API. * @typedef {object} Quat * @property {number} x - Imaginary component i. * @property {number} y - Imaginary component j. @@ -32,9 +32,10 @@ */ /**jsdoc - * The Quat API provides facilities for generating and manipulating quaternions. + * The Quat API provides facilities for generating and manipulating quaternions. * Quaternions should be used in preference to Euler angles wherever possible because quaternions don't suffer from the problem * of gimbal lock. + * * @namespace Quat * @variation 0 * @@ -59,7 +60,7 @@ class Quat : public QObject, protected QScriptable { public slots: /**jsdoc - * Multiply two quaternions. + * Multiplies two quaternions. * @function Quat(0).multiply * @param {Quat} q1 - The first quaternion. * @param {Quat} q2 - The second quaternion. @@ -90,8 +91,8 @@ public slots: glm::quat normalize(const glm::quat& q); /**jsdoc - * Calculate the conjugate of a quaternion. For a unit quaternion, its conjugate is the same as its - * {@link Quat(0).inverse|Quat.inverse}. + * Calculates the conjugate of a quaternion. For a unit quaternion, its conjugate is the same as its + * {@link Quat(0).inverse|Quat.inverse}. * @function Quat(0).conjugate * @param {Quat} q - The quaternion to conjugate. * @returns {Quat} The conjugate of q. @@ -106,8 +107,9 @@ public slots: glm::quat conjugate(const glm::quat& q); /**jsdoc - * Calculate a camera orientation given eye position, point of interest, and "up" direction. The camera's negative z-axis is - * the forward direction. The result has zero roll about its forward direction with respect to the given "up" direction. + * Calculates a camera orientation given an eye position, point of interest, and "up" direction. The camera's negative + * z-axis is the forward direction. The result has zero roll about its forward direction with respect to the given "up" + * direction. * @function Quat(0).lookAt * @param {Vec3} eye - The eye position. * @param {Vec3} target - The point to look at. @@ -121,7 +123,7 @@ public slots: glm::quat lookAt(const glm::vec3& eye, const glm::vec3& center, const glm::vec3& up); /**jsdoc - * Calculate a camera orientation given eye position and point of interest. The camera's negative z-axis is the forward + * Calculates a camera orientation given an eye position and point of interest. The camera's negative z-axis is the forward * direction. The result has zero roll about its forward direction. * @function Quat(0).lookAtSimple * @param {Vec3} eye - The eye position. @@ -137,7 +139,7 @@ public slots: glm::quat lookAtSimple(const glm::vec3& eye, const glm::vec3& center); /**jsdoc - * Calculate the shortest rotation from a first vector onto a second. + * Calculates the shortest rotation from a first vector onto a second. * @function Quat(0).rotationBetween * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. @@ -154,7 +156,7 @@ public slots: glm::quat rotationBetween(const glm::vec3& v1, const glm::vec3& v2); /**jsdoc - * Generate a quaternion from a {@link Vec3} of Euler angles in degrees. + * Generates a quaternion from a {@link Vec3} of Euler angles in degrees. * @function Quat(0).fromVec3Degrees * @param {Vec3} vector - A vector of three Euler angles in degrees, the angles being the rotations about the x, y, and z * axes. @@ -168,7 +170,7 @@ public slots: glm::quat fromVec3Degrees(const glm::vec3& vec3); /**jsdoc - * Generate a quaternion from a {@link Vec3} of Euler angles in radians. + * Generates a quaternion from a {@link Vec3} of Euler angles in radians. * @function Quat(0).fromVec3Radians * @param {Vec3} vector - A vector of three Euler angles in radians, the angles being the rotations about the x, y, and z * axes. @@ -179,7 +181,7 @@ public slots: glm::quat fromVec3Radians(const glm::vec3& vec3); /**jsdoc - * Generate a quaternion from pitch, yaw, and roll values in degrees. + * Generates a quaternion from pitch, yaw, and roll values in degrees. * @function Quat(0).fromPitchYawRollDegrees * @param {number} pitch - The pitch angle in degrees. * @param {number} yaw - The yaw angle in degrees. @@ -191,7 +193,7 @@ public slots: glm::quat fromPitchYawRollDegrees(float pitch, float yaw, float roll); /**jsdoc - * Generate a quaternion from pitch, yaw, and roll values in radians. + * Generates a quaternion from pitch, yaw, and roll values in radians. * @function Quat(0).fromPitchYawRollRadians * @param {number} pitch - The pitch angle in radians. * @param {number} yaw - The yaw angle in radians. @@ -203,7 +205,7 @@ public slots: glm::quat fromPitchYawRollRadians(float pitch, float yaw, float roll); /**jsdoc - * Calculate the inverse of a quaternion. For a unit quaternion, its inverse is the same as its + * Calculates the inverse of a quaternion. For a unit quaternion, its inverse is the same as its * {@link Quat(0).conjugate|Quat.conjugate}. * @function Quat(0).inverse * @param {Quat} q - The quaternion. @@ -219,9 +221,9 @@ public slots: glm::quat inverse(const glm::quat& q); /**jsdoc - * Get the "front" direction that the camera would face if its orientation was set to the quaternion value. + * Gets the "front" direction that the camera would face if its orientation was set to the quaternion value. * This is a synonym for {@link Quat(0).getForward|Quat.getForward}. - * The High Fidelity camera has axes x = right, y = up, -z = forward. + * The High Fidelity camera has axes x = right, y = up, -z = forward. * @function Quat(0).getFront * @param {Quat} orientation - A quaternion representing an orientation. * @returns {Vec3} The negative z-axis rotated by orientation. @@ -229,9 +231,9 @@ public slots: glm::vec3 getFront(const glm::quat& orientation) { return getForward(orientation); } /**jsdoc - * Get the "forward" direction that the camera would face if its orientation was set to the quaternion value. + * Gets the "forward" direction that the camera would face if its orientation was set to the quaternion value. * This is a synonym for {@link Quat(0).getFront|Quat.getFront}. - * The High Fidelity camera has axes x = right, y = up, -z = forward. + * The High Fidelity camera has axes x = right, y = up, -z = forward. * @function Quat(0).getForward * @param {Quat} orientation - A quaternion representing an orientation. * @returns {Vec3} The negative z-axis rotated by orientation. @@ -242,8 +244,8 @@ public slots: glm::vec3 getForward(const glm::quat& orientation); /**jsdoc - * Get the "right" direction that the camera would have if its orientation was set to the quaternion value. - * The High Fidelity camera has axes x = right, y = up, -z = forward. + * Gets the "right" direction that the camera would have if its orientation was set to the quaternion value. + * The High Fidelity camera has axes x = right, y = up, -z = forward. * @function Quat(0).getRight * @param {Quat} orientation - A quaternion representing an orientation. * @returns {Vec3} The x-axis rotated by orientation. @@ -251,8 +253,8 @@ public slots: glm::vec3 getRight(const glm::quat& orientation); /**jsdoc - * Get the "up" direction that the camera would have if its orientation was set to the quaternion value. - * The High Fidelity camera has axes x = right, y = up, -z = forward. + * Gets the "up" direction that the camera would have if its orientation was set to the quaternion value. + * The High Fidelity camera has axes x = right, y = up, -z = forward. * @function Quat(0).getUp * @param {Quat} orientation - A quaternion representing an orientation. * @returns {Vec3} The y-axis rotated by orientation. @@ -260,8 +262,8 @@ public slots: glm::vec3 getUp(const glm::quat& orientation); /**jsdoc - * Calculate the Euler angles for the quaternion, in degrees. (The "safe" in the name signifies that the angle results will - * not be garbage even when the rotation is particularly difficult to decompose with pitches around +/-90 degrees.) + * Calculates the Euler angles for the quaternion, in degrees. (The "safe" in the name signifies that the angle results + * will not be garbage even when the rotation is particularly difficult to decompose with pitches around +/-90 degrees.) * @function Quat(0).safeEulerAngles * @param {Quat} orientation - A quaternion representing an orientation. * @returns {Vec3} A {@link Vec3} of Euler angles for the orientation, in degrees, the angles being the @@ -273,7 +275,7 @@ public slots: glm::vec3 safeEulerAngles(const glm::quat& orientation); /**jsdoc - * Generate a quaternion given an angle to rotate through and an axis to rotate about. + * Generates a quaternion given an angle to rotate through and an axis to rotate about. * @function Quat(0).angleAxis * @param {number} angle - The angle to rotate through, in degrees. * @param {Vec3} axis - The unit axis to rotate about. @@ -286,7 +288,7 @@ public slots: glm::quat angleAxis(float angle, const glm::vec3& v); /**jsdoc - * Get the rotation axis for a quaternion. + * Gets the rotation axis for a quaternion. * @function Quat(0).axis * @param {Quat} q - The quaternion. * @returns {Vec3} The normalized rotation axis for q. @@ -300,7 +302,7 @@ public slots: glm::vec3 axis(const glm::quat& orientation); /**jsdoc - * Get the rotation angle for a quaternion. + * Gets the rotation angle for a quaternion. * @function Quat(0).angle * @param {Quat} q - The quaternion. * @returns {number} The rotation angle for q, in radians. WARNING: This value is in radians @@ -316,7 +318,7 @@ public slots: // spherical linear interpolation // alpha: 0.0 to 1.0? /**jsdoc - * Compute a spherical linear interpolation between two rotations, safely handling two rotations that are very similar. + * Computes a spherical linear interpolation between two rotations, safely handling two rotations that are very similar. * See also, {@link Quat(0).slerp|Quat.slerp}. * @function Quat(0).mix * @param {Quat} q1 - The beginning rotation. @@ -336,7 +338,7 @@ public slots: glm::quat mix(const glm::quat& q1, const glm::quat& q2, float alpha); /**jsdoc - * Compute a spherical linear interpolation between two rotations, for rotations that are not very similar. + * Computes a spherical linear interpolation between two rotations, for rotations that are not very similar. * See also, {@link Quat(0).mix|Quat.mix}. * @function Quat(0).slerp * @param {Quat} q1 - The beginning rotation. @@ -349,7 +351,7 @@ public slots: glm::quat slerp(const glm::quat& q1, const glm::quat& q2, float alpha); /**jsdoc - * Compute a spherical quadrangle interpolation between two rotations along a path oriented toward two other rotations. + * Computes a spherical quadrangle interpolation between two rotations along a path oriented toward two other rotations. * Equivalent to: Quat.slerp(Quat.slerp(q1, q2, alpha), Quat.slerp(s1, s2, alpha), 2 * alpha * (1.0 - alpha)). * @function Quat(0).squad * @param {Quat} q1 - Initial rotation. @@ -364,8 +366,8 @@ public slots: glm::quat squad(const glm::quat& q1, const glm::quat& q2, const glm::quat& s1, const glm::quat& s2, float h); /**jsdoc - * Calculate the dot product of two quaternions. The closer the quaternions are to each other the more non-zero the value is - * (either positive or negative). Identical unit rotations have a dot product of +/- 1. + * Calculates the dot product of two quaternions. The closer the quaternions are to each other the more non-zero the value + * is (either positive or negative). Identical unit rotations have a dot product of +/-1. * @function Quat(0).dot * @param {Quat} q1 - The first quaternion. * @param {Quat} q2 - The second quaternion. @@ -385,7 +387,7 @@ public slots: float dot(const glm::quat& q1, const glm::quat& q2); /**jsdoc - * Print to the program log a text label followed by a quaternion's pitch, yaw, and roll Euler angles. + * Prints to the program log a text label followed by a quaternion's pitch, yaw, and roll Euler angles. * @function Quat(0).print * @param {string} label - The label to print. * @param {Quat} q - The quaternion to print. @@ -403,7 +405,7 @@ public slots: void print(const QString& label, const glm::quat& q, bool asDegrees = false); /**jsdoc - * Test whether two quaternions are equal. Note: The quaternions must be exactly equal in order for + * Tests whether two quaternions are equal. Note: The quaternions must be exactly equal in order for * true to be returned; it is often better to use {@link Quat(0).dot|Quat.dot} and test for closeness to +/-1. * @function Quat(0).equal * @param {Quat} q1 - The first quaternion. From 7db1e3372051c92b891e438a59bca9cbb2ec1db6 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 30 Apr 2019 12:13:43 +1200 Subject: [PATCH 2/2] Note camera axes in Camera JSDoc --- interface/src/FancyCamera.h | 1 + 1 file changed, 1 insertion(+) diff --git a/interface/src/FancyCamera.h b/interface/src/FancyCamera.h index aead54d0fd..0cfe147138 100644 --- a/interface/src/FancyCamera.h +++ b/interface/src/FancyCamera.h @@ -20,6 +20,7 @@ class FancyCamera : public Camera { /**jsdoc * The Camera API provides access to the "camera" that defines your view in desktop and HMD display modes. + * The High Fidelity camera has axes x = right, y = up, -z = forward. * * @namespace Camera *