From abd660e2d6521fcb70bba58e41e4529b2b1471cd Mon Sep 17 00:00:00 2001 From: nobelium Date: Wed, 1 May 2013 08:03:08 +0530 Subject: [PATCH 1/5] added examples in Matrix4.js --- Source/Core/Matrix4.js | 108 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/Source/Core/Matrix4.js b/Source/Core/Matrix4.js index 878e6e3b1beb..bb594eca7596 100644 --- a/Source/Core/Matrix4.js +++ b/Source/Core/Matrix4.js @@ -796,6 +796,17 @@ define([ * @return {Array} The modified Array parameter or a new Array instance if one was not provided. * * @exception {DeveloperError} matrix is required. + * + * @example + * //converts a matrix of order 4 to an array + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * var a = Matrix4.toArray(m); + * + * //creates a = [10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0, 17.0, 18.0, 19.0, 20.0, 21.0, 22.0, 23.0, 24.0, 25.0] + * */ Matrix4.toArray = function(matrix, result) { if (typeof matrix === 'undefined') { @@ -866,6 +877,23 @@ define([ * @exception {DeveloperError} index is required and must be 0, 1, 2, or 3. * * @see Cartesian4 + * + * @example + * //returns a Cartesian4 instance with values from the specified column + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * //Example 1: Creates an instance of Cartesian + * var a = Matrix4.getColumn(m, 2); + * + * //Example 2: Sets values for Cartesian instance + * var a = new Cartesian4(); + * Matrix4.getColumn(m, 2, a); + * + * // a.x = 12.0; a.y = 16.0; a.z = 20.0; a.w = 24.0; + * */ Matrix4.getColumn = function(matrix, index, result) { if (typeof matrix === 'undefined') { @@ -907,6 +935,22 @@ define([ * @exception {DeveloperError} index is required and must be 0, 1, 2, or 3. * * @see Cartesian4 + * + * @example + * //creates a new matrix of order 4 with new column values from the Cartesian4 instance + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * var a = Matrix4.setColumn(m, 2, new Cartesian4(99.0, 98.0, 97.0, 96.0)); + * + * // m remains the same + * // a = [10.0, 11.0, 99.0, 13.0] + * // [14.0, 15.0, 98.0, 17.0] + * // [18.0, 19.0, 97.0, 21.0] + * // [22.0, 23.0, 96.0, 25.0] + * */ Matrix4.setColumn = function(matrix, index, cartesian, result) { if (typeof matrix === 'undefined') { @@ -940,6 +984,22 @@ define([ * @exception {DeveloperError} index is required and must be 0, 1, 2, or 3. * * @see Cartesian4 + * + * @example + * //returns a Cartesian4 instance with values from the specified column + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * //Example 1: Returns an instance of Cartesian + * var a = Matrix4.getRow(m, 2); + * + * //Example 1: Sets values for a Cartesian instance + * var a = new Cartesian4(); + * Matrix4.getRow(m, 2, a); + * + * // a.x = 18.0; a.y = 19.0; a.z = 20.0; a.w = 21.0; */ Matrix4.getRow = function(matrix, index, result) { if (typeof matrix === 'undefined') { @@ -980,6 +1040,22 @@ define([ * @exception {DeveloperError} index is required and must be 0, 1, 2, or 3. * * @see Cartesian4 + * + * @example + * //create a new matrix of order 4 with new row values from the Cartesian4 instance + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * var a = Matrix4.setRow(m, 2, new Cartesian4(99.0, 98.0, 97.0, 96.0)); + * + * // m remains the same + * // a = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [99.0, 98.0, 97.0, 96.0] + * // [22.0, 23.0, 24.0, 25.0] + * */ Matrix4.setRow = function(matrix, index, cartesian, result) { if (typeof matrix === 'undefined') { @@ -1353,6 +1429,22 @@ define([ * @return {Matrix4} The modified result parameter or a new Matrix4 instance if one was not provided. * * @exception {DeveloperError} matrix is required. + * + * @example + * //create a new matrix of order 4 + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * var a = Matrix4.negate(m); + * + * // m remains the same + * // a = [-10.0, -11.0, -12.0, -13.0] + * // [-14.0, -15.0, -16.0, -17.0] + * // [-18.0, -19.0, -20.0, -21.0] + * // [-22.0, -23.0, -24.0, -25.0] + * */ Matrix4.negate = function(matrix, result) { if (typeof matrix === 'undefined') { @@ -1393,6 +1485,22 @@ define([ * @return {Matrix4} The modified result parameter or a new Matrix4 instance if one was not provided. * * @exception {DeveloperError} matrix is required. + * + * @example + * //returns transpose of a matrix of order 4 + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * var a = Matrix4.negate(m); + * + * // m remains the same + * // a = [10.0, 14.0, 18.0, 22.0] + * // [11.0, 15.0, 19.0, 23.0] + * // [12.0, 16.0, 20.0, 24.0] + * // [13.0, 17.0, 21.0, 25.0] + * */ Matrix4.transpose = function(matrix, result) { if (typeof matrix === 'undefined') { From d39b56ae183b3c87d7a5d8d13c17459a6557d5da Mon Sep 17 00:00:00 2001 From: nobelium Date: Thu, 2 May 2013 14:39:15 +0530 Subject: [PATCH 2/5] added some more examples and rephrased explanations --- Source/Core/Matrix4.js | 85 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 80 insertions(+), 5 deletions(-) diff --git a/Source/Core/Matrix4.js b/Source/Core/Matrix4.js index bb594eca7596..c8f3d232d79e 100644 --- a/Source/Core/Matrix4.js +++ b/Source/Core/Matrix4.js @@ -798,13 +798,14 @@ define([ * @exception {DeveloperError} matrix is required. * * @example - * //converts a matrix of order 4 to an array + * //create an array from an instance of Matrix4 * // m = [10.0, 11.0, 12.0, 13.0] * // [14.0, 15.0, 16.0, 17.0] * // [18.0, 19.0, 20.0, 21.0] * // [22.0, 23.0, 24.0, 25.0] * var a = Matrix4.toArray(m); * + * // m remains the same * //creates a = [10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0, 17.0, 18.0, 19.0, 20.0, 21.0, 22.0, 23.0, 24.0, 25.0] * */ @@ -937,7 +938,7 @@ define([ * @see Cartesian4 * * @example - * //creates a new matrix of order 4 with new column values from the Cartesian4 instance + * //creates a new Matrix4 instance with new column values from the Cartesian4 instance * // m = [10.0, 11.0, 12.0, 13.0] * // [14.0, 15.0, 16.0, 17.0] * // [18.0, 19.0, 20.0, 21.0] @@ -1042,7 +1043,7 @@ define([ * @see Cartesian4 * * @example - * //create a new matrix of order 4 with new row values from the Cartesian4 instance + * //create a new Matrix4 instance with new row values from the Cartesian4 instance * // m = [10.0, 11.0, 12.0, 13.0] * // [14.0, 15.0, 16.0, 17.0] * // [18.0, 19.0, 20.0, 21.0] @@ -1386,6 +1387,22 @@ define([ * * @exception {DeveloperError} matrix is required. * @exception {DeveloperError} scalar is required and must be a number. + * + * @example + * //create a Matrix4 instance which is a scaled version of the supplied Matrix4 + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * var a = Matrix4.multiplyByScalar(m, -2); + * + * // m remains the same + * // a = [-20.0, -22.0, -24.0, -26.0] + * // [-28.0, -30.0, -32.0, -34.0] + * // [-36.0, -38.0, -40.0, -42.0] + * // [-44.0, -46.0, -48.0, -50.0] + * */ Matrix4.multiplyByScalar = function(matrix, scalar, result) { if (typeof matrix === 'undefined') { @@ -1431,7 +1448,7 @@ define([ * @exception {DeveloperError} matrix is required. * * @example - * //create a new matrix of order 4 + * //create a new Matrix4 instance which is a negation of a Matrix4 * // m = [10.0, 11.0, 12.0, 13.0] * // [14.0, 15.0, 16.0, 17.0] * // [18.0, 19.0, 20.0, 21.0] @@ -1487,7 +1504,7 @@ define([ * @exception {DeveloperError} matrix is required. * * @example - * //returns transpose of a matrix of order 4 + * //returns transpose of a Matrix4 * // m = [10.0, 11.0, 12.0, 13.0] * // [14.0, 15.0, 16.0, 17.0] * // [18.0, 19.0, 20.0, 21.0] @@ -1547,6 +1564,27 @@ define([ * @param {Matrix4} [left] The first matrix. * @param {Matrix4} [right] The second matrix. * @return {Boolean} true if left and right are equal, false otherwise. + * + * @example + * //compares two Matrix4 instances + * + * // a = [10.0, 14.0, 18.0, 22.0] + * // [11.0, 15.0, 19.0, 23.0] + * // [12.0, 16.0, 20.0, 24.0] + * // [13.0, 17.0, 21.0, 25.0] + * + * // b = [10.0, 14.0, 18.0, 22.0] + * // [11.0, 15.0, 19.0, 23.0] + * // [12.0, 16.0, 20.0, 24.0] + * // [13.0, 17.0, 21.0, 25.0] + * + * if(Matrix4.equals(a,b)) + * console.log("Both matrices are equal"); + * else + * console.log("They are not equal"); + * + * //Prints "Both matrices are equal" on the console + * */ Matrix4.equals = function(left, right) { return (left === right) || @@ -1582,6 +1620,27 @@ define([ * @return {Boolean} true if left and right are within the provided epsilon, false otherwise. * * @exception {DeveloperError} epsilon is required and must be a number. + * + * @example + * //compares two Matrix4 instances + * + * // a = [10.5, 14.5, 18.5, 22.5] + * // [11.5, 15.5, 19.5, 23.5] + * // [12.5, 16.5, 20.5, 24.5] + * // [13.5, 17.5, 21.5, 25.5] + * + * // b = [10.0, 14.0, 18.0, 22.0] + * // [11.0, 15.0, 19.0, 23.0] + * // [12.0, 16.0, 20.0, 24.0] + * // [13.0, 17.0, 21.0, 25.0] + * + * if(Matrix4.equalsEpsilon(a,b,0.1)) + * console.log("Difference between both the matrices is less than 0.1"); + * else + * console.log("Difference between both the matrices is not less than 0.1"); + * + * //Prints "Difference between both the matrices is not less than 0.1" on the console + * */ Matrix4.equalsEpsilon = function(left, right, epsilon) { if (typeof epsilon !== 'number') { @@ -1645,6 +1704,22 @@ define([ * @exception {DeveloperError} matrix is required. * * @see Matrix3 + * + * @example + * // returns transpose of Matrix3 instance from a Matrix4 instance + * + * // m = [10.0, 11.0, 12.0, 13.0] + * // [14.0, 15.0, 16.0, 17.0] + * // [18.0, 19.0, 20.0, 21.0] + * // [22.0, 23.0, 24.0, 25.0] + * + * var b = new Matrix3; + * Matrix4.getRotation(m,b); + * + * // m = [10.0, 14.0, 18.0] + * // [11.0, 15.0, 19.0] + * // [12.0, 16.0, 20.0] + * */ Matrix4.getRotation = function(matrix, result) { if (typeof matrix === 'undefined') { From 81a702db113c8ee0eaddb4574bec1684a80cb7d7 Mon Sep 17 00:00:00 2001 From: nobelium Date: Thu, 2 May 2013 17:34:42 +0530 Subject: [PATCH 3/5] made correction in getRotation example --- Source/Core/Matrix4.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Source/Core/Matrix4.js b/Source/Core/Matrix4.js index c8f3d232d79e..a118a64617b5 100644 --- a/Source/Core/Matrix4.js +++ b/Source/Core/Matrix4.js @@ -1708,15 +1708,15 @@ define([ * @example * // returns transpose of Matrix3 instance from a Matrix4 instance * - * // m = [10.0, 11.0, 12.0, 13.0] - * // [14.0, 15.0, 16.0, 17.0] - * // [18.0, 19.0, 20.0, 21.0] - * // [22.0, 23.0, 24.0, 25.0] + * // m = [10.0, 14.0, 18.0, 22.0] + * // [11.0, 15.0, 19.0, 23.0] + * // [12.0, 16.0, 20.0, 24.0] + * // [13.0, 17.0, 21.0, 25.0] * * var b = new Matrix3; * Matrix4.getRotation(m,b); * - * // m = [10.0, 14.0, 18.0] + * // b = [10.0, 14.0, 18.0] * // [11.0, 15.0, 19.0] * // [12.0, 16.0, 20.0] * From cf1f060c686192ccbd55fcacc69a0c41e7ed468b Mon Sep 17 00:00:00 2001 From: nobelium Date: Thu, 2 May 2013 18:03:31 +0530 Subject: [PATCH 4/5] made correction in getRotation example --- Source/Core/Matrix4.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Source/Core/Matrix4.js b/Source/Core/Matrix4.js index a118a64617b5..903034e5a262 100644 --- a/Source/Core/Matrix4.js +++ b/Source/Core/Matrix4.js @@ -1706,7 +1706,7 @@ define([ * @see Matrix3 * * @example - * // returns transpose of Matrix3 instance from a Matrix4 instance + * // returns a Matrix3 instance from a Matrix4 instance * * // m = [10.0, 14.0, 18.0, 22.0] * // [11.0, 15.0, 19.0, 23.0] From 18fecc142428f6a3e7f35728acedbbbaceb36cdb Mon Sep 17 00:00:00 2001 From: nobelium Date: Thu, 2 May 2013 22:40:38 +0530 Subject: [PATCH 5/5] mistakes in examples corrected --- Source/Core/Matrix4.js | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/Source/Core/Matrix4.js b/Source/Core/Matrix4.js index 903034e5a262..30ab4835bb4e 100644 --- a/Source/Core/Matrix4.js +++ b/Source/Core/Matrix4.js @@ -799,10 +799,10 @@ define([ * * @example * //create an array from an instance of Matrix4 - * // m = [10.0, 11.0, 12.0, 13.0] - * // [14.0, 15.0, 16.0, 17.0] - * // [18.0, 19.0, 20.0, 21.0] - * // [22.0, 23.0, 24.0, 25.0] + * // m = [10.0, 14.0, 18.0, 22.0] + * // [11.0, 15.0, 19.0, 23.0] + * // [12.0, 16.0, 20.0, 24.0] + * // [13.0, 17.0, 21.0, 25.0] * var a = Matrix4.toArray(m); * * // m remains the same @@ -1578,10 +1578,11 @@ define([ * // [12.0, 16.0, 20.0, 24.0] * // [13.0, 17.0, 21.0, 25.0] * - * if(Matrix4.equals(a,b)) + * if(Matrix4.equals(a,b)) { * console.log("Both matrices are equal"); - * else + * } else { * console.log("They are not equal"); + * } * * //Prints "Both matrices are equal" on the console * @@ -1634,10 +1635,11 @@ define([ * // [12.0, 16.0, 20.0, 24.0] * // [13.0, 17.0, 21.0, 25.0] * - * if(Matrix4.equalsEpsilon(a,b,0.1)) + * if(Matrix4.equalsEpsilon(a,b,0.1)){ * console.log("Difference between both the matrices is less than 0.1"); - * else + * } else { * console.log("Difference between both the matrices is not less than 0.1"); + * } * * //Prints "Difference between both the matrices is not less than 0.1" on the console * @@ -1713,7 +1715,7 @@ define([ * // [12.0, 16.0, 20.0, 24.0] * // [13.0, 17.0, 21.0, 25.0] * - * var b = new Matrix3; + * var b = new Matrix3(); * Matrix4.getRotation(m,b); * * // b = [10.0, 14.0, 18.0]