Mirrors/overte-AleziaKurdis
3
0
Fork 0
mirror of https://github.com/AleziaKurdis/overte.git synced 2025-04-08 23:12:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #16299 from ctrlaltdavid/DOC-187

Browse source 
DOC-187: Mat4 JSDoc
This commit is contained in:
Shannon Romano 2019-10-07 09:11:32 -07:00 committed by GitHub
commit 5bbe271c7a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 195 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

237
libraries/script-engine/src/Mat4.h
View file

@ -22,6 +22,10 @@
#include "RegisteredMetaTypes.h"
/**jsdoc
* The <code>Mat4</code> API provides facilities for generating and using 4 x 4 matrices. These matrices are typically used to
* represent transforms (scale, rotate, and translate) that convert one coordinate system into another, or perspective
* transforms that convert 3D points into screen coordinates.
*
* @namespace Mat4
* @variation 0
*
@ -39,130 +43,279 @@ class Mat4 : public QObject, protected QScriptable {
public slots:
/**jsdoc
* Multiplies two matrices.
* @function Mat4(0).multiply
* @param {Mat4} m1
* @param {Mat4} m2
* @returns {Mat4}
* @param {Mat4} m1 - The first matrix.
* @param {Mat4} m2 - The second matrix.
* @returns {Mat4} <code>m1</code> multiplied with <code>m2</code>.
*/
glm::mat4 multiply(const glm::mat4& m1, const glm::mat4& m2) const;
/**jsdoc
* Creates a matrix that represents a rotation and translation.
* @function Mat4(0).createFromRotAndTrans
* @param {Quat} rot
* @param {Vec3} trans
* @returns {Mat4}
* @param {Quat} rot - The rotation.
* @param {Vec3} trans - The translation.
* @returns {Mat4} The matrix that represents the rotation and translation.
* @example <caption>Create a matrix with rotation and translation.</caption>
* var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
* var trans = { x: 10, y: 11, z: 12 };
* var matrix = Mat4.createFromRotAndTrans(rot, trans);
* Mat4.print("Matrix:", matrix);
* // Matrix: dmat4x4((0.353553, 0.612372, -0.707107, 0.000000),
* // (-0.573223, 0.739199, 0.353553, 0.000000),
* // (0.739199, 0.280330, 0.612372, 0.000000),
* // (10.000000, 11.000000, 12.000000, 1.000000))
*/
glm::mat4 createFromRotAndTrans(const glm::quat& rot, const glm::vec3& trans) const;
/**jsdoc
* Creates a matrix that represents a scale, rotation, and translation.
* @function Mat4(0).createFromScaleRotAndTrans
* @param {Vec3} scale
* @param {Quat} rot
* @param {Vec3} trans
* @returns {Mat4}
* @param {Vec3} scale - The scale.
* @param {Quat} rot - The rotation.
* @param {Vec3} trans - The translation.
* @returns {Mat4} The matrix that represents the scale, rotation, and translation.
* @example <caption>Create a matrix with scale, rotation, and translation.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
* var trans = { x: 10, y: 11, z: 12 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
* Mat4.print("Matrix:", matrix);
* // Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
* // (-1.146447, 1.478398, 0.707107, 0.000000),
* // (1.478398, 0.560660, 1.224745, 0.000000),
* // (10.000000, 11.000000, 12.000000, 1.000000))
*/
glm::mat4 createFromScaleRotAndTrans(const glm::vec3& scale, const glm::quat& rot, const glm::vec3& trans) const;
/**jsdoc
* Creates a matrix from columns of values.
* @function Mat4(0).createFromColumns
* @param {Vec4} col0
* @param {Vec4} col1
* @param {Vec4} col2
* @param {Vec4} col
* @returns {Mat4}
* @param {Vec4} col0 - Column 0 values.
* @param {Vec4} col1 - Column 1 values.
* @param {Vec4} col2 - Column 2 values.
* @param {Vec4} col3 - Column 3 valuse.
* @returns {Mat4} The matrix with the specified columns values.
* @example <caption>Create a matrix from columns.</caption>
* var col0 = { x: 0.707107, y: 1.224745, z: -1.414214, w: 0.0 };
* var col1 = { x: -1.146447, y: 1.478398, z: 0.707107, w: 0.0 };
* var col2 = { x: 1.478398, y: 0.560660, z: 1.224745, w: 0.0 };
* var col3 = { x: 10.0, y: 11.0, z: 12.0, w: 1.0 };
* var matrix = Mat4.createFromColumns(col0, col1, col2, col3);
* Mat4.print("Matrix:", matrix);
* //Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
* // (-1.146447, 1.478398, 0.707107, 0.000000),
* // (1.478398, 0.560660, 1.224745, 0.000000),
* // (10.000000, 11.000000, 12.000000, 1.000000))
*/
glm::mat4 createFromColumns(const glm::vec4& col0, const glm::vec4& col1, const glm::vec4& col2, const glm::vec4& col3) const;
/**jsdoc
* Creates a matrix from an array of values.
* @function Mat4(0).createFromArray
* @param {number[]} numbers
* @returns {Mat4}
* @param {number[]} arr - The array of values, starting with column 0.
* @returns {Mat4} The matrix with the specified values.
* @example <caption>Create a matrix from an array.</caption>
* var arr = [
* 0.707107, 1.224745, -1.414214, 0.0,
* -1.146447, 1.478398, 0.707107, 0.0,
* 1.478398, 0.560660, 1.224745, 0.0,
* 10.0, 11.0, 12.0, 1.00
* ];
* var matrix = Mat4.createFromArray(arr);
* Mat4.print("Matrix:", matrix);
* //Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
* // (-1.146447, 1.478398, 0.707107, 0.000000),
* // (1.478398, 0.560660, 1.224745, 0.000000),
* // (10.000000, 11.000000, 12.000000, 1.000000))
*/
glm::mat4 createFromArray(const QVector<float>& floats) const;
/**jsdoc
* Extracts the translation from a matrix.
* @function Mat4(0).extractTranslation
* @param {Mat4} m
* @returns {Vec3}
* @param {Mat4} m - The matrix.
* @returns {Vec3} The translation contained in the matrix.
* @example <caption>Extract the translation from a matrix.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
* var trans = { x: 10, y: 11, z: 12 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
*
* trans = Mat4.extractTranslation(matrix);
* print("Translation: " + JSON.stringify(trans));
* // Translation: {"x":10,"y":11,"z":12}
*/
glm::vec3 extractTranslation(const glm::mat4& m) const;
/**jsdoc
* Extracts the rotation from a matrix.
* @function Mat4(0).extractRotation
* @param {Mat4} m
* @returns {Vec3}
* @param {Mat4} m - The matrix.
* @returns {Quat} The rotation contained in the matrix.
* @example <caption>Extract the rotation from a matrix.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
* var trans = { x: 10, y: 11, z: 12 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
*
* rot = Mat4.extractRotation(matrix);
* print("Rotation: " + JSON.stringify(Quat.safeEulerAngles(rot)));
* // Rotation: {"x":29.999998092651367,"y":45.00000762939453,"z":60.000003814697266}
*/
glm::quat extractRotation(const glm::mat4& m) const;
/**jsdoc
* Extracts the scale from a matrix.
* @function Mat4(0).extractScale
* @param {Mat4} m
* @returns {Vec3}
* @param {Mat4} m - The matrix.
* @returns {Vec3} The scale contained in the matrix.
* @example <caption>Extract the scale from a matrix.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
* var trans = { x: 10, y: 11, z: 12 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
*
* scale = Mat4.extractScale(matrix);
* print("Scale: " + JSON.stringify(scale));
* // Scale: {"x":1.9999998807907104,"y":1.9999998807907104,"z":1.9999998807907104}
*/
glm::vec3 extractScale(const glm::mat4& m) const;
/**jsdoc
* Transforms a point into a new coordinate system: the point value is scaled, rotated, and translated.
* @function Mat4(0).transformPoint
* @param {Mat4} m
* @param {Vec3} point
* @returns {Vec3}
* @param {Mat4} m - The transform to the new coordinate system.
* @param {Vec3} point - The point to transform.
* @returns {Vec3} The point in the new coordinate system.
* @example <caption>Transform a point.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(0, 45, 0);
* var trans = { x: 0, y: 10, z: 0 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
*
* var point = { x: 1, y: 1, z: 1 };
* var transformedPoint = Mat4.transformPoint(matrix, point);
* print("Transformed point: " + JSON.stringify(transformedPoint));
* // Transformed point: { "x": 2.8284270763397217, "y": 12, "z": -2.384185791015625e-7 }
*/
glm::vec3 transformPoint(const glm::mat4& m, const glm::vec3& point) const;
/**jsdoc
* Transforms a vector into a new coordinate system: the vector is scaled and rotated.
* @function Mat4(0).transformVector
* @param {Mat4} m
* @param {Vec3} vector
* @returns {Vec3}
* @param {Mat4} m - The transform to the new coordinate system.
* @param {Vec3} vector - The vector to transform.
* @returns {Vec3} The vector in the new coordinate system.
* @example <caption>Transform a vector.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(0, 45, 0);
* var trans = { x: 0, y: 10, z: 0 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
*
* var vector = { x: 1, y: 1, z: 1 };
* var transformedVector = Mat4.transformVector(matrix, vector);
* print("Transformed vector: " + JSON.stringify(transformedVector));
* // Transformed vector: { "x": 2.8284270763397217, "y": 2, "z": -2.384185791015625e-7 }
*/
glm::vec3 transformVector(const glm::mat4& m, const glm::vec3& vector) const;
/**jsdoc
* Calculates the inverse of a matrix.
* @function Mat4(0).inverse
* @param {Mat4} m
* @returns {Mat4}
* @param {Mat4} m - The matrix.
* @returns {Mat4} The inverse of the matrix.
* @example <caption>A matrix multiplied with its inverse is the unit matrix.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
* var trans = { x: 10, y: 11, z: 12 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
* var inverse = Mat4.inverse(matrix);
* var multiplied = Mat4.multiply(matrix, inverse);
* Mat4.print("Multiplied:", multiplied);
* //Multiplied: dmat4x4((1.000000, 0.000000, 0.000000, 0.000000),
* // (0.000000, 1.000000, -0.000000, 0.000000),
* // (0.000000, 0.000000, 1.000000, 0.000000),
* // (0.000000, 0.000000, 0.000001, 1.000000))
*/
glm::mat4 inverse(const glm::mat4& m) const;
/**jsdoc
* Gets the "forward" direction that the camera would face if its orientation was set to the rotation contained in a
* matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.
* <p>Synonym for {@link Mat4(0).getForward|getForward}.</p>
* @function Mat4(0).getFront
* @param {Mat4} m
* @returns {Vec3}
* @param {Mat4} m - The matrix.
* @returns {Vec3} The negative z-axis rotated by orientation.
*/
// redundant, calls getForward which better describes the returned vector as a direction
glm::vec3 getFront(const glm::mat4& m) const { return getForward(m); }
/**jsdoc
* Gets the "forward" direction that the camera would face if its orientation was set to the rotation contained in a
* matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.
* @function Mat4(0).getForward
* @param {Mat4} m
* @returns {Vec3}
* @param {Mat4} m - The matrix.
* @returns {Vec3} The negative z-axis rotated by the rotation in the matrix.
* @example <caption>Demonstrate that the "forward" direction is the negative z-axis.</caption>
* var rot = Quat.IDENTITY;
* var trans = Vec3.ZERO;
* var matrix = Mat4.createFromRotAndTrans(rot, trans);
* var forward = Mat4.getForward(matrix);
* print("Forward: " + JSON.stringify(forward));
* // Forward: {"x":0,"y":0,"z":-1}
*/
glm::vec3 getForward(const glm::mat4& m) const;
/**jsdoc
* Gets the "right" direction that the camera would have if its orientation was set to the rotation contained in a matrix.
* The High Fidelity camera has axes x = right, y = up, -z = forward.
* @function Mat4(0).getRight
* @param {Mat4} m
* @returns {Vec3}
* @param {Mat4} m - The matrix.
* @returns {Vec3} The x-axis rotated by the rotation in the matrix.
*/
glm::vec3 getRight(const glm::mat4& m) const;
/**jsdoc
* Gets the "up" direction that the camera would have if its orientation was set to the rotation contained in a matrix. The
* High Fidelity camera has axes x = right, y = up, -z = forward.
* @function Mat4(0).getUp
* @param {Mat4} m
* @returns {Vec3}
* @param {Mat4} m - The matrix.
* @returns {Vec3} The y-axis rotated by the rotation in the matrix.
*/
glm::vec3 getUp(const glm::mat4& m) const;
/**jsdoc
* Prints a matrix to the program log as a label followed by the matrix's values.
* @function Mat4(0).print
* @param {string} label
* @param {Mat4} m
* @param {boolean} [transpose=false]
* @param {string} label - The label to print.
* @param {Mat4} m - The matrix to print.
* @param {boolean} [transpose=false] - <code>true</code> to transpose the matrix before printing (so that it prints the
* matrix's rows), <code>false</code> to not transpose the matrix (so that it prints the matrix's columns).
* @example <caption>Two ways of printing a label and matrix value.</caption>
* var scale = Vec3.multiply(2, Vec3.ONE);
* var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
* var trans = { x: 10, y: 11, z: 12 };
* var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
*
* Mat4.print("Matrix:", matrix);
* // Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
* // (-1.146447, 1.478398, 0.707107, 0.000000),
* // (1.478398, 0.560660, 1.224745, 0.000000),
* // (10.000000, 11.000000, 12.000000, 1.000000))
*
* print("Matrix: " + JSON.stringify(matrix));
* // Matrix: {"r0c0":0.7071067094802856,"r1c0":1.2247446775436401,"r2c0":-1.4142136573791504,"r3c0":0,
* // "r0c1": -1.1464465856552124, "r1c1": 1.4783978462219238, "r2c1": 0.7071066498756409, "r3c1": 0,
* // "r0c2": 1.4783978462219238, "r1c2": 0.5606603026390076, "r2c2": 1.2247447967529297, "r3c2": 0,
* // "r0c3": 10, "r1c3": 11, "r2c3": 12, "r3c3": 1}
*/
void print(const QString& label, const glm::mat4& m, bool transpose = false) const;
};