mirror of
https://github.com/overte-org/overte.git
synced 2025-04-08 08:14:48 +02:00
Merge pull request #15476 from ctrlaltdavid/M22407
Case 22407: Quat JSDoc update
This commit is contained in:
jennaingersoll
GitHub
commit
712167c623
2 changed files with 37 additions and 34 deletions
|
|
@ -20,6 +20,7 @@ class FancyCamera : public Camera {
|
|||
|
||||
/**jsdoc
|
||||
* The <code>Camera</code> API provides access to the "camera" that defines your view in desktop and HMD display modes.
|
||||
* The High Fidelity camera has axes <code>x</code> = right, <code>y</code> = up, </code>-z</code> = forward.
|
||||
*
|
||||
* @namespace Camera
|
||||
*
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@
|
|||
#include <GLMHelpers.h>
|
||||
|
||||
/**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 <code>Quat</code> 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 <code>q</code>.
|
||||
|
|
@ -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 <code>x</code> = right, <code>y</code> = up, </code>-z</code> = forward.
|
||||
* @function Quat(0).getFront
|
||||
* @param {Quat} orientation - A quaternion representing an orientation.
|
||||
* @returns {Vec3} The negative z-axis rotated by <code>orientation</code>.
|
||||
|
|
@ -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 <code>x</code> = right, <code>y</code> = up, </code>-z</code> = forward.
|
||||
* @function Quat(0).getForward
|
||||
* @param {Quat} orientation - A quaternion representing an orientation.
|
||||
* @returns {Vec3} The negative z-axis rotated by <code>orientation</code>.
|
||||
|
|
@ -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 <code>x</code> = right, <code>y</code> = up, </code>-z</code> = forward.
|
||||
* @function Quat(0).getRight
|
||||
* @param {Quat} orientation - A quaternion representing an orientation.
|
||||
* @returns {Vec3} The x-axis rotated by <code>orientation</code>.
|
||||
|
|
@ -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 <code>x</code> = right, <code>y</code> = up, </code>-z</code> = forward.
|
||||
* @function Quat(0).getUp
|
||||
* @param {Quat} orientation - A quaternion representing an orientation.
|
||||
* @returns {Vec3} The y-axis rotated by <code>orientation</code>.
|
||||
|
|
@ -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 <code>orientation</code>, 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 <code>q</code>.
|
||||
|
|
@ -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 <code>q</code>, in radians. <strong>WARNING:</strong> 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: <code>Quat.slerp(Quat.slerp(q1, q2, alpha), Quat.slerp(s1, s2, alpha), 2 * alpha * (1.0 - alpha))</code>.
|
||||
* @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. <strong>Note:</strong> The quaternions must be exactly equal in order for
|
||||
* Tests whether two quaternions are equal. <strong>Note:</strong> The quaternions must be exactly equal in order for
|
||||
* <code>true</code> 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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue